# jlacube/spec-kitty architecture

> Architecture diagram of the GitHub repository jlacube/spec-kitty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jlacube/spec-kitty
- Repository: https://github.com/jlacube/spec-kitty

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontend
    subgraph "CLI Frontend"
        CLI["spec-kitty CLI"]:::cli
    end
    click CLI "https://github.com/jlacube/spec-kitty/tree/main/src/specify_cli/cli/commands/"

    %% Core Services Layer
    subgraph "Core Services Layer"
        Config["Config & Context Validation"]:::core
        GitOps["Git & Worktree Management"]:::core
        Dependency["Dependency Graph & Resolver"]:::core
    end
    click Config "https://github.com/jlacube/spec-kitty/tree/main/src/specify_cli/core/"
    click GitOps "https://github.com/jlacube/spec-kitty/tree/main/src/specify_cli/core/"
    click Dependency "https://github.com/jlacube/spec-kitty/tree/main/src/specify_cli/core/"

    %% Orchestrator Layer
    subgraph "Orchestrator"
        Scheduler["Scheduler & Executor"]:::orchestrator
        Agents["Agent Adapters"]:::orchestrator
        Monitor["Monitoring & State"]:::orchestrator
    end
    click Scheduler "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/orchestrator/scheduler.py"
    click Agents "https://github.com/jlacube/spec-kitty/tree/main/src/specify_cli/orchestrator/agents/"
    click Monitor "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/orchestrator/monitor.py"
    click MonitorState "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/orchestrator/state.py"

    %% External AI Agents
    Agents -->|invoke| AIAgents["External AI Agent CLIs"]:::ai

    %% Dashboard Layer
    subgraph "Dashboard Backend"
        Server["HTTP Server"]:::dashboard
        API["API Handlers & Router"]:::dashboard
        Scanner["Scanner & Lifecycle"]:::dashboard
    end
    click Server "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/server.py"
    click API "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/handlers/api.py"
    click API "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/handlers/router.py"
    click API "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/handlers/base.py"
    click Scanner "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/scanner.py"
    click Scanner "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/lifecycle.py"

    subgraph "Dashboard Frontend"
        UI["Static Assets & Templates"]:::dashboard
    end
    click UI "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/static/dashboard/dashboard.js"
    click UI "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/static/dashboard/dashboard.css"
    click UI "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/dashboard/templates/index.html"

    %% Merge Subsystem
    subgraph "Merge Subsystem"
        MergeExec["Merge Executor & Forecast"]:::infra
        MergeOrder["Ordering & Preflight"]:::infra
        MergeState["State Resolution"]:::infra
    end
    click MergeExec "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/merge/executor.py"
    click MergeExec "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/merge/forecast.py"
    click MergeOrder "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/merge/ordering.py"
    click MergeOrder "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/merge/preflight.py"
    click MergeState "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/merge/state.py"
    click MergeState "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/merge/status_resolver.py"

    %% Template System
    subgraph "Template System"
        Renderer["Core Renderer & Manager"]:::infra
        Templates["Central Templates"]:::infra
    end
    click Renderer "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/template/renderer.py"
    click Renderer "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/template/manager.py"
    click Renderer "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/template/asset_generator.py"
    click Renderer "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/template/github_client.py"
    click Templates "https://github.com/jlacube/spec-kitty/tree/main/src/specify_cli/templates/"

    %% Upgrade & Migrations
    subgraph "Upgrade & Migrations"
        Runner["Migration Runner & Registry"]:::infra
        Migrations["Versioned Migrations"]:::infra
    end
    click Runner "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/upgrade/runner.py"
    click Runner "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/upgrade/registry.py"
    click Migrations "https://github.com/jlacube/spec-kitty/tree/main/src/specify_cli/upgrade/migrations/"

    %% Validators
    subgraph "Validators"
        PathsVal["Path Validator"]:::infra
        ResearchVal["Research Validator"]:::infra
    end
    click PathsVal "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/validators/paths.py"
    click ResearchVal "https://github.com/jlacube/spec-kitty/blob/main/src/specify_cli/validators/research.py"

    %% Mission Plugins
    subgraph "Mission Plugins"
        Missions["Mission Definitions & Templates"]:::infra
    end
    click Missions "https://github.com/jlacube/spec-kitty/tree/main/src/specify_cli/missions/"

    %% File System & Git Integration
    subgraph "File System & Git"
        Kittify[".kittify"]:::fs
        Specs["kitty-specs"]:::fs
        Worktrees[".worktrees"]:::fs
    end

    %% CI/CD & Automation
    subgraph "CI/CD & Automation"
        GHActions["GitHub Actions Workflows"]:::infra
        Hooks["Release & Hook Scripts"]:::infra
    end
    click GHActions "https://github.com/jlacube/spec-kitty/tree/main/.github/workflows/"
    click Hooks "https://github.com/jlacube/spec-kitty/tree/main/scripts/git-hooks/"
    click Hooks "https://github.com/jlacube/spec-kitty/tree/main/scripts/release/"

    %% Relationships
    CLI -->|"dispatch"| Config
    CLI -->|"dispatch"| GitOps
    CLI -->|"dispatch"| Dependency
    Config --> Kittify
    GitOps --> Worktrees
    Dependency --> Specs

    CLI -->|"schedule tasks"| Scheduler
    Scheduler --> Agents
    Agents --> AIAgents
    AIAgents -->|results| Monitor
    Monitor --> Worktrees

    CLI -->|start/stop| Server
    Server --> API
    API --> Scanner
    Scanner --> Specs
    Server --> UI
    UI -->|poll/stream| API

    CLI -->|merge command| MergeExec
    MergeExec --> MergeOrder
    MergeOrder --> MergeState
    MergeState --> Worktrees

    CLI -->|render templates| Renderer
    Renderer --> Templates
    Renderer --> Kittify

    CLI -->|run migrations| Runner
    Runner --> Migrations
    Runner --> Kittify

    CLI -->|validate| PathsVal
    CLI -->|validate| ResearchVal

    CLI -->|load missions| Missions
    Missions --> Templates

    ScriptsCI["Scripts & Hooks"]:::infra
    GHActions --> ScriptsCI
    Hooks --> ScriptsCI

    %% Class Definitions
    classDef cli fill:#D0E6FF,stroke:#0366D6;
    classDef core fill:#D0E6FF,stroke:#0366D6;
    classDef orchestrator fill:#E6FFDF,stroke:#28A745;
    classDef dashboard fill:#FFF4E6,stroke:#FF8C00;
    classDef fs fill:#F0F0F0,stroke:#666666;
    classDef ai fill:#F4E6FF,stroke:#6F42C1;
    classDef infra fill:#FEF2C0,stroke:#DBAB09;
```
