spec-kitty-cli 3.2.2__tar.gz → 3.2.4__tar.gz

spec_kitty_cli-3.2.4/.github/CHANGELOG.md

@@ -0,0 +1 @@
+../docs/changelog/CHANGELOG.md

spec_kitty_cli-3.2.4/CHANGELOG.md

@@ -0,0 +1 @@
+docs/changelog/CHANGELOG.md

spec_kitty_cli-3.2.4/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: spec-kitty-cli
+Version: 3.2.4
+Summary: Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation.
+Project-URL: Repository, https://github.com/Priivacy-ai/spec-kitty
+Project-URL: Issues, https://github.com/Priivacy-ai/spec-kitty/issues
+Project-URL: Documentation, https://docs.spec-kitty.ai/
+Project-URL: Changelog, https://github.com/Priivacy-ai/spec-kitty/blob/main/CHANGELOG.md
+Author: Spec Kitty Contributors
+Maintainer: Spec Kitty Contributors
+License: MIT License
+        
+        Copyright GitHub, Inc.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agentic-development,ai-agents,ai-coding,claude-code,cli,code-generation,feature-specs,git-worktree,kanban,llm-tools,planning,requirements,sdd,spec-driven-development,specification,workflow-automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: charset-normalizer<4,>=3.4
+Requires-Dist: click>=8.2.1
+Requires-Dist: cryptography>=48.0.1
+Requires-Dist: filelock>=3.13.0
+Requires-Dist: google-re2>=1.1
+Requires-Dist: httpx[socks]>=0.28.1
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: platformdirs>=4.9.2
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pygments>=2.20.0
+Requires-Dist: python-ulid>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: readchar>=4.2.1
+Requires-Dist: requests>=2.33.0
+Requires-Dist: rich>=14.3.3
+Requires-Dist: ruamel-yaml>=0.18.0
+Requires-Dist: spec-kitty-events<7.0.0,>=6.0.0
+Requires-Dist: spec-kitty-tracker<0.5,>=0.4
+Requires-Dist: toml>=0.10.2
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: transitions>=0.9.2
+Requires-Dist: truststore>=0.10.4
+Requires-Dist: typer>=0.24.1
+Requires-Dist: websockets>=12.0
+Provides-Extra: lint
+Requires-Dist: bandit>=1.7.0; extra == 'lint'
+Requires-Dist: cyclonedx-bom>=4.0; extra == 'lint'
+Requires-Dist: msgpack>=1.2.1; extra == 'lint'
+Requires-Dist: mypy>=1.10.0; extra == 'lint'
+Requires-Dist: pip-audit>=2.7.0; extra == 'lint'
+Requires-Dist: ruff>=0.4.0; extra == 'lint'
+Requires-Dist: types-jsonschema>=4.0.0; extra == 'lint'
+Requires-Dist: types-psutil>=5.9.0; extra == 'lint'
+Requires-Dist: types-pyyaml>=6.0; extra == 'lint'
+Requires-Dist: types-requests>=2.33.0; extra == 'lint'
+Requires-Dist: types-toml>=0.10.0; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: build>=1.0.0; extra == 'test'
+Requires-Dist: chardet<6,>=3.0.4; extra == 'test'
+Requires-Dist: diff-cover>=10.0.0; extra == 'test'
+Requires-Dist: mutmut>=3.5.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest-timeout>=2.2.0; extra == 'test'
+Requires-Dist: pytest-xdist>=3.8.0; extra == 'test'
+Requires-Dist: pytest>=9.0.3; extra == 'test'
+Requires-Dist: pytestarch>=4.0.0; extra == 'test'
+Requires-Dist: respx>=0.21.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <img src="https://github.com/Priivacy-ai/spec-kitty/raw/main/media/logo_small.webp" alt="Spec Kitty logo"/>
+    <h1>Spec Kitty</h1>
+    <p><strong>Spec-driven development for AI coding agents, multi-agent workflows, and governed software factories.</strong></p>
+</div>
+
+Spec Kitty is an open-source CLI for turning product intent into a repo-native AI coding workflow:
+
+```text
+spec -> plan -> tasks -> next -> review -> accept -> merge
+```
+
+Use it to build a governed software factory around Claude Code, Codex, Cursor, Gemini, GitHub Copilot, Windsurf, OpenCode, and other AI coding agents. Spec Kitty keeps specs, plans, work packages, acceptance criteria, review state, and merge decisions in your repository, then gives agents isolated git worktrees so implementation can happen in parallel without branch chaos.
+
+[![PyPI version](https://img.shields.io/pypi/v/spec-kitty-cli?style=flat-square&logo=pypi)](https://pypi.org/project/spec-kitty-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue?style=flat-square)](https://www.python.org/downloads/)
+
+## Bright Software Factory, Not a Black Box
+
+Spec Kitty is for teams building software factories: repeatable inputs, clear work-package boundaries, isolated execution, visible progress, and review gates. It can support dark software factories and autonomous coding experiments, but it is deliberately not a lights-out black box by default. Humans define intent, architecture, and acceptance criteria; agents implement inside traceable worktrees; reviewers accept, reject, or merge with an audit trail.
+
+The goal is not more prompt text. The goal is a durable operating system for agentic coding where the repository remains the source of truth.
+
+## Is It For You?
+
+Use Spec Kitty when:
+
+- AI coding sessions are losing requirements, decisions, or acceptance criteria.
+- You want specs, plans, tasks, reviews, and merge state stored in Git.
+- Multiple agents or developers need clear work-package boundaries.
+- You are running parallel Claude Code, Codex, Cursor, Copilot, Gemini, or Windsurf work and need git worktree isolation.
+- You are moving from vibe coding to a repeatable spec-driven development workflow.
+- You want a local workflow first, with optional hosted tracker and sync integrations later.
+
+It is probably overkill for one-off edits, tiny scripts, or teams that do not use Git.
+
+## What It Provides
+
+| Need | Spec Kitty provides |
+| --- | --- |
+| Start from intent | Guided `specify`, `plan`, and `tasks` workflows |
+| Keep agents aligned | Repository-native mission artifacts under `kitty-specs/` |
+| Split implementation | Work packages with lifecycle lanes such as `planned`, `in_progress`, `for_review`, `approved`, and `done` |
+| Run agents in parallel | Isolated git worktrees under `.worktrees/` |
+| Keep quality visible | Review, accept, merge, and retrospective gates |
+| See progress | Optional local kanban dashboard with `spec-kitty dashboard` |
+| Integrate agents | Slash commands or skills for Claude Code, Codex, Cursor, Gemini, Copilot, Windsurf, OpenCode, and more |
+| Learn from missions | Every completed mission generates a retrospective by default. Tune via `.kittify/config.yaml#retrospective` or charter; see [how-to](docs/guides/use-retrospective-learning.md). |
+
+## Common Use Cases
+
+- Replace ad hoc vibe coding with spec-driven development.
+- Turn GitHub issues, product requirements, or bug reports into executable work packages.
+- Coordinate multiple AI coding agents without losing context between sessions.
+- Keep architecture decisions, constraints, and acceptance criteria close to the code.
+- Build a governed software factory that can scale toward more autonomy without hiding review, test, or merge decisions.
+
+## Governance layer
+
+Spec Kitty keeps runtime governance in the repo instead of treating it as
+agent-only prompt text. The trail model in [docs/trail-model.md](docs/trail-model.md)
+describes how `spec-kitty dispatch "<request>"` maps operator intent to
+runtime behavior, while
+[docs/host-surface-parity.md](docs/host-surface-parity.md) tracks parity across
+CLI, slash-command, and hosted surfaces.
+
+The primary standalone governance command is:
+
+- `spec-kitty dispatch "<request>"` - loads governance context, opens an Op record, and returns the context the agent must use before doing the work
+
+## Quick Start
+
+Install the CLI:
+
+```bash
+pipx install spec-kitty-cli
+```
+
+`pipx` is the preferred installer for the CLI because it keeps Spec Kitty in its
+own virtual environment and avoids the `externally-managed-environment` errors
+common on modern Linux distributions.
+
+Other supported install methods:
+
+```bash
+uv tool install spec-kitty-cli
+# or, inside an activated virtual environment
+python -m pip install spec-kitty-cli
+```
+
+Create or initialize a project:
+
+```bash
+spec-kitty init my-project --ai claude
+cd my-project
+spec-kitty verify-setup
+```
+
+Replace `claude` with your agent key when needed. Common choices include `codex`, `cursor`, `gemini`, `copilot`, `opencode`, `qwen`, `windsurf`, `kiro`, `vibe`, `pi`, and `letta`. See [Supported Agents](docs/api/supported-agents.md) for the current list.
+
+Open your AI coding agent in the project and run the core workflow:
+
+```text
+/spec-kitty.charter
+/spec-kitty.specify Build a small task list app.
+/spec-kitty.plan
+/spec-kitty.tasks
+```
+
+Then let the runtime choose the next action until the mission is ready:
+
+```bash
+spec-kitty next --agent claude --mission <mission-slug>
+```
+
+Review, accept, merge, and close the loop:
+
+```text
+/spec-kitty.review
+/spec-kitty.accept
+/spec-kitty.merge --push
+```
+
+After merge, run `/spec-kitty-mission-review`. The mission's
+`retrospective.yaml` is authored during the runtime terminus (HiC prompt or
+autonomous facilitator), not by `merge`. Once it exists, use
+`spec-kitty retrospect summary` for the cross-mission view and
+`spec-kitty agent retrospect synthesize --mission <mission-slug>` to apply any
+staged proposals (dry-run by default — pass `--apply` to mutate).
+
+For the full walkthrough, see [Your First Feature](docs/guides/your-first-feature.md).
+
+## Everyday Commands
+
+| Command | Purpose |
+| --- | --- |
+| `spec-kitty init . --ai <agent>` | Add Spec Kitty to the current repo |
+| `spec-kitty verify-setup` | Check local installation and project wiring |
+| `spec-kitty dashboard` | Open the local mission dashboard |
+| `spec-kitty next --agent <agent> --mission <slug>` | Ask Spec Kitty what the agent should do next |
+| `spec-kitty upgrade` | Update an existing project after upgrading the CLI |
+| `spec-kitty --help` | Show available commands |
+
+## Documentation
+
+Start here:
+
+- [Getting Started](docs/guides/getting-started.md)
+- [Your First Feature](docs/guides/your-first-feature.md)
+- [Orchestrator Quickstart](docs/guides/orchestrator-quickstart.md)
+- [CLI Command Reference](docs/api/cli-commands.md)
+- [Slash Commands](docs/api/slash-commands.md)
+- [Supported Agents](docs/api/supported-agents.md)
+- [Dashboard Guide](docs/guides/use-dashboard.md)
+- [Install and Upgrade](docs/guides/install-and-upgrade.md)
+
+Deeper topics:
+
+- [Spec-Driven Development](docs/architecture/spec-driven-development.md)
+- [Mission System](docs/architecture/mission-system.md)
+- [Git Worktrees](docs/architecture/git-worktrees.md)
+- [Multi-Agent Orchestration](docs/architecture/multi-agent-orchestration.md)
+- [External Orchestrator Runbook](docs/guides/run-external-orchestrator.md)
+- [Hosted Sync Workspaces](docs/guides/sync-workspaces.md)
+
+Hosted auth, sync, and tracker flows remain opt-in. For setup details, see
+[Hosted Sync Workspaces](docs/guides/sync-workspaces.md), [Internal
+Hosted-Readiness](docs/guides/internal-hosted-readiness.md), and
+[Launch-Readiness Behavior](docs/architecture/launch-readiness-future.md).
+
+## FAQ
+
+### Is Spec Kitty for dark software factories?
+
+Spec Kitty can be used as part of a dark software factory or autonomous coding pipeline, but its default model is governed and human-in-loop. It keeps specs, work packages, agent actions, review decisions, and merge state visible in the repository.
+
+### Which AI coding agents does Spec Kitty support?
+
+Spec Kitty supports common AI coding agents and coding harnesses including Claude Code, Codex, Cursor, Gemini, GitHub Copilot, OpenCode, Qwen, Windsurf, Kiro, Vibe, Pi, and Letta. See [Supported Agents](docs/api/supported-agents.md).
+
+### How is Spec Kitty different from prompt templates or Spec Kit?
+
+Spec Kitty is inspired by spec-driven development workflows, but adds repo-native mission state, work-package lanes, git worktree isolation, a local dashboard, governance commands, and an explicit `next -> review -> accept -> merge` runtime loop.
+
+### Does Spec Kitty require a SaaS service?
+
+No. Spec Kitty is local-first and stores its core artifacts in your repo. Hosted tracker and sync integrations are optional.
+
+## Development
+
+```bash
+git clone https://github.com/Priivacy-ai/spec-kitty.git
+cd spec-kitty
+pip install -e ".[test]"
+```
+
+When testing templates from a source checkout:
+
+```bash
+export SPEC_KITTY_TEMPLATE_ROOT="$(pwd)"
+spec-kitty init my-project --ai claude
+```
+
+See the [Contributing guide](docs/guides/contributing.md) for contribution guidelines.
+
+## Identity-Boundary CI Gate
+
+The `drift-detector` required check protects the shared identity-boundary
+contract across Spec Kitty repos. Contributor and admin details live in
+[Identity-Boundary CI Gate](docs/development/identity-boundary-ci-gate.md).
+
+## Support
+
+- Open a [GitHub issue](https://github.com/Priivacy-ai/spec-kitty/issues/new) for bugs, feature requests, or questions.
+- See the [changelog](docs/changelog/CHANGELOG.md) for release notes.
+- See [CONTRIBUTORS.md](CONTRIBUTORS.md) and the [GitHub contributors graph](https://github.com/Priivacy-ai/spec-kitty/graphs/contributors) for contributor credits.
+
+## License
+
+Spec Kitty is released under the [MIT License](LICENSE).

spec_kitty_cli-3.2.4/README.md

@@ -0,0 +1,221 @@
+<div align="center">
+    <img src="https://github.com/Priivacy-ai/spec-kitty/raw/main/media/logo_small.webp" alt="Spec Kitty logo"/>
+    <h1>Spec Kitty</h1>
+    <p><strong>Spec-driven development for AI coding agents, multi-agent workflows, and governed software factories.</strong></p>
+</div>
+
+Spec Kitty is an open-source CLI for turning product intent into a repo-native AI coding workflow:
+
+```text
+spec -> plan -> tasks -> next -> review -> accept -> merge
+```
+
+Use it to build a governed software factory around Claude Code, Codex, Cursor, Gemini, GitHub Copilot, Windsurf, OpenCode, and other AI coding agents. Spec Kitty keeps specs, plans, work packages, acceptance criteria, review state, and merge decisions in your repository, then gives agents isolated git worktrees so implementation can happen in parallel without branch chaos.
+
+[![PyPI version](https://img.shields.io/pypi/v/spec-kitty-cli?style=flat-square&logo=pypi)](https://pypi.org/project/spec-kitty-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue?style=flat-square)](https://www.python.org/downloads/)
+
+## Bright Software Factory, Not a Black Box
+
+Spec Kitty is for teams building software factories: repeatable inputs, clear work-package boundaries, isolated execution, visible progress, and review gates. It can support dark software factories and autonomous coding experiments, but it is deliberately not a lights-out black box by default. Humans define intent, architecture, and acceptance criteria; agents implement inside traceable worktrees; reviewers accept, reject, or merge with an audit trail.
+
+The goal is not more prompt text. The goal is a durable operating system for agentic coding where the repository remains the source of truth.
+
+## Is It For You?
+
+Use Spec Kitty when:
+
+- AI coding sessions are losing requirements, decisions, or acceptance criteria.
+- You want specs, plans, tasks, reviews, and merge state stored in Git.
+- Multiple agents or developers need clear work-package boundaries.
+- You are running parallel Claude Code, Codex, Cursor, Copilot, Gemini, or Windsurf work and need git worktree isolation.
+- You are moving from vibe coding to a repeatable spec-driven development workflow.
+- You want a local workflow first, with optional hosted tracker and sync integrations later.
+
+It is probably overkill for one-off edits, tiny scripts, or teams that do not use Git.
+
+## What It Provides
+
+| Need | Spec Kitty provides |
+| --- | --- |
+| Start from intent | Guided `specify`, `plan`, and `tasks` workflows |
+| Keep agents aligned | Repository-native mission artifacts under `kitty-specs/` |
+| Split implementation | Work packages with lifecycle lanes such as `planned`, `in_progress`, `for_review`, `approved`, and `done` |
+| Run agents in parallel | Isolated git worktrees under `.worktrees/` |
+| Keep quality visible | Review, accept, merge, and retrospective gates |
+| See progress | Optional local kanban dashboard with `spec-kitty dashboard` |
+| Integrate agents | Slash commands or skills for Claude Code, Codex, Cursor, Gemini, Copilot, Windsurf, OpenCode, and more |
+| Learn from missions | Every completed mission generates a retrospective by default. Tune via `.kittify/config.yaml#retrospective` or charter; see [how-to](docs/guides/use-retrospective-learning.md). |
+
+## Common Use Cases
+
+- Replace ad hoc vibe coding with spec-driven development.
+- Turn GitHub issues, product requirements, or bug reports into executable work packages.
+- Coordinate multiple AI coding agents without losing context between sessions.
+- Keep architecture decisions, constraints, and acceptance criteria close to the code.
+- Build a governed software factory that can scale toward more autonomy without hiding review, test, or merge decisions.
+
+## Governance layer
+
+Spec Kitty keeps runtime governance in the repo instead of treating it as
+agent-only prompt text. The trail model in [docs/trail-model.md](docs/trail-model.md)
+describes how `spec-kitty dispatch "<request>"` maps operator intent to
+runtime behavior, while
+[docs/host-surface-parity.md](docs/host-surface-parity.md) tracks parity across
+CLI, slash-command, and hosted surfaces.
+
+The primary standalone governance command is:
+
+- `spec-kitty dispatch "<request>"` - loads governance context, opens an Op record, and returns the context the agent must use before doing the work
+
+## Quick Start
+
+Install the CLI:
+
+```bash
+pipx install spec-kitty-cli
+```
+
+`pipx` is the preferred installer for the CLI because it keeps Spec Kitty in its
+own virtual environment and avoids the `externally-managed-environment` errors
+common on modern Linux distributions.
+
+Other supported install methods:
+
+```bash
+uv tool install spec-kitty-cli
+# or, inside an activated virtual environment
+python -m pip install spec-kitty-cli
+```
+
+Create or initialize a project:
+
+```bash
+spec-kitty init my-project --ai claude
+cd my-project
+spec-kitty verify-setup
+```
+
+Replace `claude` with your agent key when needed. Common choices include `codex`, `cursor`, `gemini`, `copilot`, `opencode`, `qwen`, `windsurf`, `kiro`, `vibe`, `pi`, and `letta`. See [Supported Agents](docs/api/supported-agents.md) for the current list.
+
+Open your AI coding agent in the project and run the core workflow:
+
+```text
+/spec-kitty.charter
+/spec-kitty.specify Build a small task list app.
+/spec-kitty.plan
+/spec-kitty.tasks
+```
+
+Then let the runtime choose the next action until the mission is ready:
+
+```bash
+spec-kitty next --agent claude --mission <mission-slug>
+```
+
+Review, accept, merge, and close the loop:
+
+```text
+/spec-kitty.review
+/spec-kitty.accept
+/spec-kitty.merge --push
+```
+
+After merge, run `/spec-kitty-mission-review`. The mission's
+`retrospective.yaml` is authored during the runtime terminus (HiC prompt or
+autonomous facilitator), not by `merge`. Once it exists, use
+`spec-kitty retrospect summary` for the cross-mission view and
+`spec-kitty agent retrospect synthesize --mission <mission-slug>` to apply any
+staged proposals (dry-run by default — pass `--apply` to mutate).
+
+For the full walkthrough, see [Your First Feature](docs/guides/your-first-feature.md).
+
+## Everyday Commands
+
+| Command | Purpose |
+| --- | --- |
+| `spec-kitty init . --ai <agent>` | Add Spec Kitty to the current repo |
+| `spec-kitty verify-setup` | Check local installation and project wiring |
+| `spec-kitty dashboard` | Open the local mission dashboard |
+| `spec-kitty next --agent <agent> --mission <slug>` | Ask Spec Kitty what the agent should do next |
+| `spec-kitty upgrade` | Update an existing project after upgrading the CLI |
+| `spec-kitty --help` | Show available commands |
+
+## Documentation
+
+Start here:
+
+- [Getting Started](docs/guides/getting-started.md)
+- [Your First Feature](docs/guides/your-first-feature.md)
+- [Orchestrator Quickstart](docs/guides/orchestrator-quickstart.md)
+- [CLI Command Reference](docs/api/cli-commands.md)
+- [Slash Commands](docs/api/slash-commands.md)
+- [Supported Agents](docs/api/supported-agents.md)
+- [Dashboard Guide](docs/guides/use-dashboard.md)
+- [Install and Upgrade](docs/guides/install-and-upgrade.md)
+
+Deeper topics:
+
+- [Spec-Driven Development](docs/architecture/spec-driven-development.md)
+- [Mission System](docs/architecture/mission-system.md)
+- [Git Worktrees](docs/architecture/git-worktrees.md)
+- [Multi-Agent Orchestration](docs/architecture/multi-agent-orchestration.md)
+- [External Orchestrator Runbook](docs/guides/run-external-orchestrator.md)
+- [Hosted Sync Workspaces](docs/guides/sync-workspaces.md)
+
+Hosted auth, sync, and tracker flows remain opt-in. For setup details, see
+[Hosted Sync Workspaces](docs/guides/sync-workspaces.md), [Internal
+Hosted-Readiness](docs/guides/internal-hosted-readiness.md), and
+[Launch-Readiness Behavior](docs/architecture/launch-readiness-future.md).
+
+## FAQ
+
+### Is Spec Kitty for dark software factories?
+
+Spec Kitty can be used as part of a dark software factory or autonomous coding pipeline, but its default model is governed and human-in-loop. It keeps specs, work packages, agent actions, review decisions, and merge state visible in the repository.
+
+### Which AI coding agents does Spec Kitty support?
+
+Spec Kitty supports common AI coding agents and coding harnesses including Claude Code, Codex, Cursor, Gemini, GitHub Copilot, OpenCode, Qwen, Windsurf, Kiro, Vibe, Pi, and Letta. See [Supported Agents](docs/api/supported-agents.md).
+
+### How is Spec Kitty different from prompt templates or Spec Kit?
+
+Spec Kitty is inspired by spec-driven development workflows, but adds repo-native mission state, work-package lanes, git worktree isolation, a local dashboard, governance commands, and an explicit `next -> review -> accept -> merge` runtime loop.
+
+### Does Spec Kitty require a SaaS service?
+
+No. Spec Kitty is local-first and stores its core artifacts in your repo. Hosted tracker and sync integrations are optional.
+
+## Development
+
+```bash
+git clone https://github.com/Priivacy-ai/spec-kitty.git
+cd spec-kitty
+pip install -e ".[test]"
+```
+
+When testing templates from a source checkout:
+
+```bash
+export SPEC_KITTY_TEMPLATE_ROOT="$(pwd)"
+spec-kitty init my-project --ai claude
+```
+
+See the [Contributing guide](docs/guides/contributing.md) for contribution guidelines.
+
+## Identity-Boundary CI Gate
+
+The `drift-detector` required check protects the shared identity-boundary
+contract across Spec Kitty repos. Contributor and admin details live in
+[Identity-Boundary CI Gate](docs/development/identity-boundary-ci-gate.md).
+
+## Support
+
+- Open a [GitHub issue](https://github.com/Priivacy-ai/spec-kitty/issues/new) for bugs, feature requests, or questions.
+- See the [changelog](docs/changelog/CHANGELOG.md) for release notes.
+- See [CONTRIBUTORS.md](CONTRIBUTORS.md) and the [GitHub contributors graph](https://github.com/Priivacy-ai/spec-kitty/graphs/contributors) for contributor credits.
+
+## License
+
+Spec Kitty is released under the [MIT License](LICENSE).

spec_kitty_cli-3.2.4/docs/adr/1.x/README.md

@@ -0,0 +1,15 @@
+# 1.x ADRs
+
+Architectural Decision Records for the legacy 1.x track.
+
+## Naming
+
+- `YYYY-MM-DD-N-descriptive-title-with-dashes.md`
+
+## Source of Truth
+
+This folder is canonical for 1.x decisions.
+
+The `architecture/` tree was removed by the Common Docs structural move (PR #2225).
+Existing references using the old `architecture/adrs/` paths will need updating to
+the new `docs/adr/` paths.

spec_kitty_cli-3.2.4/docs/adr/2.x/README.md

@@ -0,0 +1,23 @@
+# 2.x ADRs
+
+Architectural Decision Records for the 2.x track. **Not the current track —
+see [`docs/adr/3.x/`](../3.x/README.md) for current decisions.**
+
+## Naming
+
+- `YYYY-MM-DD-N-descriptive-title-with-dashes.md`
+
+## Source of Truth
+
+This folder is canonical for 2.x decisions (dates before 2026-03-30, the
+3.0.0 release). ADRs dated on or after 2026-03-30 were moved to
+[`docs/adr/3.x/`](../3.x/README.md). The `architecture/` tree was removed by the
+Common Docs structural move (PR #2225); existing references using the old
+`architecture/2.x/adr/<filename>` or `architecture/adrs/` paths will need
+updating to the new `docs/adr/` paths.
+
+## Status Conventions
+
+- `Accepted` means the decision remains current policy.
+- `Superseded` means a newer ADR replaced the decision; keep the file for history, but do not implement from it.
+- `Deprecated` means the direction is in active retirement and should not receive new work.

spec_kitty_cli-3.2.4/docs/adr/3.x/README.md

@@ -0,0 +1,79 @@
+# 3.x ADRs
+
+Architectural Decision Records for the 3.x track (starting 3.0.0, released 2026-03-30).
+
+## Naming
+
+- `YYYY-MM-DD-N-descriptive-title-with-dashes.md` where `N` is `1, 2, 3, …` per ADR landed on a given date.
+
+After adding an ADR file, run `python scripts/docs/freshen_adr_inventory.py docs/adr/3.x/<your-adr>.md`
+to update the page-inventory lockfile and add the row to the index table below.
+
+## Source of Truth
+
+This folder is canonical for 3.x decisions. The `architecture/` tree was removed
+by the Common Docs structural move (PR #2225); existing references using the old
+`architecture/2.x/adr/<filename>` paths will need updating to `docs/adr/3.x/`.
+
+## Status Conventions
+
+- `Accepted` means the decision remains current policy.
+- `Superseded` means a newer ADR replaced the decision; keep the file for history, but do not implement from it.
+- `Deprecated` means the direction is in active retirement and should not receive new work.
+
+## Template
+
+Use the shared template at [`docs/architecture/adr-template.md`](../../architecture/adr-template.md).
+
+## Index
+
+| Date | Title |
+|---|---|
+| 2026-04-03 | [Execution lanes own worktrees and mission branches](2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md) |
+| 2026-04-03 | [Review approval and integration completion are distinct](2026-04-03-2-review-approval-and-integration-completion-are-distinct.md) |
+| 2026-04-03 | [Feature acceptance runs on the integrated mission branch](2026-04-03-3-feature-acceptance-runs-on-the-integrated-mission-branch.md) |
+| 2026-04-04 | [Tracker binding context is discovered, not user-supplied](2026-04-04-1-tracker-binding-context-is-discovered-not-user-supplied.md) |
+| 2026-04-04 | [Mission type, mission, and mission run terminology boundary](2026-04-04-2-mission-type-mission-and-mission-run-terminology-boundary.md) |
+| 2026-04-06 | [WP state pattern for lane behavior](2026-04-06-1-wp-state-pattern-for-lane-behavior.md) |
+| 2026-04-07 | [Global slash command installation](2026-04-07-1-global-slash-command-installation.md) |
+| 2026-04-09 | [Mission identity uses ULID, not sequential prefix](2026-04-09-1-mission-identity-uses-ulid-not-sequential-prefix.md) |
+| 2026-04-09 | [CLI SaaS auth is browser-mediated OAuth, not password](2026-04-09-2-cli-saas-auth-is-browser-mediated-oauth-not-password.md) |
+| 2026-04-11 | [SaaS rollout and readiness](2026-04-11-1-saas-rollout-and-readiness.md) |
+| 2026-04-15 | [Explicit empty charter selections remain empty](2026-04-15-2-explicit-empty-charter-selections-remain-empty.md) |
+| 2026-04-19 | [CLI auth uses encrypted file-only session storage](2026-04-19-1-cli-auth-uses-encrypted-file-only-session-storage.md) |
+| 2026-04-19 | [Ticket delivery is CLI plumbing; specification is LLM content](2026-04-19-2-ticket-delivery-is-cli-plumbing-specification-is-llm-content.md) |
+| 2026-04-20 | [Mutation testing as a local-only quality gate](2026-04-20-1-mutation-testing-as-local-only-quality-gate.md) |
+| 2026-04-21 | [Private teamspace and repository sharing boundary](2026-04-21-1-private-teamspace-and-repository-sharing-boundary.md) |
+| 2026-04-25 | [Shared package boundary cutover](2026-04-25-1-shared-package-boundary.md) |
+| 2026-04-26 | [Contract pinning resolved version](2026-04-26-1-contract-pinning-resolved-version.md) |
+| 2026-04-26 | [Auth transport boundary](2026-04-26-2-auth-transport-boundary.md) |
+| 2026-04-26 | [E2E hard gate](2026-04-26-3-e2e-hard-gate.md) |
+| 2026-04-27 | [Retrospective gate shared module](2026-04-27-1-retrospective-gate-shared-module.md) |
+| 2026-05-01 | [Atomic work-package start lifecycle](2026-05-01-1-atomic-work-package-start-lifecycle.md) |
+| 2026-05-10 | [Deterministic historical mission-state repair](2026-05-10-1-deterministic-historical-mission-state-repair.md) |
+| 2026-05-14 | [Stale-lane auto-rebase classifier policy](2026-05-14-1-stale-lane-auto-rebase-classifier-policy.md) |
+| 2026-05-16 | [Doctrine layer merge semantics](2026-05-16-1-doctrine-layer-merge-semantics.md) |
+| 2026-05-19 | [Retrospective default-on policy architecture](2026-05-19-1-retrospective-default-policy-architecture.md) |
+| 2026-05-24 | [Charter freshness UX contract](2026-05-24-1-charter-freshness-ux-contract.md) |
+| 2026-05-24 | [Pack augmentation vocabulary — `overrides` and `enhances` as declarative fields](2026-05-24-2-pack-augmentation-vocabulary.md) |
+| 2026-05-24 | [`shipped` → `built-in` vocabulary cutover for doctrine layer label](2026-05-24-3-shipped-to-built-in-cutover.md) |
+| 2026-06-02 | [Pi agent is skill-only: no prompt templates, invoker deferred](2026-06-02-1-pi-agent-skill-only-support.md) |
+| 2026-06-02 | [Letta agent is skill-only: no slash-command templates, invoker and session model deferred](2026-06-02-2-letta-agent-skill-only-support.md) |
+| 2026-06-03 | [Execution-state domain model](2026-06-03-1-execution-state-domain-model.md) |
+| 2026-06-03 | [ExecutionContext owner and CommitTarget atomicity](2026-06-03-2-executioncontext-owner-and-committarget.md) |
+| 2026-06-03 | [Effector/Actor model](2026-06-03-3-effector-actor-model.md) |
+| 2026-06-05 | [Merge publish-layer boundary](2026-06-05-1-merge-publish-layer-boundary.md) |
+| 2026-06-06 | [Plan concerns to work package traceability](2026-06-06-1-plan-concerns-to-work-package-traceability.md) |
+| 2026-06-07 | [Execution-state canonical surface (`mission_runtime`)](2026-06-07-1-execution-state-canonical-surface.md) |
+| 2026-06-07 | [Session presence: multi-harness architecture](2026-06-07-1-session-presence-multi-harness-architecture.md) |
+| 2026-06-07 | [WP lane FSM, the `genesis` lane, and the finalize event-log clobber fix](2026-06-07-1-wp-lane-fsm-genesis-and-finalize-clobber.md) |
+| 2026-06-11 | [Op as a first-class execution artifact (Mission ⟷ Op ⟷ ad-hoc)](2026-06-11-1-op-as-first-class-execution-artifact.md) |
+| 2026-06-15 | [Marketplace descriptor vs publish](2026-06-15-1-marketplace-descriptor-vs-publish.md) |
+| 2026-06-19 | [A materialized-but-empty coordination worktree hard-fails — no silent primary fallback](2026-06-19-1-coord-empty-surface-fallback.md) |
+| 2026-06-21 | [Protected-branch configuration is a standalone boundary-resolved value, not a nested context sub-object](2026-06-21-1-protected-branch-config-boundary-resolved-value.md) |
+| 2026-06-22 | [MissionTopology SSOT — store the mission shape, resolve it once](2026-06-22-1-mission-topology-ssot.md) |
+| 2026-06-24 | [Kind- and topology-aware artifact placement — one partition, read/write symmetry](2026-06-24-1-kind-and-topology-aware-artifact-placement.md) |
+| 2026-06-24 | [Write-branch resolution anchors `meta.json` on the PRIMARY surface (write-surface twin)](2026-06-24-2-write-branch-resolution-primary-anchor.md) |
+| 2026-06-25 | [Terminal-artifact durable home + topology-aware teardown contract](2026-06-25-1-terminal-artifact-durable-home-teardown.md) |
+| 2026-06-26 | [Single-authority seam + call-site gate for resolution boundaries (Phase 1)](2026-06-26-1-single-authority-seam-and-call-site-gate.md) |
+| 2026-07-01 | [No legacy-compat branches in resolvers — require canonical identity, migrate legacy](2026-07-01-1-no-legacy-compat-branches-in-resolvers.md) |