repository·main·Indexed 23 days ago
https://github.com/priivacy-ai/spec-kittyA spec-driven development framework and CLI that converts product intent into governed AI coding workflows. It features a modular 2.x architecture based on event-sourced persistence, interface-first design, and local-first operation. The system manages the lifecycle of AI tasks using isolated worktrees and stores specs, plans, and review states in Git. Documentation includes CLI reference, Orchestrator API, and detailed architectural guides on domain containers like Kitty-core, Doctrine, and Charter.
The kernel package is a zero-dependency, minimal Python utility library that serves as the foundation for the spec-kitty ecosystem. It provides low-level, shared utilities used by specify_cli, charter, and doctrine.
It is designed as a 'dependency floor' to prevent cyclic imports. The core architecture follows a strict hierarchy where kernel is a leaf node and never imports from any other spec-kitty package.
The 'Charter Ownership Consolidation and Neutrality Hardening' mission is an internal refactor that introduces a new lint module. It does not introduce new CLI commands or new public HTTP/RPC APIs. Instead, it focuses on preserving existing surfaces and introducing new, stable contracts.
These contracts are testable specifications of behavior designed to ensure stability and compliance with functional (FR) and non-functional (NFR) requirements.
The Software-Dev Content Templates provide output artifact scaffolds specifically designed for the software development mission. These templates are used to shape the structure and consistency of the following artifacts produced during mission execution:
The Runtime & State Overhaul engineering notes document the design exploration for unifying mission execution context across the coord/main/lane topology. The goal is to resolve structural failures where different command surfaces independently re-derive mission state, leading to disagreements between reads, writes, and prompts.
Note: This directory contains the grounding layer for the design and is not yet a set of final Architecture Decision Records (ADRs). It captures problem evidence, architectural intent, and governing doctrine to anchor design conversations in evidence.
Key Project Links:
The Safe Sync Daemon Orphan Cleanup mission is governed by normative interface contracts. These are primarily CLI/process contracts rather than RESTful interfaces. The main product surfaces are the spec-kitty auth doctor command and the /api/health loopback endpoint.
There are three primary technical contracts:
cleanup-classification.md.auth doctor --json / --reset --json output: Defined in auth-doctor-json.md./api/health payload (extended): Defined in health-payload.md.Additionally, several behavioral contracts are enforced via tests, including startup auto-clean logic, --reset safety guards, self-retirement transitions, and network boundary constraints.
plan mission. They define the structure and shape of plans and other related artifacts generated during standalone planning workflows within Spec Kitty.scripts/tool_configs/ directory contains modular glue scripts designed to improve day-to-day usability. These scripts handle environment and bootstrap logic (such as shared Python virtual environment activation) to ensure that user-facing setup remains consistent across different shells and platforms, without altering the core behavior of Spec Kitty.Writing Styleguides in Spec Kitty are used to enforce quality standards for written prose and documentation. They are specifically scoped to ensure consistency in glossary definitions, doctrine descriptions, and other user-facing text.
Currently, the available writing styleguide is:
kitty-glossary-writing.styleguide.yaml: Scoped to the glossary. It enforces 8 principles for writing glossary terms, focusing on being "clear over clever," avoiding "buzzword soup," and utilizing HiC terminology.The documentation mission provides scaffolds for creating documentation artifacts. These templates are organized into two main categories:
divio/ directory, these follow the Divio 4-type structure: tutorial, how-to, reference, and explanation.generators/ directory, these provide configurations for API documentation generators such as JSDoc and Sphinx.Additionally, the mission includes scaffolds for mission-specific plan and spec documents.
The Mission-Lifecycle Tooling Friction mission focuses on hardening existing spec-kitty surfaces rather than introducing new external APIs. The deliverables are behavioral improvements to the following existing components:
specify, backfill-topology).Success is measured by executable acceptance tests defined in acceptance-matrix.json. If you are developing or verifying these surfaces, ensure your changes satisfy the specific behavioral contracts and negative invariants (properties that must not happen) associated with each Functional Requirement (FR).
Spec Kitty is a cross-platform CLI tool (Linux, macOS, Windows 10+) built as a single Python package (src/specify_cli/). It requires Python 3.11+.
Spec Kitty manages various configuration and profile files across different formats:
.kittify/config.yaml and agent profiles with frontmatter (.claude/agents/, .github/agents/, .augment/agents/)..codex/agents/).~/.aws/amazonq/cli-agents/), plugin manifests (.claude-plugin/plugin.json, .codex-plugin/plugin.json), and skill manifests (.kittify/command-skills-manifest.json, .kittify/skills-manifest.json).spec-kitty upgrade should complete in $\le 30$s.spec-kitty plugin build should complete in $\le 60$s.doctor tool-surfaces should complete in $\le 5$s.--yes flag must never overwrite drifted files automatically.plan-context-bootstrap-fix wave is a handoff package containing canonical artifacts designed for downstream replay. It provides the necessary context and state to allow subsequent processes or agents to resume or replay specific planning and bootstrapping operations. To identify the specific identity anchor for this package, refer to the namespace.json file within the package.