Domain Planner

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

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

Plan Storage (Mode-Defined)

Plan storage is defined by the active mode file (~/.claude/skills/domain-planner/modes/{mode}.md):

plan_root: <mode value>
plan_draft: <mode value>
plan_index: <mode value>
session_plans: <mode value>

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

Modes (Implementation Context)

Modes provide implementation-specific context — which repos to scaffold, what conventions to follow.

Check ~/.claude/skills/domain-planner/modes/ for project-specific configuration. Each mode defines:

cwd_match — directory pattern for auto-detection
Repos — frontend, backend, auth repo names and paths
Convention files — AGENTS.md locations, frontend patterns reference
Stack — backend framework, frontend framework, migration tool

If no mode matches the current directory:

You can still read/create plans if you provide explicit plan paths.
For implementation (orchestration mode), list available modes (from ~/.claude/skills/domain-planner/modes/*.md filenames) and ask the user which to use.
DO NOT search the filesystem. DO NOT spawn Explore agents.

See references/mode-template.md for the mode file format.

Auth Service Requirements (All Modes)

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

Use existing auth service packages first. Do not design or scaffold parallel auth/payments/identity implementations when the auth service already covers the capability.
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.
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

Detect project context from mode file (match CWD to cwd_match patterns).
If slice name not provided, ask: "What's the slice name (snake_case) and one-sentence business value?"
Check if plan already exists at mode-defined {plan_root}/{slice}/plan.md:

If plan does NOT exist:
- Run python3 ~/.claude/skills/domain-planner/scripts/init_slice.py {slice_name} --config {mode_file} to scaffold files
- Begin Phase 0 landscape (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 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

Plan Location

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

{plan_draft}/
└── {slice}/

{plan_root}, {plan_draft}, and {plan_index} come from the active mode file.

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

Critical Rules

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.
Binary refinement — Every user story gets "A or B?" questions with reasoning until unambiguous.
Test cases inline — Each acceptance criterion includes test scenarios (happy path + error cases).
schema.mmd is MANDATORY — Other files reference it for entity relationships.
Just-in-time reading — Read the mode's convention files before each phase.
Explicit handoffs — Reference domain-scaffolder-backend, domain-scaffolder-frontend, domain-reviewer by name.
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.
Mode-specific templates — Use ~/.claude/skills/domain-planner/assets/templates/frontend-{mode}.md when available (e.g., frontend-{mode}.md for mode-specific slices). Fall back to generic frontend.md.
Performance envelopes are binding — When a mode defines performance constraints, convert each target into explicit acceptance criteria and test scenarios across plan files.
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.
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.

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:

User story scope → determines endpoints needed
Endpoint design → determines table structure
Table design → determines access control policies
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. 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.

7-Phase Process

Phase	Goal	Output	Key Action
0. Landscape	Understand neighbors	Relationship summary	Read INDEX.md + sibling shared.md
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 mode's backend conventions
4. Frontend	Screens & interactions	frontend.md + flows.md	Read mode's frontend patterns
5. Strategy	Trade-offs	plan.md	Document "why"
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:

Read INDEX.md at mode-defined {plan_index}
Extract the tag from the user's description (e.g., "scheduling feature" → [scheduling]). If unclear, infer from the slice name or ask.
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)
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.
Check for explicit dependencies — INDEX.md descriptions contain "Depends:", "Prerequisite for", "extends" notes. Surface any that mention or relate to this slice.
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}

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 1: Discovery

Goal: Unambiguous user stories with test scenarios.

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.
Identify user types via multi-select question (can be multiple roles)
Extract stories: "As a [role], I need to [action], so that [outcome]"
Refine with structured questions — Probe vague terms ("all", "manage") with specific options
Add test scenarios per acceptance criterion
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

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)

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 mode's backend convention files (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 mode's frontend patterns reference. Use mode-specific template if available (e.g., frontend-{mode}.md).

Skip this phase if the mode indicates API-only (no frontend).

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

Mode-specific templates: Check ~/.claude/skills/domain-planner/assets/templates/frontend-{mode}.md for a template tailored to the mode's architecture. Modes 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.

Mode-Specific Phase 4 Questions

Use the questions from the mode file's "Phase 4 Questions" section instead of the generic questions in ~/.claude/skills/domain-planner/references/phase-questions.md. Mode files 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

Document trade-offs table and out-of-scope items with rationale.

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

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

External review (optional): python3 ~/.claude/skills/domain-planner/scripts/review_plan.py --slice {slice_name} --execute launches a Codex-based review using the same rubric. Use this for an independent second opinion after the quality loop passes.

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.

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

Confirm plan files use existing auth service packages from {auth_packages_root}.
Confirm any missing package capability is documented as an auth-scope proposal.
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:

Treat {auth_packages_root} as the auth/payments/identity source of truth.
Require scaffolder agents to reuse existing auth service packages before writing custom auth/payments/identity logic.
If an auth service gap is discovered, pause custom replacements and return an auth-scope proposal to the user.
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                                 │
│  7. Update INDEX.md to DONE                              │
│                                                          │
└─────────────────────────────────────────────────────────┘

Agent Coordination

Analyze plan scope — Read plan.md and the mode's repo configuration to determine which repos need work.
Initialize progress checklist — One item per repo + audit + completion.
Launch parallel agents, one per repo involved:
- Backend repos → each agent uses the domain-scaffolder-backend skill
- Frontend repos → each agent uses the domain-scaffolder-frontend skill
- Each agent works in its own repo with its own conventions
- Use the divide-and-conquer pattern: scope by concern, not files
After scaffolding completes, launch an audit agent using the domain-reviewer skill in audit mode.
Handle audit results:
- COMPLIANT (score ≥90%) → mark done, update INDEX.md
- Issues found → extract handoffs from AUDIT_REPORT.md, launch fix agents only for repos with issues
Re-audit loop — Max 3 attempts, then ask the user how to proceed.
Completion — Update INDEX.md status to DONE, report results to user.

Templates

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

Related Skills

domain-scaffolder-backend — Generate TDD-first backend code from plan
domain-scaffolder-frontend — Generate pattern-adherent frontend code from plan
domain-reviewer — Audit implementation against plan, retire completed slices
divide-and-conquer — Decompose multi-agent work into independent parallel concerns