Spec-Driven Development Toolkit

Spec Kitty Technical Evolution

From first stable PyPI release to event-log architecture and thin agent shims — every major technical addition from v1.0.0 through v3.1.1.

v1.0.0 → v2.1.4 → v3.1.1 Feb — Apr 2026
1,957
Total Commits
100+
Git Tags
12
Agent Support
4
Mission Types
Version 1.x — First Stable PyPI Release
v1.0.0Feb 24, 2026
First Stable Release — Promoted from v0.16.2
The culmination of 16 pre-release cycles. Spec Kitty graduates to a stable PyPI package with a clear contract boundary: the bundled orchestrator is gone.
Breaking Orchestrator Removed Orchestrator API
  • Bundled spec-kitty orchestrate hard-removed with no compatibility shim
  • Orchestration externalized behind spec-kitty orchestrator-api command group
  • Versioned host orchestration contract with JSON envelope responses
  • Boundary CI guardrail prevents re-introducing bundled orchestrator
  • ADR documentation for orchestration externalization (security, extensibility)
v1.0.1Feb 27
Dependency Floor Hardening
Explicit lower bounds for typer, rich, httpx, platformdirs, and readchar. Release validation robustness for version tags and branch parity.
v1.0.2Mar 4
MIT-Cleared Dependency Pins
spec-kitty-events==0.4.1 stabilized. Release train compatibility matrix added for downstream packages.
v1.0.3Mar 6
Template Schema Readiness Gate
Upgrade JSON made machine-parseable. Migration status reporting consistency. Template schema validation gate for meta.json.
Schema Gate
Version 2.x — Event Architecture & Skills
v2.0.0Feb 22, 2026
Parallel Development Track — GitHub-Only Releases
A parallel 2.x branch for SaaS features, running alongside 1.x on PyPI. Semantic versioning adoption and deterministic runtime mission template selection.
SemVer Runtime Templates
v2.0.3 – v2.0.7Jan–Feb
Architecture Cleanup Sprint
  • Target branch routing for status commits (ADR-13)
  • Explicit metadata fields (ADR-14)
  • Smart dependency detection (ADR-15)
  • Auto-create target branch on first implement (ADR-17)
  • Rich JSON outputs for agent commands (ADR-16)
  • Centralized feature detection with priority-6 fallback
v2.0.8 – v2.0.11Feb
Dashboard, Merge & Skills Foundation
  • Merge target resolution from feature meta.json
  • Dashboard sidebar collapsibility and "Done" lane semantics (ADR-21)
  • Multi-parent merge optimization
  • Agent Skills Pack introduced — canonical skill distribution (Feature 055)
  • Structured requirement mapping for WP tracing
Skills Pack Req Mapping
v2.1.0Mar 21
Promoted to Stable Main — Replaces 1.x
The 2.x line becomes the primary release. 6 canonical bundled skills with registry/installer/verification. Structured requirement mapping for delivery intent tracing.
6 Skills /clarify Removed Stable Main
v2.1.2Mar 23
Skills Expansion & DocFX Sprint
  • 6 → 8 skills: added mission-system and git-workflow
  • All 8 skills audited with full architecture documentation
  • 56 docs files now in DocFX build
  • 10 upgrade migrations for skill fixes/installations
8 Skills 56 Docs
v2.1.4Mar 27
Command File State Enforcement
Version markers in command files (<!-- spec-kitty-command-version: X.Y.Z -->). New spec-kitty doctor command-files subcommand for validation.
Version Markers Doctor CLI
Version 3.x — Architecture Refresh
v3.0.0Mar 30, 2026
Fundamental Architecture Redesign
The largest single release in Spec Kitty history. Event log becomes the sole authority for mutable WP state. Feature detection deleted. Sparse checkout removed. Hybrid command templates introduced.
3 Breaking Changes 6 New Systems 8 Modules Deleted
BREAKING CHANGES
  • Event log is sole authority — frontmatter lane, review_status, reviewed_by, progress no longer written at runtime. ~650 lines of dual-write code removed
  • Feature detection deleted — feature_detection.py (668 lines) removed. All commands require explicit --feature <slug>
  • Sparse checkout removed — planning artifacts work in-repo; code WPs use standard worktrees
NEW SYSTEMS
  • MissionContext — opaque token-based bound identity, replaces string feature detection
  • WP Ownership Manifest — execution_mode, owned_files, authoritative_surface per WP
  • Lane-weighted progress — planned=0.0, in_progress=0.3, for_review=0.6, done=1.0
  • Dedicated merge workspace — .kittify/runtime/merge/ with atomic lock mechanism
  • Thin agent shims — 56 template files → 9 canonical + 7 thin shims
  • One-shot migration framework — backfill_identity, backfill_ownership, rebuild_state, strip_frontmatter
REMOVED
  • feature_detection.py (668 lines)
  • status/legacy_bridge.py, phase.py, reconcile.py, migrate.py
  • merge/executor.py, forecast.py, status_resolver.py
  • core/agent_context.py
  • 56 full command template files
v3.1.0Apr 2026
Architecture Consolidation
Post-3.0 stabilization with major deduplication, new interactive constitution command, and mission-aware cleanup wiring.
Constitution 900+ Lines Deduped
  • Interactive constitution command — 4-phase discovery workflow
  • Mission-aware cleanup & docs wiring
  • Worktree topology context for stacked branches
  • Shared task helpers consolidation — ~900 lines deduplicated
  • Shared acceptance core module extraction
v3.1.1Apr 21
Contract Hardening Closeout
Current release. Deterministic branch and runtime JSON contracts. Upgrade migration status consistency. Template schema readiness gate.
Current
Evolution — State Management
v0.x – v1.x
Direct Frontmatter
WP state lived in YAML frontmatter fields. Every status change wrote directly to the file. Simple but fragile — merge conflicts on every parallel edit.
→
v2.x
Dual-Write
Event log + frontmatter written simultaneously. The event log was source of truth, but frontmatter was still updated for backward compatibility. ~650 lines of dual-write code.
→
v3.x
Event Log Authority
Event log (status.events.jsonl) is the sole authority. Frontmatter is read-only. Dual-write code eliminated. State derived via reducer function.
Evolution — Command Execution
v1.x
Python CLI + Full Templates
56 command template files deployed to each agent directory. Every template was a full prompt with embedded logic and context.
→
v2.x
Slash Commands + Missions
Slash commands (/spec-kitty.*) routed through mission templates. Skills pack distributed alongside. Version markers added for drift detection.
→
v3.x
Hybrid Thin Shims
Planning commands = full prompts. Execution commands = thin CLI-dispatch shims. 56 templates → 9 canonical + 7 shims. Massive reduction in template drift surface.
Before (v2.x) — 56 Templates
After (v3.x) — 16 Templates
Each of 12 agents got full copies of every command template. Each template contained the full prompt, context instructions, file discovery sections, and workflow logic. Template drift was constant.
9 canonical planning prompts (specify, plan, tasks, etc.) with full content. 7 thin shims for execution commands (implement, review, merge, etc.) that dispatch to spec-kitty agent shim. Template drift nearly eliminated.
Evolution — Feature Detection
v1.x
Branch Auto-Detect
Branch scanning, env var detection, and cwd walking to guess which feature you meant. Magic but unreliable in multi-feature repos.
→
v2.x
Priority Fallback
Centralized detection with a priority cascade. Priority-6 fallback to latest incomplete feature. Better, but still implicit — wrong guesses in edge cases.
→
v3.x
Explicit MissionContext
Feature detection deleted (668 lines). All commands require --feature <slug>. MissionContext tokens provide opaque, bound identity. Zero ambiguity.
Agent Ecosystem — 12 Supported Agents
Supported Agents
Claude Code GitHub Copilot Google Gemini Cursor Qwen Code OpenCode Windsurf GitHub Codex Kilocode Augment Code Roo Cline Amazon Q
Config-Driven Management (v0.12.0+)
Single Source of Truth
.kittify/config.yaml — only configured agents get directories, migrations, and template updates. CLI commands: list, add, remove, status, sync.
Skills Distribution
v2.1.0: 6 canonical skills. v2.1.2: 8 skills with full architecture docs. Bundled in wheels with registry, installer, and SHA-256 verification.
Mission Types
SOFTWARE-DEV
Full lifecycle
RESEARCH
Discovery + evidence
DOCUMENTATION
Divio 4-type suite
CONSTITUTION
Governance + knowledge
By The Numbers
v1.x Commits
1,124
v0.15.x → v1.0.3
v2.x Commits
311
v2.0.0a1 → v2.1.4
v3.x Commits
522
v3.0.0 → v3.1.1
Templates Eliminated
56
v3.0.0 → 16 hybrid
Feature Detection Removed
668
lines in v3.0.0
Dual-Write Removed
~650
lines in v3.0.0
Task Helpers Deduped
900+
lines in v3.1.0
ADRs Written
11+
ADR-6 through ADR-21
Docs Files
56
DocFX build (v2.1.2)
Bundled Skills
8
with SHA-256 verification
Upgrade Migrations
30+
across all versions
Review Scrutiny Categories
12
505 lines, 7 security greps
Spec Kitty v3.1.1 — Technical Evolution — Generated April 2026