mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 08:51:12 +00:00
Oleksandr Bezdieniezhnykh
6044a33197
Bundled hygiene commit before cycle-3 /implement (AZ-776, AZ-777). Mixes two concerns by user choice (autodev option B): - Cycle-3 autodev artifacts not yet committed by Step 9 (new-task): task specs for AZ-776 / AZ-777 under _docs/02_tasks/todo/ and the updated _docs/02_tasks/_dependencies_table.md. - Accumulated skill / rule tooling maintenance under .cursor/ (skills: autodev, code-review, decompose, deploy, implement, new-task, plan, refactor, retrospective, test-spec; rules: coderule, cursor-meta, meta-rule, testing; new release skill scaffolding). - Autodev bootstrap state: _docs/_autodev_state.md (step 10 in_progress) and _docs/_process_leftovers/2026-05-11_d_cross_cve_1_opencv_pin_deferred.md (replay timestamp refreshed; gtsam 4.2 still numpy<2-only). Co-authored-by: Cursor <cursoragent@cursor.com>
283 lines
22 KiB
Markdown
283 lines
22 KiB
Markdown
## 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.
|