plan

> STOP. READ THIS ENTIRE SKILL.MD BEFORE CALLING ANY ENDPOINT. # /plan Create YAML task files that `/orchestrate` executes directly. No markdown intermediate. **Before writing any plan, run `/governance` and read `/best-practices-plan`** - governance proves task understanding before planning starts, and best-practices-plan has the rules this skill enforces. ## Workflow The full pipeline is: `/governance` -> `/plan` -> `/review-plan` -> `/orchestrate`. The agent runs all four when the user says `/plan`. The user only needs to say `/plan` once. ``` 1. /governance - Prove understanding before planning (BLOCKING) 2. /memory recall - Check if this problem was already solved 3. SKILL DISCOVERY - Find existing skills that do what's needed (BLOCKING) 4. /assess - Read the target codebase 5. Identify persona - WHO uses this? Name them. 6. Decompose - Break into tasks with runner/backend/mode 7. Output YAML - Write 0N_TASKS.yaml 8. plan.py --dag - Show execution DAG to human for approval 9. plan.py --validate - Schema validation 10. /review-plan - Full validation (claims, routing, blind tests, overlap) 11. If PASS -> ask human: "Plan ready. Run /orchestrate?" 12. If human approves -> /orchestrate run 0N_TASKS.yaml 13. Optional, only when explicitly requested: run deterministic goal closure. ``` ### Optional Goal-Closure Loop Normal `/plan` remains plan-first: it writes and validates YAML, then asks before execution. Do not run the closure loop unless the user explicitly asks for "execute until done", "run with goal closure", "iterate until complete", or equivalent wording. When requested, `/plan` becomes the deterministic outer loop: ```text /plan --execute-closure 0N_TASKS.yaml --max-replans N -> plan.py --validate -> /review-plan review -> /orchestrate run -> /plan --assess-result using the orchestrate session -> stop on goal_achieved, or write follow-up/interview artifacts ``` Closed outcomes: ```text goal_achieved partially_achieved blocked wrong_plan insufficient_evidence ``` Closed recommended actions: ```text none create_followup_plan revise_existing_plan ask_human ``` `/plan` decides whether to create a follow-up/amended plan or ask the human: | Closure result | Plan response | |---|---| | `goal_achieved` | Stop successfully | | `partially_achieved` with failed tasks | Create a follow-up plan stub for remaining work | | `blocked` | Write an `/interview` request artifact | | `wrong_plan` | Stop before execution and write an `/interview` request artifact | | `insufficient_evidence` | Write an `/interview` request artifact | `/orchestrate` remains the execution engine and evidence producer. It does not own replanning. `/code-runner` remains a bounded worker inside `/orchestrate`. ### Step 2: Runner Selection (which tasks get /code-runner) Not every task needs `/code-runner`. **Code-runner is EXPENSIVE** — worktree isolation, git commit/revert cycle, multi-round LLM loop, T0 scoring, memory learning. Most tasks are simpler than that. **Runner is auto-routed if left empty.** Set it explicitly only when the heuristic is wrong. | Runner | When to use | Auto-routed when | Example | |--------|-------------|------------------|---------| | `local` | Shell command, no LLM needed | Has `command`, no `prompt` | `pytest`, `npm install`, `ruff check --fix` | | `scillm` | One-shot LLM call, simple edit | Has `prompt`, no `allowlist`+DoD assertion | Add a field, rename variable, generate docstring, classify | | `code-runner` | Complex bounded code task with verification, iteration, and context isolation | Has `prompt` + `allowlist` + DoD command/assertion + `blind_tests` | Fix multi-file bug, implement feature with test suite | **Default away from code-runner. Use it ONLY when ALL of these are true:** - The task writes/edits 1-3 specific files (use `allowlist`) - There's a runnable DoD command with a verifiable assertion - The DoD is expected to fail before the code change; already-passing gates are `local` - The fix may need multiple attempts (not a mechanical edit) - The task benefits from context isolation: only the allowlisted files should be writable - Dependencies are known and listed in `read_context` - Hidden/blind checks are listed in `blind_tests` for the orchestrate information barrier - **The DoD command does NOT require a live server** (code-runner uses git worktree isolation — the running dev server serves from the main working directory, not the worktree) **Do NOT use code-runner for:** - setup/bootstrap/deployment orchestration - Docker Compose validation - config/docs/changelog edits - pure test/lint/build gates - already-implemented work where the DoD already passes - broad architecture/design decisions For those, use `local` for deterministic commands or `scillm` for one-shot edits. **Concurrency rule:** if multiple code-runner tasks share one `cwd`, set `execution.max_concurrency: 1` unless they run in isolated worktrees or are patch-only tasks with disjoint allowlists. If any task uses `apply_to_source: true`, `/orchestrate` serializes tasks sharing that `cwd`. **NEVER use code-runner when the DoD calls a live HTTP endpoint** (e.g. `curl http://localhost:3001/...`). Code-runner edits files in an isolated worktree. The dev server doesn't see those edits. The DoD `curl` will always hit the OLD code and fail. Use `scillm` (one-shot edit to the working directory) + a separate `local` task to restart the server and verify with `curl`. **Use scillm (not code-runner) for:** - Mechanical edits: add a field, update an import, rename a variable - Config changes: update YAML, add an entry to a list - Text generation: docstrings, summaries, classifications - Any task where "just do it once, correctly" is sufficient - **Server endpoint code where the DoD requires `curl` to a live server** — edits must land in the working directory, not a worktree **Use local for:** - Running tests, linters, formatters, build commands - File operations: copy, move, create directories - Anything that's a shell command, not LLM reasoning **code-runner fields the project agent must provide:** - `allowlist` — files the LLM can write (scope boundary) - `read_context` — files the LLM should read for interface context (NOT write) - `definition_of_done` — runnable verification command with assertions - `blind_tests` — hidden assertions in `/test-lab` (required for code-runner, enforced by /review-plan) - `apply_to_source` — explicit complete-task opt-in; default false - `commit_on_success` — required true when `apply_to_source` is true - `rollback_on_failure` — required true when `apply_to_source` is true If any of these are missing, the plan is wrong. Route the task to `local`/`scillm`, or split the plan into: one implementation task and one separate local verification task. For a source-mutating code task, prefer complete-task mode: ```yaml apply_to_source: true commit_on_success: true rollback_on_failure: true ``` The plan must still provide `blind_tests`. `/orchestrate` runs those tests after the source commit and reverts that commit if hidden checks fail. ### Step 2b: Code-runner course corrections If `/orchestrate` dispatches a task to `/code-runner` and preflight returns `status: preflight_fail` with `course_correction`, `/plan` owns the amendment. Do not ask code-runner to continue and do not let it silently mutate YAML. Use the correction this way: 1. Read `{task_id}.course_correction.json` or `result.json.course_correction`. 2. Apply the recommended reroute/amend/split to the plan YAML. 3. Re-run `plan.py --validate`. 4. Re-run `/review-plan`. 5. Resume `/orchestrate` only after validation passes. Valid outcomes: | `recommended_action` | Plan response | |----------------------|---------------| | `use_local` | Change task to deterministic `local` command | | `use_scillm` | Change task to one-shot `scillm` prompt | | `amend_code_runner_contract` | Keep `code-runner`, but add missing prompt/allowlist/DoD/blind tests | | `split_task` | Split implementation from live verification | | `reroute_or_amend` | Choose the smallest safe route based on the correction rationale | ### Step 3: Skill Discovery (BLOCKING — do NOT skip) Before writing ANY task, check if an existing skill already does it. The agent MUST NOT write bespoke code when a skill exists. This is the #1 source of architectural debt. **How to check:** ```bash # Search the manifest (fastest — one file, all 225+ skills) cat ~/.pi/skills-manifest.json | python3 -c " import json, sys data = json.load(sys.stdin) for s in data['skills']: d = (s.get('description') or '').lower() if any(kw in d for kw in ['cache', 'redis', 'api']): print(f' /{s[\"name\"]}: {s[\"description\"][:100]}') " # Or search skill names directly ls ~/.pi/skills/ | grep -i cache # Or ask memory /memory recall "skill:caching" OR "skill:redis" ``` **Decision for each piece of work:** | Existing skill covers it? | Action | |---------------------------|--------| | Yes, fully | CALL the skill. Do NOT rewrite it. | | Yes, 60%+ | EXTEND the skill. Add what's missing. | | No match | CREATE new code — but document WHY in capability_overlap. | Every task in the YAML should map to CALL, EXTEND, or CREATE. If the plan is mostly CREATE, you haven't looked hard enough. `/review-plan` will flag tasks that overlap with existing skills as FAIL. ### Step 4: Compliance Governance (BLOCKING for SPARTA/CAE plans) Plans that involve CAE (Claims-Arguments-Evidence) trees, SPARTA controls, compliance verdicts, or posture assessments MUST enforce "analyst workbench, not truth engine": **Non-negotiable rules:** | Requirement | Implementation | |-------------|----------------| | NEEDS_VERIFICATION default | All CAE claims/verdicts default to NEEDS_VERIFICATION, never auto-PASS | | Human review gate | Every posture change requires compliance officer review before status change | | No autonomous certification | Agent NEVER writes "certified", "compliant", "approved" without human gate | | Retrieval language only | Use "retrieved", "found", "extracted" — never "determined", "verified", "confirmed" | **In YAML plans, add to metadata:** ```yaml metadata: compliance_governance: principle: "Analyst workbench, not truth engine" verdicts: "All default to NEEDS_VERIFICATION" human_gate: "Compliance officer reviews before status change" ``` **In task prompts, include:** ``` COMPLIANCE GOVERNANCE: This is an analyst workbench, not a truth engine. - All verdicts default to NEEDS_VERIFICATION - Human reviews before any status change - Use retrieval language ("retrieved", "found"), not judgment language ("verified", "confirmed") ``` `/review-plan` will FAIL plans that: - Auto-approve verdicts without human gates - Use "certified", "compliant", "approved" without human review step - Missing `compliance_governance` metadata for SPARTA/CAE plans Reference: `docs/WALKTHROUGH_QRA_COVERAGE_AND_EVIDENCE_CASES.md` Steps 7-11 happen automatically after writing the YAML. The human only intervenes if `/review-plan` FAILs (fix the plan) or if they want to amend the DAG before execution. ### If /review-plan FAILs Triage each failure: | Failure type | Action | |---|---| | Missing field (mode, DoD command) | Fix it yourself — no human input needed | | Wrong runner/backend | Fix if obvious, ask human if ambiguous | | Missing capability_overlap | Run `/memory recall` and fill it in | | Skill overlap detected | Ask human: use existing skill or justify new code? | | Ambiguous requirements | Use `/interview` for structured choices | | Claims don't match codebase | Re-read the code with `/assess` | After fixes, re-run `/review-plan`. Do NOT proceed to `/orchestrate` until PASS. Do NOT silently skip FAILs — every FAIL must be resolved or explicitly waived by the human. ## Plan Types Auto-detected from goal text. All types use the same YAML schema. | Type | Detected When | Pattern | |------|---------------|---------| | **code** | No UI keywords | `local` for setup/verification, `scillm` for one-shot edits, `code-runner` only for bounded iterative implementation | | **design** | views, components, TSX, dashboard, UI, React | `/mockup-lab` (Stitch) → `/ux-lab` (code) → `/mockup-lab review` (VLM verify) → `/test-interactions` | | **hybrid** | Both UI and code keywords | Stitch pipeline for UI views, code tasks in later waves | ### Design Plans **Rule: The agent NEVER designs UI.** Stitch designs it. The agent codes it. Design plans MUST specify **device type** (desktop, mobile, tablet). Pass `--device` to every `/mockup-lab` command. Stitch defaults to mobile if not specified. For any plan with UI work, each component follows 3 steps: 1. `/mockup-lab` — Stitch generates design, human approves (`--device desktop`) 2. `/ux-lab` — Agent codes React component from approved screenshots 3. `/mockup-lab review` — Gemini VLM verifies implementation matches design For small changes (colors, spacing, adding a column), skip step 1 and use `/ux-lab` + `/review-design` directly. Read `.pi/skills/mockup-lab/design-to-code.yaml` for the detailed checklist. **DoD for UI tasks must be visual** — "tsc compiles" is not done. Done means a screenshot shows real data matching the approved design. ## YAML Schema ```yaml version: 1 kind: orchestrate-plan metadata: title: "Feature Name" goal: "one-line summary" plan_type: code # code, design, or hybrid created: "2026-03-17" primary_persona: # WHO uses this (required) name: "Nico Bailon" role: "QA Engineer" source: ".pi/agents/nico-bailon/AGENTS.md" execution: max_concurrency: 3 # parallel lanes wave_barrier: false # if true, wave N must complete before wave N+1 starts scheduling_policy: dependency_only # or wave_then_dependency capability_overlap: # Phase 0 evidence (required) - "/memory recall returned: no prior Redis caching solution" - "Checked /fetcher, /dogpile — no overlap" questions_blockers: - "None" lanes: - id: "0" label: "Wave 0: Setup" - id: "1" label: "Wave 1: Implementation" - id: "2" label: "Wave 2: Validation" tasks: