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)

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

---

## Pre-Commit Hooks

The repository includes pre-commit hooks that enforce validation before commits on protected branches.

### Setup

Enable the hooks by configuring git to use the `.githooks` directory:

```bash
git config core.hooksPath .githooks
```

This only needs to be done once per clone.

### What the Hooks Do

When committing to **protected branches** (`main`, `dev`):

| Condition | Action |
|-----------|--------|
| Backend files changed | Runs `make validate` in `/backend` |
| Frontend files changed | Runs `npm run validate` in `/frontend` |
| No relevant changes | Skips validation |

If validation fails, the commit is blocked with an error message.

When committing to **feature branches**:
- Validation is skipped (allows WIP commits)
- A message reminds you to run validation manually if needed

### Why Protected Branches Only?

The hooks only enforce validation on `main` and `dev` for good reasons:

1. **Feature branches are for iteration** - WIP commits, experimentation, and rapid prototyping shouldn't be blocked
2. **Flexibility during development** - You can commit broken code to your feature branch while debugging
3. **PRs catch issues** - The merge process ensures validation passes before reaching protected branches
4. **Manual control** - You can always run `make validate` or `npm run validate` yourself

### Manual Validation

Even on feature branches, you should validate before creating a PR:

```bash
# Backend
cd backend && make validate

# Frontend
cd frontend && npm run validate
```

### Bypassing Hooks (Emergency Only)

In rare cases where you need to bypass the hook:

```bash
git commit --no-verify -m "message"
```

**Use sparingly** - this defeats the purpose of the hooks.

---

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

```bash
# 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>` |
| Enable pre-commit hooks | `git config core.hooksPath .githooks` |
| Run backend tests | `IS_TEST=True uv run pytest` |
| Run frontend tests | `npm test` |
| Backend validation | `cd backend && make validate` |
| Frontend validation | `cd frontend && npm run validate` |
| 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` |