# Development Workflow

## Core Principles

1. **plan.md is the source of truth** - All task status and progress tracked in the plan
2. **Test-Driven Development** - Red → Green → Refactor cycle with 80% coverage target
3. **CI/CD Compatibility** - All changes must pass automated pipelines before merge
4. **Incremental Progress** - Small, verifiable commits with clear purpose

## Task Lifecycle

### Step 1: Task Selection

- Review plan.md for next pending task
- Verify dependencies are complete
- Confirm understanding of acceptance criteria

### Step 2: Progress Marking

- Update task status in plan.md from `[ ]` to `[~]`
- Note start time if tracking velocity

### Step 3: Red Phase (Write Failing Tests)

- Write test(s) that define expected behavior
- Verify test fails for the right reason
- Keep tests focused and minimal

### Step 4: Green Phase (Make Tests Pass)

- Write minimum code to pass tests
- Avoid premature optimization
- Focus on correctness over elegance

### Step 5: Refactor Phase

- Improve code structure without changing behavior
- Apply relevant style guide conventions
- Remove duplication and clarify intent

### Step 6: Coverage Verification

- Run coverage report
- Ensure new code meets 80% threshold
- Add edge case tests if coverage gaps exist

### Step 7: Deviation Documentation

- If implementation differs from spec, document why
- Update spec if change is permanent
- Flag for review if uncertain

### Step 8: Code Commit

- Stage related changes only
- Write clear commit message referencing task
- Format: `[track-id] task: description`

### Step 9: Git Notes (Optional)

- Add implementation notes for complex changes
- Reference relevant decisions or trade-offs

### Step 10: Plan Update

- Mark task as `[x]` completed in plan.md
- Update any affected downstream tasks
- Note blockers or follow-up items

### Step 11: Plan Commit

- Commit plan.md changes separately
- Format: `[track-id] plan: mark task X complete`

## Phase Completion Protocol

### Checkpoint Commits

At the end of each phase:

1. Ensure all phase tasks are `[x]` complete
2. Run full test suite
3. Verify coverage meets threshold
4. Create checkpoint commit: `[track-id] checkpoint: phase N complete`

### Test Verification

```bash
{{TEST_COMMAND}}
{{COVERAGE_COMMAND}}
```

### Manual Approval Gates

Phases requiring approval before proceeding:

- Architecture changes
- API contract modifications
- Database schema changes
- Security-sensitive implementations

## Quality Assurance Gates

All code must pass these criteria before merge:

| Gate        | Requirement              | Command                  |
| ----------- | ------------------------ | ------------------------ |
| 1. Tests    | All tests passing        | `{{TEST_COMMAND}}`       |
| 2. Coverage | Minimum 80%              | `{{COVERAGE_COMMAND}}`   |
| 3. Style    | Follows style guide      | `{{LINT_COMMAND}}`       |
| 4. Docs     | Public APIs documented   | Manual review            |
| 5. Types    | No type errors           | `{{TYPE_CHECK_COMMAND}}` |
| 6. Linting  | No lint errors           | `{{LINT_COMMAND}}`       |
| 7. Mobile   | Responsive if applicable | Manual review            |
| 8. Security | No known vulnerabilities | `{{SECURITY_COMMAND}}`   |

## Development Commands

### Environment Setup

```bash
{{SETUP_COMMAND}}
```

### Development Server

```bash
{{DEV_COMMAND}}
```

### Pre-Commit Checks

```bash
{{PRE_COMMIT_COMMAND}}
```

### Full Validation

```bash
{{VALIDATE_COMMAND}}
```

## Workflow Diagram

```
┌─────────────┐
│ Select Task │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Mark [~]    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ RED: Write  │
│ Failing Test│
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ GREEN: Make │
│ Test Pass   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ REFACTOR    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Verify      │
│ Coverage    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Commit Code │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Mark [x]    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Commit Plan │
└─────────────┘
```