Domain Planner

Three modes: Planning (create specs), Quality Assessment (validate/fix specs), and Orchestration (implement specs via agents).

Use This For

• New multi-repo or cross-stack slice planning
• Quality review for an existing slice plan
• Implementation orchestration after a slice plan is accepted

Do Not Use This For

• Bug fixes, small changes, or single-repo refactors
• Direct scaffolding without a settled slice contract
• Routine implementation-detail debates that belong in scaffolder skills or code review

Skill root: ~/.claude/skills/domain-planner/ — all relative paths below resolve from here.

Shared orchestration rules: Use references/orchestration-contract.md for the cross-skill contract on worker ownership, background-task handling, and the domain suite's 100/100 convergence rule.

Plan Storage

Plan storage is resolved from the skillbox client overlay. Each client defines plan paths in its overlay.yaml, and the focus command generates a resolved context.yaml with absolute paths:

# context.yaml (auto-generated by skillbox focus)
plans:
  plan_root: /path/to/clients/{client}/plans/released
  plan_draft: /path/to/clients/{client}/plans/draft
  plan_index: /path/to/clients/{client}/plans/INDEX.md
  session_plans: /path/to/clients/{client}/plans/sessions

To find a slice: read {plan_root}/{slice}/. To check what exists: read {plan_index}. DO NOT search the filesystem for plans.

Plan paths are resolved at runtime by scripts/init_slice.py via the shared resolve_context helper, which reads the active client's context.yaml. No --config flag is needed when a skillbox client overlay matches the current working directory.

Client Context (Skillbox)

Implementation context — repos, conventions, stack — comes from the skillbox client overlay (skillbox-config/clients/{client}/overlay.yaml).

The overlay defines:

• cwd_match — directory pattern for auto-detection
• plans — plan_root, plan_draft, plan_index, session_plans
• backend — repo, domain_path, migration_tool, migration_path
• frontend — repo, features_path, types_path, api_only
• auth — packages_root, python_packages, npm_packages

If no client overlay matches the current directory:

1. Tell the user no overlay matches and create one using the skillbox-quickstart scan + generate flow before proceeding.
2. If the user declines overlay creation, you can still read/create plans with explicit --config paths to init_slice.py.
3. For implementation (orchestration mode), an overlay is required — do not proceed without one.
4. DO NOT search the filesystem. DO NOT spawn Explore agents.

Auth Service Requirements (All Modes)

The shared auth/payments/identity service ({auth_packages_root} from the client overlay) is the canonical authentication, payments, and identity layer.

1. Use existing auth service packages first. Do not design or scaffold parallel auth/payments/identity implementations when the auth service already covers the capability.
2. If auth service functionality is missing or blocking, raise an "auth-scope proposal" to the user with the gap, impacted slice, proposed package/API addition, and cross-product benefit.
3. When version drift requires unpublished local changes, temporarily symlink/link packages from local {auth_packages_root}. After auth service packages are published live, switch back to published versions and run final checks against the live auth service before closing the slice.

On Trigger

1. Detect project context from skillbox client overlay (match CWD to cwd_match patterns).

2. If slice name not provided, ask: "What's the slice name (snake_case) and one-sentence business value?"

3. Check if plan already exists at {plan_root}/{slice}/plan.md:

   If plan does NOT exist:

   • Run Pre-Planning Prerequisites (below) — parallel subagents for build-vs-clone and docs freshness
   • Run python3 ~/.claude/skills/domain-planner/scripts/init_slice.py {slice_name} to scaffold files (context resolved automatically from skillbox overlay)
   • Begin Phase 0 landscape, then Phase 0.5 Core Value Gate (Planning Mode)

   If plan exists, ask the user:

   Question: "Plan exists for {slice}. What do you want to do?" Options:

   • Implement it (Recommended) — Orchestrate scaffolding + audit until 100/100 COMPLIANT
   • Continue planning — Edit existing plan files
   • Check plan quality — Assess and fix plan files against the quality rubric
   • Check status — Show what's implemented vs planned

   Based on answer:

   • "Implement it" → Jump to Orchestration Mode (below)
   • "Continue planning" → Resume at appropriate phase
   • "Check plan quality" → Jump to Quality Assessment Mode (Phase 6b assess→fix→re-assess)
   • "Check status" → Show implementation status, suggest next action

Pre-Planning Prerequisites

When: Before Phase 0, on every new slice (plan does not yet exist). Skip for "Continue planning", "Check quality", or "Implement it" flows.

Goal: Ensure the project's public documentation and strategic positioning are current before committing to a new slice plan. Stale READMEs and unexamined build-vs-clone questions create downstream rework.

Launch two parallel subagents (divide-and-conquer pattern):

Subagent A: Build-vs-Clone Assessment

Invoke the build-vs-clone skill as a background subagent with the slice name and one-sentence business value. Its job: determine whether this work should live in an existing repo, be extracted, adopt existing open source, or be built from scratch.

Wait for its result before proceeding to Phase 0. If build-vs-clone recommends adopting or cloning, surface that to the user — it may change or cancel the slice entirely.

Subagent B: Docs Freshness Check

1. Read vision.md (repo root of each repo in the client overlay's Repositories section). This is the source of truth for project direction and competitive positioning.

2. Detect README drift — For each repo in the client overlay, run:

   git log --format="%H %ai" -1 -- README.md
   

   to get the last README commit, then:

   git diff {readme_commit}..HEAD --name-only
   

   to get all files changed since. Assess whether those changes (new features, removed features, API changes, dependency changes) make the current README inaccurate.

3. Check competitive landscape — If the README has a competitive landscape, alternatives, or comparison section, cross-reference it against vision.md positioning. Flag if competitors listed are stale or if the new slice changes the project's positioning.

4. Verdict:

   • README is current → no action, report "docs fresh" and continue
   • README needs update → invoke the readme-writing skill as a subagent, passing it the list of drifted sections and the diff summary. Wait for readme-writing to complete before returning.

After Both Subagents Return

• If build-vs-clone changed the plan (adopt/clone/extract), surface to user and halt until they confirm or redirect.
• If README was rewritten, note this in the slice's plan.md under a "Pre-planning artifacts" section so the plan reflects the current documented state.
• If the new slice materially changes the project's competitive positioning or feature set, add a WORKGRAPH.md node for a post-implementation README update (invoke readme-writing again after the slice ships). This ensures the README stays accurate after implementation, not just before planning.

---

Plan Location

{plan_root}/
├── {slice}/
│   ├── plan.md, shared.md, backend.md, frontend.md, flows.md, schema.mmd
│   └── WORKGRAPH.md
└── ...

{plan_draft}/
└── {slice}/

{plan_root}, {plan_draft}, and {plan_index} come from the skillbox client overlay's context.yaml.

schema.mmd is REQUIRED — without it, the slice won't appear in indexes or ERD views.

Critical Rules

1. No implementation code — Specs only (what & why, never how). No file structures, no framework-specific patterns, no column types. Those are the scaffolder's job.
2. Binary refinement — Every user story gets "A or B?" questions with reasoning until unambiguous.
3. Test cases inline — Each acceptance criterion includes test scenarios (happy path + error cases).
4. schema.mmd is MANDATORY — Other files reference it for entity relationships.
5. Just-in-time reading — Read the client overlay's convention files before each phase.
6. Explicit handoffs — Reference domain-scaffolder with explicit surface=backend or surface=frontend, plus domain-reviewer by name. Mention the legacy wrapper names only when explaining compatibility with older artifacts.
7. Standard stories first — Before Phase 1 Discovery, check ~/.claude/skills/domain-planner/references/standard-stories/ for reusable patterns (RBAC, feature flags, onboarding). Start from templates, don't rediscover.
8. Client-specific templates — Use ~/.claude/skills/domain-planner/assets/templates/frontend-{client}.md when available (e.g., frontend-personal.md for client-specific slices). Fall back to generic frontend.md.
9. Performance envelopes are binding — When the client overlay defines performance constraints, convert each target into explicit acceptance criteria and test scenarios across plan files.
10. Default delivery strategy is big-bang — Plan the target-state contract directly. Do not add dual routes, backward-compatibility shims, deprecation windows, or legacy endpoint support unless the user explicitly asks.
11. Separate DB transition planning from API planning — Only add a DB transition section when production data is at risk. Keep it operationally focused: backup, transactional/idempotent raw SQL execution, verification, and rollback.
12. Core Value Gate is binding — Before Phase 1 Discovery, define the primary actor, single user-visible outcome, minimum winning slice, explicit non-goals, and debt avoided by deferring them. If a story does not materially improve that outcome, defer it unless it is required for safety/risk containment or the user explicitly widens scope.
13. WORKGRAPH.md is post-plan only — It is an execution handoff artifact created after the 6 plan files are accepted. It may include writes, dependency edges, validation commands, and risk gates. Do not mix those execution details back into the plan files.

Questioning Strategy

Ask the user structured multi-choice questions for all binary/multi-choice decisions.

NEVER ask generic approval questions like:

• "Does this API contract look correct?"
• "Any changes needed before locking?"

INSTEAD, identify specific uncertainties and ask about those:

• "Should user_id be required or inferred from auth context?"
• "The notes field — max 500 chars or unlimited?"
• "Return full object or just { id, name }?"

If 95% confident, don't ask — just do it. Only ask when there's genuine ambiguity.

Every question MUST have a recommended option. Put it first with "(Recommended)".

Ask high-level questions first — they cascade down:

1. Core user-visible outcome → determines the minimum winning slice
2. User story scope → determines endpoints needed
3. Endpoint design → determines table structure
4. Table design → determines access control policies
5. Access control → determines frontend data access patterns

When to batch (single question set): Independent questions about the same topic. When to ask sequentially: When answer to Q1 changes what Q2 should ask.

See references/phase-questions.md for detailed question patterns per phase.

Planning Mode

Use Phases 0-6 below for spec creation, including the binding Phase 0.5 Core Value Gate. Planning outputs must explicitly map auth/payments/identity scope to existing auth service packages and capture missing functionality as auth-scope proposals instead of inventing local auth layers.

9-Phase Process

Phase	Goal	Output	Key Action
Pre	Docs freshness + build-vs-clone	Go/no-go, updated README if stale	Parallel subagents before planning
0. Landscape	Understand neighbors	Relationship summary	Read INDEX.md + sibling shared.md
0.5 Core Value Gate	Trim to the minimum winning slice	Core value summary	Cut expensive low-value scope before discovery
1. Discovery	User stories	Draft stories	Binary "A or B?" refinement
2. Contract	LOCK shared.md	Endpoints, errors	Confirm JSON shapes
3. Backend	Business rules & permissions	backend.md + schema.mmd	Read client's backend conventions
4. Frontend	Screens & interactions	frontend.md + flows.md	Read client's frontend patterns
5. Strategy	Trade-offs & justifications	plan.md	Document "why", alternatives, rejected approaches
5.5 Deep Review	Iterative refinement via apr	Revised plan files	Multi-round GPT Pro review until steady-state
6. Sign-off	Create files	All files	released/ or planned/?

---

Phase 0: Landscape

Goal: Understand where this slice fits in the ecosystem before asking a single discovery question.

Steps:

1. Read INDEX.md at {plan_index} (from client overlay)
2. Extract the tag from the user's description (e.g., "scheduling feature" → [scheduling]). If unclear, infer from the slice name or ask.
3. Find sibling slices — all INDEX.md rows with the same [tag]:
   • Same tag = same domain cluster (e.g., [protocol] → protocol-phases, protocol-actions, action_carryover)
   • Same repo tags = shared codebase (e.g., [auth-service] slices share the auth layer)
4. Read shared.md of the closest siblings — understand existing API contracts, entity shapes, and endpoint patterns the new slice will neighbor. Only read 2-3 most relevant, not all.
5. Check for explicit dependencies — INDEX.md descriptions contain "Depends:", "Prerequisite for", "extends" notes. Surface any that mention or relate to this slice.
6. Present a landscape summary to the user before discovery begins:

## Landscape: {new_slice}

**Domain cluster:** [{tag}] — {N} existing slices
**Siblings:** {list with status}
**Existing entities nearby:** {key entities from sibling schema.mmd/shared.md}
**Potential dependencies:** {any explicit or inferred}
**Potential conflicts:** {overlapping endpoints, duplicate entities}

7. Ask relationship questions (only if genuinely ambiguous):
   • "Does this extend {sibling} or is it independent?"
   • "{sibling} already has a {entity} endpoint — should this slice reference it or create its own?"

Why this matters: Without landscape, the planner risks designing API contracts that duplicate existing entities, miss foreign key relationships, or conflict with sibling endpoints. A 2-minute INDEX.md read prevents hours of rework.

---

Phase 0.5: Core Value Gate

Goal: Prevent planning debt by trimming the slice to the smallest user-visible win before discovery expands it.

Steps:

1. Name the primary actor — the role whose visible win anchors this slice.
2. Name the single user-visible outcome — one sentence describing what that actor can newly do or newly avoid.
3. Define the minimum winning slice — the smallest set of actions, states, and contract surface needed to deliver that outcome.
4. List explicit non-goals — name tempting additions to cut now:
   • admin/config surfaces
   • broad role matrices
   • reporting/export/history unless core to the win
   • abstractions for hypothetical reuse
   • edge-case completeness beyond the top safety failures
5. State the debt avoided — for each major cut, note the maintenance, coordination, or model-shift cost avoided by deferring it.
6. Apply the binding rule — if a proposed story does not materially improve the primary actor's visible win, defer it unless it is required for safety/risk containment or the user explicitly expands scope.
7. Escalate placement questions out of band — if the real uncertainty is adopt-vs-build, repo placement, or extraction, stop and use the build-vs-clone skill before continuing. Do not turn the slice plan into a repo-decision document.

Output format:

## Core Value Gate

- Primary actor: ...
- User-visible outcome: ...
- Minimum winning slice: ...
- Explicit non-goals: ...
- Debt avoided by deferring them: ...

Carry this summary into plan.md and use it to reject scope creep in Phases 1-5. Do not proceed to Phase 1 until this gate is explicit.

---

Phase 1: Discovery

Goal: Unambiguous user stories with test scenarios.

1. Check standard stories — Read ~/.claude/skills/domain-planner/references/standard-stories/ for applicable patterns. If the slice touches auth/RBAC, load rbac.md as a starting menu.
2. Start from the Core Value Gate — only keep stories that directly deliver the minimum winning slice or cover its top failure/safety cases.
3. Identify user types via multi-select question (can be multiple roles)
4. Extract stories: "As a [role], I need to [action], so that [outcome]"
5. Refine with structured questions — Probe vague terms ("all", "manage") with specific options
6. Add test scenarios per acceptance criterion
7. Cross-reference siblings — For each story, check: does a sibling slice already handle part of this? Flag overlaps.

Red flags requiring refinement:

• "All" or "everything" → narrow scope
• Vague verbs ("manage", "handle") → specific actions
• Missing edge cases → probe failure scenarios
• Story overlaps a sibling's scope → clarify boundary
• Story adds admin polish, configurability, or abstraction without improving the primary actor's visible win → defer it

---

Phase 2: API Contract

Goal: Complete shared.md that both teams implement against.

Cross-reference siblings from Phase 0:

• Reuse existing entity IDs as foreign keys (don't reinvent user_id, owner_id, enrollment_id)
• Follow sibling endpoint naming conventions (e.g., if siblings use /v1/{resource}, don't use /api/{resource})
• Reference sibling error code patterns (e.g., {SLICE}_NOT_FOUND convention)
• Do not add endpoints solely for deferred non-goals from the Core Value Gate

For each endpoint confirm: path, method, request/response shapes, error codes. Ask about specific uncertainties (not blanket approval).

After approval: "CONTRACT LOCKED. Changes require discussion."

---

Phase 3: Backend Spec

Before starting: Read the backend convention files from the client overlay (AGENTS.md, test philosophy docs).

Cross-reference siblings from Phase 0:

• Check sibling schema.mmd files for entities this slice should reference (FK relationships, not duplicated tables)
• If a sibling already owns an entity (e.g., key_insights owns the insights table), this slice should reference it, not recreate it

Questions to resolve:

• Data history requirements? (default update-in-place CRUD; only add version-chain patterns when explicitly requested)
• Access control policies? (owner-only, shared, lookup)
• Background jobs? (sync vs async for slow operations)
• FK relationships to sibling entities? (from Phase 0 landscape)

Output: schema.mmd conceptual ERD + backend.md business rules/permissions.

---

Phase 4: Frontend Spec

Before starting: Read the frontend patterns reference from the client overlay. Use client-specific template if available (e.g., frontend-{client}.md).

Skip this phase if the client overlay indicates API-only (api_only: true).

Goal: Clear picture of what each role sees and does.

Client-specific templates: Check ~/.claude/skills/domain-planner/assets/templates/frontend-{client}.md for a template tailored to the client's architecture. Client overlays may have project-specific sections (portal placement, FeatureGate config, cross-portal visibility) that the generic template lacks.

Critical Decision: Inline Widget vs Separate Page

Before defining routes, ask: "Does an existing widget already display this data type?"

If Yes	If No
Extend the widget with role-based props	Create new page/widget
Add inline actions (toggles, modals)	Define new routes

Features in resource-context views should almost always be inline widget extensions, not separate pages. Navigation breaks focus.

Client-Specific Phase 4 Questions

Use questions from the client overlay's Phase 4 guidance (if defined) instead of the generic questions in ~/.claude/skills/domain-planner/references/phase-questions.md. Client overlays can define questions tailored to the project's widget system (e.g., portal placement, widget layers, feature gating).

Specify: screens per role, interactions, states, user flows (flows.md). Do NOT specify component structure, widget primitives, or TypeScript types — those are the scaffolder's job.

---

Phase 5: Strategy

Goal: Make the "why" behind every major decision explicit and reviewable.

Document the following in plan.md:

1. Trade-offs table — For each significant design choice, list the option chosen, alternatives considered, and why the alternative was rejected. Format:

   Decision	Chosen	Alternative(s)	Why Not

2. Tech choice justifications — For each non-obvious technology, library, or pattern choice, state the constraint or goal it serves and what you'd switch to if that constraint changed.

3. Rejected approaches — Approaches that were considered and discarded during planning. Include enough detail that a future reader understands why without re-deriving the reasoning.

4. Out-of-scope items — With rationale for deferral (carry forward from Core Value Gate non-goals, plus any new deferrals from Phases 1-4).

A thin Phase 5 that says "we chose X" without saying "because Y, not Z" is incomplete. The quality rubric should penalize missing justifications.

---

Phase 5.5: Deep Review (apr)

Goal: Iterative architectural refinement using GPT Pro Extended Reasoning via apr, until suggestions converge to steady-state.

Why this phase exists: The Phase 6b quality loop checks rubric compliance (are all fields present? do contracts match?). This phase checks architectural quality — are the contracts well-designed? Are there better patterns? Did we miss failure modes? These are different concerns; rubric compliance does not imply good architecture.

Prerequisites: apr CLI installed (apr --version). If not installed, fall back to /codex:rescue (see Codex fallback below). If neither is available, skip this phase and note it was skipped.

Steps:

1. Set up the workflow (first time only):

   apr robot init   # creates .apr/ if it doesn't exist
   

   APR supports exactly 3 document slots: readme, spec, and implementation. To include the project README/vision and all slice files, bundle them before configuring:

   # Bundle project context: vision + README into one readme doc
   cat {project_repo}/docs/vision.md {project_repo}/README.md > {plan_root}/{slice}/.apr-readme.md
   # Bundle all slice files into a single spec for APR
   cat {plan_root}/{slice}/*.md > {plan_root}/{slice}/.apr-bundle.md
   

   Then write the workflow YAML directly (no interactive wizard needed):

   # .apr/workflows/{slice}.yaml
   name: {slice}
   description: "One-line description of what this slice does"
   documents:
     readme: "{plan_root}/{slice}/.apr-readme.md"  # docs/vision.md + README.md concatenated
     spec: "{plan_root}/{slice}/.apr-bundle.md"    # all slice files concatenated
   oracle:
     model: gpt-5.4-pro
     thinking_time: heavy
   rounds:
     output_dir: ".apr/rounds/{slice}"
   

   Set the default workflow in .apr/config.yaml:

   default_workflow: {slice}
   

   Create the rounds output directory: mkdir -p .apr/rounds/{slice}

   Before each apr run, re-bundle to pick up any changes:

   cat {project_repo}/docs/vision.md {project_repo}/README.md > {plan_root}/{slice}/.apr-readme.md
   cat {plan_root}/{slice}/*.md > {plan_root}/{slice}/.apr-bundle.md
   

2. Run revision rounds:

   apr run 1
   apr run 2
   ...
   

   Each round sends the current plan to GPT Pro Extended Reasoning for deep review. GPT Pro returns architectural improvements, missing edge cases, better API shapes, and performance concerns as git-diff-style changes.

3. Check convergence:

   apr stats -w {slice}
   

   Look for diminishing delta between rounds. When suggestions become incremental (cosmetic, stylistic, or repeat prior suggestions), you've reached steady-state. Typical: 3-5 rounds for focused slices, 5-7 for complex cross-cutting ones.

4. Integrate revisions after each round:

   apr integrate {round} --copy
   

   This generates a Claude Code integration prompt. Paste it and apply the revisions to the plan files in-place. For each proposed change, state whether you agree, partially agree, or disagree with rationale.

5. Coding agents can use apr robot for machine-friendly JSON output:

   apr robot stats -w {slice}    # convergence check
   apr robot integrate {round}   # get integration prompt
   

Exit criteria: Steady-state reached (apr stats shows <5% delta between rounds), OR user explicitly skips further rounds.

What this phase is NOT: It is not a replacement for Phase 6b's rubric-based quality loop. apr reviews improve the substance of the plan; the quality loop ensures structural completeness. Run both.

Codex Fallback (when apr is not installed)

If apr is unavailable but the codex-plugin-cc plugin is loaded, use /codex:rescue to get architectural review with your own prompt:

/codex:rescue --background --model gpt-5.4 --effort xhigh \
  Review the {slice} plan files in {plan_root}/{slice}/ for architectural quality. \
  Focus on: API contract design, failure modes, entity relationships, missing edge cases, \
  and whether better patterns exist. Read all 6 plan files. \
  Write suggestions as a numbered list with file, section, and proposed change. \
  Do NOT modify plan files. Do NOT score against the rubric (Phase 6b handles that).

Check progress with /codex:status, retrieve output with /codex:result. Integrate suggestions manually, then proceed to Phase 6.

---

Phase 6: Sign-off

6a. Write Plan Files

Populate all 6 required files from planning session:

• plan.md — Strategy, user stories, trade-offs
• shared.md — API contracts (endpoints, request/response shapes)
• backend.md — Business rules, permissions, edge cases
• frontend.md — Screens, interactions, states per role
• flows.md — User journeys and state transitions
• schema.mmd — REQUIRED conceptual ERD

6b. Quality Loop

Run the automated assess→fix→re-assess loop against the plan quality rubric. See quality-loop-workflow.md for the full workflow.

Assess (subagent or inline) → Parse score
├── 100/100 → skip to 6c
└── < 100 → fix issues → re-assess (max 3 rounds)

Assessor: Fresh-context subagent (Profile A) or inline re-read (Profile B) — scores all 6 files against the 10-dimension rubric (10 pts each, 100 total). Returns structured issues table with file, location, and fix instruction per deduction.

Fixer: The orchestrator itself — has full domain context from the planning session. Applies targeted fixes from the issues table, then re-launches the assessor.

Loop exit: Score = 100, or 3 iterations reached (escalate remaining issues to user).

After the loop, report the final score before proceeding.

6c. Save Location

Ask: "Save to released/ (locked) or planned/ (draft)?"

6d. Synthesize WORKGRAPH.md

After the 6 plan files are accepted and saved, populate WORKGRAPH.md as the execution handoff for downstream orchestration. This file is intentionally outside the plan-quality rubric: it exists to bridge accepted specs into parallel implementation waves.

Rules:

• One node per executable concern, not one node per tiny file edit
• Keep nodes concern-scoped: backend API, migration, frontend widget, test hardening
• Use explicit dependency IDs in depends_on
• Include writes globs or paths so parallel waves can avoid overlap
• Include done_when as binary completion criteria
• Include validate_cmds for the concrete commands the execution wave should run
• Use status values from: todo, in_progress, done, blocked, skipped
• Each node must be a self-contained brief — an agent should be able to pick up a single node and execute it without reading the full plan. Include:
  • context: 1-3 sentences of business context (why this node exists)
  • contract_excerpt: the relevant endpoint(s), entity shapes, or UI states from the plan files that this node implements — inline, not "see shared.md"
  • acceptance_criteria: specific, testable conditions (carry from plan files)
  • rationale: why this concern is a separate node (dependency reason, isolation reason, or parallelism reason)

The goal is independently executable briefs, not a task index that requires cross-referencing plan files. A node without embedded context forces the implementing agent to re-derive intent from the full plan, which defeats the purpose of the graph.

WORKGRAPH.md must stay concise per node but self-contained. It is not a second plan document and it is not a changelog — it is a bag of executable briefs.

README update node: If the Pre-Planning Prerequisites phase determined this slice changes the project's feature set or competitive positioning, add a final-wave readme-update node with no implementation dependencies blocked on it. Its context should summarize what changed, and its execution should invoke the readme-writing skill. This ensures documentation stays current after implementation, not just before planning.

6e. Handoff

Handoff: "Ready to implement? Run the domain-planner skill and select 'Implement it'"

External review (optional): Use /codex:rescue to get an independent second opinion after the quality loop passes:

/codex:rescue --background --model gpt-5.4 --effort xhigh \
  Review the {slice_name} plan in {plan_root}/{slice_name}/ against \
  the rubric at ~/.claude/skills/domain-planner/references/plan-quality-rubric.md. \
  Score all 10 dimensions (10 pts each, 100 total). \
  Write REVIEW.md in the plan directory. Do not modify plan files.

Check with /codex:status, retrieve with /codex:result. The review_plan.py script remains available as a standalone fallback (python3 ~/.claude/skills/domain-planner/scripts/review_plan.py --slice {slice_name} --execute).

---

Quality Assessment Mode

When user selects "Check plan quality", run the Phase 6b quality loop as a standalone mode using references/quality-loop-workflow.md.

In this mode, Scope Discipline is not just generic anti-creep checking: it must explicitly grade whether the plan preserves the Phase 0.5 Core Value Gate and represents the highest-best-use 80/20 slice for the primary actor's visible win.

Auth service checks are mandatory in quality assessment mode for auth/payments/identity slices:

1. Confirm plan files use existing auth service packages from {auth_packages_root} (resolved from client overlay).
2. Confirm any missing package capability is documented as an auth-scope proposal.
3. Confirm temporary local symlink/link usage (if needed for unpublished versions) includes final validation against published/live auth service packages.

Orchestration Mode

When user selects "Implement it" for an existing plan, become the orchestrator agent.

Auth service enforcement is mandatory in orchestration mode:

1. Treat {auth_packages_root} as the auth/payments/identity source of truth.
2. Require scaffolder agents to reuse existing auth service packages before writing custom auth/payments/identity logic.
3. If an auth service gap is discovered, pause custom replacements and return an auth-scope proposal to the user.
4. If unpublished auth service changes are needed locally, use temporary symlink/link workflow first, then re-validate with published/live auth service packages before marking DONE.

See references/orchestration-workflow.md for the full workflow.

Overview

┌─────────────────────────────────────────────────────────┐
│  ORCHESTRATOR (this agent)                               │
│  Owns: progress checklist, agent coordination            │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  1. Analyze plan to determine scope (which repos)        │
│  2. Launch scaffolder agents (parallel, one per repo)    │
│  3. Wait for completion                                  │
│  4. Launch audit agent (domain-reviewer)                 │
│  5. If issues: launch fix agents, re-audit               │
│  6. Loop until COMPLIANT (100/100)                       │
│  6b. Hardening gate: /crap → /mutate (score ≤ 30)       │
│  7. Update INDEX.md to DONE                              │
│                                                          │
└─────────────────────────────────────────────────────────┘

Agent Coordination

1. Analyze plan scope — Read plan.md and the client overlay's repo configuration to determine which repos need work.

2. Initialize progress checklist — One item per repo + audit + completion.

3. Launch parallel agents, one per repo involved:

   • Backend repos → each agent uses the domain-scaffolder skill with surface=backend
   • Frontend repos → each agent uses the domain-scaffolder skill with surface=frontend
   • Each agent works in its own repo with its own conventions
   • Use the divide-and-conquer pattern: scope by concern, not files

4. After scaffolding completes, launch an audit agent using the domain-reviewer skill in audit mode.

5. Handle audit results:

   • COMPLIANT (score = 100/100) → proceed to hardening gate (step 6b)
   • Issues found → extract handoffs from AUDIT_REPORT.md, launch fix agents only for repos with issues

6. Re-audit loop — Max 5 attempts with stall triage, then escalate with a specific blocker report.

6b. Hardening gate (/crap score check) — After audit convergence (100/100 COMPLIANT), launch a background subagent to assess structural quality before retirement:

Audit 100/100 → /crap hardening gate → retire

Subagent prompt:

Run /crap against the files touched by this slice across all repos involved. If FINAL_SCORE > 30, run /mutate on the top 3 hotspots and add tests until FINAL_SCORE drops to 30 or below. Report: pass (score ≤ 30) or fail (score > 30 after hardening) with the final score and any surviving hotspots.

Gate rules:

• Pass (FINAL_SCORE ≤ 30): Proceed to step 7 (completion/retirement).
• Fail after hardening (FINAL_SCORE > 30): Report surviving hotspots to the user with the score and file list. Ask whether to (a) accept current score and proceed to retirement, or (b) launch targeted fix agents for the hotspots.
• Scope: Only score files that were created or modified by this slice's scaffolding — do not score the entire repo. Use the writes globs from WORKGRAPH.md nodes to determine scope.
• Skip condition: If the user passed --skip-hardening or explicitly says to skip, proceed directly to step 7.

This gate catches high-complexity/low-coverage code before it gets retired and forgotten. The /crap + /mutate combination targets the riskiest code paths with mutation testing, ensuring test coverage is meaningful (not just line coverage).

7. Completion — Update INDEX.md status to DONE, report results to user (including final CRAP score if hardening gate ran).

---

Templates

See ~/.claude/skills/domain-planner/assets/templates/ — copied automatically by ~/.claude/skills/domain-planner/scripts/init_slice.py.

Related Skills

• domain-scaffolder — Generate backend or frontend code from plan using the explicit surface selection
• domain-reviewer — Audit implementation against plan, retire completed slices
• divide-and-conquer — Decompose multi-agent work into independent parallel concerns