## How to Use

Type `/autodev` to start or continue the full workflow. The orchestrator detects where your project is and picks up from there.

```
/autodev              — start a new project or continue where you left off
```

If you want to run a specific skill directly (without the orchestrator), use the individual commands:

```
/problem                — interactive problem gathering → _docs/00_problem/
/research               — solution drafts → _docs/01_solution/
/plan                   — architecture, ADRs, components, tests, epics → _docs/02_document/
/test-spec              — blackbox/perf/resilience/security test specs → _docs/02_document/tests/
/decompose              — atomic task specs (multi-mode) → _docs/02_tasks/todo/
/implement              — sequential dependency-aware batches with code review and completeness gates → _docs/03_implementation/
/test-run               — runs the test suite (functional / perf modes) with gating
/code-review            — multi-phase review used by /implement
/refactor               — 8-phase structured refactoring (incl. testability sub-mode) → _docs/04_refactoring/
/security               — OWASP-driven audit → _docs/05_security/
/deploy                 — containerization, CI/CD, environments, observability, procedures, scripts → _docs/04_deploy/
/release                — execute deploy artifacts in prod, smoke-test, watch, decide rollback → _docs/04_release/
/document               — bottom-up reverse-engineering of an existing codebase → _docs/02_document/
/new-task               — interactive feature planning for an existing codebase → _docs/02_tasks/todo/
/ui-design              — HTML+CSS mockups + design system → _docs/02_document/ui_mockups/
/retrospective          — metrics + lessons log → _docs/06_metrics/ + _docs/LESSONS.md
```

## How It Works

The autodev is a state machine that persists its state to `_docs/_autodev_state.md`. On every invocation it reads the state file, cross-checks against the `_docs/` folder structure, shows a status summary with context from prior sessions, and continues execution.

```
/autodev invoked
    │
    ▼
Read _docs/_autodev_state.md → cross-check _docs/ folders
    │
    ▼
Show status summary (progress, key decisions, last session context)
    │
    ▼
Execute current skill (read its SKILL.md, follow its workflow)
    │
    ▼
Update state file → auto-chain to next skill → loop
```

The state file tracks completed steps, key decisions, blockers, and session context. This makes re-entry across conversations seamless — the autodev knows not just where you are, but what decisions were made and why.

Skills auto-chain without pausing between them. The only pauses are:
- **BLOCKING gates** inside each skill (user must confirm before proceeding)
- **Session boundaries** declared in each flow's auto-chain rules (e.g., after `decompose`, after `decompose tests`) — suggested new-conversation breakpoints to keep context fresh

There are three flows, resolved on every invocation (see `skills/autodev/SKILL.md` § Flow Resolution):

| Flow | When | Steps |
|------|------|-------|
| **greenfield** | empty workspace, no source yet | 17 steps: Problem → Research → Plan → UI Design → Test Spec → Decompose → Implement → Code Testability Revision → Decompose Tests → Implement Tests → Run Tests → Test-Spec Sync → Update Docs → Security Audit (opt) → Performance Test (opt) → Deploy → Release → Retrospective |
| **existing-code** | source files present | one-time baseline (Document → Architecture Baseline Scan → Test Spec → Code Testability Revision → Decompose Tests → Implement Tests → Run Tests → optional Refactor) then a feature-cycle loop (New Task → Implement → Run Tests → Test-Spec Sync → Update Docs → Security Audit (opt) → Performance Test (opt) → Deploy → Release → Retrospective → loops back to New Task) |
| **meta-repo** | `.gitmodules`, workspace manifest, or multi-component aggregator | uses `monorepo-*` skills + `_docs/_repo-config.yaml` instead of per-component BUILD-SHIP folders |

A typical greenfield project spans several conversations because of session boundaries. Re-entry is seamless: type `/autodev` in a new conversation and the orchestrator reads `_docs/_autodev_state.md` to pick up exactly where you left off.

## Skill Descriptions

### autodev (meta-orchestrator)

Auto-chaining engine that sequences the full BUILD → SHIP → EVOLVE workflow. Persists state to `_docs/_autodev_state.md`, surfaces top-3 lessons from `_docs/LESSONS.md` at every invocation, replays any `_docs/_process_leftovers/` entries, tracks key decisions and session context, and flows through the active flow's steps without manual skill invocation. Maximizes work per conversation with seamless cross-session re-entry.

### problem

Interactive 4-phase interview that builds `_docs/00_problem/`. Asks probing questions across 8 dimensions (problem & goals, scope, hardware & environment, software & tech, acceptance criteria, input data, security, operational) until all required files can be written with concrete, measurable, quantifiable content. Acceptance criteria must include numeric targets; input data must include `expected_results/` mappings.

### research

8-step deep research methodology. Mode A produces initial solution drafts. Mode B assesses and revises existing drafts. Classifies output as **Technical-component selection** (full per-mode API verification gates apply) or **Non-technical investigation** (gates relaxed). Source tiering, fact extraction, comparison frameworks, validation, exact-fit component selection. Run multiple rounds until the solution is solid.

### plan

6-step planning workflow with one half-step (4.5: Architecture Decision Records). Produces blackbox test specs (delegated to test-spec), glossary, architecture vision, architecture document, data model, deployment plan, component specs with interfaces, risk assessment, ADRs, test specifications, and work item epics. Heavy interaction at BLOCKING gates (glossary+vision, architecture, components, mitigations, ADRs).

### test-spec

4-phase test specification workflow. Phase 1 analyzes input data + expected-results completeness. Phase 2 emits 8 test artifacts (environment, test-data, blackbox, performance, resilience, security, resource-limit, traceability matrix). Phase 3 is the hard gate that requires every test to have quantifiable expected results. Phase 4 emits runner scripts. Cycle-update mode for incremental refresh.

### decompose

Multi-mode task decomposition with 6 internal step files. Implementation mode runs Step 1 (Bootstrap), 1.5 (Module Layout), 1.7 (System-Pipeline owner tasks), 2 (per-component tasks), 4 (Cross-Verification). Tests-only mode runs Step 1t (Test Infrastructure), 3 (Blackbox tasks), 4. Single-component mode runs Step 2 only. Each task is tracker-prefixed and capped at 5 complexity points. The 1.7 step exists specifically to prevent the GPS-passthrough class of failure (see `meta-rule.mdc`).

### implement

Orchestrator that reads task specs, computes dependency-aware execution batches via topological sort, **implements tasks sequentially within each batch** (no subagents, no parallel execution — see `.cursor/rules/no-subagents.mdc`), runs code review after each batch, runs cumulative code review every K batches, and commits per batch. Has a Product Implementation Completeness Gate (Step 15) that compares promises in task specs / architecture against actual production code, plus a System-Pipeline Audit (Step 15.b) that walks architecture-named pipelines and verifies a real production caller wires each adjacent component pair. Either gate's FAIL stops the cycle until remediation tasks are created.

### code-review

7-phase code review against task specs (Phase 7 is Architecture Compliance against `module-layout.md` and `architecture.md`). Produces structured findings with verdict: PASS, PASS_WITH_WARNINGS, or FAIL. Three modes: full (per batch), baseline (one-time architecture scan of an existing codebase), cumulative (mid-implementation across batches with `## Baseline Delta`).

### test-run

Runs the test suite. Functional mode (default): detects pytest/dotnet/cargo/npm or `scripts/run-tests.sh`, applies a System-Under-Test Reality Gate to refuse passes where internal product modules were stubbed, classifies failures and skips, gates on outcome. Perf mode: detects `scripts/run-performance-tests.sh` or k6/locust/artillery/wrk, captures latency/throughput/error metrics, compares against thresholds.

### refactor

8-phase structured refactoring: baseline → discovery → analysis → safety net → execution → test sync → verification → documentation. Two input modes (Automatic / Guided). Testability sub-mode skips Phase 3 by design and emits a `testability_changes_summary.md` for user review. Each run lives in its own `RUN_DIR` under `_docs/04_refactoring/NN-<run-name>/`.

### security

5-phase OWASP-based audit: dependency scan → static analysis → OWASP Top 10 review → infrastructure review → consolidated security report. Severity-ranked, evidence-based, actionable. Complementary to `code-review` Phase 4 (lightweight security quick-scan).

### deploy

7-step deployment planning. Produces documents for steps 1–6 (status & env, containerization, CI/CD pipeline, environment strategy, observability, deployment procedures) and executable scripts in step 7 (`deploy.sh`, `pull-images.sh`, `start-services.sh`, `stop-services.sh`, `health-check.sh`).

### release

Executes the deployment plan produced by `/deploy` against a target environment. 6 phases: pre-release gate (AC + risk + rollback readiness), strategy select (all-at-once / blue-green / canary / manual), execute (run scripts, monitor exit codes), smoke test (delegate to test-run prod-smoke), watch window (read observability for the configured duration), commit-or-rollback. Outputs `_docs/04_release/release_<version>.md`. Produces a definitive Released / Rolled-Back / Aborted verdict; failure of any phase auto-triggers rollback unless the user opts to investigate.

### retrospective

4-step workflow: collect metrics → analyze trends → produce report → update lessons log (`_docs/LESSONS.md`, ring buffer of last 15 entries consumed by `new-task`, `plan`, `decompose`, and `autodev`). Cycle-end (default) and incident modes; incident mode is auto-invoked after a 3-strike failure.

### document

Bottom-up codebase documentation. Analyzes existing code from modules through components to architecture, then retrospectively derives problem/restrictions/acceptance criteria. Alternative entry point for existing codebases — produces the same `_docs/` artifacts as problem + plan, but from code analysis instead of user interview. Two workflow files: `workflows/full.md` (full / focus-area / resume) and `workflows/task.md` (incremental update for a single task).

### new-task

Existing-code feature planning loop. Walks the user through Step 1 (description) → Step 2 (complexity assessment, consults `LESSONS.md`) → Step 3 (research if needed) → Step 4 (codebase analysis incl. test-coverage gap) → Step 4.5 (contract & layout check) → Step 5 (validate assumptions) → Step 6 (write task spec) → Step 7 (tracker ticket) → Step 8 (loop or finalize).

### ui-design

End-to-end UI workflow. Phase 0 (complexity detection: full vs quick) → Phase 1 (context check) → Phase 2 (requirements) → Phase 3 (direction exploration) → Phase 4 (design system synthesis: `DESIGN.md`) → Phase 5 (HTML+Tailwind code generation) → Phase 6 (visual verification, optional MCP enhancements) → Phase 7 (user review) → Phase 8 (iteration). Has Applicability Check that refuses to run on non-UI projects.

### monorepo-* (suite-level)

Six skills for meta-repos: `monorepo-discover` (write/refresh `_docs/_repo-config.yaml`), `monorepo-document` (sync unified docs), `monorepo-cicd` (sync CI/compose/env templates), `monorepo-onboard` (atomic add-component), `monorepo-status` (read-only drift report), `monorepo-e2e` (sync suite-level integration harness). They never cross domains; each touches exactly one artifact class.

## Developer TODO (Project Mode)

The numbered list below mirrors greenfield-flow ordering. Existing-code projects start at `/document`, then enter the feature-cycle loop at `/new-task`. See `skills/autodev/flows/{greenfield,existing-code,meta-repo}.md` for the authoritative step tables.

### BUILD (greenfield)

```
1. /problem            — interactive 4-phase interview → _docs/00_problem/
                          required: problem.md, restrictions.md, acceptance_criteria.md, input_data/
                          optional: security_approach.md
2. /research           — solution drafts (Mode A draft, Mode B assess) → _docs/01_solution/
3. /plan               — glossary, architecture vision, architecture, data model, deployment, components,
                          risks, ADRs (Step 4.5), test specs, epics → _docs/02_document/
                          (Step 1 invokes /test-spec internally)
4. /ui-design          — HTML+Tailwind mockups (UI projects only) → _docs/02_document/ui_mockups/
5. /test-spec          — produces 8 test-spec artifacts + traceability matrix → _docs/02_document/tests/
                          (already invoked from /plan Step 1; Step 5 here is the explicit autodev step)
6. /decompose          — implementation tasks + module-layout + system-pipeline owner tasks →
                          _docs/02_tasks/todo/
7. /implement          — sequential dependency-aware batches; per-batch code-review;
                          Product Completeness Gate + System-Pipeline Audit → _docs/03_implementation/
8. (auto) Code Testability Revision  — surgical refactor to make code runnable under tests
9. /decompose tests    — test-only decomposition mode → _docs/02_tasks/todo/
10. /implement (tests) — implements test tasks
11. /test-run          — full functional suite gate
12. /test-spec --cycle-update  — append implementation-learned scenarios
13. /document --task   — update affected component / module / architecture docs
14. /security          — OWASP-based audit (optional gate)
15. /test-run --perf   — perf/load tests (optional gate)
```

### SHIP

```
16. /deploy            — containerization, CI/CD, environments, observability, procedures, scripts → _docs/04_deploy/
17. /release           — execute deploy artifacts in prod, smoke-test, watch, decide rollback → _docs/04_release/
```

### EVOLVE

```
18. /retrospective     — metrics + trends + lessons-log update → _docs/06_metrics/ + _docs/LESSONS.md
       (cycle-end mode after release; incident mode auto-fires after 3-strike failure)

After greenfield completes, the state file is rewritten to point at the existing-code flow's
feature-cycle loop, which begins with /new-task and ends with /retrospective. The loop runs once
per feature with state.cycle incremented.

Off-cycle:
/refactor              — full 8-phase refactor → _docs/04_refactoring/NN-<run-name>/
/document              — full reverse-engineering of an unfamiliar codebase
```

Or just use `/autodev` to run all the above automatically — the orchestrator chooses the right flow, sequences steps, surfaces lessons, processes leftovers, and pauses only at BLOCKING gates and declared session boundaries.

## Available Skills

| Skill | Triggers | Output |
|-------|----------|--------|
| **autodev** | "autodev", "auto", "start", "continue", "what's next" | Orchestrates full workflow (3 flows) |
| **problem** | "problem", "define problem", "new project" | `_docs/00_problem/` |
| **research** | "research", "investigate" | `_docs/01_solution/` |
| **plan** | "plan", "decompose solution" | `_docs/02_document/` (incl. ADRs) |
| **test-spec** | "test spec", "blackbox tests", "test scenarios" | `_docs/02_document/tests/` + `scripts/` |
| **decompose** | "decompose", "task decomposition", "decompose tests" | `_docs/02_tasks/todo/` + `_docs/02_document/module-layout.md` |
| **implement** | "implement", "start implementation" | `_docs/03_implementation/` (sequential — see `no-subagents.mdc`) |
| **test-run** | "run tests", "test suite", "verify tests", "perf test" | Test results + verdict |
| **code-review** | "code review", "review code" | Verdict: PASS / FAIL / PASS_WITH_WARNINGS (7 phases) |
| **new-task** | "new task", "add feature", "new functionality" | `_docs/02_tasks/todo/` |
| **ui-design** | "design a UI", "mockup", "design system" | `_docs/02_document/ui_mockups/` |
| **refactor** | "refactor", "improve code", "testability" | `_docs/04_refactoring/NN-<run-name>/` |
| **security** | "security audit", "OWASP", "vulnerability scan" | `_docs/05_security/` |
| **document** | "document", "document codebase", "reverse-engineer docs" | `_docs/02_document/` + `_docs/00_problem/` + `_docs/01_solution/` |
| **deploy** | "deploy", "CI/CD", "observability", "containerize" | `_docs/04_deploy/` (plans + scripts) |
| **release** | "release", "ship", "go live", "rollback" | `_docs/04_release/` (executed deploy + verdict) |
| **retrospective** | "retrospective", "retro", "metrics review" | `_docs/06_metrics/` + `_docs/LESSONS.md` |
| **monorepo-discover** | "discover monorepo", "scan submodules" | `_docs/_repo-config.yaml` |
| **monorepo-document** | "sync monorepo docs" | unified `_docs/*.md` |
| **monorepo-cicd** | "sync compose", "sync ci" | suite-level CI/compose/env templates |
| **monorepo-onboard** | "onboard component", "register submodule" | atomic component addition |
| **monorepo-status** | "monorepo status", "drift report" | read-only drift report |
| **monorepo-e2e** | "suite e2e", "integration harness" | `e2e/docker-compose.suite-e2e.yml` and fixtures |

> The `.cursor/agents/` directory is intentionally empty. Per `.cursor/rules/no-subagents.mdc` the main agent does not delegate to subagents in this workspace; `/implement` runs tasks sequentially.

## Project Folder Structure

```
_docs/
├── _autodev_state.md                   — autodev orchestrator state (≤30 lines; pointer only)
├── _process_leftovers/                  — deferred tracker writes replayed at next /autodev (per tracker.mdc)
├── _repo-config.yaml                    — meta-repo only; produced by monorepo-discover
├── LESSONS.md                           — ring buffer of last 15 actionable lessons (consumed by autodev/new-task/plan/decompose)
├── 00_problem/                          — problem definition, restrictions, AC, input data + expected_results/
├── 00_research/                         — intermediate research artifacts
├── 01_solution/                         — solution drafts, tech stack, security analysis
├── 02_document/
│   ├── architecture.md                 — includes ## Architecture Vision (user-confirmed)
│   ├── glossary.md                     — user-confirmed terminology
│   ├── system-flows.md
│   ├── data_model.md
│   ├── module-layout.md                — per-component Owns/Imports-from/Public API (decompose Step 1.5)
│   ├── architecture_compliance_baseline.md  — existing-code baseline scan output
│   ├── risk_mitigations.md
│   ├── adr/[NNN]_[decision_slug].md    — Architectural Decision Records (plan Step 4.5)
│   ├── components/[##]_[name]/          — description.md + tests.md per component
│   ├── contracts/<component>/<name>.md  — versioned public-API contracts
│   ├── common-helpers/
│   ├── tests/                           — environment, test-data, blackbox, performance, resilience, security, resource-limit, traceability matrix
│   ├── ui_mockups/                      — HTML+CSS mockups, DESIGN.md (ui-design skill)
│   ├── diagrams/
│   └── FINAL_report.md
├── 02_tasks/                            — task lifecycle folders + _dependencies_table.md
│   ├── _dependencies_table.md
│   ├── todo/                            — tasks ready for implementation
│   ├── backlog/                         — parked tasks (not scheduled yet)
│   └── done/                            — completed/archived tasks
├── 02_task_plans/                       — per-task research artifacts (new-task skill)
├── 03_implementation/                   — batch_*_cycle*.md, implementation_report_*.md, implementation_completeness_cycle*.md, cumulative_review_*.md
│   └── reviews/                         — code review reports per batch
├── 04_deploy/                           — containerization, CI/CD, environments, observability, procedures, deploy_scripts.md, reports/
├── 04_refactoring/NN-<run-name>/        — baseline_metrics, discovery, analysis, test_specs, execution_log, test_sync, verification, FINAL_report (one folder per refactor run)
├── 04_release/                          — release_<version>.md (one per /release invocation), rollback_<version>.md
├── 05_security/                         — dependency_scan, static_analysis, owasp_review, infrastructure_review, security_report
└── 06_metrics/                          — retro_<YYYY-MM-DD>.md, structure_<YYYY-MM-DD>.md, perf_<YYYY-MM-DD>_<run-label>.md, incident_<YYYY-MM-DD>_<skill>.md
```

## Standalone Mode

`research` and `refactor` support standalone mode — output goes to `_standalone/` (git-ignored):

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

## Single Component Mode (Decompose)

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

Appends tasks for that component to `_docs/02_tasks/todo/` without running bootstrap or cross-verification.