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