domain-planner

name	domain-planner
description	Plan new multi-repo domain slices, assess plan quality, or orchestrate implementation from an accepted slice plan. Use for "plan the X slice", multi-repo feature planning, API contract design, "implement the X slice", or slice-quality review; not for bug fixes, small refactors, or single-repo work. When a slice premise depends on live external reality rather than internal repo evidence, run a bounded GPT-5 Pro / Deep Research gate before committing to the plan.
license	MIT
metadata	{"requires_beads":true}

Domain Planner

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

First Progress Marker (Required)

Start the first progress update with the exact prefix Using domain-planner.

Preferred format: Using domain-planner to <goal>. First I will <next concrete step>.

Do not change or omit that prefix.

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.

Accepted slice execution routes through /divide-and-conquer. domain-planner may define the slice, mint the accepted br epic/child issues, and name the needed domain-scaffolder/domain-reviewer handoffs, but /divide-and-conquer owns the ready frontier, claims, worker waves, and status updates once implementation begins.

Operator Companion Gates

Use _shared/references/domain-companion-gates.md for the optional operator-level gates around this public skill.

• Use no-ragrets at slice start to define future outcome, evidence, and failure avoided before locking the plan premise.
• Use reality-check-for-project before new plan work when existing code, roadmap docs, plans, or Beads may already cover or contradict the slice.
• Use beads-workflow after plan acceptance to convert the accepted slice into a self-contained br epic and child graph.
• Use beads-br for concrete br lifecycle mechanics and beads-bv to check ready frontier, graph health, priority, and blockers before /divide-and-conquer executes the graph.

These companion skills may be operator-private or globally installed. Do not add them as hard public depends_on entries unless this skill is being wrapped or overlaid for an operator-private environment.

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

Before manual rg/sed/find inspection, capture the active overlay and slice-plan state with the shared context snapshot helper:

python3 ~/.claude/skills/_shared/scripts/domain_context_snapshot.py --cwd "$PWD" --slice {slice_name} --pretty

Use the JSON output to identify plan roots, repo paths, convention references, missing overlay sections, required plan-file presence, and workflow artifacts. Only fall back to freehand shell inspection for concrete files the snapshot surfaces as relevant.

Git Step Guard

Before any workflow step runs git, resolve the target repository from the client overlay or explicit handoff and prove that path is inside a git repo:

target_repo="${target_repo:-$PWD}"
if git -C "$target_repo" rev-parse --git-dir >/dev/null 2>&1; then
  repo_root="$(git -C "$target_repo" rev-parse --show-toplevel 2>/dev/null || printf '%s\n' "$target_repo")"
else
  printf 'Skipping git step: %s is not a git repository. Resolve the target repo from the client overlay or pass an explicit repo path.\n' "$target_repo"
  repo_root=""
fi

Only run git with git -C "$repo_root" ... when repo_root is non-empty. If the current directory is a repo-collection parent such as /srv/skillbox/repos, select the intended repo from the overlay first; if it cannot be resolved, skip the git-dependent check and report that skip clearly.

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) — route delegated checks through /divide-and-conquer when they run in parallel
   • 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, unexamined build-vs-clone questions, and externally unverified market/regulatory assumptions create downstream rework.

Route the prerequisite worker issues that apply through /divide-and-conquer. A and B always run. C runs only when the slice is externally gated. If the work is kept in-process because it is tiny, say so explicitly.

Subagent A: Build-vs-Clone Assessment

Invoke the build-vs-clone skill through /divide-and-conquer 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:

   target_repo="{repo_from_client_overlay}"
   if git -C "$target_repo" rev-parse --git-dir >/dev/null 2>&1; then
     repo_root="$(git -C "$target_repo" rev-parse --show-toplevel 2>/dev/null || printf '%s\n' "$target_repo")"
     readme_commit="$(git -C "$repo_root" log --format="%H %ai" -1 -- README.md)"
     if [ -n "$readme_commit" ]; then
       git -C "$repo_root" diff "${readme_commit%% *}"..HEAD --name-only
     else
       printf 'Skipping README drift diff: README.md has no git history in %s.\n' "$repo_root"
     fi
   else
     printf 'Skipping README drift git check: %s is not a git repository.\n' "$target_repo"
   fi
   

   to get all files changed since the last README commit. Assess whether those changes (new features, removed features, API changes, dependency changes) make the current README inaccurate. If the repo cannot be resolved, record the clear skip message instead of running a bare git command.

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 → route a /divide-and-conquer Bead for the readme-writing skill, passing it the list of drifted sections and the diff summary. Wait for readme-writing to complete before returning.

Subagent C: External Reality Gate via escalate (conditional)

Run this only when the slice's go/no-go depends on current outside facts rather than local repo inspection. Typical triggers:

• the slice changes target buyer, pricing, packaging, or competitive wedge
• the slice depends on current vendor/platform motion or ecosystem viability
• the slice relies on regulatory or compliance assumptions that may have changed
• the slice's business value depends on 2024-2026 market structure, buyer behavior, or incumbent weakness

Routing rules:

1. Invoke escalate with caller: domain-planner, the slice name, the decision at risk, internal evidence already checked, and the exact external unknown.
2. If escalate returns route: thesis-gtm, run thesis-gtm --skip-vision for the affected product. This is forced when the uncertainty is strategic positioning, ICP, wedge, GTM, target buyer, pricing, packaging, or customer promise.
3. If escalate returns route: deep-research-prompt, run the bounded Oracle handoff for narrow vendor, regulation, platform, API, or adjacent-market facts.
4. If escalate returns route: web-check, answer the bounded question with a short current-source check and cite the result in the plan.
5. If escalate returns skip, record the skip reason under pre-planning artifacts and continue. If it returns too-broad, narrow the external question before Phase 0.
6. If a wiki vault exists and the gate did not already file through thesis-gtm, distill the result to _sources/notes/domain-planner-<slice>-<date>.md and run /wiki ingest before Phase 0.

Wait for Subagent C before proceeding when it runs. If it invalidates the slice premise, halt planning and surface the contradiction to the user.

After Prerequisite Workers 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 external reality gate ran, record the note/session artifact under "Pre-planning artifacts" and carry any newly surfaced constraints or invalidated assumptions into Phase 0 and Phase 0.5.
• If the new slice materially changes the project's competitive positioning or feature set, carry a README update issue requirement into Phase 6e so the post-sign-off br epic gets a final-wave documentation issue (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
│   └── review.mmdx
└── ...

{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. review.mmdx is REQUIRED at human checkpoints — generate it from the current plan when a human is being asked to approve, revise, block, or choose save location. It is a checkpoint mirror, not a canonical plan file. The execution graph lives in br — do not scaffold or hand-edit WORKGRAPH.md. A WORKGRAPH.md may be rendered after Phase 6e only as a generated, throwaway view of the br epic.

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. The br epic replaces WORKGRAPH as the execution graph — After the 6 plan files pass Phase 5.5 deep review, reach Phase 6b 100/100 through a fresh worker, and are accepted, mint a br epic for the slice with one child issue per execution node (writes, deps, validation, model route, risk live there as --design/--notes/--acceptance-criteria/labels per _shared/references/beads-contract.md). Do not create, edit, or consume WORKGRAPH.md as source state. If a human-readable WORKGRAPH.md is useful, render it from br after the epic exists and treat it as disposable. Hand execution to /divide-and-conquer against that epic instead of launching ad hoc parallel workers from this skill.
14. review.mmdx is the human checkpoint surface — Before any human sign-off, build/update review.mmdx from all current plan files using the mmdx skill's chart-stacking contract and the opinionated structure in references/mmdx-review-checkpoint.md. The MMDX must expose every decision-grade detail through linked charts: core value, stories, endpoints, errors, schema, backend rules, frontend states, flows, decisions, non-goals, risks, open questions, performance envelopes, and the post-sign-off br epic/child-issue handoff when present.

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	D&C prereq workers 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 + human checkpoint	All files + review.mmdx	Quality loop, MMDX drilldown, 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 or Fresh Worker)

Goal: Iterative architectural refinement using GPT Pro Extended Reasoning via apr or a fresh-context review worker, 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) or /divide-and-conquer with a fresh-worker substrate. Use runtime-native subagents or /codex:rescue only when selected as the worker transport behind that orchestration path. If no fresh-worker substrate is available, stop and surface the missing prerequisite. Do not replace this phase with in-process self-review.

Gate: Phase 5.5 must finish before Phase 6b. Phase 6e must not mint a br epic, and no optional WORKGRAPH.md view may be rendered, until Phase 5.5 has either reached steady-state or the user explicitly records an override. An override can save a draft but must not silently start execution.

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.6-sol
     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 the fresh worker reports no material architectural changes), OR user explicitly records an override and the plan remains draft-only.

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.

Fresh-Worker Fallback (when apr is not installed)

If apr is unavailable, launch a fresh reviewer through the active worker substrate. Use /codex:rescue when the codex-plugin-cc plugin is loaded:

/codex:rescue --background --model gpt-5.6-sol --effort medium \
  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.

For other worker substrates, use the same prompt and require a file/section-specific suggestions list. The reviewer must not modify plan files and must not score the rubric; Phase 6b handles rubric scoring separately.

---

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 (fresh worker) → Parse score
├── 100/100 → skip to 6c
└── < 100 → fix issues → re-assess (max 3 rounds)

Assessor: Fresh-context worker launched through /divide-and-conquer/NTM. If no worker substrate is available, stop and surface the missing prerequisite instead of assessing in-process. The assessor scores all 6 files against the 10-dimension rubric (10 pts each, 100 total) and returns a 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. If 3 iterations are reached below 100, run stall triage and escalate the remaining issues to the user; do not proceed to Phase 6c/6d/6e until a fresh worker returns 100/100 or the user explicitly records a sub-100 override. A sub-100 override may save a draft, but it must not mint the execution epic.

After the loop, report the final score before proceeding. Phase 6e is blocked unless the score is 100/100.

6c. Human Checkpoint MMDX Review

Before asking a human to approve, revise, block, or choose the save location, create/update {plan_root}/{slice}/review.mmdx as the review surface. Use the mmdx skill, specifically its chart-stacking guidance, references/diagram-selection.md, and references/visual-grammar.md.

Use references/mmdx-review-checkpoint.md as the required structure. The MMDX entry chart must be a decision surface with a visible READY, REVISE, or BLOCKED conclusion; linked child charts must carry every decision-grade detail from the six plan files; and the visual grammar must preserve chart-crimes-style honesty with source disclosure, status labels, visible caveats, and no color-only meaning.

cp ~/.claude/skills/domain-planner/assets/templates/review.mmdx {plan_root}/{slice}/review.mmdx
python3 ~/.claude/skills/mmdx/scripts/mmd.py {plan_root}/{slice}/review.mmdx --preflight-only
python3 ~/.claude/skills/mmdx/scripts/mmd.py {plan_root}/{slice}/review.mmdx --open

Do not continue to save-location sign-off until the MMDX preflight passes and the human checkpoint is presented with the path/URL.

6d. Save Location

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

6e. Mint the br Epic and Child Issues

After Phase 5.5 deep review is complete, Phase 6b returns 100/100 from a fresh worker, and the 6 plan files are accepted and saved, mint the slice's execution graph in br (beads_rust). The epic + child issues are the durable source of truth for downstream orchestration; an optional WORKGRAPH.md is only a regenerable view. The cross-skill contract (naming, labels, lifecycle, attribution, commit policy) lives in _shared/references/beads-contract.md.

Bootstrap once per repo (idempotent):

python3 ~/.claude/skills/_shared/scripts/br_helpers.py ensure
export BR_AGENT_NAME=domain-planner BR_HARNESS=claude-code BR_MODEL="$CLAUDE_MODEL"

Install contract: filtered skill installs that include domain-planner must also ship the sibling _shared/ bundle. Helper resolution prefers <skills-root>/_shared/scripts beside the resolved domain-planner skill and falls back to ~/.claude/skills/_shared/scripts; if neither exists, the helper prints both expected locations and the install requirement.

Mint the epic, then one child issue per executable concern:

EPIC=$(br create "{slice}: {one-line value}" --slug epic-{slice} --type epic --priority 1 --json | jq -r .id)

python3 ~/.claude/skills/_shared/scripts/br_helpers.py mint-node \
  exec-001-{kebab-title} '{Title}' \
  --epic "$EPIC" \
  --concern {backend-api|frontend-widget|migration|test-hardening|...} \
  --repo {repo-slug} \
  --writes 'src/domain/{slice}/**' --writes 'tests/{slice}/**' \
  --done-when '{binary completion check}' \
  --validate '{repo-native test command}' \
  --model-route '{Grok 4.5 NTM orchestrator|Codex gpt-5.6-sol medium|Codex gpt-5.6-sol max escalation|Codex gpt-5.6-terra ultra fallback|Grok 4.5 design/UX|Grok 4.5 task-runner|Grok dispatcher|Grok CLI sidecar}' \
  --risk {none|human|external} \
  --depends-on {parent-issue-id}  # repeat for each dependency

Rules per node:

• One node per executable concern, not one node per tiny file edit
• Keep nodes concern-scoped: backend API, migration, frontend widget, test hardening
• --depends-on carries explicit dependency IDs; cycles are rejected by br dep
• --writes globs prevent parallel-wave overlap
• --done-when becomes the issue's acceptance_criteria field
• --validate lines become notes for the worker to run
• --model-route is required before handoff:
  • use Grok 4.5 NTM orchestrator only for accepted-frontier dispatch, tending, harvest, and convergence; it never edits this plan
  • use Codex gpt-5.6-sol medium for ordinary no-ragrets bead composition, domain-planner follow-up, decomposition/synthesis, system design, architecture, high-impact code, integration review, commit acceptance, and final-say nodes; use Codex gpt-5.6-sol max escalation for pivotal planning or when another model is struggling; if SOL is unavailable use Codex gpt-5.6-terra ultra fallback
  • use Grok 4.5 design/UX for UI/UX, visual design, design systems, CSS/tokens, screenshot parity, and fresh-eyes design review; use Codex gpt-5.6-sol max for pivotal route-blocker triage; ordinary authority stays on SOL medium
  • prefer Grok 4.5 task-runner for bounded scripting, docs, fixtures, generated-command cleanup, classification artifacts, deterministic codemods, or $commit nodes with exact write scope or a read-only artifact, validation, stop rules, Codex gpt-5.6-sol final review, and final authority (Terra ultra fallback when SOL is unavailable); escalate to Codex if the runner stalls, drifts, or cannot validate
  • use Grok dispatcher or Grok CLI sidecar only for routing/preflight or read-only evidence artifacts
• Status flows through br update --claim → br update -s blocked → br close
• Each node must be a self-contained brief — an agent should be able to pick up a single issue and execute it without reading the full plan. After minting, populate --description (or br update --description) with:
  • 1-3 sentences of business context (why this node exists)
  • the relevant endpoint(s), entity shapes, or UI states from the plan files this node implements — inline, not "see shared.md"
  • rationale for why this concern is a separate node (dependency, isolation, or parallelism reason)

The goal is independently executable issues, 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.

If a markdown view is useful for human scanning, render an optional WORKGRAPH.md view inside the run directory used by downstream orchestration:

python3 ~/.claude/skills/_shared/scripts/br_helpers.py render-workgraph \
  --epic "$EPIC" --out {run_dir}/WORKGRAPH.md
echo "$EPIC" > {run_dir}/EPIC_ID.txt

Do not edit the rendered file by hand and do not feed it back as source state. All execution updates happen through br update, br close, dependencies, and issue fields.

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

6f. Handoff

Handoff: "Ready to implement? Run /divide-and-conquer for the minted {slice} br epic and follow its ready frontier."

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

/codex:rescue --background --model gpt-5.6-sol --effort medium \
  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 diagnostic (python3 ~/.claude/skills/domain-planner/scripts/review_plan.py --slice {slice_name} --execute), but it does not replace the fresh-worker Phase 6b gate.

---

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, hand the accepted plan's br epic to /divide-and-conquer. This skill supplies the slice contract and domain-specific worker prompts; /divide-and-conquer is the orchestrator for Beads frontier selection, worker dispatch, claims, fix waves, hardening issues, and status updates.

Implementation mode is an end-to-end delivery run. Do not one-shot the first implementation pass and return a partial plan or partial progress report. Carry the accepted slice through scaffolding, fresh-context audit/re-review loops, hardening, retirement, and commit batching unless a blocker requires a human decision.

Use fresh eyes through /divide-and-conquer/NTM:

• initial domain-reviewer audit runs in a fresh worker
• each post-fix re-review runs in a fresh worker
• high-risk or cross-repo slices get a separate hardening/review worker before retirement

If the worker substrate is unavailable, stop and surface that missing prerequisite. Do not replace these review gates with local self-review.

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 (/divide-and-conquer)                      │
│  Owns: br frontier, claims, worker waves, status         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  1. Analyze plan to determine scope (which repos)        │
│  2. Claim ready br issues and launch scoped workers      │
│  3. Wait for completion                                  │
│  4. Claim audit issue (domain-reviewer)                  │
│  5. If issues: mint/claim fix Beads, re-audit            │
│  6. Loop until COMPLIANT (100/100)                       │
│  6b. Hardening gate: /crap → /mutate (score ≤ 30)       │
│  7. Retire slice, batch commits, report validation        │
│                                                          │
└─────────────────────────────────────────────────────────┘

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 tracking — Use the slice's br epic and child issues as the durable tracker. A checklist is only a rendered view.

3. Route parallel work through /divide-and-conquer:

   • 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
   • Scope by concern, not files; /divide-and-conquer verifies disjoint writes before launching a ready wave

4. After scaffolding completes, route the audit issue through /divide-and-conquer 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 and mint each finding as a br issue under the slice's epic:

     python3 ~/.claude/skills/_shared/scripts/br_helpers.py mint-node \
       finding-{kebab-summary} '{Finding title}' \
       --epic "$EPIC" --type bug --priority 1 \
       --concern audit-fix --repo {repo} \
       --depends-on {parent-node-id} \
       --done-when '{verification step from AUDIT_REPORT.md}'
     

     Then let /divide-and-conquer claim and dispatch the ready fix issues only for repos with issues; each fix worker uses the standard --claim / --close --suggest-next lifecycle.

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), mint or claim a hardening issue and route it through /divide-and-conquer 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 the slice's br child issues plus a guarded git diff after git -C "$target_repo" rev-parse --git-dir >/dev/null 2>&1 succeeds; if the repo cannot be resolved, report the skip clearly.
• 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 — Retire the slice via domain-reviewer, verify INDEX.md is DONE, run the commit skill for every touched repo, and report results to the user (including final audit score, final CRAP score if hardening ran, validation commands, commit SHAs, and any explicit leftovers).

---

Templates

See ~/.claude/skills/domain-planner/assets/templates/. Initial plan templates are copied automatically by ~/.claude/skills/domain-planner/scripts/init_slice.py; review.mmdx is copied/filled during the Phase 6c human checkpoint.

Related Skills

• [[skill-issue]]
• 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
• no-ragrets — Optional operator gate for future-success, evidence, and regret-avoidance checks.
• reality-check-for-project — Optional operator gate for code/docs/Beads strategic alignment before planning or closeout.
• beads-workflow — Optional operator gate for plan-to-br graph conversion and polish.
• beads-br — Optional operator gate for br issue lifecycle mechanics.
• beads-bv — Optional operator gate for Beads graph health, priority, and ready-frontier review.
• escalate — Owns the external-reality gate for Subagent C and routes to thesis-gtm, deep-research-prompt, web-check, or skip.
• thesis-gtm — Destination chosen by escalate when the slice premise is really a product-thesis / buyer / GTM question.
• deep-research-prompt — Destination chosen by escalate for narrower live external unknowns that need an Oracle-ready prompt plus execution wrapper.
• mmdx — Owns Mermaid/MMDX chart-stack authoring, preflight, encoding, and opening for the human checkpoint review surface.
• chart-crimes — Supplies the persuasive-but-truthful visual grammar for decision-grade review charts: verdict titles, direct labels, status color, source disclosure, and caveats.

Verification / Closeout Contract

For skill-contract edits, rerun:

python3 skill-issue/scripts/quick_validate.py domain-planner

Before returning, confirm all of the following:

1. The plan path and mode were resolved before planning/orchestration advice.
2. Pre-planning prerequisites report build-vs-clone, docs freshness, and the external reality gate as used, skipped, or not applicable.
3. If the external reality gate ran, the response names the escalate route (thesis-gtm, deep-research-prompt, web-check, skip, or too-broad), plus the note/session artifact it produced.
4. If a wiki vault existed and the gate surfaced durable findings, _sources/notes/ + /wiki ingest status is explicit.
5. Architectural review (apr or fallback) is reported as used, skipped, or unavailable rather than implied.
6. For any human checkpoint, review.mmdx is generated/updated, validated with the mmdx preflight command, and presented as the review drilldown artifact.