cardosofelipe/syndarix
1
0
Fork 0
forked from cardosofelipe/fast-next-template
Code Issues 18 Pull Requests Wiki Activity

docs: extract coding standards and add workflow documentation

Browse Source 
- Create docs/development/WORKFLOW.md with branch strategy, issue
  management, testing requirements, and code review process
- Create docs/development/CODING_STANDARDS.md with technical patterns,
  auth DI pattern, testing patterns, and security guidelines
- Streamline CLAUDE.md to link to detailed documentation instead of
  embedding all content
- Add branch/issue workflow rules: single branch per feature for both
  design and implementation phases

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Felipe Cardoso
2026-01-01 11:46:09 +01:00
parent f3fb4ecbeb
commit a7ba0f9bd8
3 changed files with 623 additions and 304 deletions
Download Patch File Download Diff File Expand all files Collapse all files

387
CLAUDE.md
View File

@@ -9,9 +9,11 @@ Claude Code context for **Syndarix** - AI-Powered Software Consulting Agency.
## 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
@@ -43,9 +45,11 @@ search_knowledge(project_id="proj-123", query="auth flow")
create_issue(project_id="proj-123", title="Add login")
```
### Syndarix-Specific Directories
### Directory Structure
```
docs/
├── development/ # Workflow and coding standards
├── requirements/ # Requirements documents
├── architecture/ # Architecture documentation
├── adrs/ # Architecture Decision Records
@@ -53,97 +57,96 @@ docs/
```
### Current Phase
**Backlog Population** - Creating detailed issues for Phase 0-1 implementation.
---
## Development Workflow & Standards
## Development Standards
**CRITICAL: These rules are mandatory for all development work.**
**CRITICAL: These rules are mandatory. See linked docs for full details.**
### 1. Issue-Driven Development
### Quick Reference
**Every piece of work MUST have an issue in the Gitea tracker first.**
| 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) |
- Issue tracker: https://gitea.pragmazest.com/cardosofelipe/syndarix/issues
- Create detailed, well-scoped issues before starting work
- Structure issues to enable parallel work by multiple agents
- Reference issues in commits and PRs
### Essential Rules Summary
### 2. Git Hygiene
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`
**Branch naming convention:** `feature/123-description`
### Common Commands
- Every issue gets its own feature branch
- No direct commits to `main` or `dev`
- Keep branches focused and small
- Delete branches after merge
```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
**Workflow:**
# Frontend
npm test # Unit tests
npm run lint # Lint
npm run type-check # Type check
npm run generate:api # Regenerate API client
```
main (production-ready)
└── dev (integration branch)
└── feature/123-description (issue branch)
```
### 3. Testing Requirements
**All code must be tested. No exceptions.**
- **TDD preferred**: Write tests first when possible
- **Test after**: If not TDD, write tests immediately after testable code
- **Coverage types**: Unit, integration, functional, E2E as appropriate
- **Minimum coverage**: Aim for >90% on new code
### 4. Code Review Process
**Before merging any feature branch, code must pass multi-agent review:**
| Check | Description |
|-------|-------------|
| Bug hunting | Logic errors, edge cases, race conditions |
| Linting | `ruff check` passes with no errors |
| Typing | `mypy` passes with no errors |
| Formatting | Code follows style guidelines |
| Performance | No obvious bottlenecks or N+1 queries |
| Security | No vulnerabilities (OWASP top 10) |
| Architecture | Follows established patterns and ADRs |
**Issue is NOT done until review passes with flying colors.**
### 5. QA Before Main
**Before merging `dev` into `main`:**
- Full test suite passes
- Manual QA verification
- Performance baseline check
- Security scan
- Code must be clean, functional, bug-free, well-architected, and secure
### 6. Implementation Plan Updates
- Keep `docs/architecture/IMPLEMENTATION_ROADMAP.md` updated
- Mark completed items as work progresses
- Add new items discovered during implementation
### 7. UI/UX Design Approval
**Frontend tasks involving UI/UX require design approval:**
1. **Design Issue**: Create issue with `design` label
2. **Prototype**: Build interactive React prototype (navigable demo)
3. **Review**: User inspects and provides feedback
4. **Approval**: User approves before implementation begins
5. **Implementation**: Follow approved design, respecting design system
**Design constraints:**
- Prototypes: Best effort to match design system (not required)
- Production code: MUST follow `frontend/docs/design-system/` strictly
---
### Key Extensions to Add (from PragmaStack base)
## 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
@@ -151,244 +154,20 @@ main (production-ready)
---
## PragmaStack Development Guidelines
*The following guidelines are inherited from PragmaStack and remain applicable.*
## Claude Code-Specific Guidance
### Critical User Preferences
#### File Operations - NEVER Use Heredoc/Cat Append
**ALWAYS use Read/Write/Edit tools instead of `cat >> file << EOF` commands.**
This triggers manual approval dialogs and disrupts workflow.
```bash
# WRONG ❌
cat >> file.txt << EOF
content
EOF
# CORRECT ✅ - Use Read, then Write tools
```
#### 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
### When Working with This Stack
**Dependency Management:**
- Backend uses **uv** (modern Python package manager), not pip
- Always use `uv run` prefix: `IS_TEST=True uv run pytest`
- Or use Makefile commands: `make test`, `make install-dev`
- Add dependencies: `uv add <package>` or `uv add --dev <package>`
**Database Migrations:**
- Use the `migrate.py` helper script, not Alembic directly
- Generate + apply: `python migrate.py auto "message"`
- Never commit migrations without testing them first
- Check current state: `python migrate.py current`
**Frontend API Client Generation:**
- Run `npm run generate:api` after backend schema changes
- Client is auto-generated from OpenAPI spec
- Located in `frontend/src/lib/api/generated/`
- NEVER manually edit generated files
**Testing Commands:**
- Backend unit/integration: `IS_TEST=True uv run pytest` (always prefix with `IS_TEST=True`)
- Backend E2E (requires Docker): `make test-e2e`
- Frontend unit: `npm test`
- Frontend E2E: `npm run test:e2e`
- Use `make test` or `make test-cov` in backend for convenience
**Backend E2E Testing (requires Docker):**
- Install deps: `make install-e2e`
- Run all E2E tests: `make test-e2e`
- Run schema tests only: `make test-e2e-schema`
- Run all tests: `make test-all` (unit + E2E)
- Uses Testcontainers (real PostgreSQL) + Schemathesis (OpenAPI contract testing)
- Markers: `@pytest.mark.e2e`, `@pytest.mark.postgres`, `@pytest.mark.schemathesis`
- See: `backend/docs/E2E_TESTING.md` for complete guide
### 🔴 CRITICAL: Auth Store Dependency Injection Pattern
**ALWAYS use `useAuth()` from `AuthContext`, NEVER import `useAuthStore` directly!**
```typescript
// ❌ WRONG - Bypasses dependency injection
import { useAuthStore } from '@/lib/stores/authStore';
const { user, isAuthenticated } = useAuthStore();
// ✅ CORRECT - Uses dependency injection
import { useAuth } from '@/lib/auth/AuthContext';
const { user, isAuthenticated } = useAuth();
```
**Why This Matters:**
- E2E tests inject mock stores via `window.__TEST_AUTH_STORE__`
- Unit tests inject via `<AuthProvider store={mockStore}>`
- Direct `useAuthStore` imports bypass this injection → **tests fail**
- ESLint will catch violations (added Nov 2025)
**Exceptions:**
1. `AuthContext.tsx` - DI boundary, legitimately needs real store
2. `client.ts` - Non-React context, uses dynamic import + `__TEST_AUTH_STORE__` check
### E2E Test Best Practices
When writing or fixing Playwright tests:
**Navigation Pattern:**
```typescript
// ✅ CORRECT - Use Promise.all for Next.js Link clicks
await Promise.all([
page.waitForURL('/target', { timeout: 10000 }),
link.click()
]);
```
**Selectors:**
- Use ID-based selectors for validation errors: `#email-error`
- Error IDs use dashes not underscores: `#new-password-error`
- Target `.border-destructive[role="alert"]` to avoid Next.js route announcer conflicts
- Avoid generic `[role="alert"]` which matches multiple elements
**URL Assertions:**
```typescript
// ✅ Use regex to handle query params
await expect(page).toHaveURL(/\/auth\/login/);
// ❌ Don't use exact strings (fails with query params)
await expect(page).toHaveURL('/auth/login');
```
**Configuration:**
- Uses 12 workers in non-CI mode (`playwright.config.ts`)
- Reduces to 2 workers in CI for stability
- Tests are designed to be non-flaky with proper waits
### Important Implementation Details
**Authentication Testing:**
- Backend fixtures in `tests/conftest.py`:
- `async_test_db`: Fresh SQLite per test
- `async_test_user` / `async_test_superuser`: Pre-created users
- `user_token` / `superuser_token`: Access tokens for API calls
- Always use `@pytest.mark.asyncio` for async tests
- Use `@pytest_asyncio.fixture` for async fixtures
**Database Testing:**
```python
# Mock database exceptions correctly
from unittest.mock import patch, AsyncMock
async def mock_commit():
raise OperationalError("Connection lost", {}, Exception())
with patch.object(session, 'commit', side_effect=mock_commit):
with patch.object(session, 'rollback', new_callable=AsyncMock) as mock_rollback:
with pytest.raises(OperationalError):
await crud_method(session, obj_in=data)
mock_rollback.assert_called_once()
```
**Frontend Component Development:**
- Follow design system docs in `frontend/docs/design-system/`
- Read `08-ai-guidelines.md` for AI code generation rules
- Use parent-controlled spacing (see `04-spacing-philosophy.md`)
- WCAG AA compliance required (see `07-accessibility.md`)
**Security Considerations:**
- Backend has comprehensive security tests (JWT attacks, session hijacking)
- Never skip security headers in production
- Rate limiting is configured in route decorators: `@limiter.limit("10/minute")`
- Session revocation is database-backed, not just JWT expiry
### Common Workflows Guidance
**When Adding a New Feature:**
1. Start with backend schema and CRUD
2. Implement API route with proper authorization
3. Write backend tests (aim for >90% coverage)
4. Generate frontend API client: `npm run generate:api`
5. Implement frontend components
6. Write frontend unit tests
7. Add E2E tests for critical flows
8. Update relevant documentation
**When Fixing Tests:**
- Backend: Check test database isolation and async fixture usage
- Frontend unit: Verify mocking of `useAuth()` not `useAuthStore`
- E2E: Use `Promise.all()` pattern and regex URL assertions
**When Debugging:**
- Backend: Check `IS_TEST=True` environment variable is set
- Frontend: Run `npm run type-check` first
- E2E: Use `npm run test:e2e:debug` for step-by-step debugging
- Check logs: Backend has detailed error logging
**Demo Mode (Frontend-Only Showcase):**
- Enable: `echo "NEXT_PUBLIC_DEMO_MODE=true" > frontend/.env.local`
- Uses MSW (Mock Service Worker) to intercept API calls in browser
- Zero backend required - perfect for Vercel deployments
- **Fully Automated**: MSW handlers auto-generated from OpenAPI spec
- Run `npm run generate:api` → updates both API client AND MSW handlers
- No manual synchronization needed!
- Demo credentials (any password ≥8 chars works):
- User: `demo@example.com` / `DemoPass123`
- Admin: `admin@example.com` / `AdminPass123`
- **Safe**: MSW never runs during tests (Jest or Playwright)
- **Coverage**: Mock files excluded from linting and coverage
- **Documentation**: `frontend/docs/DEMO_MODE.md` for complete guide
### Tool Usage Preferences
**Prefer specialized tools over bash:**
- Use Read/Write/Edit tools for file operations
- Never use `cat`, `echo >`, or heredoc for file manipulation
- Use Task tool with `subagent_type=Explore` for codebase exploration
- Use Grep tool for code search, not bash `grep`
**When to use parallel tool calls:**
- Independent git commands: `git status`, `git diff`, `git log`
- Reading multiple unrelated files
- Running multiple test suites simultaneously
- Independent validation steps
## Custom Skills
No Claude Code Skills installed yet. To create one, invoke the built-in "skill-creator" skill.
**Potential skill ideas for this project:**
- API endpoint generator workflow (schema → CRUD → route → tests → frontend client)
- Component generator with design system compliance
- Database migration troubleshooting helper
- Test coverage analyzer and improvement suggester
- E2E test generator for new features
## Additional Resources
**Comprehensive Documentation:**
**Documentation:**
- [AGENTS.md](./AGENTS.md) - Framework-agnostic AI assistant context
- [README.md](./README.md) - User-facing project overview
- `backend/docs/` - Backend architecture, coding standards, common pitfalls
- `frontend/docs/design-system/` - Complete design system guide
- [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
**Testing Documentation:**
- Backend tests: `backend/tests/` (97% coverage)
- Frontend E2E: `frontend/e2e/README.md`
- Design system: `frontend/docs/design-system/08-ai-guidelines.md`
---
**For project architecture, development commands, and general context, see [AGENTS.md](./AGENTS.md).**

312
docs/development/CODING_STANDARDS.md Normal file
View File

@@ -0,0 +1,312 @@
# Coding Standards
Technical coding standards and patterns for Syndarix development.
## Table of Contents
- [Backend Standards](#backend-standards)
- [Frontend Standards](#frontend-standards)
- [Testing Patterns](#testing-patterns)
- [Security Guidelines](#security-guidelines)
---
## Backend Standards
### Dependency Management
- Use **uv** (modern Python package manager), not pip
- Always use `uv run` prefix for commands
- Add dependencies: `uv add <package>` or `uv add --dev <package>`
```bash
# Running tests
IS_TEST=True uv run pytest
# Or use Makefile
make test
make install-dev
```
### Database Migrations
- Use the `migrate.py` helper script, not Alembic directly
- Never commit migrations without testing them first
```bash
# Generate and apply migration
python migrate.py auto "message"
# Check current state
python migrate.py current
```
### Authentication Testing Fixtures
Backend fixtures in `tests/conftest.py`:
| Fixture | Purpose |
|---------|---------|
| `async_test_db` | Fresh SQLite per test |
| `async_test_user` | Pre-created regular user |
| `async_test_superuser` | Pre-created admin user |
| `user_token` | Access token for regular user |
| `superuser_token` | Access token for admin |
```python
# Always use these decorators for async tests
@pytest.mark.asyncio
async def test_something():
pass
# Use for async fixtures
@pytest_asyncio.fixture
async def my_fixture():
pass
```
### Database Exception Mocking
```python
from unittest.mock import patch, AsyncMock
async def mock_commit():
raise OperationalError("Connection lost", {}, Exception())
with patch.object(session, 'commit', side_effect=mock_commit):
with patch.object(session, 'rollback', new_callable=AsyncMock) as mock_rollback:
with pytest.raises(OperationalError):
await crud_method(session, obj_in=data)
mock_rollback.assert_called_once()
```
### Security Considerations
- Backend has comprehensive security tests (JWT attacks, session hijacking)
- Never skip security headers in production
- Rate limiting: `@limiter.limit("10/minute")`
- Session revocation is database-backed, not just JWT expiry
---
## Frontend Standards
### Auth Store Dependency Injection
**CRITICAL: ALWAYS use `useAuth()` from `AuthContext`, NEVER import `useAuthStore` directly!**
```typescript
// ❌ WRONG - Bypasses dependency injection
import { useAuthStore } from '@/lib/stores/authStore';
const { user, isAuthenticated } = useAuthStore();
// ✅ CORRECT - Uses dependency injection
import { useAuth } from '@/lib/auth/AuthContext';
const { user, isAuthenticated } = useAuth();
```
**Why This Matters:**
- E2E tests inject mock stores via `window.__TEST_AUTH_STORE__`
- Unit tests inject via `<AuthProvider store={mockStore}>`
- Direct `useAuthStore` imports bypass this injection → **tests fail**
- ESLint will catch violations
**Exceptions:**
1. `AuthContext.tsx` - DI boundary, legitimately needs real store
2. `client.ts` - Non-React context, uses dynamic import + `__TEST_AUTH_STORE__` check
### API Client Generation
```bash
# After backend schema changes
npm run generate:api
```
- Client is auto-generated from OpenAPI spec
- Located in `frontend/src/lib/api/generated/`
- **NEVER manually edit generated files**
### Component Development
- Follow design system docs in `frontend/docs/design-system/`
- Read `08-ai-guidelines.md` for AI code generation rules
- Use parent-controlled spacing (see `04-spacing-philosophy.md`)
- WCAG AA compliance required (see `07-accessibility.md`)
### Route Groups Structure
```
src/app/[locale]/
├── (auth)/ # Public auth pages (login, register, password reset)
│ # Uses AuthLayoutClient - redirects authenticated users
├── (authenticated)/ # Protected app pages
│ # Uses AuthGuard + Header/Footer
├── admin/ # Admin pages with sidebar
│ # Uses AuthGuard requireAdmin
├── dev/ # Design system documentation
└── prototypes/ # UI prototypes for approval
```
---
## Testing Patterns
### Frontend Unit Tests
```typescript
// Mock useAuth correctly
jest.mock('@/lib/auth/AuthContext', () => ({
useAuth: () => ({
user: { id: '1', email: 'test@example.com' },
isAuthenticated: true,
}),
}));
```
### E2E Test Best Practices (Playwright)
**Navigation Pattern:**
```typescript
// ✅ CORRECT - Use Promise.all for Next.js Link clicks
await Promise.all([
page.waitForURL('/target', { timeout: 10000 }),
link.click()
]);
```
**Selectors:**
- Use ID-based selectors for validation errors: `#email-error`
- Error IDs use dashes not underscores: `#new-password-error`
- Target `.border-destructive[role="alert"]` to avoid Next.js route announcer conflicts
- Avoid generic `[role="alert"]` which matches multiple elements
**URL Assertions:**
```typescript
// ✅ Use regex to handle query params
await expect(page).toHaveURL(/\/auth\/login/);
// ❌ Don't use exact strings (fails with query params)
await expect(page).toHaveURL('/auth/login');
```
**Configuration:**
- Uses 12 workers in non-CI mode
- Reduces to 2 workers in CI for stability
### Backend E2E Testing
Requires Docker for Testcontainers.
```bash
# Install deps
make install-e2e
# Run all E2E tests
make test-e2e
# Run schema tests only
make test-e2e-schema
# Run all tests (unit + E2E)
make test-all
```
Uses:
- Testcontainers (real PostgreSQL)
- Schemathesis (OpenAPI contract testing)
Markers:
- `@pytest.mark.e2e`
- `@pytest.mark.postgres`
- `@pytest.mark.schemathesis`
See: `backend/docs/E2E_TESTING.md` for complete guide.
---
## Security Guidelines
### OWASP Top 10 Compliance
All code must be reviewed for:
- Injection vulnerabilities (SQL, command, XSS)
- Broken authentication
- Sensitive data exposure
- Security misconfiguration
- Insecure deserialization
### Rate Limiting
```python
from app.core.limiter import limiter
@router.post("/endpoint")
@limiter.limit("10/minute")
async def endpoint():
pass
```
### JWT Security
- Tokens stored securely (httpOnly cookies preferred)
- Short expiration times
- Refresh token rotation
- Database-backed session revocation
---
## Common Workflows
### Adding a New Feature
1. Start with backend schema and CRUD
2. Implement API route with proper authorization
3. Write backend tests (aim for >90% coverage)
4. Generate frontend API client: `npm run generate:api`
5. Implement frontend components
6. Write frontend unit tests
7. Add E2E tests for critical flows
8. Update relevant documentation
### Fixing Tests
| Layer | Check |
|-------|-------|
| Backend | Test database isolation, async fixture usage |
| Frontend unit | Mock `useAuth()` not `useAuthStore` |
| E2E | Use `Promise.all()` pattern, regex URL assertions |
### Debugging
| Layer | Action |
|-------|--------|
| Backend | Check `IS_TEST=True` environment variable |
| Frontend | Run `npm run type-check` first |
| E2E | Use `npm run test:e2e:debug` for step-by-step |
| All | Check logs - backend has detailed error logging |
---
## Demo Mode
Frontend-only showcase mode for demos without backend.
```bash
# Enable
echo "NEXT_PUBLIC_DEMO_MODE=true" > frontend/.env.local
```
- Uses MSW (Mock Service Worker) to intercept API calls
- Zero backend required - perfect for Vercel deployments
- MSW handlers auto-generated from OpenAPI spec
- Run `npm run generate:api` → updates both API client AND MSW handlers
**Demo Credentials:**
- User: `demo@example.com` / `DemoPass123`
- Admin: `admin@example.com` / `AdminPass123`
**Safety:**
- MSW never runs during tests (Jest or Playwright)
- Mock files excluded from linting and coverage
See: `frontend/docs/DEMO_MODE.md` for complete guide.

228
docs/development/WORKFLOW.md Normal file
View File

@@ -0,0 +1,228 @@
# Development Workflow
This document defines the development workflow, branching strategy, and issue management rules for Syndarix.
## Issue-Driven Development
**Every piece of work MUST have an issue in the Gitea tracker first.**
- Issue tracker: https://gitea.pragmazest.com/cardosofelipe/syndarix/issues
- Create detailed, well-scoped issues before starting work
- Structure issues to enable parallel work by multiple agents
- Reference issues in commits and PRs
---
## Git Branching Strategy
### Branch Naming Convention
```
feature/<issue-number>-<short-description>
```
Examples:
- `feature/123-user-authentication`
- `feature/456-project-dashboard`
### Branch Workflow
```
main (production-ready)
└── dev (integration branch)
└── feature/123-description (issue branch)
```
### Rules
1. **Every issue gets its own feature branch**
2. **No direct commits to `main` or `dev`**
3. **Keep branches focused and small**
4. **Delete branches after merge**
5. **All branches must be mergeable to dev** - if work isn't ready to merge, keep it in a separate branch
---
## Issue and Branch Structure for Features
### Single Branch per Feature
For UI/UX features that require both design and implementation:
1. **Create a single feature branch** for both design prototype and implementation
2. **Do NOT create separate branches** for design vs implementation
### Issue Structure Options
Choose one of these approaches based on complexity:
#### Option A: Single Issue with Tasks (Recommended for most features)
```markdown
## Issue: Add User Profile Page (#123)
### Tasks
- [ ] Design: Create interactive prototype in /prototypes
- [ ] Design: Get user approval on the design
- [ ] Implementation: Build page following design system
- [ ] Implementation: Write tests
- [ ] Cleanup: Remove prototype after implementation
```
Branch: `feature/123-user-profile-page`
#### Option B: User Story with Sub-Issues (For complex features)
```markdown
## User Story: Project Management (#100)
├── Sub-issue: Design project dashboard (#101)
├── Sub-issue: Implement project dashboard (#102)
├── Sub-issue: Design project settings (#103)
└── Sub-issue: Implement project settings (#104)
```
Branch: `feature/100-project-management` (single branch for the entire user story)
**Important:** Even with multiple sub-issues, use a **single branch** for the user story.
---
## UI/UX Design Workflow
### For New UI Features
1. **Create Issue**: Use `design` label
2. **Build Prototype**: Create in `/frontend/src/app/[locale]/prototypes/<feature>/`
3. **User Review**: Get feedback on the prototype
4. **Approval**: User approves design before implementation
5. **Implementation**: Build in production location following design system
6. **Cleanup**: Remove prototype after implementation
### Design Guidelines
| Phase | Requirements |
|-------|-------------|
| **Prototype** | Best effort to match design system (not required) |
| **Production** | MUST follow `frontend/docs/design-system/` strictly |
---
## Testing Requirements
**All code must be tested. No exceptions.**
### Testing Approach
- **TDD preferred**: Write tests first when possible
- **Test after**: If not TDD, write tests immediately after testable code
- **Coverage types**: Unit, integration, functional, E2E as appropriate
- **Minimum coverage**: Aim for >90% on new code
### Testing Commands
```bash
# Backend
IS_TEST=True uv run pytest # Unit/integration tests
make test-e2e # E2E tests (requires Docker)
# Frontend
npm test # Unit tests
npm run test:e2e # E2E tests
```
---
## Code Review Process
**Before merging any feature branch, code must pass multi-agent review:**
| Check | Description |
|-------|-------------|
| Bug hunting | Logic errors, edge cases, race conditions |
| Linting | `ruff check` / `eslint` passes with no errors |
| Typing | `mypy` / `tsc --noEmit` passes with no errors |
| Formatting | Code follows style guidelines |
| Performance | No obvious bottlenecks or N+1 queries |
| Security | No vulnerabilities (OWASP top 10) |
| Architecture | Follows established patterns and ADRs |
**Issue is NOT done until review passes with flying colors.**
---
## QA Before Main
**Before merging `dev` into `main`:**
- [ ] Full test suite passes
- [ ] Manual QA verification
- [ ] Performance baseline check
- [ ] Security scan
- [ ] Code must be clean, functional, bug-free, well-architected, and secure
---
## Commit Message Format
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Formatting, missing semicolons, etc.
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `test`: Adding missing tests
- `chore`: Maintenance tasks
### Examples
```
feat(auth): add password reset functionality
fix(api): handle null response in user endpoint
docs(readme): update installation instructions
test(frontend): add unit tests for ProjectDashboard
```
---
## Pull Request Process
1. **Create PR from feature branch to dev**
2. **PR title**: Same format as commit messages
3. **PR body**: Include summary, test plan, and issue reference
4. **Wait for CI**: All checks must pass
5. **Code review**: Address all feedback
6. **Merge**: Squash and merge when approved
7. **Cleanup**: Delete feature branch after merge
---
## Documentation Updates
- Keep `docs/architecture/IMPLEMENTATION_ROADMAP.md` updated
- Mark completed items as work progresses
- Add new items discovered during implementation
- Update ADRs when architectural decisions change
---
## Quick Reference
| Action | Command/Location |
|--------|-----------------|
| Create branch | `git checkout -b feature/<issue>-<desc>` |
| Run backend tests | `IS_TEST=True uv run pytest` |
| Run frontend tests | `npm test` |
| Check types (backend) | `uv run mypy src/` |
| Check types (frontend) | `npm run type-check` |
| Lint (backend) | `uv run ruff check src/` |
| Lint (frontend) | `npm run lint` |
| Generate API client | `npm run generate:api` |