spec-kitty.plan

Prompt file imported from wildcard/caro (.codex/prompts/spec-kitty.plan.md). Fill in {{arguments}} before use. Copyright stays with the author.

Path: .kittify/templates/commands/plan.md

User Input

{{arguments}}

You MUST consider the user input before proceeding (if not empty).

Location Pre-flight Check (CRITICAL for AI Agents)

Before proceeding with planning, verify you are in the correct working directory:

Check your current branch:

git branch --show-current

Expected output: A feature branch like 001-feature-name If you see main: You are in the wrong location!

This command MUST run from a feature worktree, not the main repository.

If you're on the main branch:

1. Check for available worktrees: ls .worktrees/
2. Navigate to the appropriate feature worktree: cd .worktrees/<feature-name>
3. Verify you're in the right place: git branch --show-current should show the feature branch
4. Then re-run this command

The script will fail if you're not in a feature worktree. 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/<feature>/tasks/). Never refer to a folder by name alone.

This is intentional - worktrees provide isolation for parallel feature development.

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

• 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 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):

1. 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.
2. For trivial features, standard practices are acceptable (vanilla HTML, simple file structure, no build tools). Only probe if the user's request suggests otherwise.
3. When you have sufficient context for the scope, summarize into an Engineering Alignment note and confirm.
4. If user explicitly asks to skip questions or use defaults, acknowledge and proceed with best practices for that feature type.

Outline

1. 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 .kittify/scripts/bash/setup-plan.sh --json yet.
   • Once every planning question has a concrete answer and the alignment summary is confirmed by the user, continue.

2. Setup: Run .kittify/scripts/bash/setup-plan.sh --json from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.

3. Load context: Read FEATURE_SPEC and .kittify/memory/constitution.md. Load IMPL_PLAN template (already copied).

4. 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: …] only when the user deliberately postpones a decision
   • Fill Constitution Check section from constitution and challenge any conflicts directly with the user
   • Evaluate gates (ERROR if violations unjustified or questions remain unanswered)
   • Phase 0: Run spec-kitty research (or /spec-kitty.research) to scaffold research.md, data-model.md, and research CSV logs, then populate findings using the validated planning answers
   • Phase 1: Generate data-model.md, contracts/, quickstart.md based on confirmed intent (building on the Phase 0 outputs)
   • Phase 1: Update agent context by running the agent script
   • Re-evaluate Constitution Check post-design, asking the user to resolve new gaps before proceeding

5. Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.

Phases

Phase 0: Outline & Research

Kick off this phase by running spec-kitty research to scaffold the mission-specific files listed below. Then use the checklist to enrich each artifact with the clarifications uncovered during planning.

1. Extract unknowns from Technical Context above:

   • For each NEEDS CLARIFICATION → research task
   • For each dependency → best practices task
   • For each integration → patterns task

2. Generate and dispatch research agents:

   For each unknown in Technical Context:
     Task: "Research {unknown} for {feature context}"
   For each technology choice:
     Task: "Find best practices for {tech} in {domain}"
   

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

1. Extract entities from feature spec → data-model.md:

   • Entity name, fields, relationships
   • Validation rules from requirements
   • State transitions if applicable

2. Generate API contracts from functional requirements:

   • For each user action → endpoint
   • Use standard REST/GraphQL patterns
   • Output OpenAPI/GraphQL schema to /contracts/

3. Agent context update:

   • Run .kittify/scripts/bash/update-agent-context.sh codex
   • These scripts detect which AI agent is in use
   • Update the appropriate agent-specific context file
   • Add only new technology from current plan
   • Preserve manual additions between markers

Output: data-model.md, /contracts/*, quickstart.md, agent-specific file

Key rules

• Use absolute paths
• ERROR on gate failures or unresolved clarifications