forked from cardosofelipe/fast-next-template
Felipe Cardoso
e6e98d4ed1
- Added "Stack Verification" section to CLAUDE.md with detailed steps. - Updated WORKFLOW.md to mandate running the full stack before marking work as complete. - Prevents issues where high test coverage masks application startup failures.
205 lines
6.4 KiB
Markdown
205 lines
6.4 KiB
Markdown
# 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).**
|