## Developer TODO (Project Mode)

### BUILD (green-field or new features)

```
1. Create _docs/00_problem/                      — describe what you're building
   - problem.md                                   (required)
   - restrictions.md                              (required)
   - acceptance_criteria.md                       (required)
   - security_approach.md                         (optional)

2. /research                                     — produces solution drafts in _docs/01_solution/
   Run multiple times: Mode A → draft, Mode B → assess & revise
   Finalize as solution.md

3. /plan                                         — architecture, components, risks, tests → _docs/02_plans/

4. /decompose                                    — feature specs, implementation order → _docs/02_tasks/

5. /implement-initial                            — scaffold project from initial_structure.md (once)

6. /implement-wave                               — implement next wave of features (repeat per wave)

7. /implement-code-review                        — review implemented code (after each wave or at the end)

8. /implement-black-box-tests                    — E2E tests via Docker consumer app (after all waves)

9. commit & push
```

### SHIP (deploy and operate)

```
10. /implement-cicd                              — validate/enhance CI/CD pipeline
11. /deploy                                      — deployment strategy per environment
12. /observability                               — monitoring, logging, alerting plan
```

### EVOLVE (maintenance and improvement)

```
13. /refactor                                    — structured refactoring (skill, 6-phase workflow)
```

## Implementation Flow

### `/implement-initial`

Reads `_docs/02_tasks/<topic>/initial_structure.md` and scaffolds the project skeleton: folder structure, shared models, interfaces, stubs, .gitignore, .env.example, CI/CD config, DB migrations setup, test structure.

Run once after decompose.

### `/implement-wave`

Reads `SUMMARY.md` and `cross_dependencies.md` from `_docs/02_tasks/<topic>/`.

1. Detects which features are already implemented
2. Identifies the next wave (phase) of independent features
3. Presents the wave for confirmation (blocks until user confirms)
4. Launches parallel `implementer` subagents (max 4 concurrent; same-component features run sequentially)
5. Runs tests, reports results
6. Suggests commit

Repeat `/implement-wave` until all phases are done.

### `/implement-code-review`

Reviews implemented code against specs. Reports issues by type (Bug/Security/Performance/Style/Debt) with priorities and suggested fixes.

### `/implement-black-box-tests`

Reads `_docs/02_plans/<topic>/e2e_test_infrastructure.md` (produced by plan skill). Builds a separate Docker-based consumer app that exercises the system as a black box — no internal imports, no direct DB access. Runs E2E scenarios, produces a CSV test report.

Run after all waves are done.

### `/implement-cicd`

Reviews existing CI/CD pipeline configuration, validates all stages work, optimizes performance (parallelization, caching), ensures quality gates are enforced (coverage, linting, security scanning).

Run after `/implement-initial` or after all waves.

### `/deploy`

Defines deployment strategy per environment: deployment procedures, rollback procedures, health checks, deployment checklist. Outputs `_docs/02_components/deployment_strategy.md`.

Run before first production release.

### `/observability`

Plans logging strategy, metrics collection, distributed tracing, alerting rules, and dashboards. Outputs `_docs/02_components/observability_plan.md`.

Run before first production release.

### Commit

After each wave or review — standard `git add && git commit`. The wave command suggests a commit message.

## Available Skills

| Skill | Triggers | Purpose |
|-------|----------|---------|
| **research** | "research", "investigate", "assess solution" | 8-step research → solution drafts |
| **plan** | "plan", "decompose solution" | Architecture, components, risks, tests, epics |
| **decompose** | "decompose", "task decomposition" | Feature specs + implementation order |
| **refactor** | "refactor", "refactoring", "improve code" | 6-phase structured refactoring workflow |
| **security** | "security audit", "OWASP" | OWASP-based security testing |

## Project Folder Structure

```
_docs/
├── 00_problem/
│   ├── problem.md
│   ├── restrictions.md
│   ├── acceptance_criteria.md
│   └── security_approach.md
├── 01_solution/
│   ├── solution_draft01.md
│   ├── solution_draft02.md
│   ├── solution.md
│   ├── tech_stack.md
│   └── security_analysis.md
├── 01_research/
│   └── <topic>/
├── 02_plans/
│   └── <topic>/
│       ├── architecture.md
│       ├── system-flows.md
│       ├── components/
│       └── FINAL_report.md
├── 02_tasks/
│   └── <topic>/
│       ├── initial_structure.md
│       ├── cross_dependencies.md
│       ├── SUMMARY.md
│       └── [##]_[component]/
│           └── [##].[##]_feature_[name].md
└── 04_refactoring/
    ├── baseline_metrics.md
    ├── discovery/
    ├── analysis/
    ├── test_specs/
    ├── coupling_analysis.md
    ├── execution_log.md
    ├── hardening/
    └── FINAL_report.md
```

## Implementation Tools

| Tool | Type | Purpose |
|------|------|---------|
| `implementer` | Subagent | Implements a single feature from its spec. Launched by implement-wave. |
| `/implement-initial` | Command | Scaffolds project skeleton from `initial_structure.md`. Run once. |
| `/implement-wave` | Command | Detects next wave, launches parallel implementers. Repeatable. |
| `/implement-code-review` | Command | Reviews code against specs. |
| `/implement-black-box-tests` | Command | E2E tests via Docker consumer app. After all waves. |
| `/implement-cicd` | Command | Validate and enhance CI/CD pipeline. |
| `/deploy` | Command | Plan deployment strategy per environment. |
| `/observability` | Command | Plan logging, metrics, tracing, alerting. |

## Standalone Mode (Reference)

Any skill can run in standalone mode by passing an explicit file:

```
/research @my_problem.md
/plan @my_design.md
/decompose @some_spec.md
/refactor @some_component.md
```

Output goes to `_standalone/<topic>/` (git-ignored) instead of `_docs/`. Standalone mode relaxes guardrails — only the provided file is required; restrictions and acceptance criteria are optional.

Single component decompose is also supported:

```
/decompose @_docs/02_plans/<topic>/components/03_parser/description.md
```
