admin/.cursor/README.md

## How to Use

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

```
/autopilot              — 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, components, tests → _docs/02_document/
/decompose              — atomic task specs → _docs/02_tasks/
/implement              — batched parallel implementation → _docs/03_implementation/
/deploy                 — containerization, CI/CD, observability → _docs/04_deploy/
```

## How It Works

The autopilot is a state machine that persists its state to `_docs/_autopilot_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.

```
/autopilot invoked
    │
    ▼
Read _docs/_autopilot_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 autopilot 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 boundary** after decompose (suggests new conversation before implement)

A typical project runs in 2-4 conversations:
- Session 1: Problem → Research → Research decision
- Session 2: Plan → Decompose
- Session 3: Implement (may span multiple sessions)
- Session 4: Deploy

Re-entry is seamless: type `/autopilot` in a new conversation and the orchestrator reads the state file to pick up exactly where you left off.

## Skill Descriptions

### autopilot (meta-orchestrator)

Auto-chaining engine that sequences the full BUILD → SHIP workflow. Persists state to `_docs/_autopilot_state.md`, tracks key decisions and session context, and flows through problem → research → plan → decompose → implement → deploy without manual skill invocation. Maximizes work per conversation with seamless cross-session re-entry.

### problem

Interactive interview that builds `_docs/00_problem/`. Asks probing questions across 8 dimensions (problem, scope, hardware, software, acceptance criteria, input data, security, operations) until all required files can be written with concrete, measurable content.

### research

8-step deep research methodology. Mode A produces initial solution drafts. Mode B assesses and revises existing drafts. Includes AC assessment, source tiering, fact extraction, comparison frameworks, and validation. Run multiple rounds until the solution is solid.

### plan

6-step planning workflow. Produces integration test specs, architecture, system flows, data model, deployment plan, component specs with interfaces, risk assessment, test specifications, and Jira epics. Heavy interaction at BLOCKING gates.

### decompose

4-step task decomposition. Produces a bootstrap structure plan, atomic task specs per component, integration test tasks, and a cross-task dependency table. Each task gets a Jira ticket and is capped at 5 complexity points.

### implement

Orchestrator that reads task specs, computes dependency-aware execution batches, launches up to 4 parallel implementer subagents, runs code review after each batch, and commits per batch. Does not write code itself.

### deploy

7-step deployment planning. Status check, containerization, CI/CD pipeline, environment strategy, observability, deployment procedures, and deployment scripts. Produces documents for steps 1-6 and executable scripts in step 7.

### code-review

Multi-phase code review against task specs. Produces structured findings with verdict: PASS, FAIL, or PASS_WITH_WARNINGS.

### refactor

6-phase structured refactoring: baseline, discovery, analysis, safety net, execution, hardening.

### security

OWASP-based security testing and audit.

### retrospective

Collects metrics from implementation batch reports, analyzes trends, produces improvement reports.

### 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.

## Developer TODO (Project Mode)

### BUILD

```
0. /problem                                      — interactive interview → _docs/00_problem/
   - problem.md                                   (required)
   - restrictions.md                              (required)
   - acceptance_criteria.md                       (required)
   - input_data/                                  (required)
   - security_approach.md                         (optional)

1. /research                                     — solution drafts → _docs/01_solution/
   Run multiple times: Mode A → draft, Mode B → assess & revise

2. /plan                                         — architecture, data model, deployment, components, risks, tests, Jira epics → _docs/02_document/

3. /decompose                                    — atomic task specs + dependency table → _docs/02_tasks/

4. /implement                                    — batched parallel agents, code review, commit per batch → _docs/03_implementation/
```

### SHIP

```
5. /deploy                                       — containerization, CI/CD, environments, observability, procedures → _docs/04_deploy/
```

### EVOLVE

```
6. /refactor                                     — structured refactoring → _docs/04_refactoring/
7. /retrospective                                — metrics, trends, improvement actions → _docs/05_metrics/
```

Or just use `/autopilot` to run steps 0-5 automatically.

## Available Skills

| Skill | Triggers | Output |
|-------|----------|--------|
| **autopilot** | "autopilot", "auto", "start", "continue", "what's next" | Orchestrates full workflow |
| **problem** | "problem", "define problem", "new project" | `_docs/00_problem/` |
| **research** | "research", "investigate" | `_docs/01_solution/` |
| **plan** | "plan", "decompose solution" | `_docs/02_document/` |
| **decompose** | "decompose", "task decomposition" | `_docs/02_tasks/` |
| **implement** | "implement", "start implementation" | `_docs/03_implementation/` |
| **code-review** | "code review", "review code" | Verdict: PASS / FAIL / PASS_WITH_WARNINGS |
| **refactor** | "refactor", "improve code" | `_docs/04_refactoring/` |
| **security** | "security audit", "OWASP" | Security findings report |
| **document** | "document", "document codebase", "reverse-engineer docs" | `_docs/02_document/` + `_docs/00_problem/` + `_docs/01_solution/` |
| **deploy** | "deploy", "CI/CD", "observability" | `_docs/04_deploy/` |
| **retrospective** | "retrospective", "retro" | `_docs/05_metrics/` |

## Tools

| Tool | Type | Purpose |
|------|------|---------|
| `implementer` | Subagent | Implements a single task. Launched by `/implement`. |

## Project Folder Structure

```
_docs/
├── _autopilot_state.md                  — autopilot orchestrator state (progress, decisions, session context)
├── 00_problem/                          — problem definition, restrictions, AC, input data
├── 00_research/                         — intermediate research artifacts
├── 01_solution/                         — solution drafts, tech stack, security analysis
├── 02_document/
│   ├── architecture.md
│   ├── system-flows.md
│   ├── data_model.md
│   ├── risk_mitigations.md
│   ├── components/[##]_[name]/          — description.md + tests.md per component
│   ├── common-helpers/
│   ├── integration_tests/               — environment, test data, functional, non-functional, traceability
│   ├── deployment/                      — containerization, CI/CD, environments, observability, procedures
│   ├── diagrams/
│   └── FINAL_report.md
├── 02_tasks/                            — [JIRA-ID]_[name].md + _dependencies_table.md
├── 03_implementation/                   — batch reports, FINAL report
├── 04_deploy/                           — containerization, CI/CD, environments, observability, procedures, scripts
├── 04_refactoring/                      — baseline, discovery, analysis, execution, hardening
└── 05_metrics/                          — retro_[YYYY-MM-DD].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/` without running bootstrap or cross-verification.