kiss-plan

name	kiss-plan
description	Executes the implementation planning workflow using the plan template to generate design artefacts. Use when creating an implementation plan for a feature, breaking down architecture into actionable design documents, or before running kiss-taskify.
argument-hint	Optional guidance for the planning phase
compatibility	Requires kiss project structure with .kiss/ directory
metadata	{"author":"github-kiss","source":"agent-skills/kiss-plan/kiss-plan.md"}
user-invocable	true
disable-model-invocation	false

User Input

$ARGUMENTS

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

Audience and tone (interactive mode)

When KISS_AGENT_MODE=interactive (the default), assume the user has limited technical background and limited domain knowledge — they may know basics but lack deep expertise in implementation planning. Run this skill as a guided questionnaire:

• One question at a time. No walls of questions.
• Yes / no first. Phrase so yes, no, not sure, or skip is a valid answer.
• Translate jargon, don't strip it. Use the technical term but always pair it with a plain-English gloss the first time it appears.
• Choices, not blank fields. When yes/no isn't enough, offer 2-4 lettered options (A/B/C/D) with one-line plain-language descriptions of the trade-off. Always include "Not sure — pick a sensible default".
• Always recommend. State the option you would pick and why in one sentence so the user can reply "yes" / "ok" to accept. Pull defaults from upstream artefacts (spec, architecture, ADRs, standards) before asking blank.
• Show, don't ask. When upstream artefacts already imply an answer, propose it as a pre-filled finding and ask for a yes / no confirmation rather than asking the user to fill in a blank.
• not sure / skip triggers a sensible default, marked "(default applied — confirm later)" in the artefact, and a debt entry in this skill's debt file.

When KISS_AGENT_MODE=auto (or --auto), skip the questionnaire entirely: apply sensible defaults from upstream artefacts and log decisions to the parent agent's decision log.

Pre-Execution Checks

Check for extension hooks (before planning):

• Check if .kiss/extensions.yml exists in the project root.

• If it exists, read it and look for entries under the hooks.before_plan key

• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.

• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:

  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation

• When constructing slash commands from hook command names, replace dots (.) with hyphens (-). For example, kiss.git.commit → /kiss-git-commit.

• For each executable hook, output the following based on its optional flag:

  • Optional hook (optional: true):

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to the Outline.
    

• If no hooks are registered or .kiss/extensions.yml does not exist, skip silently

Outline

1. Setup: Run scripts/bash/setup-plan.sh --json from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

2. Load context: Read FEATURE_SPEC and {context.paths.docs}/standards.md. Load IMPL_PLAN template (already copied).

3. Execute plan workflow: Follow the structure in IMPL_PLAN template to:

   • Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
   • Fill Standards Check section from standards
   • Evaluate gates (ERROR if violations unjustified)
   • Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
   • Phase 1: Generate data-model.md, contracts/, quickstart.md
   • Phase 1: Update agent context by running the agent script
   • Re-evaluate Standards Check post-design

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

5. Check for extension hooks: After reporting, check if .kiss/extensions.yml exists in the project root.

   • If it exists, read it and look for entries under the hooks.after_plan key

   • If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

   • Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.

   • For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:

     • If the hook has no condition field, or it is null/empty, treat the hook as executable
     • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation

   • When constructing slash commands from hook command names, replace dots (.) with hyphens (-). For example, kiss.git.commit → /kiss-git-commit.

   • For each executable hook, output the following based on its optional flag:

Phases

Phase 0: Outline & Research

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. Define interface contracts (if project has external interfaces) → /contracts/:

   • Identify what interfaces the project exposes to users or other systems
   • Document the contract format appropriate for the project type
   • Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
   • Skip if project is purely internal (build scripts, one-off tools, etc.)

3. Agent context update:

   • Update the plan reference between the <!-- KISS START --> and <!-- KISS END --> markers in CLAUDE.md to point to the plan file created in step 1 (the IMPL_PLAN path)

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

Key rules

• Use absolute paths for filesystem operations; use project-relative paths for references in documentation and agent context files
• ERROR on gate failures or unresolved clarifications

Inputs

• Feature Specification ({context.current.spec}): current.spec.
  • If set: Read the specification file at this path.
  • If null: Search {context.paths.specs} for the most recent spec.md.
  • If not provided: Ask the user to provide a path to the specification or run /kiss-specify first.

Outputs

• Implementation Plan ({context.paths.plans}/{context.current.feature}/plan.md): paths.plans}/current.feature}/plan.md.

  • Behavior: Write the plan file. If it exists and confirm_before_write is true, ask the user.
  • Overwrite guarded by {context.preferences.confirm_before_write}.

• Research Findings ({context.paths.plans}/{context.current.feature}/research.md): paths.plans}/current.feature}/research.md.

  • Behavior: Write research findings documenting design decisions.
  • Overwrite guarded by {context.preferences.confirm_before_write}.

• Data Model ({context.paths.plans}/{context.current.feature}/data-model.md): paths.plans}/current.feature}/data-model.md.

  • Behavior: Write entity definitions and relationships.
  • Overwrite guarded by {context.preferences.confirm_before_write}.

Context Update

After this skill completes successfully, update .kiss/context.yml:

• Set current.plan to the path of the created plan file
• Set current.feature if inferred or confirmed during planning
• Leave all other current.* fields unchanged
• Do not modify paths.or preferences.

Handoffs

• Create Tasks: run /kiss-taskify to continue the workflow.
• Create Checklist: run /kiss-checklist to continue the workflow.