Kspec Plan

Plan to Spec Translation

Translate approved plans into specs and tasks. Plans are durable artifacts — they persist in the shadow branch, link to derived work, and provide auditable planning history across sessions.

When to Use

• After plan mode approval — turning an approved plan into trackable specs and tasks
• Creating specs for new features or multi-spec capabilities
• Translating design documents into the spec hierarchy

Not for: Raw ideas (use kspec inbox add), single spec creation (use $kspec-writing-specs), or triage (use $kspec-triage).

Two Paths

Import Path (Recommended for 3+ Specs)

Write a structured markdown document, import it as a durable plan record, iterate as needed, then derive specs/tasks when the plan is ready.

kspec plan import ./plan.md --dry-run                           # Preview plan record
kspec plan import ./plan.md --module @target-module             # Store plan (+ optional module)
kspec plan import ./edited.md --into @plan-ref                  # Re-import edits into existing plan
kspec plan set @plan-ref --status approved                      # Approve when ready
kspec plan derive @plan-ref --module @target-module             # Materialize specs/tasks

Manual Path (1-2 Specs)

Create plan record and specs incrementally via CLI.

kspec plan add --title "Plan Title" --content "Description" --status approved
kspec item add --under @parent --title "Feature" --type feature --slug slug
kspec item ac add @slug --given "..." --when "..." --then "..."
kspec derive @slug

When to Use Which

Three-Phase Workflow

Phase 1: Design

Always start here — never skip research.

If the project defines a plan-design workflow (for example @spec-plan-design), start it now:

kspec workflow start @spec-plan-design

Otherwise follow these steps directly:

1. Explore — Read relevant code, understand current state
2. Clarify — Identify ambiguities, resolve with user
3. Design — Spec structure, AC coverage, trait selection
4. Review — Check for completeness and gaps

Design concludes by choosing import or manual path.

Phase 2: Execute

If the project defines plan-execution workflows, start the matching one:

# Import path
kspec workflow start @spec-plan-import

# Manual path
kspec workflow start @spec-plan-manual

Otherwise run the import or manual path commands directly (see the path examples above).

Before deriving, ask the user: should this plan use a shared branch for task stacking? If yes, run kspec plan branch @ref after approval and before derive. This is a planning decision — dispatch handles the rest automatically.

Phase 3: Validate

After import and derive:

kspec validate              # Check spec quality
kspec validate --alignment  # Verify spec-task links

Plan Document Format

The import parser extracts specs, tasks, and notes from this markdown structure:

# Plan Title

## Specs

```yaml
- title: Example Feature
  slug: example-feature
  type: feature
  parent: "@parent-module"
  description: One-line description of the user-visible capability
  traits:
    - example-project-trait
  acceptance_criteria:
    - id: ac-1
      given: A described precondition
      when: A user-visible action happens
      then: A specific observable outcome
    - id: ac-2
      given: A described error precondition
      when: The error path is triggered
      then: A specific recovery or guidance outcome
  implementation_notes: |
    Per-spec implementation notes. Attached to this spec's derived task.

- title: Example Requirement
  slug: example-requirement
  type: requirement
  parent: "@example-feature"
  acceptance_criteria:
    - id: ac-1
      given: A described precondition
      when: A user-visible action happens
      then: A specific observable outcome
```

## Tasks

derive_from_specs: true

```yaml
- title: Example task title
  slug: example-task
  description: |
    Brief description of the task — what to do and why. Include scope
    boundaries when they are not obvious from the spec.
  priority: 2
  tags:
    - docs
  spec_ref: "@example-feature"
  depends_on:
    - "@example-requirement"
```

## Implementation Notes

General architecture notes attached to the plan record.
Use this section for cross-spec implementation context.

Section Reference

Spec Fields

Spec Language Quality

Specs in plan documents must follow the same behavioral language rules as any spec. See $kspec-writing-specs for the full rules. Key points:

• ACs describe observable behavior — not internal mechanisms. Use natural language a non-developer could follow, not code-level terms.
• ACs contain only assertions — no rationale, design commentary, or backward compatibility notes. Those belong in descriptions or implementation_notes.
• Specs are standalone and timeless — describe what the system does, not how it differs from a previous version. Use spec fields (depends_on, relates_to) for relationships.
• Implementation guidance goes in tasks — task descriptions are the right place for file paths, class names, and technical approach.

Task Fields

Trait Selection

Traits are not shipped by kspec init — each project defines its own trait catalog. Before writing specs, review what's available in this project and pick matching ones:

kspec trait list                       # See the project's trait catalog
kspec trait get @<trait-slug>          # See a trait's inherited ACs

For each spec you write, scan the catalog for traits whose behavior the spec implements (for example: output formatting, destructive-operation prompts, list filtering, error guidance, batch refs, shadow-state mutation). If no matching trait exists and the cross-cutting behavior recurs across 3+ specs, consider defining a new trait. See Creating New Traits — covered in $kspec-writing-specs.

Trait Naming in Plan Documents

Use the full trait slug as it appears in kspec trait list — import only auto-prefixes @, not any specific trait namespace prefix:

# Wrong — uses the un-prefixed name
traits:
  - some-trait

# Correct — full slug from the project trait catalog
traits:
  - example-project-trait

YAML Pitfalls

Plan documents embed YAML that is parsed as structured data. Common issues:

Block Scalars for Complex Text

Use | (literal block scalar) when AC text contains quotes, colons, or special characters:

# Problem — mixed quoting breaks parser
acceptance_criteria:
  - id: ac-1
    when: "kspec foo" is run

# Solution — block scalar preserves content literally
acceptance_criteria:
  - id: ac-1
    when: |
      "kspec foo" is run

Colons in Values

YAML treats : (colon-space) as a key-value separator:

# Problem — parsed as nested key
then: output shows time: 10:30

# Solution — quote the value
then: "output shows time: 10:30"

Best Practice

Use block scalars (|) for ALL given/when/then text. This avoids every quoting issue:

acceptance_criteria:
  - id: ac-1
    given: |
      user has an existing session
    when: |
      user runs "kspec session start"
    then: |
      session context shows: active tasks, recent notes, inbox count

Always Dry-Run First

kspec plan import ./plan.md --dry-run

Import dry-run confirms:

• Title, status, and stored module look right
• The file is readable and the full document will be stored as plan content
• No plan state is changed while previewing

Post-Import Checklist

After importing, verify the stored plan record:

# Review plan title/content/status/module
kspec plan get @plan-slug

# Iterate on the document if needed
kspec plan export @plan-slug --output ./plan.md
kspec plan import ./plan.md --into @plan-slug --reason "Refined scope"

# Approve when ready to materialize work
kspec plan set @plan-slug --status approved

# Derive specs/tasks from the stored plan document
kspec plan derive @plan-slug

# Validate the resulting refs and coverage surface
kspec validate

If derived tasks are too generic to execute without chat history, add a structured task note immediately after derive:

kspec task note @task-slug "Execution context:
- Background: why this task exists
- Scope: concrete boundaries for this task
- Files: exact files/areas to touch
- Verification: commands/tests to run"

Plan Lifecycle

draft → approved → active → completed
                     ↓
                  rejected

• Import stores the full document as a plan record and defaults to draft
• Import may optionally store module_ref for later derive
• Manual creates plan as approved
• Branch (optional) — after approval but before derive, ask the user whether tasks should target a shared plan branch or the default integration branch. If the user wants task stacking:

kspec plan branch @plan-ref          # Deterministic: plan/<slug>/<short-ref>
kspec plan branch @plan-ref --name feat/custom-name  # Custom name

Dispatch automatically targets the plan branch for all derived tasks. Without a plan branch, tasks target the default integration branch as usual.

• Derive materializes an approved plan into specs and tasks by default, then transitions it to active
• Mark completed when all derived work is done:

kspec plan set @plan --status completed

Plan branch lifecycle: When a plan has a branch, all derived tasks fork from and merge back into that branch. Task work accumulates on the plan branch as tasks are completed. Once all tasks are done and the plan is marked completed, the plan branch requires manual merging into the project's integration branch using the project-defined merge command. A future kspec plan merge command may automate this, but for now it is a manual step.

Programmatic Alternative: Batch

For fully programmatic creation (scripts, agent pipelines):

kspec batch --commands '[
  {"command":"item add","args":{"under":"@parent","title":"Feature X","type":"feature","slug":"feature-x"}},
  {"command":"item ac add","args":{"ref":"@feature-x","given":"...","when":"...","then":"..."}},
  {"command":"derive","args":{"ref":"@feature-x"}}
]'

Atomic — all succeed or all roll back. Use --dry-run to preview.

Command Reference

# Design phase — start the project's plan-design workflow if it exists
kspec workflow start @spec-plan-design

# Import path
kspec plan import <path> [--module @module] --dry-run         # Preview plan record
kspec plan import <path> [--module @module] [--status approved]  # Create stored plan record
kspec plan export <plan-ref> --output ./plan.md
kspec plan import <path> --into <plan-ref> [--reason "..."]  # Re-import edits
kspec plan set <plan-ref> --status approved
kspec plan derive <plan-ref> [--module @module] [--no-tasks]

# Manual path
kspec plan add --title "..." --content "..." --status approved
kspec plan get <ref>
kspec plan set <ref> --status <status>
kspec plan note <ref> "..."
kspec plan list

# Plan branch (opt-in task stacking)
kspec plan branch <ref>                              # Create/resume deterministic branch
kspec plan branch <ref> --name <branch>              # Custom branch name
kspec plan set <ref> --branch <name>                 # Set branch manually
kspec plan set <ref> --branch ""                     # Clear branch (revert to default)

# Validation
kspec validate
kspec validate --completeness
kspec validate --alignment

Integration

• $kspec-writing-specs — Spec authoring details (types, AC format, traits)
• $kspec-task-work — After specs are created, work on derived tasks
• $kspec-triage — Inbox items may trigger plan creation
• $kspec-observe — Friction during planning becomes observations