/spec-kitty.plan - Create Implementation Plan
Version: 0.11.0+
📍 WORKING DIRECTORY: Stay in the repository root checkout
IMPORTANT: Plan works in the repository root checkout. NO worktrees created.
# Run from project root (same directory as /spec-kitty.specify):
# You should already be here if you just ran /spec-kitty.specify
# Creates:
# - kitty-specs/<mission_slug>/plan.md → In repository root checkout
# (the NNN- prefix in the directory listing is display-only metadata)
# - Commits to target branch
# - NO worktrees created
Do NOT cd anywhere. Stay in the repository root checkout.
Mission Handle Rule
/spec-kitty.plan operates on an existing mission, so use --mission <handle>
when the CLI needs a mission selector.
<handle> can be the mission's mission_id (ULID), mid8 (first 8 chars of
the ULID), or mission_slug.
- Prefer
mission_id or mid8 when the repo has multiple similarly named
missions.
- The resolver disambiguates by
mission_id and returns a structured
MISSION_AMBIGUOUS_SELECTOR error on ambiguity — there is no silent fallback.
User Input
The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after /spec-kitty.<command> or $spec-kitty.<command>) is the User Input referenced elsewhere in these instructions.
You MUST consider this user input before proceeding (if not empty).
Commit Boundary (issue #846)
/spec-kitty.plan will refuse to advance the plan phase unless two
gates pass:
Entry gate. spec.md must already be both committed (tracked +
present at HEAD) and substantive (at least one populated FR-###
row — not just template placeholders). If either check fails, the CLI
returns phase_complete=false with a blocked_reason naming "committed
AND substantive" and does not create or commit plan.md.
Exit gate. plan.md is only auto-committed when its Technical Context
section contains a real Language/Version value (and at least one peer
field) — not the [e.g., …] / [NEEDS CLARIFICATION …] placeholders. If
the plan is left as scaffold, it stays untracked on disk and the CLI
returns phase_complete=false with a substantive-plan blocked_reason.
Section presence is the only signal — adding arbitrary prose without the
required structural rows does not count as substantive (no byte-length
escape hatch).
To advance: populate the Technical Context with real values, then re-run
spec-kitty agent mission setup-plan --json. The substantive plan will be
auto-committed and phase_complete will report true.
Reference: kitty-specs/charter-e2e-827-followups-01KQAJA0/contracts/specify-plan-commit-boundary.md.
Branch Strategy Confirmation (MANDATORY)
Before asking planning questions or generating artifacts, you must make the branch contract explicit.
- Never describe the landing branch vaguely. Always name the actual branch value.
- If the user says the feature should land somewhere else, stop and resolve that before writing
plan.md.
- You must repeat the branch contract twice during this command:
- immediately after parsing
setup-plan --json
- again in the final report before suggesting
/spec-kitty.tasks
Charter Context Bootstrap (required)
Before planning interrogation, load charter context for this action:
spec-kitty charter context --action plan --json
- If JSON
mode is bootstrap, apply JSON text as first-run governance context and follow referenced docs as needed.
- If JSON
mode is compact, continue with condensed governance context.
Location Check (0.11.0+)
This command runs in the repository root checkout, not in a worktree.
- Resolve branch context from deterministic JSON output, not from
meta.json inspection:
- Run
spec-kitty agent mission setup-plan --mission <mission-slug> --json
- Use
current_branch, target_branch / base_branch, and planning_base_branch / merge_target_branch (plus uppercase aliases) from that payload
- Use
branch_matches_target from that payload to detect branch mismatch; do not probe branch state manually inside the prompt
- Planning artifacts live in
kitty-specs/<mission_slug>/ (the NNN- prefix is display-only metadata)
- The plan template is committed to the target branch after generation
Path reference rule: When you mention directories or files, provide either the absolute path or a path relative to the project root (for example, kitty-specs/<mission>/tasks/). Never refer to a folder by name alone.
Agent Context Files (do not mutate)
This command does not update agent-specific context files.
- Do not search for or mutate
CLAUDE.md, AGENTS.md, or similar
agent-specific files as part of /spec-kitty.plan.
- Do not hunt for updater scripts or imaginary
spec-kitty agent context update
commands. No supported context-update command exists in this release.
- Planning outputs are the mission planning artifacts only:
plan.md
research.md
data-model.md
contracts/
quickstart.md
occurrence_map.yaml when bulk-edit planning applies
Decision Moment Protocol
Before asking any clarifying question during plan elaboration, you MUST:
Run spec-kitty agent decision open to mint a decision_id:
spec-kitty agent decision open \
--mission <mission-slug> \
--flow plan \
--slot-key plan.<section>.<question-slug> \
--input-key <snake_case_key> \
--question "<question text>" \
[--options '["option1","option2","Other"]']
Capture the returned decision_id from the JSON output.
Ask the question to the user in chat.
After the user answers, run exactly one of:
- Resolved:
spec-kitty agent decision resolve <decision_id> --mission <slug> --final-answer "<answer>"
- Deferred:
spec-kitty agent decision defer <decision_id> --mission <slug> --rationale "<reason>"
- Canceled:
spec-kitty agent decision cancel <decision_id> --mission <slug> --rationale "<reason>"
When deferring, write the inline marker into plan.md:
[NEEDS CLARIFICATION: <brief description>] <!-- decision_id: <decision_id> -->
Before finishing this command, run:
spec-kitty agent decision verify --mission <slug>
Resolve all findings (DEFERRED_WITHOUT_MARKER, MARKER_WITHOUT_DECISION,
STALE_MARKER) before proceeding.
Important constraints:
--slot-key format: plan.<section>.<question-slug> (e.g.,
plan.architecture.db-choice).
--input-key is the snake_case programmatic key (e.g., db_choice).
- The
decision_id on the wire is a plain ULID (26 chars). The DM- prefix
appears only in artifact filenames, not in CLI arguments.
- The verifier cross-checks
[NEEDS CLARIFICATION: …] <!-- decision_id: <id> -->
sentinels in plan.md against the decisions index and exits non-zero on drift.
- Widening is represented by the CLI/SaaS widen flow; if that flow returns
canonical thread metadata, it must be recorded as
DecisionPointWidened.
- Local-only; no SaaS calls needed.
Planning Interrogation (mandatory)
Before executing any scripts or generating artifacts you must interrogate the specification and stakeholders.
Scope proportionality (CRITICAL): FIRST, assess the feature's complexity from the spec:
- Trivial/Test Features (hello world, simple static pages, basic demos): Ask 1-2 questions maximum about tech stack preference, then proceed with sensible defaults
- Simple Features (small components, minor API additions): Ask 2-3 questions about tech choices and constraints
- Complex Features (new subsystems, multi-component features): Ask 3-5 questions covering architecture, NFRs, integrations
- Platform/Critical Features (core infrastructure, security, payments): Full interrogation with 5+ questions
Scenario-to-design handoff: For non-trivial features, anchor planning
questions in the concrete user flows from the spec rather than generic
architecture preferences.
Domain rule follow-through: When the spec implies approvals, lifecycle
states, irreversible operations, or business-critical validations, ask 1-2
targeted questions about invariants, transitions, atomicity, and externally
visible events or integrations. Skip this for trivial features.
User signals to reduce questioning: If the user says "use defaults", "just make it simple", "skip to implementation", "vanilla HTML/CSS/JS" - recognize these as signals to minimize planning questions and use standard approaches.
First response rule:
- For TRIVIAL features: Ask ONE tech stack question, then if answer is simple (e.g., "vanilla HTML"), proceed directly to plan generation
- For other features: Ask a single architecture question tied to the riskiest scenario, rule, or lifecycle constraint and end with
WAITING_FOR_PLANNING_INPUT
If the user has not provided plan context, keep interrogating with one question at a time.
Conversational cadence: After each reply, assess if you have SUFFICIENT context for this feature's scope. For trivial features, knowing the basic stack is enough. Only continue if critical unknowns remain.
Planning requirements (scale to complexity):
- Maintain a Planning Questions table internally covering questions appropriate to the feature's complexity (1-2 for trivial, up to 5+ for platform-level). Track columns
#, Question, Why it matters, and Current insight. Do not render this table to the user.
- For trivial features, standard practices are acceptable (vanilla HTML, simple file structure, no build tools). Only probe if the user's request suggests otherwise.
- When you have sufficient context for the scope, summarize into an Engineering Alignment note and confirm. Include invariant, state-transition, or event assumptions when they materially affect the design.
- If user explicitly asks to skip questions or use defaults, acknowledge and proceed with best practices for that feature type.
Bulk-Edit Check (if applicable)
If this mission is marked change_mode: bulk_edit in meta.json — or if the
spec describes renaming the same string (identifier, path, key, label, term)
across many files — load the spec-kitty-bulk-edit-classification skill and
follow it. You will produce kitty-specs/<mission>/occurrence_map.yaml
alongside the other planning artifacts. Every one of the 8 standard categories
(code_symbols, import_paths, filesystem_paths, serialized_keys, cli_commands,
user_facing_strings, tests_fixtures, logs_telemetry) must have an explicit
action. Without that artifact, the implement command will refuse to start
the first WP.
If the mission is not a bulk edit, skip this step.
Outline
Check planning discovery status:
- If any planning questions remain unanswered or the user has not confirmed the Engineering Alignment summary, stay in the one-question cadence, capture the user's response, update your internal table, and end with
WAITING_FOR_PLANNING_INPUT. Do not surface the table. Do not run the setup command yet.
- Once every planning question has a concrete answer and the alignment summary is confirmed by the user, continue.
Resolve mission context deterministically (CRITICAL - prevents wrong mission selection):
- Prefer an explicit mission slug from user direction or from the current directory path (
kitty-specs/<mission-slug>/...)
- If you do not yet have an explicit mission slug, run
spec-kitty agent mission setup-plan --json once without --mission
- If that call succeeds, treat its JSON as the canonical setup payload and skip step 3
- If that call returns an ambiguity error with
available_missions, stop and resolve one explicit mission slug before continuing
Setup: If step 2 did not already return a successful setup payload, run spec-kitty agent mission setup-plan --mission <mission-slug> --json from the repository root and parse JSON for:
result: "success" or error message
mission_slug: Resolved feature slug
spec_file: Absolute path to resolved spec.md
plan_file: Absolute path to the created plan.md
feature_dir: Absolute path to the feature directory
current_branch: branch checked out when planning started
target_branch / base_branch (deterministic branch contract for downstream commands)
planning_base_branch / merge_target_branch: explicit aliases for planning and merge intent
branch_strategy_summary: canonical sentence describing the branch strategy
Before proceeding, explicitly state to the user:
- Current branch at plan start
- Intended planning/base branch
- Final merge target for completed changes
- Whether
branch_matches_target says the current branch matches that intended target
Example:
# Resolve the active mission handle, then pass it to setup-plan.
# The --mission flag accepts mission_id (ULID), mid8 (first 8 chars), or mission_slug.
# The resolver disambiguates by mission_id; ambiguous handles become structured errors.
spec-kitty agent context resolve --mission <handle> --json
spec-kitty agent mission setup-plan --mission <handle> --json
Error handling: If the command fails with "Cannot detect mission", "Multiple missions found", or MISSION_AMBIGUOUS_SELECTOR, pass an unambiguous handle — the mission_id or its 8-char prefix mid8 always disambiguates.
Load context: Read spec_file from setup-plan JSON output and .kittify/charter/charter.md if it exists. If the charter file is missing, skip Charter Check and note that it is absent. Load IMPL_PLAN template (already copied).
Execute plan workflow: Follow the structure in IMPL_PLAN template, using the validated planning answers as ground truth:
- Update Technical Context with explicit statements from the user or discovery research; mark
[NEEDS CLARIFICATION: …] <!-- decision_id: <id> --> only when the user deliberately postpones a decision (call decision defer before writing each such marker)
- If a charter exists, fill Charter Check section from it and challenge any conflicts directly with the user. If no charter exists, mark the section as skipped.
- Evaluate gates (ERROR if violations unjustified or questions remain unanswered)
- Phase 0: Generate research.md (commission research to resolve every outstanding clarification, prioritizing unresolved domain rules, lifecycle questions, and event/integration behavior before generic tech comparisons)
- Phase 1: Generate data-model.md, contracts/, quickstart.md based on confirmed intent; when applicable, capture entities/value objects, invariants, state transitions, and externally visible events in the design artifacts
- Re-evaluate Charter Check post-design, asking the user to resolve new gaps before proceeding
STOP and report: This command ends after Phase 1 planning. Report branch, IMPL_PLAN path, and generated artifacts.
⚠️ CRITICAL: DO NOT proceed to task generation! The user must explicitly run /spec-kitty.tasks to generate work packages. Your job is COMPLETE after reporting the planning artifacts.
Phases
Phase 0: Outline & Research
Extract unknowns from Technical Context above:
- For each NEEDS CLARIFICATION → research task
- For each unresolved rule, invariant, lifecycle edge, or event/integration ambiguity → domain research task
- For each dependency → best practices task
- For each integration → patterns task
Generate and dispatch research agents:
For each unknown in Technical Context:
Task: "Research {unknown} for {feature context}"
For each unresolved domain rule:
Task: "Clarify invariant, state transition, or event behavior for {feature context}"
For each technology choice:
Task: "Find best practices for {tech} in {domain}"
Consolidate findings in research.md using format:
- Decision: [what was chosen]
- Rationale: [why chosen]
- Alternatives considered: [what else evaluated]
Output: research.md with all NEEDS CLARIFICATION resolved
Phase 1: Design & Contracts
Prerequisites: research.md complete
Extract entities from feature spec → data-model.md:
- Entity name, fields, relationships
- Validation rules from requirements
- Invariants or atomicity boundaries if applicable
- State transitions if applicable
Generate API contracts from functional requirements:
- For each user action → endpoint
- For each externally visible event, webhook, or integration callback → contract or payload shape when applicable
- Use standard REST/GraphQL patterns
- Output OpenAPI/GraphQL schema to
/contracts/
Output: data-model.md, /contracts/*, quickstart.md
Key rules
- Use absolute paths
- ERROR on gate failures or unresolved clarifications
⛔ MANDATORY STOP POINT
This command is COMPLETE after generating planning artifacts.
After reporting:
plan.md path
research.md path (if generated)
data-model.md path (if generated)
contracts/ contents (if generated)
YOU MUST STOP HERE.
Do NOT:
- ❌ Generate
tasks.md
- ❌ Create work package (WP) files
- ❌ Create
tasks/ subdirectories
- ❌ Proceed to implementation
The user will run /spec-kitty.tasks when they are ready to generate work packages.
Next suggested command: /spec-kitty.tasks (user must invoke this explicitly)
1---2name: spec-kitty-plan-23description: Create an implementation plan4---5# /spec-kitty.plan - Create Implementation Plan67**Version**: 0.11.0+89## 📍 WORKING DIRECTORY: Stay in the repository root checkout1011**IMPORTANT**: Plan works in the repository root checkout. NO worktrees created.1213```bash14# Run from project root (same directory as /spec-kitty.specify):15# You should already be here if you just ran /spec-kitty.specify1617# Creates:18# - kitty-specs/<mission_slug>/plan.md → In repository root checkout19# (the NNN- prefix in the directory listing is display-only metadata)20# - Commits to target branch21# - NO worktrees created22```2324**Do NOT cd anywhere**. Stay in the repository root checkout.2526## Mission Handle Rule2728`/spec-kitty.plan` operates on an existing mission, so use `--mission <handle>`29when the CLI needs a mission selector.3031- `<handle>` can be the mission's `mission_id` (ULID), `mid8` (first 8 chars of32 the ULID), or `mission_slug`.33- Prefer `mission_id` or `mid8` when the repo has multiple similarly named34 missions.35- The resolver disambiguates by `mission_id` and returns a structured36 `MISSION_AMBIGUOUS_SELECTOR` error on ambiguity — there is no silent fallback.3738## User Input3940The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after `/spec-kitty.<command>` or `$spec-kitty.<command>`) is the User Input referenced elsewhere in these instructions.4142You **MUST** consider this user input before proceeding (if not empty).43## Commit Boundary (issue #846)4445`/spec-kitty.plan` will refuse to advance the plan phase unless **two**46gates pass:47481. **Entry gate.** `spec.md` must already be both **committed** (tracked +49 present at HEAD) and **substantive** (at least one populated `FR-###`50 row — not just template placeholders). If either check fails, the CLI51 returns `phase_complete=false` with a `blocked_reason` naming "committed52 AND substantive" and does **not** create or commit `plan.md`.53542. **Exit gate.** `plan.md` is only auto-committed when its Technical Context55 section contains a real `Language/Version` value (and at least one peer56 field) — not the `[e.g., …]` / `[NEEDS CLARIFICATION …]` placeholders. If57 the plan is left as scaffold, it stays untracked on disk and the CLI58 returns `phase_complete=false` with a substantive-plan `blocked_reason`.5960Section presence is the only signal — adding arbitrary prose without the61required structural rows does **not** count as substantive (no byte-length62escape hatch).6364To advance: populate the Technical Context with real values, then re-run65`spec-kitty agent mission setup-plan --json`. The substantive plan will be66auto-committed and `phase_complete` will report `true`.6768Reference: `kitty-specs/charter-e2e-827-followups-01KQAJA0/contracts/specify-plan-commit-boundary.md`.6970## Branch Strategy Confirmation (MANDATORY)7172Before asking planning questions or generating artifacts, you must make the branch contract explicit.7374- Never describe the landing branch vaguely. Always name the actual branch value.75- If the user says the feature should land somewhere else, stop and resolve that before writing `plan.md`.76- You must repeat the branch contract twice during this command:77 1. immediately after parsing `setup-plan --json`78 2. again in the final report before suggesting `/spec-kitty.tasks`7980## Charter Context Bootstrap (required)8182Before planning interrogation, load charter context for this action:8384```bash85spec-kitty charter context --action plan --json86```8788- If JSON `mode` is `bootstrap`, apply JSON `text` as first-run governance context and follow referenced docs as needed.89- If JSON `mode` is `compact`, continue with condensed governance context.9091## Location Check (0.11.0+)9293This command runs in the **repository root checkout**, not in a worktree.9495- Resolve branch context from deterministic JSON output, not from `meta.json` inspection:96 - Run `spec-kitty agent mission setup-plan --mission <mission-slug> --json`97 - Use `current_branch`, `target_branch` / `base_branch`, and `planning_base_branch` / `merge_target_branch` (plus uppercase aliases) from that payload98 - Use `branch_matches_target` from that payload to detect branch mismatch; do not probe branch state manually inside the prompt99- Planning artifacts live in `kitty-specs/<mission_slug>/` (the `NNN-` prefix is display-only metadata)100- The plan template is committed to the target branch after generation101102**Path reference rule:** When you mention directories or files, provide either the absolute path or a path relative to the project root (for example, `kitty-specs/<mission>/tasks/`). Never refer to a folder by name alone.103104## Agent Context Files (do not mutate)105106This command does **not** update agent-specific context files.107108- Do **not** search for or mutate `CLAUDE.md`, `AGENTS.md`, or similar109 agent-specific files as part of `/spec-kitty.plan`.110- Do **not** hunt for updater scripts or imaginary `spec-kitty agent context update`111 commands. No supported context-update command exists in this release.112- Planning outputs are the mission planning artifacts only:113 - `plan.md`114 - `research.md`115 - `data-model.md`116 - `contracts/`117 - `quickstart.md`118 - `occurrence_map.yaml` when bulk-edit planning applies119120## Decision Moment Protocol121122Before asking **any** clarifying question during plan elaboration, you MUST:1231241. Run `spec-kitty agent decision open` to mint a decision_id:125 ```126 spec-kitty agent decision open \127 --mission <mission-slug> \128 --flow plan \129 --slot-key plan.<section>.<question-slug> \130 --input-key <snake_case_key> \131 --question "<question text>" \132 [--options '["option1","option2","Other"]']133 ```134 Capture the returned `decision_id` from the JSON output.1351362. Ask the question to the user in chat.1371383. After the user answers, run **exactly one** of:139 - Resolved:140 `spec-kitty agent decision resolve <decision_id> --mission <slug> --final-answer "<answer>"`141 - Deferred:142 `spec-kitty agent decision defer <decision_id> --mission <slug> --rationale "<reason>"`143 - Canceled:144 `spec-kitty agent decision cancel <decision_id> --mission <slug> --rationale "<reason>"`1451464. When deferring, write the inline marker into `plan.md`:147 ```148 [NEEDS CLARIFICATION: <brief description>] <!-- decision_id: <decision_id> -->149 ```1501515. Before finishing this command, run:152 `spec-kitty agent decision verify --mission <slug>`153 Resolve all findings (`DEFERRED_WITHOUT_MARKER`, `MARKER_WITHOUT_DECISION`,154 `STALE_MARKER`) before proceeding.155156**Important constraints:**157- `--slot-key` format: `plan.<section>.<question-slug>` (e.g.,158 `plan.architecture.db-choice`).159- `--input-key` is the snake_case programmatic key (e.g., `db_choice`).160- The `decision_id` on the wire is a plain ULID (26 chars). The `DM-` prefix161 appears only in artifact filenames, not in CLI arguments.162- The verifier cross-checks `[NEEDS CLARIFICATION: …] <!-- decision_id: <id> -->`163 sentinels in `plan.md` against the decisions index and exits non-zero on drift.164- Widening is represented by the CLI/SaaS widen flow; if that flow returns165 canonical thread metadata, it must be recorded as `DecisionPointWidened`.166- Local-only; no SaaS calls needed.167168## Planning Interrogation (mandatory)169170Before executing any scripts or generating artifacts you must interrogate the specification and stakeholders.171172- **Scope proportionality (CRITICAL)**: FIRST, assess the feature's complexity from the spec:173 - **Trivial/Test Features** (hello world, simple static pages, basic demos): Ask 1-2 questions maximum about tech stack preference, then proceed with sensible defaults174 - **Simple Features** (small components, minor API additions): Ask 2-3 questions about tech choices and constraints175 - **Complex Features** (new subsystems, multi-component features): Ask 3-5 questions covering architecture, NFRs, integrations176 - **Platform/Critical Features** (core infrastructure, security, payments): Full interrogation with 5+ questions177178- **Scenario-to-design handoff**: For non-trivial features, anchor planning179 questions in the concrete user flows from the spec rather than generic180 architecture preferences.181182- **Domain rule follow-through**: When the spec implies approvals, lifecycle183 states, irreversible operations, or business-critical validations, ask 1-2184 targeted questions about invariants, transitions, atomicity, and externally185 visible events or integrations. Skip this for trivial features.186187- **User signals to reduce questioning**: If the user says "use defaults", "just make it simple", "skip to implementation", "vanilla HTML/CSS/JS" - recognize these as signals to minimize planning questions and use standard approaches.188189- **First response rule**:190 - For TRIVIAL features: Ask ONE tech stack question, then if answer is simple (e.g., "vanilla HTML"), proceed directly to plan generation191 - For other features: Ask a single architecture question tied to the riskiest scenario, rule, or lifecycle constraint and end with `WAITING_FOR_PLANNING_INPUT`192193- If the user has not provided plan context, keep interrogating with one question at a time.194195- **Conversational cadence**: After each reply, assess if you have SUFFICIENT context for this feature's scope. For trivial features, knowing the basic stack is enough. Only continue if critical unknowns remain.196197Planning requirements (scale to complexity):1981991. Maintain a **Planning Questions** table internally covering questions appropriate to the feature's complexity (1-2 for trivial, up to 5+ for platform-level). Track columns `#`, `Question`, `Why it matters`, and `Current insight`. Do **not** render this table to the user.2002. For trivial features, standard practices are acceptable (vanilla HTML, simple file structure, no build tools). Only probe if the user's request suggests otherwise.2013. When you have sufficient context for the scope, summarize into an **Engineering Alignment** note and confirm. Include invariant, state-transition, or event assumptions when they materially affect the design.2024. If user explicitly asks to skip questions or use defaults, acknowledge and proceed with best practices for that feature type.203204## Bulk-Edit Check (if applicable)205206If this mission is marked `change_mode: bulk_edit` in `meta.json` — or if the207spec describes renaming the same string (identifier, path, key, label, term)208across many files — load the `spec-kitty-bulk-edit-classification` skill and209follow it. You will produce `kitty-specs/<mission>/occurrence_map.yaml`210alongside the other planning artifacts. Every one of the 8 standard categories211(code_symbols, import_paths, filesystem_paths, serialized_keys, cli_commands,212user_facing_strings, tests_fixtures, logs_telemetry) must have an explicit213action. Without that artifact, the `implement` command will refuse to start214the first WP.215216If the mission is not a bulk edit, skip this step.217218## Outline2192201. **Check planning discovery status**:221 - If any planning questions remain unanswered or the user has not confirmed the **Engineering Alignment** summary, stay in the one-question cadence, capture the user's response, update your internal table, and end with `WAITING_FOR_PLANNING_INPUT`. Do **not** surface the table. Do **not** run the setup command yet.222 - Once every planning question has a concrete answer and the alignment summary is confirmed by the user, continue.2232242. **Resolve mission context deterministically** (CRITICAL - prevents wrong mission selection):225 - Prefer an explicit mission slug from user direction or from the current directory path (`kitty-specs/<mission-slug>/...`)226 - If you do not yet have an explicit mission slug, run `spec-kitty agent mission setup-plan --json` once without `--mission`227 - If that call succeeds, treat its JSON as the canonical setup payload and skip step 3228 - If that call returns an ambiguity error with `available_missions`, stop and resolve one explicit mission slug before continuing2292303. **Setup**: If step 2 did not already return a successful setup payload, run `spec-kitty agent mission setup-plan --mission <mission-slug> --json` from the repository root and parse JSON for:231 - `result`: "success" or error message232 - `mission_slug`: Resolved feature slug233 - `spec_file`: Absolute path to resolved spec.md234 - `plan_file`: Absolute path to the created plan.md235 - `feature_dir`: Absolute path to the feature directory236 - `current_branch`: branch checked out when planning started237 - `target_branch` / `base_branch` (deterministic branch contract for downstream commands)238 - `planning_base_branch` / `merge_target_branch`: explicit aliases for planning and merge intent239 - `branch_strategy_summary`: canonical sentence describing the branch strategy240241 Before proceeding, explicitly state to the user:242 - Current branch at plan start243 - Intended planning/base branch244 - Final merge target for completed changes245 - Whether `branch_matches_target` says the current branch matches that intended target246247 **Example**:248 ```bash249 # Resolve the active mission handle, then pass it to setup-plan.250 # The --mission flag accepts mission_id (ULID), mid8 (first 8 chars), or mission_slug.251 # The resolver disambiguates by mission_id; ambiguous handles become structured errors.252 spec-kitty agent context resolve --mission <handle> --json253 spec-kitty agent mission setup-plan --mission <handle> --json254 ```255256 **Error handling**: If the command fails with "Cannot detect mission", "Multiple missions found", or `MISSION_AMBIGUOUS_SELECTOR`, pass an unambiguous handle — the `mission_id` or its 8-char prefix `mid8` always disambiguates.2572584. **Load context**: Read `spec_file` from setup-plan JSON output and `.kittify/charter/charter.md` if it exists. If the charter file is missing, skip Charter Check and note that it is absent. Load IMPL_PLAN template (already copied).2592605. **Execute plan workflow**: Follow the structure in IMPL_PLAN template, using the validated planning answers as ground truth:261 - Update Technical Context with explicit statements from the user or discovery research; mark `[NEEDS CLARIFICATION: …] <!-- decision_id: <id> -->` only when the user deliberately postpones a decision (call `decision defer` before writing each such marker)262 - If a charter exists, fill Charter Check section from it and challenge any conflicts directly with the user. If no charter exists, mark the section as skipped.263 - Evaluate gates (ERROR if violations unjustified or questions remain unanswered)264 - Phase 0: Generate research.md (commission research to resolve every outstanding clarification, prioritizing unresolved domain rules, lifecycle questions, and event/integration behavior before generic tech comparisons)265 - Phase 1: Generate data-model.md, contracts/, quickstart.md based on confirmed intent; when applicable, capture entities/value objects, invariants, state transitions, and externally visible events in the design artifacts266 - Re-evaluate Charter Check post-design, asking the user to resolve new gaps before proceeding2672686. **STOP and report**: This command ends after Phase 1 planning. Report branch, IMPL_PLAN path, and generated artifacts.269270 **⚠️ CRITICAL: DO NOT proceed to task generation!** The user must explicitly run `/spec-kitty.tasks` to generate work packages. Your job is COMPLETE after reporting the planning artifacts.271272## Phases273274### Phase 0: Outline & Research2752761. **Extract unknowns from Technical Context** above:277 - For each NEEDS CLARIFICATION → research task278 - For each unresolved rule, invariant, lifecycle edge, or event/integration ambiguity → domain research task279 - For each dependency → best practices task280 - For each integration → patterns task2812822. **Generate and dispatch research agents**:283 ```284 For each unknown in Technical Context:285 Task: "Research {unknown} for {feature context}"286 For each unresolved domain rule:287 Task: "Clarify invariant, state transition, or event behavior for {feature context}"288 For each technology choice:289 Task: "Find best practices for {tech} in {domain}"290 ```2912923. **Consolidate findings** in `research.md` using format:293 - Decision: [what was chosen]294 - Rationale: [why chosen]295 - Alternatives considered: [what else evaluated]296297**Output**: research.md with all NEEDS CLARIFICATION resolved298299### Phase 1: Design & Contracts300301**Prerequisites:** `research.md` complete3023031. **Extract entities from feature spec** → `data-model.md`:304 - Entity name, fields, relationships305 - Validation rules from requirements306 - Invariants or atomicity boundaries if applicable307 - State transitions if applicable3083092. **Generate API contracts** from functional requirements:310 - For each user action → endpoint311 - For each externally visible event, webhook, or integration callback → contract or payload shape when applicable312 - Use standard REST/GraphQL patterns313 - Output OpenAPI/GraphQL schema to `/contracts/`314315**Output**: data-model.md, /contracts/*, quickstart.md316317## Key rules318319- Use absolute paths320- ERROR on gate failures or unresolved clarifications321322---323324## ⛔ MANDATORY STOP POINT325326**This command is COMPLETE after generating planning artifacts.**327328After reporting:329- `plan.md` path330- `research.md` path (if generated)331- `data-model.md` path (if generated)332- `contracts/` contents (if generated)333334**YOU MUST STOP HERE.**335336Do NOT:337- ❌ Generate `tasks.md`338- ❌ Create work package (WP) files339- ❌ Create `tasks/` subdirectories340- ❌ Proceed to implementation341342The user will run `/spec-kitty.tasks` when they are ready to generate work packages.343344**Next suggested command**: `/spec-kitty.tasks` (user must invoke this explicitly)