How jlacube/spec-kitty works
Project type and purpose
• This is a full-stack command‐line application plus embedded web dashboard, implemented in Python as a modular monolith.
• Purpose: orchestrate multiple LLM agents in a spec-driven development workflow, managing feature specs, work-packages, git worktrees, automated merges, and a real-time Kanban dashboard.
File structure
• Top-level directories:
• src/specify_cli/ – all Python code for CLI commands, core services, orchestrator, dashboard, merge, template system, upgrades, validators
• .kittify/ – project scaffolding & mission templates, configuration, guardrails
• kitty-specs/ – feature specification, plan, tasks artifacts per feature
• .worktrees/ (created at runtime) – isolated workspaces for each work-package
• docs/, examples/, research/ – documentation, tutorials, sample workflows
• tests/ – comprehensive unit, integration, and end-to-end tests
• .github/, scripts/, CI workflows – build, test, release automation
• Key modules under src/specify_cli/:
• cli/commands – the command dispatchers for spec-kitty commands
• core/ – configuration, context validation, git operations, worktree management, dependency graph, VCS abstraction
• orchestrator/ – scheduler, executor, agent adapters, state management, monitoring, integration tests
• dashboard/ – server, API handlers, scanner, static assets, templates (MVC pattern)
• merge/ – multi-parent merge, preflight validation, conflict forecast, state resolution
• template/, doc_generators.py – render templates, generate mission artifacts
• upgrade/ – versioned migrations to evolve project structure
• Config files (pyproject.toml, package.json, docs assets) indicate Python packaging and Node-based CSS/JS for the dashboard front-end.
README for additional insights
• Confirms CLI entrypoint spec-kitty, 12 AI agents supported, real-time Kanban dashboard via spec-kitty dashboard
• Describes a spec-driven workflow: constitution → specify → plan → tasks → implement → review → accept → merge
• Highlights workspace-per-work-package strategy: one git worktree per WP under .worktrees/ symlinked back to .kittify/ for shared constitution
a. Main components:
1. CLI Frontend
– spec-kitty command dispatcher (entrypoint)
– CLI modules: parser → command implementations in src/specify_cli/cli/commands
2. Core Services Layer
– Configuration & context validation (core/config.py, core/context_validation.py)
– Git & worktree management (core/git_ops.py, core/worktree.py, core/vcs/*)
– Dependency graph & project resolution
3. Orchestrator
– Scheduler & executor (orchestrator/scheduler.py, orchestrator/executor.py)
– Agent adapters plugin system (orchestrator/agents/*.py)
– Monitoring & state persistence (orchestrator/monitor.py, orchestrator/state.py)
4. AI Agents (external processes)
– Claude, Codex, Copilot, Gemini, Cursor, etc. (invoked via CLI wrappers)
5. Dashboard Backend
– HTTP server (dashboard/server.py)
– API handlers & router (dashboard/handlers/api.py, etc.)
– Scanner & lifecycle events push updates to UI
6. Dashboard Frontend
– Static assets: HTML/CSS/JS under dashboard/static/dashboard
– Browser UI (Kanban board, progress metrics)
7. File System & Git Repository
– .kittify/ for config & templates
– kitty-specs/ storing spec/plan/tasks artifacts
– .worktrees/ holding feature WP sandboxes
– Git branches & commits for feature lifecycle
8. CI/CD & Release Automation
– GitHub Actions workflows, pre-commit hooks, release scripts
b. Relationships and interactions:
• CLI interprets user commands → invokes Core Services → reads/writes filesystem, manipulates Git & worktrees
• Orchestrator commands drive AI agent adapters → agents generate or review content → results written back
• Dashboard server scans the repo state and orchestrator state files → exposes REST/WebSocket API → frontend polls/streams updates
• CLI commands (dashboard, merge, etc.) can start/stop the server, push metrics, trigger merges, cleanup worktrees
• Upgrade & template subsystems mutate .kittify/ and project structure based on version migrations
c. Architectural patterns and principles:
• Layered architecture: CLI layer → core services → orchestrator → external agents
• Plugin pattern for agent integration under orchestrator/agents (conforming to a common protocol)
• MVC for dashboard: handlers serve model (state files), templates/static assets form the view
• Git worktree strategy as sandbox isolation pattern
• Config-driven behavior (.kittify/config.yaml, mission YAML) for domain adaptation
d. Key technologies and libraries:
• Language: Python 3.11+
• CLI parsing: click or argparse via src/specify_cli/cli
• Web server: Python HTTP server in src/specify_cli/dashboard/server.py (custom or lightweight framework)
• Templating: Jinja2 for both CLI code generators and dashboard templates
• Git integration: subprocess-based wrappers in core/vcs/git.py, core/vcs/jujutsu.py
• State serialization: JSON frontmatter in markdown, .json files under .worktrees
• Static UI assets: vanilla JS/CSS (no heavy front-end framework)
• Testing: pytest for Python, Playwright for dashboard end-to-end
Be detailed and explicit
• Important patterns: worktree isolation, plugin loading, migration runner, pre-commit hook trigger
• Essential modules by name (e.g., “core/git_ops.py,” “orchestrator/scheduler.py,” “dashboard/handlers/api.py”)
• Don’t over-normalize: break the system into these major components and show interactions at their boundaries