Update deployment skill documentation to reflect new 7-step workflow and directory structure. Enhance README with detailed usage instructions for the autopilot feature and clarify skill descriptions. Adjust paths for deployment templates to align with the updated documentation structure.

2026-04-22 09:16:38 +00:00 · 2026-03-19 17:05:59 +02:00
parent 05411d19b8
commit f70d701979
10 changed files with 921 additions and 50 deletions
@@ -1,42 +1,149 @@
+## 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_plans/
+/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.
+
+### rollback
+
+Reverts implementation to a specific batch checkpoint using git revert, verifies integrity.
+
 ## Developer TODO (Project Mode)

 ### BUILD

 ```
-1. Create _docs/00_problem/                      — describe what you're building
+0. /problem                                      — interactive interview → _docs/00_problem/
   - problem.md                                   (required)
   - restrictions.md                              (required)
   - acceptance_criteria.md                       (required)
   - input_data/                                  (required)
   - security_approach.md                         (optional)

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

-3. /plan                                         — architecture, data model, deployment, components, risks, tests, Jira epics → _docs/02_plans/
+2. /plan                                         — architecture, data model, deployment, components, risks, tests, Jira epics → _docs/02_plans/

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

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

 ### SHIP

 ```
-6. /deploy                                       — containerization, CI/CD, environments, observability, procedures → _docs/02_plans/deployment/
+5. /deploy                                       — containerization, CI/CD, environments, observability, procedures → _docs/04_deploy/
 ```

 ### EVOLVE

 ```
-7. /refactor                                     — structured refactoring → _docs/04_refactoring/
-8. /retrospective                                — metrics, trends, improvement actions → _docs/05_metrics/
+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_plans/` |
 | **decompose** | "decompose", "task decomposition" | `_docs/02_tasks/` |
@@ -44,7 +151,7 @@
 | **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 |
-| **deploy** | "deploy", "CI/CD", "observability" | `_docs/02_plans/deployment/` |
+| **deploy** | "deploy", "CI/CD", "observability" | `_docs/04_deploy/` |
 | **retrospective** | "retrospective", "retro" | `_docs/05_metrics/` |
 | **rollback** | "rollback", "revert batch" | `_docs/03_implementation/rollback_report.md` |

@@ -58,6 +165,7 @@

 ```
 _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
@@ -74,6 +182,7 @@ _docs/
 │   └── FINAL_report.md
 ├── 02_tasks/                            — [JIRA-ID]_[name].md + _dependencies_table.md
 ├── 03_implementation/                   — batch reports, rollback report, 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
 ```