standard-dev-workflow

# standard-dev-workflow — 8-phase pipeline for any non-trivial dev task User-locked 2026-05-24. Sub-agents wherever possible. Default to this pipeline; deviate only with explicit reason recorded. ## When to invoke - Starting any non-trivial implementation (3+ steps, multiple files, design-required) - Starting a planning session ("plan X", "design Y") - Starting research ("research X", "what's the literature on Y") - Bug investigation ("fix this", "debug X", "why is Y failing") - Architecture review needed - Refactor with side effects ## When NOT to invoke - Single-file 1-line edits (just do it) - Routine probe / status / report responses - Hot-fixes <5 lines with clear root cause - The task is already mid-pipeline (don't restart unless explicitly needed) ## The 8 phases (in order, all sub-agent-dispatched where possible) ### Phase 1 — Prompt engineering (Opus) **Goal**: rewrite the user's raw ask into a well-scoped task spec. - Opus (main session OR dispatched sub-agent) rewrites with: required-reading list, tool-use clause, verification clause, noise-calibration spec, ScholarEval scoring if research-claim - Output: a self-contained task spec future sub-agents can execute without back-and-forth ### Phase 2 — Plan (Opus + `superpowers:writing-plans` + skill discovery) **Goal**: produce a written implementation plan. - Load `superpowers:writing-plans` skill - Opus drafts plan - Read `docs/skill_index.md` — for each plan step, surface which skill encodes the discipline - Output: numbered-step plan with skill-per-step + risk + verification gate per step ### Phase 3 — Research (current web sources + Gemini/agy + Opus, parallel) **Goal**: ground the plan in current literature + best practices. - Use available web-research tools for authoritative recent literature (research papers, GitHub repositories, and relevant technical writing from the last 90-180 days) - Optionally dispatch Gemini for 3rd-opinion read on the plan: **post-2026-06-18, the `gemini` CLI is unavailable for this tier** (Google One/unpaid cutoff) — substitute `agy` (antigravity via `agy_dispatch.sh`, Gemini 3.5 Flash High) for the Google-opinion seat. See the peer-review council's seat-9 for the invocation pattern. - Update the plan with sourced findings — anything ADDED / CONTRADICTED / SUPERSEDED in published practice gets folded in - Output: revised plan with cited sources + flagged "the lit says X, our plan says Y, reconcile" ### Phase 4 — Council review **Goal**: surface conflicts / blind spots in the plan via 9-seat global LLM council. - Pass the plan + research findings to council with verbatim question - ScholarEval 8-dim scoring if any research-claim component - Update plan with chairman synthesis recommendations - Output: plan v2 with council-flagged risks resolved or explicitly accepted ### Phase 5 — Implementation (codex preferred, cursor for wiring / long-running) **Goal**: execute the plan. - **codex** (gpt-5.5 default): preferred for FRONTIER coding work, peer-review audits, bounded multi-file writes with spec - **cursor** (auto-mode): preferred for BASIC WIRING + LONG JOBS — unlimited tokens until Sept 2026 on auto-mode, so multi-file refactors / content writes / dispatch-script generation - For any long-running background/job-runner script: cite whatever this repo's job-runner-authoring skill is in the dispatch prompt, if one exists - For skill summarization: use `use-skill-review` v2 ritual - Output: implemented diff with verification commands ### Phase 6 — Code review (Opus + Sonnet via `code-review:code-review` skill) **Goal**: catch what codex/cursor missed. - Dispatch `code-review:code-review` skill OR sonnet-tier Agent with explicit review brief - Opus for high-stakes / architecture / security review; Sonnet for routine review - 3-way audit pattern when warranted (Claude + codex + gemini on same scope — agree=ship, dissent=investigate) - Output: green-light OR specific patches needed ### Phase 7 — Architecture / deep research (Gemini, when needed) **Goal**: heavy architectural decisions OR specialized research that exceeds ordinary web research. - `use-gemini` (agy with `--sandbox`, read-only); `--approval-mode plan` is gemini-CLI-era and dead post-2026-06-18 - Or dispatch Gemini for 3rd-opinion deep research where Opus plus authoritative sources surfaced unclear answers - Output: architectural recommendation OR resolved research question ### Phase 8 — Debug (Opus + codex via debug skill) **Goal**: when something broke or behavior is unexpected. - Load `superpowers:systematic-debugging` skill - Opus + codex pair: Opus reasons + codex audits + Opus reasons again - Check any project-local known-bug-class notes first, if this repo keeps one - If it's a new bug class worth remembering: record it wherever this project tracks that - Output: root cause identified + fix verified + notes updated if novel ## Hard rules (no exceptions) 1. **Use sub-agents wherever possible.** Main session is orchestrator; sub-agents do the work. Conserves context for orchestration + reflection. 2. **Phase 1 is mandatory** for any task that survived "is this trivial?" check. Don't skip the explicit prompt/spec drafting pass thinking it's overhead. 3. **Phase 4 (council review) is mandatory** for any plan that costs >$50 to execute OR touches a public-ship surface. Below $50 + internal-only, Phase 4 is advisory. 4. **codex vs cursor decision**: codex for FRONTIER reasoning / peer-review / spec-driven; cursor for BULK WIRING / multi-file content writes / long-running unlimited-token jobs. Don't waste cursor's unlimited budget on small audits. 5. **Phase 6 (code review) is mandatory** before any commit that changes >50 lines OR touches money-handling / API-key-handling / production code. ## Tool-tier routing table | Task surface | Tier 1 | Tier 2 | Tier 3 | |---|---|---|---| | Frontier coding / peer-review audit | codex (gpt-5.5) | gemini-3.1-pro | Opus | | Bulk multi-file refactor / wiring | cursor (auto, unlimited until Sept 2026) | codex | sonnet sub-agent | | Architecture review | Gemini/agy (post-2026-06-18: `agy_dispatch.sh` substitutes gemini CLI) | Opus | peer-review council | | Debug single bug | Opus + codex pair | Sonnet + codex | gemini | | Bug-class novel detection | Opus | codex audit | project bug-notes query | | Research / lit scan | available web-research tools + authoritative sources | gemini deep-research | council ScholarEval | | Plan review | 9-seat council | gemini 3rd-opinion | Opus self-audit | | Code review | code-review skill (Opus) | sonnet sub-agent | codex 2nd-opinion | ## Anti-patterns | Anti-pattern | Fix | |---|---| | Skipping Phase 1 → vague prompts to sub-agents → they drift | Always write the task spec first | | Skipping Phase 3 → reproducing internal wisdom that's superseded externally | Research current authoritative sources first; reconcile literature vs plan before Phase 4 | | Skipping Phase 4 on >$50 plans → expensive walkbacks | Council review pays for itself at >$50 | | Burning cursor's unlimited-tokens budget on 100-line edits | Use codex for small spec-driven work; reserve cursor for bulk | | Codex frontier reasoning on simple wiring | Use cursor or codex-spark for cheap mechanical work | | Opus reviewing every commit (over-spend on context) | Sonnet sub-agent for routine; Opus for high-stakes | | Debugging without checking prior known-bug notes first | Always check what's already known before debugging from scratch | | Sub-agent dispatched without verbatim spec → vague output | Phase 1 produces the spec; pass it through unchanged | ## Sub-agent dispatch template (Phase 5) When delegating implementation: > CONTEXT: <task spec from Phase 1, verbatim> > PLAN: <plan from Phases 2-4 with council fixes folded in> > SKILLS TO LOAD FIRST: <list per docs/skill_index.md> > IMPLEMENTATION: <step-by-step from plan> > VERIFICATION: <gate per step from plan> > SECRET-HANDLING: secret-hygiene discipline — use env-var reads, never hardcode keys > LONG-RUNNING JOB (if applicable): cite this repo's job-runner/driver-authoring skill, if one exists, for crash-safety and completion-signal discipline > REPORT: <a> what was done, <b> verification result, <c> any deferred items + why ## Sibling skills - `superpowers:writing-plans` — Phase 2 plan structure - `superpowers:subagent-driven-development` — Phase 2 + Phase 5 sub-agent execution - Available web-research tools — Phase 3 current-source research - `use-gemini` — Phase 5/6/7 delegation tool - `code-review:code-review` — Phase 6 - `superpowers:systematic-debugging` — Phase 8 - Secret-hygiene discipline applies across all phases - `use-skill-review` — when a skill in the rotation needs refresh per its trigger criteria ## What this skill REFUSES to do 1. **Skip Phase 1** on non-trivial tasks. Vague prompts to sub-agents waste their tokens + miss requirements. 2. **Allow main session to do work sub-agents could do.** Orchestrator role — delegate everything possible. 3. **Use Opus where Sonnet/Haiku would suffice.** Tier the model to the task; Opus is for opus-grade reasoning. 4. **Skip Phase 4 council review on >$50 plans.** Council pays for itself; bypass needs documented rationale. 5. **Wait for user when ACT-discipline applies.** Act on reversible + sub-$150 + non-public + non-destructive; ask otherwise. ## Quick reference (the 8-line checklist) ``` □ 1. Write the task spec (Opus explicit prompt/spec drafting pass) □ 2. Plan with superpowers + list per-step skills (Opus) □ 3. Research current authoritative sources + Gemini → update plan □ 4. Peer-review council (9-seat) → fold fixes into plan □ 5. Implement: codex (frontier) OR cursor (wiring/long, unlimited Sept 2026) □ 6. Review: code-review skill (Opus for high-stakes, Sonnet routine) □ 7. Architecture: use-gemini (agy with --sandbox, read-only); --approval-mode plan is gemini-CLI-era and dead post-2026-06-18 □ 8. Debug: Opus + codex pair + known-bug-class query first ```