convez.ai
AgenteDevOps & InfraestruturaIntermediário
Priivacy-ai

Spec Kitty

Priivacy-ai/spec-kitty

Fábrica de software spec-driven para agentes de IA com auditoria e gates de revisão

Ver no GitHub
Muito bomPluginScore · de 0 a 100

CLI open-source para desenvolvimento dirigido por especificações em projetos com agentes de IA. Transforma intenção de produto em fluxo de trabalho controlado, mantendo specs, planos, tarefas e decisões de merge no repositório Git, com suporte a worktrees isoladas para execução paralela de múltiplos agentes (Claude Code, Cursor, Gemini, Copilot, etc).

Instalação

$npx convez-ai Priivacy-ai/spec-kitty

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1,7 mil
Forks
199
Acompanhando
8
Saúde
62%
Último commit
há 1 dia
Versão
v3.2.7
Issues abertas
882
Contribuidores
57

Casos de uso

  • Organizar workflows de múltiplos agentes de IA em paralelo com isolamento por git worktree
  • Implementar spec-driven development com rastreabilidade completa em Git
  • Automatizar ciclos plan → task → review → merge com artefatos repositório-nativos

Veredito

Ferramenta sólida para equipes que querem sair do 'vibe coding' e estabelecer governança real em workflows com agentes de IA. Requer disciplina e Git; não é para scripts únicos, mas é ouro para fábricas de software sérias.

README

A tradução para o português deste README ainda está na fila.

Spec Kitty is an open-source CLI for turning product intent into a repo-native AI coding workflow:

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 License: MIT Python 3.11+

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

NeedSpec Kitty provides
Start from intentGuided specify, plan, and tasks workflows
Keep agents alignedRepository-native mission artifacts under kitty-specs/
Split implementationWork packages with lifecycle lanes such as planned, in_progress, for_review, approved, and done
Run agents in parallelIsolated git worktrees under .worktrees/
Keep quality visibleReview, accept, merge, and retrospective gates
See progressOptional local kanban dashboard with spec-kitty dashboard
Integrate agentsSlash commands or skills for Claude Code, Codex, Cursor, Gemini, Copilot, Windsurf, OpenCode, and more
Learn from missionsEvery completed mission generates a retrospective by default. Tune via .kittify/config.yaml#retrospective or charter; see how-to.

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 describes how spec-kitty advise, spec-kitty ask, and spec-kitty do map operator intent to runtime behavior, while docs/host-surface-parity.md tracks parity across CLI, slash-command, and hosted surfaces.

Three primary commands drive this layer:

  • spec-kitty advise - surfaces relevant doctrine, guidelines, and warnings for the current context
  • spec-kitty ask - queries the knowledge base for specific guidance
  • spec-kitty do - executes governed actions, ensuring compliance with the trail model

Quick Start

Install the CLI:

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:

uv tool install spec-kitty-cli
# or, inside an activated virtual environment
python -m pip install spec-kitty-cli

Create or initialize a project:

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 for the current list.

Open your AI coding agent in the project and run the core workflow:

/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:

spec-kitty next --agent claude --mission <mission-slug>

Review, accept, merge, and close the loop:

/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.

Everyday Commands

CommandPurpose
spec-kitty init . --ai <agent>Add Spec Kitty to the current repo
spec-kitty verify-setupCheck local installation and project wiring
spec-kitty dashboardOpen the local mission dashboard
spec-kitty next --agent <agent> --mission <slug>Ask Spec Kitty what the agent should do next
spec-kitty upgradeUpdate an existing project after upgrading the CLI
spec-kitty --helpShow available commands

Documentation

Start here:

Deeper topics:

Hosted auth, sync, and tracker flows remain opt-in. For setup details, see Hosted Sync Workspaces, Internal Hosted-Readiness, and Launch-Readiness Behavior.

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.

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

git clone https://github.com/Priivacy-ai/spec-kitty.git
cd spec-kitty
pip install -e ".[test]"

When testing templates from a source checkout:

export SPEC_KITTY_TEMPLATE_ROOT="$(pwd)"
spec-kitty init my-project --ai claude

See 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.

Support

License

Spec Kitty is released under the MIT License.

Ver o original no GitHub

Bom para

Relacionados