## Developer TODO (Project Mode)

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

```
1. Create _docs/00_problem/                      — describe what you're building, restrictions, acceptance criteria and samples of data system works with
   - problem.md                                   (required)
   - restrictions.md                              (required)
   - acceptance_criteria.md                       (required)
   - input_data                                   (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, Jira epics → _docs/02_plans/

4. /decompose                                    — flat numbered task specs + _dependencies_table.md → _docs/02_tasks/

5. /implement                                    — auto-orchestrates all tasks: batches by dependencies, launches parallel implementers, runs code review, loops until done

6. commit & push
```

### SHIP (deploy and operate)

```
7. /deploy                                       — containerization, CI/CD, environment strategy, observability, deployment procedures (skill, 5-step workflow)
```

### EVOLVE (maintenance and improvement)

```
8. /refactor                                     — structured refactoring (skill, 6-phase workflow)
9. /retrospective                                — collect metrics, analyze trends, produce improvement report (skill)
```

## Implementation Flow

### `/implement`

Reads flat task files and `_dependencies_table.md` from `_docs/02_tasks/`.

1. Parses dependency graph, detects which tasks are already completed
2. Computes next batch of tasks (max 4 parallel, respecting dependencies)
3. Assigns file ownership per agent to prevent conflicts
4. Launches `implementer` subagents in parallel immediately
5. Runs `/code-review` skill on the batch's changes
6. If review FAIL — blocks for user confirmation; otherwise continues
7. Runs tests, commits and pushes to remote
8. Loops until all tasks are done

### `/code-review`

Multi-phase code review invoked after each implementation batch:

1. Context loading — reads task specs to understand intent
2. Spec compliance — verifies each acceptance criterion is satisfied
3. Code quality — SOLID, DRY, KISS, error handling, naming, complexity
4. Security quick-scan — injection, secrets, input validation
5. Performance scan — O(n^2), N+1, unbounded fetches
6. Cross-task consistency — interface compatibility across batch

Produces structured findings with severity (Critical/High/Medium/Low) and verdict (PASS/FAIL/PASS_WITH_WARNINGS).

### `/deploy`

Comprehensive deployment skill (5-step workflow):

1. Containerization — Dockerfiles per component, docker-compose for dev and tests
2. CI/CD Pipeline — lint, test, security scan, build, deploy with quality gates
3. Environment Strategy — dev, staging, production with secrets management
4. Observability — structured logging, metrics, tracing, alerting, dashboards
5. Deployment Procedures — rollback, health checks, graceful shutdown

Outputs to `_docs/02_plans/deployment/`. Run after `/implement` or before first production release.

### `/retrospective`

Collects metrics from batch reports and code review findings, analyzes trends across implementation cycles, and produces improvement reports. Outputs to `_docs/05_metrics/`.

### `/rollback`

Reverts implementation to a specific batch checkpoint using git revert, resets Jira ticket statuses, and verifies rollback integrity with tests.

### Commit

After each confirmed batch, the `/implement` skill automatically commits and pushes to the remote branch.

## 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" | Flat numbered task specs + dependency table |
| **implement** | "implement", "start implementation" | Orchestrate task batches with parallel agents |
| **code-review** | "code review", "review code" | 6-phase structured review with findings |
| **refactor** | "refactor", "refactoring", "improve code" | 6-phase structured refactoring workflow |
| **security** | "security audit", "OWASP" | OWASP-based security testing |
| **deploy** | "deploy", "CI/CD", "containerize", "observability" | Containerization, CI/CD, observability, deployment procedures |
| **retrospective** | "retrospective", "retro", "metrics review" | Collect metrics, analyze trends, produce improvement report |

## Project Folder Structure

```
_docs/
├── 00_problem/
│   ├── problem.md
│   ├── restrictions.md
│   ├── acceptance_criteria.md
│   ├── input_data/
│   └── security_approach.md
├── 00_research/
│   ├── 00_ac_assessment.md
│   ├── 00_question_decomposition.md
│   ├── 01_source_registry.md
│   ├── 02_fact_cards.md
│   ├── 03_comparison_framework.md
│   ├── 04_reasoning_chain.md
│   └── 05_validation_log.md
├── 01_solution/
│   ├── solution_draft01.md
│   ├── solution_draft02.md
│   ├── solution.md
│   ├── tech_stack.md
│   └── security_analysis.md
├── 02_plans/
│   ├── architecture.md
│   ├── system-flows.md
│   ├── data_model.md
│   ├── risk_mitigations.md
│   ├── components/
│   │   └── [##]_[name]/
│   │       ├── description.md
│   │       └── tests.md
│   ├── common-helpers/
│   ├── integration_tests/
│   │   ├── environment.md
│   │   ├── test_data.md
│   │   ├── functional_tests.md
│   │   ├── non_functional_tests.md
│   │   └── traceability_matrix.md
│   ├── deployment/
│   │   ├── containerization.md
│   │   ├── ci_cd_pipeline.md
│   │   ├── environment_strategy.md
│   │   ├── observability.md
│   │   └── deployment_procedures.md
│   ├── diagrams/
│   └── FINAL_report.md
├── 02_tasks/
│   ├── [JIRA-ID]_initial_structure.md
│   ├── [JIRA-ID]_[short_name].md
│   ├── ...
│   └── _dependencies_table.md
├── 03_implementation/
│   ├── batch_01_report.md
│   ├── batch_02_report.md
│   ├── ...
│   └── FINAL_implementation_report.md
├── 04_refactoring/
│   ├── baseline_metrics.md
│   ├── discovery/
│   ├── analysis/
│   ├── test_specs/
│   ├── coupling_analysis.md
│   ├── execution_log.md
│   ├── hardening/
│   └── FINAL_report.md
└── 05_metrics/
    └── retro_[date].md
```

## Implementation Tools

| Tool | Type | Purpose |
|------|------|---------|
| `implementer` | Subagent | Implements a single task from its spec. Launched by /implement. |
| `/implement` | Skill | Orchestrates all tasks: dependency batching, parallel agents, code review. |
| `/code-review` | Skill | Multi-phase code review with structured findings. |
| `/deploy` | Skill | Containerization, CI/CD, observability, deployment procedures. |
| `/retrospective` | Skill | Collect metrics, analyze trends, produce improvement reports. |
| `/rollback` | Command | Revert to a batch checkpoint with Jira status reset. |

## Automations (Planned)

Future automations to explore (Cursor Automations, launched March 2026):
- PR review: trigger code-review skill on PR open (start with Bugbot — read-only, comments only)
- Security scan: trigger security skill on push to main/dev
- Nightly: run integration tests on schedule

Status: experimental — validate with Bugbot first before adding write-heavy automations.

## Standalone Mode (Reference)

Only `research` and `refactor` support standalone mode by passing an explicit file:

```
/research @my_problem.md
/refactor @some_component.md
```

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

## Single Component Mode (Decompose)

Decompose supports single component mode when given a component file from within `_docs/02_plans/components/`:

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

This appends tasks for that component to the existing `_docs/02_tasks/` directory without running bootstrap or cross-verification steps.