Configuration Reference

This document describes all configuration files used by Spec Kitty.

meta.json (Feature Metadata)

Each feature has a meta.json file in its directory that stores metadata about the feature.

Location: kitty-specs/<feature-slug>/meta.json

Fields:

{
  "feature_number": "014",
  "slug": "014-comprehensive-end-user-documentation",
  "friendly_name": "Comprehensive End-User Documentation",
  "mission": "documentation",
  "vcs": "git",
  "source_description": "Original feature description provided during /spec-kitty.specify",
  "created_at": "2026-01-16T12:00:00Z"
}

Field	Type	Description
`feature_number`	string	Three-digit feature number (e.g., "014")
`slug`	string	Full feature slug including number
`friendly_name`	string	Human-readable feature name
`mission`	string	Mission type: `software-dev`, `research`, or `documentation`
`vcs`	string	VCS backend: `git` (auto-detected if not specified)
`source_description`	string	Original description from `/spec-kitty.specify`
`created_at`	string	ISO 8601 timestamp of creation

VCS Lock: Once a feature is created, its VCS is locked in meta.json. All workspaces for that feature use the same VCS backend. This ensures consistency across work packages.

Work Package Frontmatter

Each work package file (tasks/WP##-*.md) contains YAML frontmatter that tracks its status.

Location: kitty-specs/<feature-slug>/tasks/WP##-*.md

Fields:

---
work_package_id: "WP01"
title: "Setup and Configuration"
lane: "planned"
dependencies: ["WP00"]
subtasks:
  - "T001"
  - "T002"
  - "T003"
phase: "Phase 1 - Foundation"
assignee: ""
agent: ""
shell_pid: ""
review_status: ""
reviewed_by: ""
review_feedback: ""
history:
  - timestamp: "2026-01-16T12:00:00Z"
    lane: "planned"
    agent: "system"
    shell_pid: ""
    action: "Prompt generated via /spec-kitty.tasks"
---

Field	Type	Description
`work_package_id`	string	WP identifier (e.g., "WP01")
`title`	string	Work package title
`lane`	string	Current lane: `planned`, `claimed`, `in_progress`, `for_review`, `approved`, `done`, `blocked`, `canceled`. Alias: `doing` → `in_progress`.
`dependencies`	list	WP IDs this WP depends on
`subtasks`	list	Task IDs belonging to this WP
`phase`	string	Development phase
`assignee`	string	Human assignee name
`agent`	string	AI agent type (e.g., "claude")
`shell_pid`	string	Process ID of implementing agent
`review_status`	string	Empty, `has_feedback`, or `approved`
`reviewed_by`	string	Reviewer name
`review_feedback`	string	Feedback pointer to persisted artifact (for example, `feedback://001-feature/WP01/20260227T120000Z-ab12cd34.md`)
`history`	list	Activity log entries

docfx.json (Documentation Build)

DocFX configuration for building the documentation site.

Location: docs/docfx.json

Key sections:

{
  "build": {
    "content": [
      {
        "files": [
          "*.md",
          "tutorials/*.md",
          "how-to/*.md",
          "reference/*.md",
          "explanation/*.md",
          "toc.yml"
        ]
      }
    ],
    "resource": [
      {
        "files": ["assets/**"]
      }
    ],
    "dest": "_site",
    "template": ["default", "modern"],
    "globalMetadata": {
      "_appTitle": "Spec Kitty Documentation",
      "_enableSearch": true
    }
  }
}

Section	Description
`content.files`	Markdown files to include
`resource.files`	Static assets (images, CSS)
`dest`	Output directory (don't commit this)
`template`	DocFX templates to use
`globalMetadata`	Site-wide settings

toc.yml (Table of Contents)

Defines the documentation navigation structure.

Location: docs/toc.yml

Format:

- name: Home
  href: index.md

- name: Tutorials
  items:
    - name: Getting Started
      href: tutorials/getting-started.md
    - name: Your First Feature
      href: tutorials/your-first-feature.md

- name: How-To Guides
  items:
    - name: Install & Upgrade
      href: how-to/install-spec-kitty.md

Each entry has:

name: Display text in navigation
href: Path to markdown file
items: Nested navigation items (optional)

charter.md (Project Principles)

Optional file defining project-wide coding principles and standards.

Location: .kittify/memory/charter.md

Purpose: When present, all slash commands reference these principles. Claude and other agents will follow these guidelines during implementation.

Example:

# Project Charter

## Code Quality Principles

1. All APIs must have rate limiting
2. All database queries must use parameterized statements
3. All user input must be validated
4. Test coverage must be at least 80%

## Architecture Principles

1. Use dependency injection for testability
2. Separate business logic from infrastructure
3. Document all public APIs

Creating: Use /spec-kitty.charter to interactively create this file.

Mission Configuration (Advanced)

Mission-specific templates and configuration.

Location: .kittify/missions/<mission-key>/

Structure:

.kittify/missions/
├── software-dev/
│   └── mission.yaml
├── research/
│   └── mission.yaml
└── documentation/
    └── mission.yaml

mission.yaml fields:

key: software-dev
name: Software Development
domain: Building software features
phases:
  - research
  - design
  - implement
  - test
  - review
artifacts:
  - spec.md
  - plan.md
  - tasks.md
  - data-model.md

VCS Configuration (0.12.0+)

Spec Kitty uses Git as the version control backend. Configuration options control VCS detection and behavior.

Project-Level VCS Settings

Spec Kitty uses git for version control. Once a feature is created, its VCS is locked in meta.json:

{
  "slug": "016-documentation",
  "vcs": "git"
}

All work packages for that feature use the same VCS backend, ensuring consistency.

Checking Current VCS

Use spec-kitty verify-setup --diagnostics to see which VCS is active:

$ spec-kitty verify-setup --diagnostics
VCS Backend: git

Agent Configuration

Spec Kitty supports AI agents across different platforms. Agent configuration is stored in .kittify/config.yaml and can be managed via CLI commands. Slash-command agents use user-global command roots; Codex and Vibe use project-local command skills under .agents/skills/.

Supported Agents

Agent Key	Managed Surface	Platform
`claude`	`~/.claude/commands/`	Claude (Anthropic)
`copilot`	`~/.github/prompts/`	GitHub Copilot
`gemini`	`~/.gemini/commands/`	Google Gemini
`cursor`	`~/.cursor/commands/`	Cursor AI
`qwen`	`~/.qwen/commands/`	Qwen Code
`opencode`	`~/.opencode/command/`	OpenCode
`windsurf`	`~/.windsurf/workflows/`	Windsurf
`codex`	`.agents/skills/spec-kitty.<command>/`	Codex CLI
`kilocode`	`~/.kilocode/workflows/`	Kilocode
`auggie`	`~/.augment/commands/`	Augment Code
`roo`	`~/.roo/commands/`	Roo Cline
`q`	`~/.amazonq/prompts/`	Amazon Q

Configuration File

Agent configuration is stored in .kittify/config.yaml:

agents:
  available:
    - opencode
    - claude

Field	Type	Description
`agents.available`	list	Agents enabled for this project

Config-Driven Agent Management

Starting in spec-kitty 0.12.0, agent configuration follows a config-driven model where .kittify/config.yaml is the single source of truth for which agents are active in your project.

Key principles:

Active agents are derived from config.yaml
Slash-command files are installed globally at CLI startup
Codex and Vibe command skills are project-local under .agents/skills/
Migrations respect config.yaml - only process configured agents
Use spec-kitty agent config commands to manage agents (not manual editing)

Schema:

agents:
  available:
    - claude
    - codex
    - opencode

Fields:

available (list): Agent keys currently active in project

See:

Managing AI Agents - Complete guide to agent management commands
CLI Reference: spec-kitty agent config - Command syntax and options
ADR #6: Config-Driven Agent Management - Architectural decision rationale

Legacy behavior: Projects without agents.available field default to the full slash-command agent set for backward compatibility (currently 13 agent keys in the active CLI surface). To adopt config-driven model, use spec-kitty agent config remove to remove unwanted agents.

Managing Agents

List Configured Agents

spec-kitty agent config list

Output:

Configured agents:
  ✓ opencode (~/.opencode/command/ (global))
  ✓ claude (~/.claude/commands/ (global))

Available but not configured:
  - codex, copilot, gemini, ...

Add Agents

spec-kitty agent config add claude codex

This command:

Registers slash-command agents against their global command roots
Installs project-local command skills for Codex and Vibe
Updates config.yaml to include new agents

Remove Agents

spec-kitty agent config remove codex gemini

This command:

Deletes agent directories
Updates config.yaml to remove agents

Options:

--keep-config: Delete directory but keep in config (useful for temporary removal)

Check Agent Status

spec-kitty agent config status

Shows a table of all agents with their status:

OK: Configured and managed command surface exists
Missing: Configured but managed command surface doesn't exist
Orphaned: Directory exists but not configured
Not used: Neither configured nor present

Example output:

┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┓
┃ Agent Key ┃ Directory           ┃ Configured ┃ Exists ┃ Status   ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━┩
│ opencode  │ ~/.opencode/command/ (global)     │ ✓ │ ✓ │ OK       │
│ claude    │ ~/.claude/commands/ (global)      │ ✓ │ ✓ │ OK       │
│ codex     │ .agents/skills/ (project skills)  │ ✗ │ ✓ │ Orphaned │
└───────────┴─────────────────────┴────────────┴────────┴──────────┘

⚠ 1 orphaned directory found (present but not configured)

Sync Filesystem with Config

spec-kitty agent config sync

Synchronizes filesystem with config.yaml:

By default, removes orphaned directories (present but not configured)
Use --create-missing to check configured managed surfaces and restore supported project-local skill roots
Use --keep-orphaned to keep orphaned directories

Examples:

# Remove orphaned agents (default)
spec-kitty agent config sync

# Create missing directories for configured agents
spec-kitty agent config sync --create-missing

# Keep orphaned directories
spec-kitty agent config sync --keep-orphaned

Agent Selection During Init

When creating a new project, select agents interactively or via CLI:

# Interactive selection
spec-kitty init myproject

# CLI selection
spec-kitty init myproject --ai opencode,claude

# Single agent
spec-kitty init myproject --ai opencode

Selected agents are stored in config.yaml and their directories are created automatically.

Migration Behavior

Important: Migrations respect config.yaml as the single source of truth.

Upgrades only process configured agents - If you remove an agent, upgrades won't recreate it
Deleted agents stay deleted - Manual deletions are respected
Legacy projects fallback gracefully - Projects without config.yaml process the full supported slash-command agent set

This ensures your agent preferences are preserved across upgrades.

Troubleshooting

Q: Why did upgrade recreate agents I deleted?

This was a bug in versions prior to 0.12.0. Upgrade to the latest version and use spec-kitty agent config remove instead of manual deletion.

Q: How do I add an agent I initially skipped?

spec-kitty agent config add <agent-key>

Q: Can I use multiple agents in one project?

Yes! Configure multiple agents in config.yaml and they'll be used according to your selection strategy (preferred or random).

Q: What if I manually deleted agent directories?

Use spec-kitty agent config sync to clean up the config or --create-missing to recreate them.

Legacy Configuration

.kittify/active-mission (Deprecated)

Status: Deprecated in v0.8.0+

Previously stored the project-wide active mission. Now missions are per-feature and stored in meta.json.

If you see this file in older projects, it will be ignored. The mission in each feature's meta.json takes precedence.

Getting Started

Claude Code Integration

Table of Contents

Configuration Reference

meta.json (Feature Metadata)

Work Package Frontmatter

docfx.json (Documentation Build)

toc.yml (Table of Contents)

charter.md (Project Principles)

Mission Configuration (Advanced)

VCS Configuration (0.12.0+)

Project-Level VCS Settings

Checking Current VCS

Agent Configuration

Supported Agents

Configuration File

Config-Driven Agent Management

Managing Agents

List Configured Agents

Add Agents

Remove Agents

Check Agent Status

Sync Filesystem with Config

Agent Selection During Init

Migration Behavior

Troubleshooting

Legacy Configuration

.kittify/active-mission (Deprecated)

See Also

Getting Started

Practical Usage