Plan Execute

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
• User-question prompts mean to ask the user directly in Codex.
• Ignore Claude-specific mode-switch instructions when they appear.
• Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
• For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
• If a required step/tool cannot run in this environment, stop and ask the user before adapting.

Codex Project-Reference Loading (No Hooks)

Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.

Always read:

• docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
• docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
• docs/project-reference/lessons.md (always-on guardrails and anti-patterns)

Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.

Situation-based docs:

• Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): project-structure-reference.md
• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec authoring, docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
• Behavior/public-contract changes or spec-test-code sync: workflow-spec-test-code-cycle-reference.md plus the spec docs above
• Derived spec indexes/ERDs/reimplementation guides: spec-system-reference.md and source Feature Specs under docs/specs/
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Land the selected plan phase as working, fully-tested, reviewed, user-approved code — executing it phase-by-phase through testing, code review, and approval gates — committed only after every quality gate (100% tests, 0 critical issues, explicit approval) passes — NEVER bypass a gate to declare done.

Summary:

• Purpose: consume an EXISTING plan, one phase per run — Step 0 detects plans/*.md + selects the next incomplete phase (prefer IN_PROGRESS, else earliest Planned). Use $feature-implement instead when no plan exists yet — it creates plans, this consumes them.
• Full step spine (run in declared order, emit ✓ Step N: each): Step 1 Analysis & Task Extraction (read plan fully, Goal-Contract read, Trace Gate, seed task tracking 0–6) → Step 2 Implementation (code step-by-step, type-check + compile; UI → ui-ux-designer) → Step 3 Testing (tester, loop debugger until 100%) → Step 4 Code Review (code-reviewer until 0 critical) → Step 5 User Approval (BLOCKING — stop and wait) → Step 6 Finalize (project-manager + docs-manager status/docs, git-manager auto-commit).
• Three BLOCKING gates cannot be faked-green: Step 3 tests 100% pass, Step 4 zero critical issues, Step 5 explicit user approval before Finalize/commit. — why: a partial-green gate ships the regression the test exists to catch.
• Two STOP-before-coding gates: Pre-Implementation Granularity Gate (refuse planning verbs / unnamed files / unresolved decisions → sub-plan with $plan) + bugfix Trace Gate (require the End→Start debugger trace for any bug/regression/behavior-changing plan). Also the Spec-Loop Gate (property TC + mutation-killed test + Dual-Feedback) closes any behavior change.
• Step 2 is SEQUENTIAL by default; wave fan-out is OPT-IN. --parallel / --parallel=on dispatches disjoint-write-set phases as one wave of fullstack-developer subagents in ONE message, barrier, then recomputes the next wave against the updated repo. --parallel=auto fans out ONLY when every in-scope phase carries the ## Parallel Execution block (PAR/SEQ tag + declared write set) written by $plan — no block, no fan-out.
• Mode flags add/remove ONE step, never relax a running gate: --approval=off (auto/trust, skip Step 5, optional $ALL_PHASES loop over every incomplete phase), --tests=off (skip Step 3), --parallel={auto|on|off} (off default = sequential; bare --parallel/on opts in to wave dispatch; auto fans out only on plan-declared PAR/SEQ metadata). No flags = full 7-step spine, run sequentially.
• Standalone (no parent [Workflow] row via the current task list) → wrap the spine in plan → plan-review → proceed → $changes-review → $why-review, the two reviews as the LAST todos.

Slash-command routing: /code, /code-auto, /code-no-test, /code-parallel no longer resolve — use $plan-execute with the matching flag: /code-auto → --approval=off, /code-no-test → --tests=off, /code-parallel → --parallel.

Workflow:

1. Plan Detection — Find latest plan or use provided path, select next incomplete phase
2. Analysis & Tasks — Extract tasks from phase file into task tracking
3. Implementation — Implement step-by-step, run type checks
4. Testing — Call tester subagent; must reach 100% pass before proceeding
5. Code Review — Call code-reviewer subagent; must reach 0 critical issues
6. User Approval — BLOCKING gate: wait for explicit user approval
7. Finalize — Update status, docs, and auto-commit

Key Rules:

• Tests must be 100% passing (Step 3 gate)
• Critical issues must be 0 (Step 4 gate)
• User must explicitly approve before finalize (Step 5 gate)
• One plan phase per command run — a multi-phase run requires --approval=off with $ALL_PHASES=Yes
• Phases run sequentially unless fan-out is explicitly opted in; even then, two phases writing the same file NEVER share a wave
• Mode flags (see Mode Flags): --approval=off (auto/trust, no approval gate + optional all-phases loop), --tests=off (skip the test step), --parallel={auto|on|off} (default off = sequential; on = opt in to wave dispatch; auto = fan out only when the plan declares PAR/SEQ tags + write sets). No flags = full 7-step spine below, run sequentially.

MUST ATTENTION READ CLAUDE.md then THINK HARDER to start working on the following plan:

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

$ARGUMENTS

plan-execute vs feature-implement: plan-execute executes an EXISTING plan phase-by-phase (Step 0 detects plans/*.md) and owns the back of the pipeline — phase gates, auto-commit, and the --parallel/--approval/--tests flags. Use $feature-implement instead when you have only a feature description and need research + planning done first. feature-implement creates plans; plan-execute consumes them.

Standalone Mode Pipeline (skip entirely if invoked inside a workflow)

MANDATORY — standalone $plan-execute only. When this skill is invoked OUTSIDE a workflow, wrap the core spine (Steps 0-6) in this quality loop. Detect an active workflow via the current task list FIRST: if a parent [Workflow] row exists, SKIP this section — the surrounding workflow already sequences plan/review/why-review (e.g. workflow-refactor).

Create these as task tracking tasks up front, in order, then execute them:

1. $plan — if Step 0 finds no plan for the request, author one first. If a plan already exists, record that and skip to step 2.
2. $plan-review — recursively review/validate the plan; fix validated findings before proceeding.
3. Proceed — run the core spine (Steps 0-6) against the approved plan.
4. $changes-review — review the diff before commit (the post-gate; see Standalone Review Gate below).
5. $why-review — review rationale and change quality of the implementation.

This is the single pre+post quality loop for standalone runs.

Mode Flags

$plan-execute runs the full step spine below by default. Optional flags adapt the spine for the cases formerly served by dedicated skills — each flag only adds or removes a single step against the host step numbering (Step 3 Testing, Step 4 Code Review, Step 5 User Approval, Step 6 Finalize); the shared spine and every quality bar are otherwise unchanged.

$ALL_PHASES (only meaningful with --approval=off): Yes (default in auto mode) processes ALL incomplete phases in one run, auto-looping to the next phase after each Finalize; No implements one phase then asks before continuing. With --approval=on (default), always one phase per run — so cross-phase wave dispatch is only ever reachable in a multi-phase run (--approval=off + $ALL_PHASES=Yes) or on a phase whose sub-phases are independently implementable.

Flag-modified step behavior

• --parallel=auto → Step 2 (Implementation): metadata-gated fan-out — dispatch waves ONLY when every in-scope phase carries a ## Parallel Execution block written by $plan; the moment one phase lacks it, the whole run reverts to sequential. auto NEVER derives a write set from the plan's prose — see Step 2 Wave Dispatch.
• --parallel / --parallel=on → Step 2: the explicit opt-in — dispatch waves even when the plan declares no PAR/SEQ tags or ## Execution Waves line. You MUST first derive each phase's write set yourself from its Related Code Files / Implementation Steps and from the generated/mirrored artifacts those edits cascade into; a phase whose write set you cannot name stays out of the wave. Colliding phases still go in different waves — opting in never authorizes co-scheduling two writers of one file.
• --parallel=off (DEFAULT) → Step 2: no wave dispatch; implement every phase sequentially in the main agent. This is the normal path and needs no justification — no flag is required to stay sequential. All gates and quality bars unchanged.
• --tests=off → Step 3 (Testing): Skip entirely. Proceed Implementation → Code Review. The Source/test drift check still applies to any tests that already exist. Keep existing tests real and genuinely passing — NEVER comment out tests, weaken assertions, or use fake data to make them pass — why: faked green hides the regression the test exists to catch.
• --approval=off → Step 5 (User Approval): Skip the blocking gate. Finalize (status, docs, auto-commit) runs once Steps 1-4 pass. When $ALL_PHASES=Yes, loop back to Step 0 for the next incomplete phase; on the last phase, generate the summary report and ask about /preview.

Behavior preserved: the debugger-trace gate, granularity gate, testing/review quality bars, and all SYNC blocks apply in EVERY mode. Flags change which gates run, never how rigorously a running gate is enforced.

Pre-Implementation Granularity Gate (MANDATORY)

If ANY check fails → STOP. Ask user: "Phase needs more detail before implementation. Refine with $plan? [Y/n]" Implement only phases with named files, concrete actions, and resolved decisions — DO NOT implement a phase containing planning verbs, unnamed files, or unresolved decisions.

Step 0: Plan Detection & Phase Selection

If $ARGUMENTS is empty:

1. Find latest plan.md in ./plans
2. Parse plan for phases and status, auto-select next incomplete (prefer IN_PROGRESS or earliest Planned)

If $ARGUMENTS provided: Use that plan and detect which phase to work on.

Output: ✓ Step 0: [Plan Name] - [Phase Name]

Workflow Sequence

Rules: Follow steps 1-6 in order. Each step requires output marker ✓ Step N:. Mark each complete in task tracking before proceeding. Do not skip steps.

Step 1: Analysis & Task Extraction

Read plan file completely. Map dependencies. List ambiguities. Identify required skills and activate from catalog. If the plan references analysis files in .ai/workspace/analysis/, re-read them before implementation.

Goal Contract read (BEFORE any code change): resolve the active Goal Contract per SYNC:goal-contract-satisfaction-loop — active plan goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → create from the current request via .claude/templates/goal-contract-template.md — and read its saved success criteria. After implementation/verification (Step 3+), append an Iteration Log entry with evidence and remaining gaps.

Pre-Implementation Trace Gate: If the plan is for a bugfix, failed verification, stale/incorrect final output, regression, or behavior-changing fix, MUST ATTENTION verify the plan or referenced analysis includes Debugger Trace: End -> Start, all feeder paths, hypothesis matrix, owning fix layer, and forward convergence proof. If missing, STOP and report the missing trace links instead of implementing.

task tracking Initialization:

• Initialize task tracking with Step 0: [Plan Name] - [Phase Name] and all steps (1-6)
• Read phase file, look for tasks/steps/phases/sections/numbered/bulleted lists
• Convert to task tracking tasks with UNIQUE names:
  • Phase Implementation tasks → Step 2.X (Step 2.1, Step 2.2, etc.)
  • Phase Testing tasks → Step 3.X
  • Phase Code Review tasks → Step 4.X

Output: ✓ Step 1: Found [N] tasks across [M] phases - Ambiguities: [list or "none"]

Step 2: Implementation

Implement selected plan phase step-by-step following extracted tasks. Mark tasks complete as done. UI work → call ui-ux-designer subagent. Run type check + compile to verify.

Step 2 Wave Dispatch (opt-in — --parallel=on)

Fan-out is OFF unless opted in. Run this section only when BOTH hold: (a) this run covers more than one phase ($ALL_PHASES=Yes, or a phase whose sub-phases are independently implementable), AND (b) the user passed --parallel / --parallel=on, or passed --parallel=auto and every in-scope phase carries a ## Parallel Execution block. Either condition unmet → implement sequentially. Sequential is the safe default and needs no justification.

1. Take the write set of every in-scope phase from the plan's declaration — its ## Parallel Execution block (Mode · Write set · Wave · SEQ dependency) written by $plan. Under --parallel=auto that block is MANDATORY: a plan lacking it falls back to sequential, and you NEVER reconstruct a write set from Related Code Files / Implementation Steps — why: a derived write set structurally cannot see cascade or generated writes, so two phases editing different source files can both write the same generated/mirrored/catalog/lockfile artifact that neither phase would ever name, and the wave corrupts it. Under --parallel=on the user has accepted that risk: derive the set yourself, then explicitly enumerate the generated, mirrored, and regenerated artifacts each phase's edits trigger and add them to that phase's write set before grouping. A phase whose write set still cannot be named is INELIGIBLE for a wave — implement it inline or send it back to $plan.
2. Refuse to co-schedule two writers of the same file — ANY path shared between two phases puts them in different waves. No "they only touch different functions" exception: the unit of ownership is the file. A phase tagged SEQ, or whose named dependency has not yet returned, never joins the current wave.
3. Declare, then spawn in ONE message — emit Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason), then spawn EVERY member of the wave in a single response as fullstack-developer subagents (UI-only phase → ui-ux-designer; route other specialties per .claude/skills/shared/sub-agent-selection-guide.md). Brief each with: its phase-file path, environment info, its EXCLUSIVE file-ownership boundary (cross-boundary edits forbidden — report the conflict instead), and its return contract.
4. Barrier, then re-evaluate against the updated repo — advance only after EVERY member returns. The barrier is YOUR accounting, not a signal you wait for: hold the wave's member list in the task tracker and mark each member by name as returned / failed / timed-out / partial. An unaccounted member is never dropped and never assumed successful. When every member is accounted for AND all returned cleanly, verify no file was written outside its owner's boundary, run type-check + compile on the merged result, THEN recompute the next wave against the repo as it now stands — never against the wave plan you computed before dispatch, because a returned phase can change what a later phase writes.
5. Wave failure branch — the barrier does NOT advance on an incomplete wave. If any member fails, times out, or returns partial work:
   • Classify partial as FAILED. A member reporting "mostly done", or whose evidence does not match its declared write set, counts as failed — not returned.
   • Never let the survivors stand in for the missing member, and never proceed to Step 3 on a wave that is not fully accounted for.
   • Quarantine the failed member's work — inspect exactly what it wrote, and revert its partial edits if they leave the tree uncompilable. Record the files it touched.
   • Fall back to sequential for that phase — merge the clean returns, restore compile-green, then re-implement the failed phase INLINE in the main agent (never re-dispatch it into another wave). A phase that also fails sequentially → STOP and report; do not carry it into the next wave.
   • A cross-boundary write fails the whole wave — revert the out-of-boundary edits, re-run that phase sequentially, and drop fan-out for the remainder of the run: the write-set model that authorized the wave is proven wrong.
   • Report the failure in the Step 2 output — a wave that fell back is never reported as a clean fan-out.
6. Do not dispatch when the gain is not there — a single-phase run, a one-file phase, or a wave of one implements inline (dispatch overhead > gain).

Gates are SEQ boundaries and are never parallelized away. Step 3 Testing, Step 4 Code Review, and the Step 5 user-approval gate run AFTER the barrier on the merged result — never concurrently with the phases they gate, and a subagent's own self-check NEVER substitutes for the host gate.

Output: ✓ Step 2: Implemented [N] files - [X/Y] tasks complete, compilation passed — when waves ran, append - waves: [w1 members] → [w2 members], and name any member that failed/timed-out plus the phase that fell back to sequential

Step 3: Testing

Call tester subagent. ANY tests fail → STOP, call debugger subagent, fix, re-run. Repeat until 100% pass.

Testing standards: Unit tests may use mocks. Integration tests use test environment. Forbidden: commenting out tests, changing assertions to pass, TODO/FIXME to defer fixes.

Output: ✓ Step 3: Tests [X/X passed] - All requirements met

Validation: If X ≠ total, Step 3 INCOMPLETE - do not proceed.

Step 4: Code Review

Call code-reviewer subagent. Critical issues found → STOP, fix, re-run tester, re-run code-reviewer. Repeat until no critical issues.

Output: ✓ Step 4: Code reviewed - [0] critical issues

Validation: If critical issues > 0, Step 4 INCOMPLETE - do not proceed.

Spec-Loop Gate (applies in EVERY mode, standalone included)

A behavior change is not "done" until the spec-loop closes (canonical: SYNC:spec-loop-discipline in .claude/skills/shared/sync-inline-versions.md). After implementing a behavior-bearing phase, the four rules gate completion: (1) every [HARD] §4 rule / §5 invariant the phase touched has a universally-quantified property TC ("for ALL inputs in {domain}, {invariant} holds") + boundary counter-case, not just an example; (2) the changed core-logic line is mutation-killed — a surviving mutant on a changed line is a missing invariant, write the killing test (MUTATION-SCORE bar, not line-coverage %); (3) the finding fed the Dual-Feedback Ledger into BOTH the spec AND the tests (a blank Spec-feedback OR Test-feedback cell = INCOMPLETE), never a code-only change. A phase with a behavior change but no property TC, no mutation-killed test, and no Dual-Feedback entry is INCOMPLETE — re-verify the whole package (spec + tests + code, not just the diff) before reporting success.

Step 5: User Approval ⏸ BLOCKING GATE

Present summary (3-5 bullets): what implemented (name the waves when Step 2 fanned out), tests passed, code review outcome.

This gate is a SEQ boundary — it is never merged into a wave, never delegated to a subagent, and never satisfied by "the parallel phases all reported success". Only --approval=off removes it.

Ask user explicitly: "Phase implementation complete. All tests pass, code reviewed. Approve changes?"

Stop and wait - do not proceed until user responds.

Output: ✓ Step 5: User approved - Ready to complete

Step 6: Finalize

Prerequisites: User approved in Step 5.

1. STATUS UPDATE (one wave — PAR): spawn project-manager (plan status file) and docs-manager (documentation) together in ONE message — disjoint write sets — and barrier on both returns before continuing.

2. ONBOARDING CHECK: Detect onboarding requirements + generate summary.

3. AUTO-COMMIT (SEQ — after the barrier): Call git-manager subagent; it stages the merged result of BOTH updates, so it never shares the wave above. Run only if Steps 1-2 successful + User approved + Tests passed.

Output: ✓ Step 6: Finalize - Status updated - Git committed

First Principle — Easy to Change

The success metric of every coding decision is future change cost. DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique exists to serve one goal: making the next change cheaper.

When evaluating code, a refactor, a test, or an abstraction, ask: does this make the next change cheaper or more expensive?

• Reject "best practices" that raise change cost (premature abstraction, speculative generality, leaky indirection, ceremony without payoff).
• Name the real enemies in findings: coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early.
• A simpler design that is easy to change beats a sophisticated design that isn't.

Apply this lens before invoking any specific rule, pattern, or checklist below — if a downstream rule would raise change cost, this principle wins.

Critical Enforcement Rules

Step output format: ✓ Step [N]: [Brief status] - [Key metrics]

task tracking tracking required: Initialize at Step 0, mark each step complete before next.

Mandatory subagent calls: Step 3: tester | Step 4: code-reviewer | Step 6: project-manager AND docs-manager AND git-manager

Blocking gates:

• Step 3: Tests must be 100% passing
• Step 4: Critical issues must be 0
• Step 5: User must explicitly approve

Execute every step in declared order; proceed only when validation passes and the user has approved; run one plan phase per command. Do not skip steps, proceed on failed validation, or assume approval without a user response.

Workflow Recommendation

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If you are NOT already in a workflow, you MUST ATTENTION use ask the user directly to ask the user. Do NOT judge task complexity or decide this is "simple enough to skip" — the user decides whether to use a workflow, not you:

1. Activate workflow-refactor workflow (Recommended) — scout → investigate → plan → plan-execute → review → production-readiness-review → test → docs
2. Execute $plan-execute directly — run this skill standalone

Next Steps (Standalone: MUST ATTENTION ask user by asking the user directly. Skip if inside workflow.)

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use ask the user directly to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

• "Proceed with full workflow (Recommended)" — I'll detect the best workflow to continue from here (code implemented). This ensures review, testing, and docs steps aren't skipped.
• "$code-simplifier" — Simplify implementation
• "$integration-test" — Generate/update integration tests from test specs
• "$workflow-review-changes" — Review changes before commit
• "Skip, continue manually" — user decides

Standalone Review Gate (Non-Workflow Only)

Post-gate of the Standalone Mode Pipeline. Full standalone loop: plan → plan-review → proceed → $changes-review → $why-review; the two review steps below are its tail.

MANDATORY IMPORTANT MUST ATTENTION: If this skill is called outside a workflow (standalone $plan-execute), you MUST ATTENTION create task tracking todo tasks for $changes-review then $why-review as the last tasks in your task list. This ensures all changes are reviewed before commit even without a workflow enforcing it.

If already running inside a workflow (e.g., workflow-feature, workflow-refactor), skip this — the workflow sequence handles $changes-review at the appropriate step.

[IMPORTANT] Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.

Prerequisites: MUST ATTENTION READ before executing:

• docs/project-reference/frontend-patterns-reference.md
• docs/project-reference/scss-styling-guide.md — Styling/BEM guide (read when task involves frontend/UI)
• docs/project-reference/design-system/README.md — Design system tokens (read when task involves frontend/UI)
• docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

End-to-Start Debugger Trace — For non-trivial bugs, failed verification, regression fixes, behavior-changing code, or unclear code flow, start from the observed final state and walk backward before proposing a fix.

1. Frame 0: observed end state — Name the exact user-visible output, failing assertion, log line, persisted value, API response, rendered UI, or aggregate bucket. Record the reader/query/renderer that produced it with file:line evidence.
2. Walk backward one hop at a time — Trace final reader -> projection/cache/storage -> writer -> consumer/handler/job -> producer/caller -> original trigger. At every hop record: input, transformation, output, owner, and evidence.
3. Enumerate all feeder paths — Find every upstream producer/caller/event/job that can write into the final path, including retry, async, cache, background, and alternate UI/API paths. Mark each path verified, ruled out, or still unknown.
4. Build the hypothesis matrix — For each plausible cause, list evidence for, evidence against, how to reproduce/verify, blast radius, and status (primary, contributing, ruled out, latent). Do not fix until competing causes are explicitly resolved or bounded.
5. Choose the owning fix layer — Identify the invariant owner and the lowest shared point that protects all downstream consumers. A fix at the symptom site is rejected unless the symptom site owns the invariant.
6. Prove convergence forward — After choosing the fix, walk start -> end again and show how the corrected state reaches the observed final output. Map each root cause to a fix part and each fix part to a test/proof.

BLOCKED until: final state named · backward trace written · all feeder paths enumerated · hypothesis matrix completed · owning fix layer justified · forward convergence proof mapped to tests.

NEVER: Start at the first suspicious code path. Collapse multiple producers into one "flow". Treat duplicate symptoms as duplicate records without proving the read model. Skip ruled-out hypotheses.

Plan Granularity — Every phase must pass 5-point check before implementation:

1. Lists exact file paths to modify (not generic "implement X")
2. No planning verbs (research, investigate, analyze, determine, figure out)
3. Steps ≤30min each, phase total ≤3h
4. ≤5 files per phase
5. No open decisions or TBDs in approach

Failing phases → create sub-plan. Repeat until ALL leaf phases pass (max depth: 3). Self-question: "Can I start coding RIGHT NOW? If any step needs 'figuring out' → sub-plan it."

Nested Task Expansion Contract — For workflow-step invocation, the [Workflow] ... row is only a parent container; the child skill still creates visible phase tasks.

1. Call the current task list first. If a matching active parent workflow row exists, set nested=true and record parentTaskId; otherwise run standalone.
2. Create one task per declared phase before phase work. When nested, prefix subjects [N.M] $skill-name — phase.
3. When nested, link the parent with TaskUpdate(parentTaskId, addBlockedBy: [childIds]).
4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
5. Mark exactly one child in_progress before work and completed immediately after evidence is written.
6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason.

Blocked until: the current task list done, child phases created, parent linked when nested, first child marked in_progress.

Project Reference Docs Gate — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions.

1. Identify scope: file types, domain area, and operation.
2. Read docs/project-config.json first — the project's machine-readable map. It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it before investigating, planning, or coding — never assume framework defaults (CLAUDE.md + reference docs are derived from it). If it — or the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any required reference doc — is missing or stale, auto-run $project-init or the narrow route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) first; if Codex mirrors or AGENTS.md are stale, ask the user to run $sync-codex (never auto-run it).
3. Required docs by trigger: always docs/project-reference/lessons.md; doc lookup docs-index-reference.md; review code-review-rules.md; backend/CQRS/API backend-patterns-reference.md; domain/entity domain-entities-reference.md; frontend/UI frontend-patterns-reference.md; styles/design scss-styling-guide.md + design-system/design-system-canonical.md; integration tests integration-test-reference.md; E2E e2e-test-reference.md; feature docs/specs feature-spec-reference.md + spec-system-reference.md + spec-principles.md; behavior/public-contract/spec-test-code sync workflow-spec-test-code-cycle-reference.md; derived spec index/ERD/reimplementation guides spec-system-reference.md + source Feature Specs under docs/specs/; architecture/new area project-structure-reference.md.
4. Read every required doc, then before target work state: Reference docs read: ... | Not applicable: ....

Ready when: scope evaluated, docs/project-config.json consulted, required docs checked/read or setup route completed, lessons.md confirmed, citation emitted.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.

1. Search 3+ similar patterns (grep/glob) — cite file:line evidence
2. Read existing files in target area — understand structure, base classes, conventions
3. Run python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists
4. Map dependencies via connections or callers_of — know what depends on your target
5. Write investigation to .ai/workspace/analysis/ for non-trivial tasks (3+ files)
6. Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth
7. NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader

BLOCKED until: - [ ] Read target files - [ ] Grep 3+ patterns - [ ] Graph trace (if graph.db exists) - [ ] Assumptions verified with evidence

Source/test drift check. For coding, fix, debug, investigation, test, or review work: when source behavior changes, inspect affected unit/integration/E2E tests and decide from evid

…(truncated)