Plan

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, merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: in_progress on start, completed on end. [BLOCKING] Every completed/skipped step MUST include evidence or explicit skip reason. [BLOCKING] If Task tools unavailable, maintain equivalent step-by-step plan tracker with same status transitions.

Quick Summary

Goal: Research the codebase and collaborate with the user to deliver a validated, implementation-ready phased plan — every phase startable immediately (exact file paths, zero open decisions, mapped TC IDs) — so coding proceeds without rework at minimum future change cost.

Summary:

• PLANNING ONLY — NEVER implement/execute code; produce plan.md + per-phase phase-XX files + a goal.md Goal Contract, then hand off.
• Main pipeline (the steps AI keeps forgetting): pre-check active/suggested plan → bootstrap Goal Contract (goal.md) → ONE research wave (researcher + scout subagents, spawned together, barrier before synthesis) → codebase + project-reference analysis (scout if docs absent) → planner subagent writes plan.md + phase-XX files (Alternatives, Rationale, UI Layout, Test Specs) → parallelism pass (tag every phase PAR/SEQ + write set + ## Execution Waves) → post-plan granularity self-check → mandatory final tasks.
• The plan output itself carries parallelism metadata — every phase tagged PAR/SEQ with the write set it owns, every SEQ naming its forcing dependency (see Plan Parallelism Metadata). Omitting it is a defect of THIS skill: $plan-execute fans out only on what the plan declares.
• --mode={ci|cro} routing: ci plans a fix from a GitHub Actions run/log (loads references/mode-ci.md); cro plans conversion-rate optimization (25-item framework, references/mode-cro.md); default (no flag) = standard flow. Mode only ADDS a reference payload — SAME engine, SAME $plan-review gate, SAME planner agent.
• Default mode HARD (parallel subagents, project-reference docs, the $plan-review convergence loop under its 3-round ceiling); fast mode ONLY when EVERY trivial-task condition holds. Every phase passes the 5-point granularity check ("Can I start coding RIGHT NOW?"), carries ## Test Specifications with TC IDs, uses bottom-up estimation (phase-hours drive man-days; SP DERIVED).
• Mandatory final tasks + gates: write Test Specs per phase → $plan-validate → $plan-review (convergence loop, 3-round ceiling) → $why-review (standalone) → re-estimate vs finalized phases; New Tech/Lib gate before approval; Domain Entity Gate (MANDATORY when the plan touches an entity/VO/aggregate) — apply SYNC:domain-entity-change-gate so the plan DECIDES classification, invariant ownership, aggregate boundary, concurrency, construction, events, and the test obligation (each naming its owning file) instead of deferring them to implementation; ask the user directly confirm before any next step.

Workflow:

1. Pre-Check — Detect active/suggested plan or create new directory
2. Research wave — All independent research threads spawned in ONE message (researcher + scout subagents, max 5 tool calls each), then a barrier before synthesis
3. Codebase Analysis — Search for project reference docs (patterns-reference, project-structure, architecture, adr); scout if not found
4. Plan Creation — Planner subagent creates plan.md + phase-XX files with full sections
5. Parallelism pass — Tag every phase PAR/SEQ with its write set; declare ## Execution Waves in plan.md
6. Post-Validation — Optionally interview user to confirm decisions via $plan-validate

Key Rules:

• PLANNING ONLY: do NOT implement or execute code changes
• Always run $plan-review after plan creation
• Ask user to confirm before any next step
• MANDATORY IMPORTANT MUST ATTENTION detect new tech/lib in plan and create validation task (see New Tech/Lib Gate below)
• MANDATORY IMPORTANT MUST ATTENTION when the plan touches an entity, value object, or aggregate, run the Domain Entity Gate below — state paradigm + subdomain fit BEFORE any entity task, and answer every triggered decision row with its OWNING FILE; "discover during implementation" is not an answer. Record No domain-entity surface — gate N/A when it does not fire

First Principle — Easy to Change

Success metric of every coding decision: future change cost. DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique serves one goal: making next change cheaper.

Evaluating code, refactor, test, abstraction, ask: does this make next change cheaper or more expensive?

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

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

Default Mode Policy

Default mode HARD (full rigor). Every section below — parallel researcher subagents, the full $plan-review convergence loop (3-round ceiling), base-class greps, microservices/event-driven analysis, mandatory user approval — applies by default.

Opt out to fast mode ONLY when ALL true (task genuinely trivial):

• Single-file edit, ≤30 lines changed
• No design choice (only one reasonable approach)
• No cross-service impact, no contract change, no new dependency
• No new pattern — follows existing codebase pattern
• User explicitly asked for a quick change

Any condition fails → use full protocol below. When in doubt, default hard — skipping rigor on a non-trivial task wastes more rework than rigor saves.

Fast mode skips (and only skips): parallel researcher subagents (direct grep instead), the $plan-review re-review loop (single round, no fresh re-review even when findings remain), $plan-validate interview (inline confirm only), New Tech/Lib Gate (only if truly no new deps).

New Tech/Lib Gate (MANDATORY for all plans)

MANDATORY IMPORTANT MUST ATTENTION after plan creation, detect new tech/packages/libraries not in project. If found: task tracking per lib → WebSearch top 3 alternatives → compare (fit, size, community, learning curve, license) → recommend with confidence % → ask the user directly to confirm. Skip if plan uses only existing dependencies.

Domain Entity Gate (MANDATORY when the plan touches an entity, VO, or aggregate)

Apply SYNC:domain-entity-change-gate (inlined below) — the SAME protocol $plan-review and $changes-review read, and whose A–P checklist $domain-entities-review owns. — why: a plan that leaves aggregate boundary, invariant ownership, or concurrency to "discover during implementation" ships a design review will reject, and the rework is paid twice.

Fires when the plan introduces or changes a domain entity / value object / aggregate root, its fields, invariants, relationships, or state transitions; an aggregate boundary, repository, or cross-aggregate reference; a domain event; or a concurrency/reconstitution concern. Otherwise record No domain-entity surface — gate N/A.

The plan MUST name the decision AND the owning file for every triggered row — an unanswered row is a plan that is not executable:

1. Classification — entity vs value object vs aggregate root (swap test applied).
2. Invariant ownership — which rules the entity enforces vs which the boundary validates; failure signalling (throw vs Result) consistent with the project convention.
3. Aggregate boundary + concurrency — what shares a transaction and why; cross-aggregate refs by ID; concurrency token on the ROOT; enforcing mechanism for any set-based invariant.
4. Construction vs reconstitution — separate creation and load paths; load raises no events.
5. Events — what is raised, when it dispatches (after commit / outbox), domain vs integration contract.
6. Test obligation — each invariant gets a property TC + boundary counter-case as a planned task, NEVER left implicit.

MUST ATTENTION state paradigm (OO-mutable / type-driven-immutable / event-sourced) and subdomain fit (core / supporting / generic / CRUD) BEFORE planning entity tasks — NEVER plan a rich domain model for a CRUD subdomain, and NEVER plan setter/mutability tasks against an immutable or event-sourced model.

Greenfield Mode

Auto-detected: No existing codebase found (no discovered source directories, no manifest files, no populated project-config.json) → skill auto-switches to greenfield mode. Planning artifacts (docs/, plans/, .claude/) don't count — repository must have actual code directories with content.

When greenfield detected:

1. Skip codebase analysis phase (researcher subagents grepping code)
2. Replace with: market research + business evaluation via WebSearch + WebFetch
3. Delegate architecture decisions to solution-architect agent
4. Output: plans/{id}/plan.md with greenfield-specific phases (domain model, tech stack, project structure)
5. Skip reading project reference docs (won't exist in greenfield)
6. Enable broad web research: tech landscape, best practices, framework comparisons
7. Every decision point requires ask the user directly with 2-4 options + confidence %
8. [CRITICAL] Business-First Protocol: Tech stack decisions come AFTER full business analysis. Do NOT ask user to pick tech stack upfront. Instead: complete business evaluation → derive technical requirements → research current market options → produce comparison report → present to user. See solution-architect agent for full tech stack research methodology.

• Research reports <=150 lines; plan.md <=80 lines
• External Memory: Write all research/analysis to .ai/workspace/analysis/{task-name}.analysis.md. Re-read ENTIRE analysis file before generating plan.

Run the planning methodology engine. Load the relevant references/engine-*.md for each phase (skip a phase per its own skip rule):

• references/engine-research.md — Research & Analysis (skip if given researcher reports)
• references/engine-figma.md — Design Context Extraction (skip if no Figma URLs / backend-only)
• references/engine-codebase-understanding.md — Codebase Understanding (skip if given scout reports)
• references/engine-solution-design.md — Solution Design (trade-offs, security, performance, edge cases, architecture)
• references/engine-plan-organization.md — Plan Creation, Organization & Output Standards

Mode Dispatch (--mode={ci|cro})

Default (no --mode flag): IGNORE this section — run the standard plan flow below, byte-for-byte unchanged. --mode only adds a domain-specific reference load + intake convention on top of the SAME engine, the SAME mandatory $plan-review gate, and the SAME planner agent. It never replaces the engine.

When a --mode is present: (1) read the matching references/mode-*.md; (2) apply its intake + domain focus to $ARGUMENTS; (3) run the standard plan workflow below — same planner subagent, same phase-file structure, same mandatory $plan-review. The mode adds a reference payload only.

Scaffolding-First Protocol (Conditional)

Activation conditions (ALL must be true):

1. Active workflow is workflow-greenfield-init OR workflow-big-feature
2. AI MUST ATTENTION self-investigate for existing base/foundational abstractions using these patterns:
   • Abstract/base classes: abstract class.*Base|Base[A-Z]\w+|Abstract[A-Z]\w+
   • Generic interfaces: interface I\w+<|IGeneric|IBase
   • Infrastructure abstractions: IRepository|IUnitOfWork|IService|IHandler
   • Utility/extension layers: Extensions|Helpers|Utils|Common (directories or classes)
   • Frontend foundations: base.*component|base.*service|base.*store|abstract.*component (if frontend present)
   • DI/IoC registration: search for DI registration patterns idiomatic to project's framework
3. If existing scaffolding found → SKIP. Log: "Existing scaffolding detected at {file:line}. Skipping Phase 1 scaffolding."
4. If NO foundational abstractions found → PROCEED with scaffolding phase.

When activated:

Phase 1 of plan MUST ATTENTION be Architecture Scaffolding — all base abstract classes, generic interfaces, infrastructure abstractions, DI registration with OOP/SOLID principles. Runs BEFORE feature stories. AI self-investigates what base classes the tech stack needs. All infrastructure behind interfaces with ≥1 concrete implementation (Dependency Inversion). Phase 1's deliverable MUST ATTENTION also include the golden-path example set $scaffold emits — one worked, compile-checked *.example.* per applicable pattern (backend: command · query · handler · entity-with-invariants · value-object · repository · domain event + event handler; frontend-if-UI: form · list · store · API service; tests: one integration test on happy + failure path) in an isolated, production-excluded examples/ tree using the scaffolded base abstractions, so post-scaffold $architecture-review-full gate has real, gradeable code before any feature work.

When skipped: Plan proceeds normally — feature stories build on existing base classes.

PLANNING-ONLY — Collaboration Required

DO NOT use the manual plan-mode switching tool — already in a planning workflow. DO NOT implement or execute any code changes. COLLABORATE with user: ask decision questions, present options with recommendations. After plan creation, ALWAYS run $plan-review to validate plan. ASK user to confirm plan before any next step.

Your mission

Pre-Creation Check (Active vs Suggested Plan)

Check ## Plan Context section in injected context:

• If "Plan:" shows a path → Active plan exists. Ask user: "Continue with this? [Y/n]"
• If "Suggested:" shows a path → Branch-matched hint only. Ask if user wants to activate or create new.
• If "Plan: none" → Create new plan using naming from ## Naming section.

Workflow

1. If creating new: create directory using Plan dir: from ## Naming section, then run node .claude/scripts/set-active-plan.cjs {plan-dir}. If reusing: use active plan path from Plan Context. Pass directory path to every subagent.
2. Goal Contract bootstrap (BEFORE investigation and phase writing): resolve active goal per SYNC:goal-contract-satisfaction-loop — create/update {plan-dir}/goal.md from .claude/templates/goal-contract-template.md, recording original request, purpose, success criteria, constraints, required evidence. Every phase's success criteria maps to a saved goal criterion. Redact secrets.
3. Follow strictly the "Plan Creation & Organization" rules in references/engine-plan-organization.md.
4. Project-reference preflight — BEFORE dispatch. Resolve and read the required project-reference documents first. Record missing or stale references as scoped research inputs; never discover the governing conventions only after workers have already started.
5. Research wave — ONE message, ONE barrier. Enumerate the independent research threads this task needs — per-module code investigation, pattern discovery, dependency mapping, prior-art/library search — then tag each PAR/SEQ and declare Parallel plan: wave 1 = [...] · SEQ = [...] (reason) before dispatch. Research is read-only, so a thread is PAR unless it consumes another thread's output (name that output). Spawn the whole wave in ONE message: researcher agents (max 2) for external/prior-art threads, max 5 tool calls per agent; scout agents for codebase threads, one per module/area with a disjoint read scope. Give each agent its own report path under {plan-dir}/research/ or {plan-dir}/scout/ so no two agents write the same file.
6. Analyze codebase against the preflight references. ONLY IF a required reference is missing or older than 3 days: include a scoped $scout <instructions> member in the research wave to gather the missing evidence; do not launch an unplanned later round trip.
7. Barrier, then synthesize. Advance only after EVERY wave member returns (a skipped thread counts as returned). Read the report FILES (not memory), reconcile conflicting findings, and record unresolved gaps — a second wave is dispatched only for gaps the first wave exposed.
8. Main agent gathers research/scout report filepaths; pass to planner subagent with prompt to create implementation plan.
9. Parallelism pass (MANDATORY before handoff). Validate each phase's Mode, Wave, write set, and SEQ dependency, then write the ## Execution Waves line — see Plan Parallelism Metadata. This is what lets $plan-execute fan out; an untagged plan executes strictly sequentially.
10. Main agent receives implementation plan from planner; ask user to review.

Post-Plan Validation (Optional)

After plan creation, offer validation interview to confirm decisions before implementation.

Check ## Plan Context → Validation: mode=X, questions=MIN-MAX:

If mode is prompt: Use ask the user directly tool with options above. If user chooses validation or mode is auto: Execute $plan-validate {plan-path} SlashCommand.

Output Requirements

Plan Directory Structure (use Plan dir: from ## Naming section)

{plan-dir}/
├── research/
│   ├── researcher-XX-report.md
│   └── ...
├── reports/
│   ├── XX-report.md
│   └── ...
├── scout/
│   ├── scout-XX-report.md
│   └── ...
├── plan.md
├── phase-XX-phase-name-here.md
└── ...

Research Output Requirements

• Research markdown reports concise (<=150 lines); cover all topics + citations.

Plan File Specification

• Every plan.md MUST ATTENTION start with YAML frontmatter:

  ---
  title: '{Brief title}'
  description: '{One sentence for card preview}'
  status: pending
  priority: P2
  effort: { sum of phases, e.g., 4h }
  story_points: { sum of phase SPs, e.g., 8 }
  man_days_traditional: '{ total e.g., 6d (4d code + 2d test) }'
  man_days_ai: '{ total with AI e.g., 3d (2d code + 1d test) }'
  branch: { current git branch }
  tags: [relevant, tags]
  created: { YYYY-MM-DD }
  ---
  

• Save overview at {plan-dir}/plan.md (<80 lines): list each phase with status, progress, Mode (PAR/SEQ), links to phase files; add the ## Execution Waves line below the phases table.

• For each phase, create {plan-dir}/phase-XX-phase-name-here.md with sections: Context links, Overview, Key Insights, Requirements, Alternatives Considered (minimum 2 approaches with pros/cons), Design Rationale (WHY chosen approach), Architecture, UI Layout (see below), Related code files, Parallel Execution (Mode PAR/SEQ · Write set · SEQ dependency — see below), Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps.

• UI Layout: For frontend-facing phases, include ASCII wireframe. Classify components by tier (common/domain-shared/page-app). For backend-only phases: ## UI Layout → N/A — Backend-only change.

Plan Parallelism Metadata (MANDATORY — every plan output)

$plan-execute fans out ONLY on what the plan declares. An untagged plan forces sequential execution, so omitting this metadata is a defect of THIS skill, not of the executor.

1. Tag every phase PAR or SEQ — in the plan.md phases table (Mode column) and in each phase file's ## Parallel Execution section. PAR = its inputs contain no pending phase's output AND its write set is disjoint from every other PAR phase.

2. Declare the write set per phase — the exact file paths the phase creates / modifies / deletes (globs only when their members are enumerable from the plan). Two PAR phases MUST have disjoint write sets; any overlap → merge the phases, or demote the later one to SEQ and name the shared file.

3. Every SEQ names its forcing dependency — SEQ — needs phase-02's {migration | generated type | contract | file}. "Feels sequential", "safer in order", or an unnamed dependency is not a reason: retag it PAR.

4. Group PAR phases into waves in a ## Execution Waves line in plan.md: Execution waves: wave 1 = [phase-01, phase-03] · wave 2 = [phase-04] · SEQ = [phase-02 (needs phase-01 schema), phase-06 (approval gate)].

5. Gates and reviews are SEQ boundaries — a user-approval, review, verification, or migration phase never shares a wave with the phases it gates; it runs after that wave's barrier.

6. Phase-file block format (copy verbatim into each phase file):

   ## Parallel Execution
   
   - Mode: PAR | SEQ
   - Write set: `src/a/x.ts`, `src/a/x.spec.ts`
   - Wave: 1
   - SEQ dependency: {name the phase + the exact artifact it produces — omit when Mode: PAR}
   

Behavior/Sync Planning Checks

• For behavior-changing work, every phase should name changed behavior, unchanged behavior to preserve, TC/test proof, and docs/spec sync action.
• For AI-extracted specs/TCs, plan must mark them reference-only until canonical acceptance.
• For .claude skills/hooks/workflows/sync tooling, plan must include generated mirror sync or explicit no-sync evidence.

IMPORTANT Task Planning Notes (MUST ATTENTION FOLLOW)

• Always break work into many small todo tasks via task tracking
• Always add a final review todo task to verify work quality and identify fixes/enhancements
• MANDATORY FINAL TASKS: After all planning todos, ALWAYS add these final tasks:
  1. Task: "Write test specifications for each phase" — Add ## Test Specifications with TC-{FEATURE}-{NNN} IDs to every phase file. Use $spec [mode=tests] if feature docs exist; Evidence: TBD for TDD-first mode.
  2. Task: "Run $plan-validate" — $plan-validate skill interviews user with critical questions, validates plan assumptions.
  3. Task: "Run $plan-review" — $plan-review skill, convergence loop (review → validate findings → fix → fresh full re-review) bounded by a 3-round ceiling, NEVER a target: a clean pass ENDS the loop at ANY round, round 1 included; round 3 completing with CRITICAL/HIGH/MEDIUM still open escalates by asking the user directly, never a silent PASS. SP raises the RIGOR of each round, never a round floor: ≤3 → checklist + code-proof trace; 4-8 → + adversarial simulation; >8 → code-proof trace mandatory in every round.
  4. Task: "Run $why-review (standalone only)" — If NOT inside a workflow, $why-review validates design rationale, alternatives considered, risk assessment. Skip if a workflow already includes $why-review.
  5. Task: "Re-evaluate estimation against finalized plan" — Pre-completion estimates anchor on scope guesses; finalized phases reveal true cost. After phases/TCs/decisions locked: (a) re-derive bottom_up_hours = Σ phase_hours from finalized phase files; (b) recompute likely_days, risk_margin_pct, min-max range per SYNC:estimation-framework; (c) compare to current frontmatter man_days_traditional / story_points. If |delta| > 20% → UPDATE frontmatter, add reestimate_delta_pct: <signed> + 1-line reestimate_reason. If |delta| > 50% → flag SHOULD-RESCOPE and surface to user by asking the user directly before implementation.

Important Notes

• Activate needed skills from catalog during process.
• Token efficiency without sacrificing quality. Sacrifice grammar for concision in reports.
• Unresolved questions → list at end of report.

Standalone Review Gate (Non-Workflow Only)

MANDATORY IMPORTANT MUST ATTENTION: If skill is called outside a workflow (standalone $plan), generated plan MUST ATTENTION include $changes-review as a final phase/task in plan. Ensures all implementation changes get reviewed before commit even without a workflow enforcing it.

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

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, MUST ATTENTION use ask the user directly to present these options. Do NOT skip because task seems "simple" or "obvious" — user decides:

• "Proceed with full workflow (Recommended)" — Detect best workflow to continue (plan created). Ensures review, validation, implementation, testing not skipped.
• "$why-review" — Validate design rationale before implementation (standalone only — skipped when workflow includes it)
• "$plan-review" — Validate plan before implementation
• "$plan-validate" — Interview user to confirm plan decisions
• "$plan-execute" — Start coding & testing the finalized plan. Recommended implementation route after plan validated.
• "Skip, continue manually" — user decides

Post-Plan Granularity Self-Check (MANDATORY)

After creating all phase files, run recursive decomposition loop:

1. Score each phase against 5-point criteria (file paths, no planning verbs, ≤30min steps, ≤5 files, no open decisions)
2. Each FAILING phase → create task to decompose into sub-plan (with own $plan → $plan-review → $plan-validate → fix cycle)
3. Re-score new phases. Repeat until ALL leaf phases pass (max depth: 3)
4. Self-question: "For each phase, can I start coding RIGHT NOW? If any needs 'figuring out' → sub-plan it."

Preservation Inventory (MANDATORY for bugfixes)

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

• docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)
• docs/specs/ — Test specifications by module (read existing TCs to include test strategy in plan)

Each phase file MUST ATTENTION satisfy: <=5 files per phase, <=3h effort, clear success criteria, mapped test cases.

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

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.

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."

Preservation Inventory — MANDATORY for bugfix plans. Trigger keywords in plan title/frontmatter: fix, bug, regression, broken, defect. Author MUST produce this table BEFORE writing implementation steps.

Columns: Invariant | file:line | Why (data consequence if broken) | Verification (TC-ID or grep)

BLOCKED until: ≥3 rows · every File cell has file:line · every Verification cell has TC-ID or grep (not "manually verify")

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.

Task Tracking & External Report Persistence — Bootstrap this before execution; then run project-reference doc prefetch before target/source work.

1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.
2. Mark one task in_progress before work and completed immediately after evidence; never batch transitions.
3. For plan/review work, create plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md before first finding.
4. Append findings after each file/section/decision and synthesize from the report file at the end.
5. Final output cites Full report: plans/reports/{filename}.

Blocked until: task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding.

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.

Sequential Thinking Protocol — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe.

Trigger when: complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation.

Format (explicit mode — visible thought trail):

1. Thought N/M: [aspect] — one aspect per thought, state assumptions/uncertainty
2. Thought N/M [REVISION of Thought K]: ... — when prior reasoning invalidated; state Original / Why revised / Impact
3. Thought N/M [BRANCH A from Thought K]: ... — explore alternative; converge with decision rationale
4. Thought N/M [HYPOTHESIS]: ... then [VERIFICATION]: ... — test before acting
5. Thought N/N [FINAL] — only when verified, all critical aspects addressed, confidence >80%

Mandatory closers: Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete.

Stop conditions: confidence <80% on any critical decision → escalate by asking the user directly · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task.

Implicit mode: apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy).

Deep-dive: see $sequential-thinking skill (.claude/skills/sequential-thinking/SKILL.md) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades).

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 `

…(truncated)