syndarix/docs/development/WORKFLOW.md

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)

## 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)

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

# 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

---

Rigorous Implementation Workflow

This workflow applies to ALL feature implementations. Follow this process rigorously:

1. Branch Setup

# Create feature branch from dev
git checkout dev && git pull
git checkout -b feature/<issue-number>-<description>

2. Planning Phase

• Read the issue thoroughly, understand ALL sub-tasks
• Identify components and their dependencies
• Determine if multi-agent parallel execution is appropriate
• Create a detailed execution plan before writing any code

3. Implementation with Continuous Testing

After EACH sub-task:

• Run unit tests for the component
• Run integration tests if applicable
• Verify type checking passes
• Verify linting passes
• Keep coverage high (aim for >90%)

Both modules must be tested:

• Backend: IS_TEST=True uv run pytest + E2E tests
• Frontend: npm test + E2E tests (if applicable)

4. Multi-Agent Review (MANDATORY before considering done)

Before closing an issue, perform deep review from multiple angles:

Review Type	Focus Areas
Code Quality	Logic errors, edge cases, race conditions, error handling
Security	OWASP Top 10, input validation, authentication, authorization
Performance	N+1 queries, memory leaks, inefficient algorithms
Architecture	Pattern adherence, separation of concerns, extensibility
Testing	Coverage completeness, test quality, edge case coverage
Documentation	Code comments, README, API docs, usage examples

No stone unturned. No sloppy results. No unreviewed work.

5. Stack Verification (CRITICAL - NON-NEGOTIABLE)

ALWAYS run the full stack and verify it boots correctly before considering ANY work done.

# Start the full development stack
make dev

# Check backend logs for startup errors
docker compose -f docker-compose.dev.yml logs backend --tail=100

# Start frontend separately
cd frontend && npm run dev

# Check frontend console for errors

A feature is NOT complete if:

• The stack doesn't boot
• There are import errors in logs
• Health checks fail
• Any component crashes on startup

This rule exists because:

• Tests can pass but the application won't start (import errors, missing deps)
• 90% test coverage is worthless if the app crashes on boot
• Docker builds can mask local issues

6. Final Validation Checklist

• All tests pass (unit, integration, E2E)
• Type checking passes
• Linting passes
• Stack boots successfully (backend + frontend)
• Logs show no errors
• Coverage meets threshold (>90% backend, >90% frontend)
• Documentation updated
• Issue checklist 100% complete
• Multi-agent review passed

When to Use Parallel Agents

Use multiple agents working in parallel when:

• Sub-tasks are independent (no shared state/dependencies)
• Different expertise areas (backend vs frontend)
• Time-critical deliveries with clear boundaries

Do NOT use parallel agents when:

• Tasks share state or have dependencies
• Sequential testing is required
• Integration points need careful coordination

---

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