syndarix/CLAUDE.md

CLAUDE.md

Claude Code context for Syndarix - AI-Powered Software Consulting Agency.

Built on PragmaStack. See AGENTS.md for base template context.

---

Syndarix Project Context

Vision

Syndarix is an autonomous platform that orchestrates specialized AI agents to deliver complete software solutions with minimal human intervention. It acts as a virtual consulting agency with AI agents playing roles like Product Owner, Architect, Engineers, QA, etc.

Repository

• URL: https://gitea.pragmazest.com/cardosofelipe/syndarix
• Issue Tracker: Gitea Issues (primary)
• CI/CD: Gitea Actions

Core Concepts

Agent Types & Instances:

• Agent Type = Template (base model, failover, expertise, personality)
• Agent Instance = Spawned from type, assigned to project
• Multiple instances of same type can work together

Project Workflow:

1. Requirements discovery with Product Owner agent
2. Architecture spike (PO + BA + Architect brainstorm)
3. Implementation planning and backlog creation
4. Autonomous sprint execution with checkpoints
5. Demo and client feedback

Autonomy Levels:

• FULL_CONTROL: Approve every action
• MILESTONE: Approve sprint boundaries
• AUTONOMOUS: Only major decisions

MCP-First Architecture: All integrations via Model Context Protocol servers with explicit scoping:

# All tools take project_id for scoping
search_knowledge(project_id="proj-123", query="auth flow")
create_issue(project_id="proj-123", title="Add login")

Directory Structure

docs/
├── development/    # Workflow and coding standards
├── requirements/   # Requirements documents
├── architecture/   # Architecture documentation
├── adrs/          # Architecture Decision Records
└── spikes/        # Spike research documents

Current Phase

Backlog Population - Creating detailed issues for Phase 0-1 implementation.

---

Development Standards

CRITICAL: These rules are mandatory. See linked docs for full details.

Quick Reference

Topic	Documentation
Workflow & Branching	docs/development/WORKFLOW.md
Coding Standards	docs/development/CODING_STANDARDS.md
Design System	frontend/docs/design-system/
Backend E2E Testing	backend/docs/E2E_TESTING.md
Demo Mode	frontend/docs/DEMO_MODE.md

Essential Rules Summary

1. Issue-Driven Development: Every piece of work MUST have an issue first
2. Branch per Feature: feature/<issue-number>-<description>, single branch for design+implementation
3. Testing Required: All code must be tested, aim for >90% coverage
4. Code Review: Must pass multi-agent review before merge
5. No Direct Commits: Never commit directly to main or dev
6. Stack Verification: ALWAYS run the full stack before considering work done (see below)

CRITICAL: Stack Verification Before Merge

This is NON-NEGOTIABLE. A feature with 100% test coverage that crashes on startup is WORTHLESS.

Before considering ANY issue complete:

# 1. Start the dev stack
make dev

# 2. Wait for backend to be healthy, check logs
docker compose -f docker-compose.dev.yml logs backend --tail=100

# 3. Start frontend
cd frontend && npm run dev

# 4. Verify both are running without errors

The issue is NOT done if:

• Backend crashes on startup (import errors, missing dependencies)
• Frontend fails to compile or render
• Health checks fail
• Any error appears in logs

Why this matters:

• Tests run in isolation and may pass despite broken imports
• Docker builds cache layers and may hide dependency issues
• A single ModuleNotFoundError renders all test coverage meaningless

Common Commands

# Backend
IS_TEST=True uv run pytest          # Run tests
uv run ruff check src/              # Lint
uv run mypy src/                    # Type check
python migrate.py auto "message"    # Database migration

# Frontend
npm test                            # Unit tests
npm run lint                        # Lint
npm run type-check                  # Type check
npm run generate:api                # Regenerate API client

---

Claude Code-Specific Guidance

Critical User Preferences

File Operations:

• ALWAYS use Read/Write/Edit tools instead of cat >> file << EOF
• Never use heredoc - it triggers manual approval dialogs

Work Style:

• User prefers autonomous operation without frequent interruptions
• Ask for batch permissions upfront for long work sessions
• Work independently, document decisions clearly
• Only use emojis if the user explicitly requests it

Critical Pattern: Auth Store DI

ALWAYS use useAuth() from AuthContext, NEVER import useAuthStore directly!

// ❌ WRONG
import { useAuthStore } from '@/lib/stores/authStore';

// ✅ CORRECT
import { useAuth } from '@/lib/auth/AuthContext';

See CODING_STANDARDS.md for details.

Tool Usage Preferences

Prefer specialized tools over bash:

• Use Read/Write/Edit tools for file operations
• Use Task tool with subagent_type=Explore for codebase exploration
• Use Grep tool for code search, not bash grep

Parallel tool calls for:

• Independent git commands
• Reading multiple unrelated files
• Running multiple test suites
• Independent validation steps

---

Key Extensions (from PragmaStack base)

• Celery + Redis for agent job queue
• WebSocket/SSE for real-time updates
• pgvector for RAG knowledge base
• MCP server integration layer

---

Additional Resources

Documentation:

• AGENTS.md - Framework-agnostic AI assistant context
• README.md - User-facing project overview
• docs/development/ - Development workflow and standards
• backend/docs/ - Backend architecture and guides
• frontend/docs/design-system/ - Complete design system

API Documentation (when running):

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/api/v1/openapi.json

---

For project architecture, development commands, and general context, see AGENTS.md.