# CLAUDE.md

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

**Built on PragmaStack.** See [AGENTS.md](./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:
```python
# 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](./docs/development/WORKFLOW.md) |
| **Coding Standards** | [docs/development/CODING_STANDARDS.md](./docs/development/CODING_STANDARDS.md) |
| **Design System** | [frontend/docs/design-system/](./frontend/docs/design-system/) |
| **Backend E2E Testing** | [backend/docs/E2E_TESTING.md](./backend/docs/E2E_TESTING.md) |
| **Demo Mode** | [frontend/docs/DEMO_MODE.md](./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:

```bash
# 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

```bash
# 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!**

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

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

See [CODING_STANDARDS.md](./docs/development/CODING_STANDARDS.md#auth-store-dependency-injection) 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](./AGENTS.md) - Framework-agnostic AI assistant context
- [README.md](./README.md) - User-facing project overview
- [docs/development/](./docs/development/) - Development workflow and standards
- [backend/docs/](./backend/docs/) - Backend architecture and guides
- [frontend/docs/design-system/](./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](./AGENTS.md).**