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

---

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