Big Task

/big-task

One skill to route engineering work. Hides /gsd-*, /audit-fix-loop, /pr-fix-loop, /codebase-sweep, /think-ultra, etc. under a single memorable name.

Auto-trigger: User describes a task touching 3+ files or creating new functionality. See rules/workflow.md → Big Task Auto-Trigger.

Override: User says "skip workflow", "just do it directly", "quick and dirty" → drop to direct execution.

Default bias: LIGHTER process. GSD's multi-agent ceremony (plan-checker, CONTEXT/PLAN/SUMMARY docs, revision loops) only pays off when it catches real bugs that direct implementation would ship. For locked-design UI work, well-understood patterns, and single-responsibility additions, full GSD is pure overhead. Use risk, not file count, as the primary decision axis.

Tier 4 engine routing — match the engine to the work shape, don't pick a single default:

If unclear, silently pick superpowers (judgment-strong, two-stage review gates — safer default for ambiguous engine choice). Log the choice in the PR's ## Autonomous decisions section. Do NOT ask the user — see Phase -1.

The /gsd-* planning overhead (CONTEXT / PATTERNS / RESEARCH / REVIEW / VALIDATION / VERIFICATION meta-artifacts per phase) is real — don't pay it for small Tier 4 work. But the execute-phase engine itself is lean (~15% orchestrator), so don't penalize GSD for the planning-phase overhead when long autonomous runs are the actual need.

Phase -1 — Autonomous-by-default mode (DEFAULT ON — overrides every "ask once" elsewhere in this skill)

Once /big-task is invoked, the entire flow runs autonomously through to PR-merged. Do NOT pause for confirmation between phases, between fix loops, between commits, between detection routings, or between audit rounds unless one of the Critical Decision Triggers below is hit.

The user already opted into autonomous execution by invoking this skill — every additional checkpoint is friction they explicitly do not want. If the skill's wording elsewhere says "ask once" / "surface to user" / "wait for confirmation", this section overrides it unless the situation matches a Critical Decision Trigger.

Critical Decision Triggers (the ONLY 4 reasons to pause)

Pause and ask the user ONLY if the next action falls into one of these classes:

1. Irreversible architectural choice — picking a database engine, ORM, primary framework, monorepo tool, deployment target, auth provider, or anything else that future code will copy and that costs >1 day to undo.
2. Money / secrets / PII boundary — code that moves money (charges, refunds, credits), introduces or rotates secrets, exfiltrates PII, or alters access boundaries (auth scopes, RBAC, row-level security, payment paths).
3. Requirements ambiguity that would invalidate already-shipped work — the user's prompt has multiple readings AND picking the wrong reading would mean reverting a meaningful chunk of already-committed code. Surface ONLY when re-reading the prompt twice still doesn't disambiguate AND there's no safer "do both / do neither" middle path.
4. User-facing breaking change — public API contract change, data migration that requires user action, removal of a documented feature, force-push to a shared branch.

If the next action is NOT in one of those 4 classes, proceed without asking. Pick the more conservative path silently and log the choice in a ## Autonomous decisions section of the final PR description so the user can audit after-the-fact.

Auto-resolutions (replace every "ask once" prompt with these silent defaults)

Fix routing — inline vs subagent (severity-agnostic)

Once an issue is flagged, it WILL be fixed. The only question is who fixes it. Pick by cost to main thread, not by severity:

Subagent contract: receives {issue_id, file_paths, severity, finding_text}, loads context from disk, applies fix, runs build+typecheck+lint+tests, returns {status: FIXED|BLOCKED, files_touched: [...], commit_sha} ≤200 tokens. Main thread aggregates, never sees raw fix output.

Anti-pattern to avoid: flagging an issue at confidence ≥80 and then "deferring as MINOR follow-up" because it's tedious. That's the exact failure mode the user called out — the audit found it, so fix it. If the fix is expensive, that's what subagents are for.

How to ask when a Critical Decision Trigger IS hit

Format (≤ 3 sentences total):

[CRITICAL DECISION] <one sentence: what's at stake and why this is class N>
A) <option> — <consequence>
B) <option> — <consequence>
Pick A / B / or describe a third path.

No essay. Just the decision. Then wait — do not proceed until user answers.

Mid-flight escape hatch (user-initiated)

User can interrupt at ANY point with: "stop", "pause", "wait", "let me look", or by hitting Ctrl-C. Respect interruption immediately. Resume on user's explicit "continue" / "go" / "proceed" / "moveon".

Status updates while autonomous

While running autonomously, emit ONE short progress line per phase boundary (≤ 80 chars):

▸ Phase 2b · parallel-worktree (4 tasks) · running
✓ Phase 2b · 4/4 green · committed (a1b2c3d) · → Phase 2c
✓ Phase 2c · review clean · → Phase 2g
✓ Phase 2g · 6/6 PASS · → Phase 6a

NOT a multi-paragraph essay per phase. The user will read commits + PR description for detail; mid-flight chatter steals their attention without informing them.

Final report (at PR-opened or PR-merged)

ONE summary block (per existing Exit section, augmented):

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /big-task ▸ COMPLETE  (autonomous run)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Phases shipped: N
 Commits: N      LOC: +A / -B
 Tests: unit X / integ Y / e2e Z
 Autonomous decisions made:
   • <decision 1 — what was silently picked and why>
   • <decision 2 — ...>
 Critical-decision pauses: N (none / list)
 Deferred follow-ups (FLAG batch): N (linked from PR)
 PR: <url>

The ## Autonomous decisions log is non-optional — it's the receipt the user needs to audit autonomy after-the-fact.

Phase 0.0 — Project workflow profile (FIRST, auto-detects)

Profile routing happens BEFORE the tier rubric. Three-step resolution:

Step 1 — Explicit block in ./CLAUDE.md (highest priority)

Grep for workflow-profile:start in ./CLAUDE.md. If found, extract <name> from the ## Workflow Profile: <name> line inside the block. That's the profile. Skip to Step 3.

(CLAUDE.md is loaded into session context at start — usually you can just scan existing context instead of re-reading the file.)

Step 2 — Auto-detect from repo signals (runs only when no explicit block)

Run ONE bash command to collect signals (≤1s):

{
  # Schema: concrete file existence tests only — DO NOT use `ls glob | head` because that always succeeds on empty input in zsh
  ( [ -f prisma/schema.prisma ] || [ -f drizzle.config.ts ] || [ -f drizzle.config.js ] || [ -f drizzle.config.mjs ] || [ -f knexfile.js ] || [ -d db/migrations ] || { [ -d migrations ] && find migrations -maxdepth 1 -name "*.sql" 2>/dev/null | grep -q . ; } ) && echo schema
  # Auth / payment libs
  [ -f package.json ] && grep -qE '"(stripe|@stripe|better-auth|next-auth|@auth/core|lucia)"' package.json 2>/dev/null && echo auth-payment
  # Components dir (root OR src/ OR app/) + UI framework
  ( [ -d components ] || [ -d src/components ] || [ -d app/components ] ) && [ -f package.json ] && grep -qE '"(tailwindcss|@radix-ui|@chakra-ui|@mui/material|shadcn)"' package.json 2>/dev/null && echo components-ui
  # Locked design reference
  ( [ -f HANDOFF.md ] || [ -d directions ] || [ -d docs/design ] ) && echo design-ref
  # E2E framework
  [ -f package.json ] && grep -q '"@playwright/test"' package.json 2>/dev/null && echo playwright
  # Markdown content volume
  CONTENT=0
  for d in content/posts _posts content/blog docs/posts posts; do
    [ -d "$d" ] && CONTENT=$((CONTENT + $(find "$d" -maxdepth 2 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')))
  done
  [ "$CONTENT" -gt 5 ] && echo "content-$CONTENT"
  # Backend language indicator
  ( [ -f go.mod ] || [ -f Cargo.toml ] || [ -f pyproject.toml ] ) && echo backend-lang
} 2>/dev/null

Classify from emitted signals — apply rules in order, first match wins:

Call this the repo-shape profile. It reflects what the codebase IS, not what the current task IS.

Step 2.5 — Task intent (judgment, NOT keyword matching)

The repo scan answers "what shape is this project?". Now you need to answer "what shape is this task?". Reason about the request — do NOT pattern-match words. You are an LLM; you can read the task holistically the way an experienced engineer would. Someone saying "I was reading about Stripe" is not the same as "integrate Stripe payments", even though both contain the word Stripe.

The core question: what is the task actually doing to the system?

Classify what the task modifies or introduces. These categories carry inherent risk regardless of repo shape:

"Heavy by nature" — modification risk dominates any repo shape

• Persistence layer changes — schema, data model, new tables, column adds, migrations
• Trust boundary changes — building or altering an auth/authz/session/permissions system
• Revenue path changes — code that actually moves money (charges, refunds, credits, paywall gating)
• Atomicity/concurrency guarantees — transactions, distributed locks, idempotency keys, race-condition fixes
• Cross-system contracts — API contract changes with external consumers, protocol versioning, webhook schemas between services
• New architectural subsystem introduction — something that doesn't exist yet in the repo and whose shape will be copied by future code

"Light by nature" — task is content or cosmetic

• Written prose work — articles, translations, copy edits, doc updates, typos, README changes
• Pure cosmetic visual tweaks — color, spacing, alignment, font-size — where no new UX pattern is being introduced
• Single config/script tweaks where the config schema is stable and the change is one line or one value

"UI by nature" — rendered output, no system-risk boundary crossed

• Building/restyling components, screens, routes that apply existing design patterns
• The N+1-th application of a pattern that already lives in the repo

Framing questions when the above doesn't settle it cleanly:

1. Blast radius — if this ships wrong, what breaks? A wrong color is a bad afternoon. A double-charge is a refund + customer anger + possible chargeback fees. Bigger blast → heavier tier.
2. Reversibility — can a single git revert undo this, or is there data migration / state mutation to unwind? Unwindable-with-data = heavier.
3. Design vs. translation — is the user asking for a design decision (which pattern? which trade-off?) or the translation of an existing design (apply HANDOFF.md to these 5 screens)? Decisions are heavier; translations are lighter.
4. Pattern novelty — is this the N+1 application of a known pattern, or does this task set a new pattern? New pattern = heavier.

Combining rule → final profile

Apply in order, first match wins:

1. Task is heavy by nature (any of the 6 categories above) → heavy regardless of repo
2. Task is light by nature (pure content / cosmetic / trivial config) → light regardless of repo
3. Task introduces a new subsystem or sets a new architectural pattern → max(repo, one-level-up) — a blog getting a real-time comment subsystem promotes to ui or heavy, not light
4. Task matches the repo's default shape (UI work in a UI repo, content in a blog repo) → use the repo profile
5. Genuinely ambiguous — default to the lighter tier and proceed. If the task grows beyond the tier mid-flight, escalate then. Only ask the user upfront when the request is unparseable.

Print the reasoning, not a label: Profile: heavy (repo: light; intent: task introduces a revenue boundary — Stripe paywall). State what you judged, not what you matched.

Examples (showing judgment, not lookup)

• Blog repo + "translate this post" → light — task is prose translation; repo is light; align.
• Blog repo + "add Stripe paywall for premium posts" → heavy — task introduces a revenue boundary; blast radius is customer money; repo shape is irrelevant.
• Backend repo + "fix a typo in README" → light — task is prose; no system-risk boundary; repo shape is irrelevant.
• Backend repo + "add a new column to the users table" → heavy — task modifies persistence; even though it's a small diff, the blast radius of a bad migration is high.
• UI repo + "build a real-time notification subsystem from scratch" → heavy — task introduces a new architectural subsystem that will set patterns.
• UI repo + "restyle the button to match the new design reference" → ui — task is translation-of-design, N+1 pattern application.
• UI repo + "decide whether to use Zustand or Redux for state management" → heavy — task is a design decision that will be copied across the codebase.
• Any repo + "fix alignment of the footer on mobile" → light — pure cosmetic tweak, no pattern change.

Step 3 — Route by final profile

If light-project:

• Exit big-task immediately. Execute the request directly in the current context — no subagents, no planning, no tier rubric, no superpowers cycle.
• This is the project's "just do it" stance for solo blog/content/script work.
• Escalation exception: if the request clearly involves schema migrations, cross-service protocol changes, atomicity, or concurrency, silently escalate to Phase 0 rubric (per Phase -1 auto-resolution table) and log the escalation in the PR's ## Autonomous decisions section. Do NOT pause to confirm — schema/auth/concurrency are class-2 critical decisions only when the user is making the architectural choice itself, not when escalating tier.

If ui-project:

• Force Tier 3 (GSD-lite), skip Phase 0 rubric entirely. File count and "architectural risk" heuristics don't apply — UI work is visual-driven with Playwright verification, which inverts the usual risk calculus.
• Use superpowers subagent-driven-development for multi-component work. Invoke brainstorming ONLY for a truncated spec (1 page max) — do NOT produce inline code, TypeScript essays, or 1000+ line plans.
• Plans are checkbox task lists (files + Playwright assertion per task), not treatises.
• Verification at Phase 2g is MANDATORY Playwright sweep: Claude reads the PNGs directly (multimodal), compares against design reference. No LLM verifier agent.
• Skip GSD entirely — no .planning/ phase directories, no CONTEXT/PATTERNS/RESEARCH/VALIDATION/VERIFICATION meta-artifacts.

If heavy-project:

• Proceed with Phase 0 rubric below, BUT at Tier 4 use superpowers full cycle (brainstorming → spec → writing-plans → subagent-driven-development → requesting-code-review → verification-before-completion), NOT the /gsd-* chain.
• Worktrees, TDD-mandatory, human + automated code review all apply.
• Invoke /gsd-* only on explicit user request ("use GSD", "/gsd-autonomous") OR when genuinely needed for cross-phase dependency tracking.

If unknown: fall through to Phase 0 rubric. Default Tier 4 engine is superpowers, NOT /gsd-* chain (see description paragraph above). When the task completes, if the project has durable character, suggest the user run /workflow-profile <name> to make routing sticky and skip the detection cost next time.

Overrides

• User says "skip workflow" / "just do it" / "quick and dirty" → drop to direct execution regardless of profile.
• User says "use GSD" / "use superpowers" → override the engine choice for this one task.
• User wants durable override: run Skill(skill="workflow-profile", args="<light|ui|heavy>") to write an explicit block (wins against auto-detect forever after).

When auto-detection gets it wrong

If detected profile is obviously wrong (e.g., auto-detected ui on a repo that's actually a backend-with-small-UI heavy project), trust the auto-detect and proceed silently (per Phase -1). Re-route ONLY mid-flight if 2+ phases produce FLAG verdicts pointing at the wrong profile — at that point the evidence is on disk, not a judgment call. Log the detected profile in PR ## Autonomous decisions so the user can /workflow-profile <name> to pin a different one for next time.

Phase 0 — Risk-tier decision (≤ 30s)

Risk is the primary axis. File count is secondary. A 15-file UI migration from a locked design spec is LOWER risk than a 3-file atomic credit-deduction change. Route accordingly.

Decision rubric

When GSD is PURE OVERHEAD (skip full GSD even at tier 4 file count)

• Locked-design UI migration: design reference (HANDOFF.md, Figma export, directions/*.jsx, etc.) already specifies pixel-exact layout. Most of GSD's "what are we building?" scaffolding is redundant ceremony. Use Tier 3 GSD-lite instead.
• Repetitive pattern application: adding the N+1-th screen that follows the same shape as the existing N. Copy the pattern, adjust for new content, ship.
• Solo dev + short horizon: traceability / handoff artifacts exist to coordinate a team. If no one else will read them, they're writing docs for yourself at significant token cost.
• Design already validated: if /gsd-spike or /gsd-sketch already produced findings, don't re-plan those findings through another plan-checker loop. Apply them directly.

When GSD is WORTH IT (insist on tier 4 even at low file count)

• Atomic / concurrent / transactional logic: plan-checker catches race conditions before execution. Cheaper than debugging production.
• Schema changes / migrations: compile-time types can pass while the live DB is broken. Full verification gates matter.
• Multi-plan wave parallelism: 2+ independent workstreams benefit from explicit dependency declaration + parallel executor agents.
• Revenue-path code: payment, credits, unlock flows — correctness > velocity.
• Cross-cutting protocol changes: shifting a message format or API contract across many call sites — plan-checker's coverage audit earns its keep.

Tier ambiguity → silently pick the lighter tier and proceed (per Phase -1 auto-resolution + the existing "bias toward lighter tier" rule). Log the chosen tier + the alternative considered in PR ## Autonomous decisions. Do NOT ask the user mid-flight — if the lighter tier turns out wrong, escalate by promoting the next phase to a higher tier rather than backtracking the current one.

Default = proceed at the rubric-matched tier. Bias toward the lighter tier when in doubt.

Phase 0.5 — Optional pre-phase (tier 4 only)

Use when an idea is unproven OR UI-heavy with unclear direction. Produces throwaway output that auto-wraps into a project skill, so the learnings persist after exploration.

• Feasibility unknown ("can we even do X?"): Skill(skill="gsd-spike") → throwaway experiment → Skill(skill="gsd-spike-wrap-up") to package findings into a project skill.
• UI direction unclear ("what should this look like?"): Skill(skill="gsd-sketch") → HTML multi-variant mockups → Skill(skill="gsd-sketch-wrap-up") to package.

Default = skip. Only invoke when requirements are genuinely ambiguous at the implementation or aesthetic level.

External design artifacts (brownfield bundles): If the user hands you a pre-made design bundle from an external tool (Claude Design, Figma export, v0 export, external spec/prototype, chat log with locked decisions), copy it to a persistent repo path before Phase 1 — typically docs/{project-slug}/reference/. Do not leave references pointing at /tmp/ or external URLs — they will break mid-project. Then cite these persistent paths in PROJECT.md so downstream phases always find them.

Model selection (consistency across all subagents)

When .planning/config.json has model_profile: "quality", every GSD subagent spawned throughout the big-task flow should use Opus — not just researcher/roadmapper as the current gsd-tools per-role defaults set. Pass model: "opus" explicitly on all Task(subagent_type=...) invocations:

• gsd-research-synthesizer (tool default is sonnet even under quality; override)
• gsd-plan-checker, gsd-verifier, gsd-nyquist-auditor
• gsd-codebase-mapper (both initial map and refresh scans)
• feature-dev:code-reviewer (Phase 4 tracks)
• think-ultra (Phase 2c, Phase 3)

For balanced profile: Sonnet everywhere. For budget: Haiku for simple retrieval/formatting only, Sonnet for anything requiring judgment. For inherit: match the current session model.

Rationale: Tier 4 multi-week scope amortizes the Opus cost across downstream planning/execution — cheaper than shipping a bad plan and rewriting phases. Don't let per-role defaults silently downgrade synthesis or verification.

Subagent Dispatch Policy

Every phase below carries a Subagent policy line. The policy has four modes, chosen by the nature of the work, NOT by tier:

Default: NEVER inline when tier ≥ 3 AND independent task count ≥ 3. Past that scale, inline bloats main-thread context and defeats the autonomous-run advantage of subagent architectures.

Orchestrator discipline (applies to all subagent modes):

• Subagents load inputs from disk themselves (plan file, design ref, diff snapshot). Do NOT inject full task text from controller into every prompt — that's how superpowers' orchestrator accidentally hoards context across a 20-task plan.
• Subagents return structured summaries ≤200 tokens ({task, status, findings}), not raw output.
• Orchestrator state lives on disk (.planning/phases/N/state.json for Tier 4, TodoWrite for Tier 3) — never in main-thread chat history.
• Use superpowers:using-git-worktrees before any parallel-worktree dispatch. Worktree isolation is what removes the shared-state bar that superpowers:dispatching-parallel-agents otherwise imposes on parallel implementers.

Announce the chosen mode when entering a phase: Phase 2b · parallel-readonly (4 routes). Makes routing auditable and catches inline overuse.

Phase 1 — Bootstrap

Route by tier from Phase 0.

1a — Tier 3 GSD-lite (DEFAULT for most "big" tasks):

Write a short inline plan directly in the response. Keep it ≤1 page:

## Plan

**Objective:** [1 sentence]
**Files to touch:** [bulleted list, 3-10 files]
**Key references:** [design spec, existing pattern file, API contract]
**Test plan:** [unit / integration / E2E scope — be specific]
**Acceptance criteria:** [3-5 verifiable conditions]
**Rollback:** [how to revert if needed — usually just `git revert <commit>`]

Then proceed to Phase 2 with this inline plan as the single implicit phase. Do NOT spawn gsd-planner, gsd-plan-checker, gsd-discuss-phase, or any .planning/ scaffolding. The value of those agents is catching ambiguity and architectural risk that isn't present in tier 3 work.

Skip straight to TDD: write failing tests based on acceptance criteria → implement → verify.

1b — Tier 4 full GSD, new project: Skill(skill="gsd-new-project"). Creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md. For brownfield codebases, gsd-new-project will offer to run a codebase map — accept it and choose gsd-map-codebase (comprehensive). The 4-agent parallel sweep produces 7 structured docs (STACK, INTEGRATIONS, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, CONCERNS). The last 3 — especially CONCERNS (README drift, tech debt, v2 migration blockers) — are what make downstream phase planning actually work for multi-week scope.

1c — Tier 4 full GSD, existing .planning/: If .planning/codebase/ is missing or stale, refresh it first:

• No existing map, or major codebase changes since last map: Skill(skill="gsd-map-codebase") — 4 parallel agents, 7 comprehensive docs. Essential for Tier 4 — lightweight scans skip CONCERNS/CONVENTIONS/TESTING which planners need.
• Recent map exists but one specific area changed substantially: Skill(skill="gsd-scan" args="--focus <area>") — 1 agent, targeted refresh.

Then Skill(skill="gsd-new-milestone") — creates milestone ROADMAP.

After ROADMAP.md is created (1b or 1c): run Skill(skill="gsd-analyze-dependencies") to auto-suggest Depends on: entries for each phase.

Phase 2 — Phase loop (per phase)

Tier 3 (DEFAULT — GSD-lite): route by independent task count (see Subagent Dispatch Policy).

• ≤2 tasks on same file/module → inline. TDD → implement → code-reviewer agent → commit.
• 3+ tasks on shared files → serial-subagent via Skill(skill="superpowers:subagent-driven-development"). Fresh implementer + spec reviewer + quality reviewer per task.
• 3+ tasks on disjoint files, mechanical work (locked-design migration, pattern N+1 application) → parallel-worktree: isolate each task with superpowers:using-git-worktrees, then dispatch parallel Task() implementers. Worktree isolation removes the shared-file bar. If .planning/ already exists, Skill(skill="gsd-execute-phase") does this natively.

Skip CONTEXT.md / PLAN.md / SUMMARY.md ceremony regardless. One phase, one commit batch, done.

Tier 4 (full GSD): Skill(skill="gsd-autonomous") runs the full loop: discuss → plan → plan-check → execute → verify → (audit/complete/cleanup) automatically. Use when risk justifies the multi-agent ceremony (see Phase 0 "When GSD is worth it").

Manual / deep mode (tier 4 opt-in): instead of (or before) gsd-autonomous, invoke sub-skills explicitly for finer control:

• Skill(skill="gsd-spec-phase") — Socratic spec refinement; use when WHAT the phase delivers is genuinely unclear.
• Skill(skill="gsd-discuss-phase") — adaptive context-gathering; use when autonomous would skip nuance the user must weigh in on.
• Skill(skill="gsd-list-phase-assumptions") — surface implicit assumptions BEFORE planning. Cheap way to front-load the plan-checker's most valuable catches.
• Skill(skill="gsd-plan-phase") — standalone plan creation with plan-checker loop.
• Skill(skill="gsd-review") — cross-AI peer review; invoke only for novel patterns or revenue-path changes.
• Skill(skill="gsd-execute-phase") — wave-based execution; pause between phases.

Escape hatches for over-engineered tier-4 flows:

• Skill(skill="gsd-fast") — trivial task inline, no subagents, no planning overhead. Use when you accidentally routed a tier-2 task through big-task.
• Skill(skill="gsd-quick") — atomic commits + state tracking but skip optional agents (plan-checker, verifier). Middle ground when you want GSD's commit discipline without the ceremony.

2a — Plan specification (by tier)

Tier 3 (GSD-lite) — minimum viable plan:

• Unit tests: TDD — failing test first, then implementation. Non-negotiable.
• Design reference: cite the authoritative source (HANDOFF.md, Figma URL, existing pattern file) in the inline plan. No need to generate a new UI-SPEC.md if one already exists upstream.
• Acceptance criteria: 3-5 verifiable conditions. Grep-checkable beats subjective.
• Integration / E2E: only if the task actually crosses system boundaries. A pure-UI component doesn't need integration tests.

Tier 4 (full GSD) — every phase must include:

• Unit tests: TDD.
• Integration tests: real APIs/DBs, no mocks (per rules/engineering.md).
• E2E tests: UI changes → e2e-runner agent.
• UI spec: frontend phase WITHOUT existing design reference → Skill(skill="gsd-ui-phase"). Skip if a locked design reference already exists (e.g., HANDOFF.md + directions/*.jsx authoritative). Don't double-spec.
• AI spec: AI-heavy phase (prompts, evals, guardrails) → Skill(skill="gsd-ai-integration-phase").
• Design doc: 2-5 sentences covering data flow + key decisions.

Before planning (tier 4): Skill(skill="gsd-list-phase-assumptions") surfaces implicit assumptions BEFORE gsd-plan-phase. This is the single cheapest way to front-load the plan-checker's most valuable catches.

2b — Implement

Subagent policy:

• Tier 3, ≤2 tasks same file → inline
• Tier 3, 3+ tasks shared files → serial-subagent via superpowers:subagent-driven-development
• Tier 3, 3+ tasks disjoint files (mechanical) → parallel-worktree (set up worktrees with superpowers:using-git-worktrees first, then dispatch parallel Task() implementers)
• Tier 4 → parallel-worktree, orchestrated by gsd-autonomous (wave-based)

Announce: Phase 2b · <mode> (<N> tasks).

TDD non-negotiable: tests red → minimal impl green → refactor. Per-phase atomic commit (from /gsd-execute-phase or inline commit).

2c — Review

Multipass per rules/workflow.md → Review Discipline. Tier 3+ runs ≥2 passes; never ship after a single pass. Tier 4 already enforces this via Phase 3/4. AX never reviews — agent runs every pass autonomously.

Pass 1 — code-reviewer agent. Reads diff, returns severity-classified findings.

• Small diff (<500 LOC, <5 files): single agent.
• Large diff (≥500 LOC or ≥5 files): parallel-readonly fan-out — one reviewer per concern (security / types / tests / logic / error-handling). Each returns {concern, findings: [{severity, location, note}]} ≤200 tokens. Aggregate, dedupe overlap.

Pass 2 — domain reviewer. Pick by language/stack — Skill(skill="code-review"), python-review, go-review, or equivalent. Catches idioms/anti-patterns Pass 1 misses.

Triggered passes (any tier, parallel with Pass 2):

UI changes are covered by Phase 2g visual verification — don't double-pass.

Per Phase -1: fix all findings, severity controls how (inline vs subagent), not whether.

Tier 3: skip think-ultra unless the diff involves security / concurrency / data mutation. Tier 4: Skill(skill="think-ultra") on the phase diff (git diff <phase-base>...HEAD) AFTER pass 1 + pass 2 + triggers. Focus: regressions, unused code, test gaps, architecture concerns, security. Address HIGH/CRITICAL before proceeding.

2d — Audit-fix loop (OPTIONAL for tier 3)

Only run if Phase 2c surfaced findings worth sweeping.

Tier 3: Skill(skill="audit-fix-loop") — iterative fix-test-verify. Skip entirely if review was clean. Tier 4: Skill(skill="gsd-audit-fix") — integrated audit-to-fix pipeline with phase state.

Both terminate when zero high-confidence issues remain and changed-file coverage hits 80%+.

2e — Reflect (SKIP for tier 3 unless something surprising surfaced)

Tier 4: Skill(skill="gsd-extract_learnings") — structured extraction into the gsd learnings store for future phases. Tier 3: only capture learning if it's genuinely new and cross-project-applicable (e.g., a framework gotcha, a surprising library behavior). Otherwise skip — project memory isn't a journal. Append to ~/.claude/projects/<project>/memory/ only for durable patterns.

2f — Knowledge sync (AUTO — runs every phase)

Always invoke Skill(skill="neat-freak") at phase boundary. Three-audience editorial pass:

1. Agent memory (~/.claude/projects/<...>/memory/) — relative dates → absolute, completed todos removed, conflicting facts merged
2. Project root markdown (CLAUDE.md / AGENTS.md) — routes / env vars / decisions kept current for the next session
3. docs/ + README.md — integration-guide / architecture / runbook / handoff files reconciled against the diff (cross-project sync if upstream/downstream affected)

The skill is internally idempotent — it no-ops cleanly when there's nothing to reconcile, so running on every phase is safe. The doc edits land in the same end-of-phase commit as the code (per Phase -1 auto-resolution).

Codemaps: if codemaps exist AND were meaningfully affected → Skill(skill="update-codemaps") AFTER neat-freak. Codemap regeneration is its own concern (archit

…(truncated)