annotations/.cursor/README.md

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