Windsurf rules

1---
2name: orchestrate-project
3model: sonnet
4description: "Meta-skill that enforces the 6-phase core loop (discover → elaborate → plan → build → verify → release) with hard gates. Use to coordinate multi-phase projects with guaranteed quality checkpoints. One-time command for the entire project lifecycle."
5---
6 
7# Orchestrate
8> **HARD GATE** — **HARD GATE** — Do NOT invoke orchestrate-project unless you have a clear multi-phase workflow. Single-skill tasks should use dedicated skills instead. Orchestrate is for complex, multi-stage work that requires coordination across phases.
9 
10 
11The orchestrate skill coordinates projects through a prescriptive 6-phase core loop with hard gates, ensuring consistent quality and preventing scope creep.
12 
13## Quick Start
14 
15```bash
16# Start a new project (initializes specs/ YAML cockpit and begins discover phase)
17claude /orchestrate --mode standard
18 
19# Or resume an existing project at the current phase
20claude /orchestrate --mode standard --resume
21 
22# For low-risk scenarios (hotfixes, refactors on well-tested code)
23claude /orchestrate --mode fast-track
24```
25 
26## The 6-Phase Core Loop
27 
281. **DISCOVER** (3-6 hours): Understand problem. Deliverables: `requirements/VISION_LATEST.yaml`, `requirements/SCOPE_LATEST.yaml`, `plans/TECH_STACK_LATEST.md`.
292. **ELABORATE** (3-6 hours): Research solutions. Deliverables: Prior art in scope YAML, ADRs in `specs/adr/`.
303. **PLAN** (2-4 hours): Write verifiable plan. Deliverables: `release-plan.yaml`, `epics/eNN-*.yaml` with `verify:` per task.
314. **BUILD** (1-8 hours): Execute plan. Runs build-epic once per story in WSJF order. Deliverables: Code; update `execution-status.yaml`.
325. **VERIFY** (1-3 hours): Validate success criteria. Deliverables: UAT evidence, `specs/EVALS-*.md` if used.
336. **RELEASE** (30 min - 2 hours): Ship to production. Deliverables: Release tag (vX.Y.Z), `state.yaml` `release.last_tag`.
34 
35### Checkpoint / resume
36 
37Track progress via `specs/state.yaml` `project_cycle`:
38- `project_cycle.current_phase`: current phase (1–6)
39- `project_cycle.completed_phases`: completed phase numbers
40- `handoff.next_skill`: skill for the current phase
41- On resume, read `project_cycle.current_phase` and continue from there
42 
43See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate types.
44 
45## How Orchestrate Works
46 
471. **Maintains state.yaml** — Tracks current phase, `active_epic`, `active_flow`, decisions, risks.
482. **Spawns appropriate skills** — Routes by `model:` frontmatter. Decisions pass only via `specs/state.yaml` `handoff` between spawns.
493. **Methodology lenses** — If `specs/tech-architecture/e*-TEST_PLAN_LATEST.md` or ADRs exist, apply at phase gates.
504. **Enforces gates** — Hard stops if success criteria not met.
515. **The Gatekeeper** — Between stories in BUILD: read `specs/execution-status.yaml`; previous story must be `done` before starting the next; use `build-epic` for the 8-step epic cycle.
526. **Pauses for confirmation** — After each phase, asks "Ready to proceed?".
537. **Snapshots** — `bash scripts/bp-yaml-snapshot.sh` before major release cuts.
54 
55## Orchestration Modes
56 
57- **Standard**: Enforce all gates. Use for new features and major refactors.
58- **Fast-Track**: Skip negotiable gates. Use for hotfixes and minor improvements.
59- **Ad-Hoc**: Warnings only. Use for prototyping and spikes (non-production).
60 
61See [REFERENCE.md](REFERENCE.md) for full mode behaviors.
62 
63## Verification
64 
65All phases complete with artifacts:
66```bash
67verify: test -f specs/state.yaml && test -f specs/release-plan.yaml && test -f specs/product/SCOPE_LATEST.yaml && ls specs/epics/*.yaml 1>/dev/null && echo "✅ All phases complete"
68```
69 
70 
71 
72<!-- story: e05s03 -->
73 
74---
75 
76# Orchestrate Reference: Phases, Modes, and Workflows
77 
78Detailed documentation for the `orchestrate-project` meta-skill.
79 
80## The 6-Phase Core Loop
81 
82### PHASE 1: DISCOVER
83- **Goal**: Understand the problem completely and map existing context.
84- **Deliverables**: `requirements/VISION_LATEST.yaml`, `requirements/SCOPE_LATEST.yaml`, `plans/TECH_STACK_LATEST.md`.
85- **Skills**: `survey-context`, `elaborate-spec`, `grill-me`.
86- **Gate**: Confirm ("Is the problem clear?").
87 
88### PHASE 2: ELABORATE
89- **Goal**: Research solutions and lock architectural design.
90- **Deliverables**: Prior art in scope YAML, ADRs in `specs/adr/`.
91- **Skills**: `grill-me`, `model-domain`, `define-language`, `deepen-architecture`, `design-interface`.
92- **Gate**: Quality ≥94% (via `request-review`) + Confirm ("Are decisions locked?").
93 
94### PHASE 3: PLAN
95- **Goal**: Write a verifiable implementation plan with success criteria.
96- **Deliverables**: `release-plan.yaml`, `epics/eNN-*.yaml` with `verify:` per task.
97- **Skills**: `scope-work`, `slice-tasks`, `plan-work`.
98- **Gate**: Quality (request-review ≥94%) + slopcheck [SUS]/[SLOP].
99 
100### PHASE 4: BUILD
101- **Goal**: Execute the plan story-by-story using the 8-step `build-epic` cycle with TDD and vertical slices.
102- **Deliverables**: Code; `execution-status.yaml` updated per story; `specs/metrics/cycle-times.yaml` row per story.
103- **Skills**: `build-epic` (conductor) → per-story: `survey-context`, `plan-work`, `kickoff-branch`, `develop-tdd`, `verify-work`, `audit-code`, `commit-message`, `release-branch`.
104- **BCP tracking**: `plan-release` sizes each story in Business Complexity Points (BCP) before the build queue; `plan-work` confirms and writes the size to `state.yaml` as `epic_cycle.story_bcps`. See `docs/references/bcp.md` for the canonical sizing method.
105- **Timestamps**: `survey-context` stamps `metrics.story_start`; `release-branch` stamps `metrics.story_end` and writes BCP/hr to `specs/metrics/cycle-times.yaml`.
106- **next_skill**: Each critical-path skill writes `handoff.next_skill` to `state.yaml`. Agents resume by reading `state.yaml` — no guessing.
107- **Dashboard**: `npm run dashboard` (TUI) or `npm run dashboard:web` (browser, port 7742) shows live pipeline, epic queue, BCP metrics, and cycle-time ledger.
108- **Gate**: Integration tests PASS; all 8 build-epic steps completed per story.
109 
110### PHASE 5: VERIFY
111- **Goal**: Validate success criteria and ensure production readiness.
112- **Deliverables**: UAT evidence, eval results.
113- **Skills**: `run-evals`, `verify-work`, `audit-code`, `request-review` (optional).
114- **Gate**: Verification Script confirmed; `verify-work` not on `main`/`master`.
115 
116### PHASE 6: RELEASE (Integrate)
117- **Goal**: Ship to `main` with full traceability.
118- **Deliverables**: Release tag (vX.Y.Z), release notes via semantic-release.
119- **Skills**: `commit-message`, `release-branch`.
120- **Git arc**:
121  1. Plan on `main` (Discover / Plan)
122  2. `kickoff-branch` → worktree + feature branch + clean baseline
123  3. Build / Verify / Review on feature branch
124  4. Integrate: **solo-local** (`scripts/land-branch.sh`) or **team-pr** (`gh pr create` → squash merge)
125  5. Cleanup worktree; **end on `main`** in primary repo root
126- **Gate**: Safety ("About to land on main. Confirm?").
127 
128---
129 
130## Orchestration Modes
131 
132### Mode 1: Standard (Enforce All Gates)
133**Use Case**: New features, major refactors, architectural changes.
134**Behavior**:
135- All Confirm gates require explicit user approval.
136- All Quality gates are hard stops if threshold is not met.
137- No shortcuts or phase skipping.
138 
139### Mode 2: Fast-Track (Skip Negotiable Gates)
140**Use Case**: Hotfixes, minor improvements, refactors on well-tested code.
141**Behavior**:
142- Skip Discover if `requirements/SCOPE_LATEST.yaml` exists.
143- Skip Elaborate if design decisions are already locked.
144- Skip Verify if coverage ≥95% + all tests PASS.
145- Soft gates auto-approve if baseline conditions are met.
146 
147### Mode 3: Ad-Hoc (Legacy, Warnings Only)
148**Use Case**: Exploration, prototyping, spikes (NOT for production).
149**Behavior**:
150- Gates emit warnings but do not block execution.
151- User can manually skip any phase.
152- No enforced quality thresholds.
153 
154---
155 
156## Gate & Checkpoint Types
157*See `docs/references/gates.md` and `docs/references/checkpoints.md` for full specs.*
158 
159- **Confirm**: Requires human "yes/no" decision.
160- **Quality**: Automated threshold check (e.g., coverage, audit score).
161- **Safety**: Destructive actions require risk acknowledgment.
162- **Transition**: Mandatory artifact presence check.
163- **slopcheck**: Identification of [SUS] (Suspicious) or [SLOP] (High-risk) packages.
164 
165---
166 
167## Error Recovery & State
168Orchestrate maintains `specs/state.yaml` to track:
169- **Current flow / epic**: `active_flow`, `active_epic_id`, `epic_cycle`.
170- **Handoff**: `last_step_completed`, `open_decisions`, `required_reading`, `next_skill`.
171- **Git**: `branch`, `hash` for session continuity.
172- **Progress**: Story status lives in `execution-status.yaml` only.
173 
174In the event of a crash or exit, run `claude /orchestrate --resume` to pick up exactly where the session left off.
175