Skip to content

File Structure Reference

This document describes the complete directory structure of a Spec Kitty project.


Project Root Overview

my-project/
├── .kittify/ # Spec Kitty configuration and templates
├── kitty-specs/ # Feature specifications
├── .worktrees/ # Git worktrees for execution workspaces (lane-based in 2.x)
├── .claude/ # Claude Code slash commands
├── .cursor/ # Cursor slash commands
├── .gemini/ # Gemini CLI slash commands
├── (other agent dirs) # Other AI agent directories
├── docs/ # Project documentation
├── src/ # Your source code
└── .git/ # Git repository

.kittify/ Directory

Contains Spec Kitty configuration, templates, and project memory.

.kittify/
├── templates/ # Document templates
│ ├── spec-template.md # Specification template
│ ├── plan-template.md # Plan template
│ ├── tasks-template.md # Tasks breakdown template
│ └── task-prompt-template.md # Individual WP prompt template
├── missions/ # Mission configurations
│ ├── software-dev/
│ │ └── mission.yaml
│ ├── research/
│ │ └── mission.yaml
│ └── documentation/
│ └── mission.yaml
└── charter/ # Charter governance
└── charter.md # Project principles (optional)

Key Files

FilePurpose
templates/*.mdTemplates used by /spec-kitty.specify, /spec-kitty.plan, etc.
missions/*/mission.yamlMission-specific configuration and phases
charter/charter.mdProject-wide principles referenced by governed commands

kitty-specs/ Directory

Contains all feature specifications. Each feature has its own subdirectory.

kitty-specs/
├── 001-user-authentication/ # First feature
│ ├── meta.json # Feature metadata
│ ├── spec.md # Specification document
│ ├── plan.md # Implementation plan
│ ├── research.md # Research findings (optional)
│ ├── tasks.md # Task breakdown
│ ├── data-model.md # Data model (software-dev)
│ ├── checklists/ # Validation checklists
│ │ └── requirements.md
│ └── tasks/ # work package prompts
│ ├── WP01-setup.md
│ ├── WP02-api.md
│ └── WP03-frontend.md
├── 002-payment-processing/ # Second feature
│ └── ...
└── 014-documentation/ # Feature 014
└── ...

Feature Directory Contents

File/DirectoryCreated ByPurpose
meta.json/spec-kitty.specifyFeature metadata and mission
spec.md/spec-kitty.specifyUser stories, requirements, acceptance criteria
plan.md/spec-kitty.planArchitecture, design decisions, implementation concern Map (IC-## entries)
research.md/spec-kitty.researchResearch findings and evidence (optional)
tasks.md/spec-kitty.tasksTask breakdown translated from IC-## implementation concerns
wps.yaml/spec-kitty.tasksMachine-readable WP manifest with plan_concern_refs traceability to IC-## entries
data-model.md/spec-kitty.planDatabase schema (software-dev mission)
checklists//spec-kitty.specifyValidation checklists (canonical requirements.md plus optional domain checklists)
tasks//spec-kitty.tasksIndividual WP prompt files

Implementation concerns (IC-01, IC-02, …) are plan-level architectural units that appear in plan.md. They are not work packages — /spec-kitty.tasks translates them into executable WPs. Each WP in wps.yaml cites which IC-## entries it addresses via plan_concern_refs, maintaining full plan-to-task traceability.


.worktrees/ Directory (0.11.0+)

Contains Git worktrees for implementation. Features create one shared workspace per execution lane.

.worktrees/
├── 014-documentation-lane-a/ # Lane A workspace (shared by sequential WPs)
│ ├── src/ # Code (on lane branch)
│ ├── docs/ # Documentation
│ └── .git # Pointer to main .git
├── 014-documentation-lane-b/ # Parallel lane workspace
│ └── ...

Key Points

  • Features create one worktree per execution lane
  • Each lane worktree has its own branch: <feature-slug>-lane-<id>
  • Worktrees share the .git database with the repository root checkout
  • Created by spec-kitty implement WP##
  • Removed after merge with git worktree remove

Worktree vs repository root checkout

LocationWhen to Use
repository root checkout (my-project/)Planning: /spec-kitty.specify, /spec-kitty.plan, /spec-kitty.tasks
Worktree (.worktrees/...)Implementation: /spec-kitty.implement, coding, testing in the resolved execution workspace

VCS Directories

Spec Kitty uses Git as the version control backend.

.git/ Directory

Standard Git repository directory.

.git/
├── config # Repository configuration
├── HEAD # current branch reference
├── objects/ # Git object database
├── refs/ # Branch and tag references
└── worktrees/ # Git worktree info (managed internally)

Agent Directories

Each supported AI agent has its own directory for slash commands.

my-project/
├── .claude/
│ └── commands/
│ ├── spec-kitty.specify.md
│ ├── spec-kitty.plan.md
│ ├── spec-kitty.tasks.md
│ ├── spec-kitty.implement.md
│ ├── spec-kitty.review.md
│ ├── spec-kitty.accept.md
│ ├── spec-kitty.merge.md
│ ├── spec-kitty.status.md
│ ├── spec-kitty.charter.md
│ ├── spec-kitty.research.md
│ └── spec-kitty.analyze.md
├── .cursor/
│ └── commands/
│ └── (same files)
├── .gemini/
│ └── commands/
│ └── (same files)
└── (10 more agent directories)

See Supported Agents for the complete list.


docs/ Directory (Divio Structure)

Documentation organized by the Divio 4-type system.

docs/
├── index.md # Landing page
├── _meta/sections.yaml # Section registry (the site/ build reads it)
├── tutorials/ # Learning-oriented
│ ├── getting-started.md
│ └── your-first-mission.md
├── how-to/ # Task-oriented
│ ├── install-spec-kitty.md
│ ├── create-specification.md
│ └── implement-work-package.md
├── reference/ # Information-oriented
│ ├── cli-commands.md
│ ├── slash-commands.md
│ └── configuration.md
├── explanation/ # Understanding-oriented
│ ├── spec-driven-development.md
│ └── execution-lanes.md
└── assets/
├── images/
└── css/

Complete Example

Here’s a complete project structure with one active feature:

my-project/
├── .git/ # Git repository
├── .gitignore
├── .kittify/
│ ├── templates/
│ │ ├── spec-template.md
│ │ ├── plan-template.md
│ │ ├── tasks-template.md
│ │ └── task-prompt-template.md
│ ├── missions/
│ │ ├── software-dev/
│ │ ├── research/
│ │ └── documentation/
│ └── charter/
│ └── charter.md
├── .claude/
│ └── commands/
│ └── (13 slash command files)
├── kitty-specs/
│ └── 001-auth-system/
│ ├── meta.json
│ ├── spec.md
│ ├── plan.md
│ ├── tasks.md
│ └── tasks/
│ ├── WP01-setup.md
│ ├── WP02-api.md
│ └── WP03-ui.md
├── .worktrees/
│ ├── 001-auth-system-lane-a/
│ └── 001-auth-system-lane-b/
├── docs/
│ └── (documentation)
├── src/
│ └── (source code)
├── tests/
│ └── (test files)
├── pyproject.toml
└── README.md

See Also

Getting Started

Practical Usage