spec-manager
loki-ai-ch/spec-manager
Workflow local para specs rastreáveis em projetos com AI coding agents
Ver no GitHubAgent CLI local-first para desenvolvimento guiado por especificações. Gerencia specs em markdown + git com validação automática, ciclo de vida de tarefas e cartões de decisão. Funciona offline, integrado com Claude Code, Cursor, Windsurf e outros coding agents.
Instalação
npx convez-ai loki-ai-ch/spec-manager1 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
Casos de uso
- Estruturar prompts para coding agents com especificações validadas
- Manter histórico de decisões e verificações em git sem backend
- Integrar specs com Claude Code, Cursor, Windsurf e MiMo-Code
- Reduzir chaos ao forçar specs antes da implementação por agents
Veredito

Ferramenta sólida para quem quer disciplina metodológica em projetos com coding agents. Abordagem local-first sem dependências externas é vantagem real, mas exige adoção de workflow específico pela equipe.
README
A tradução para o português deste README ainda está na fila.
spec-manager
Make AI coding work traceable. spec-manager is a local-first workflow layer for Claude Code, Codex, OpenCode, MiMo-Code, CodeBuddy, Cursor, Windsurf, and other coding agents.
You do not need to understand the full methodology before trying it. Start with one project, one request, and one command.
Why Use It
- Less chaos: AI agents write code after a lightweight spec, not from a vague prompt.
- Better handoff: specs, tasks, decisions, and verification records live in markdown/JSON files in your repo.
- Works with your agent: install the right workflow file for Claude Code, Codex, OpenCode, MiMo-Code, CodeBuddy, Cursor, or Windsurf.
Everything is local: markdown + git storage, no backend, no network dependency, no MCP requirement.
3-Minute Start
# 1. Install or run directly
npm install -g spec-manager
# or: npx spec-manager <command>
# 2. Initialize your project
cd my-project
spec-manager project init --name my-project
# 3. Add instructions for your AI coding tool
spec-manager project agents --provider all
Now ask your agent:
Use spec-manager to add user authentication.
For Claude Code / CodeBuddy skills:
/spec-manager add user authentication
The agent will create specs and ask for approval before implementation. You can stop there and inspect the files, or continue into a full task.
MiMo-Code
MiMo-Code reads AGENTS.md, so setup is intentionally small:
npm install -g @mimo-ai/cli
spec-manager project agents --provider mimocode
mimocode
This installs the shared spec-manager workflow capsule into AGENTS.md.
Agent Setup
If you do not want every provider, install only the one you use:
spec-manager project agents --provider list
spec-manager project agents --provider claude
spec-manager project agents --provider codex
spec-manager project agents --provider opencode
spec-manager project agents --provider mimocode
spec-manager project agents --provider codebuddy
spec-manager project agents --provider cursor
spec-manager project agents --provider windsurf
Preview changes first:
spec-manager project agents --provider mimocode --dry-run
| Provider | Entry point | Files |
|---|---|---|
| Claude Code | Native skill | CLAUDE.md, .claude/skills/spec-manager/ |
| Codex | AGENTS.md workflow capsule | AGENTS.md |
| OpenCode | AGENTS.md workflow capsule | AGENTS.md |
| MiMo-Code | AGENTS.md workflow capsule | AGENTS.md |
| CodeBuddy | Native skill | CODEBUDDY.md, .codebuddy/skills/spec-manager/ |
| Cursor | Project rules | .cursorrules |
| Windsurf | Project rules | .windsurfrules |
When You Want More Control
You can drive the workflow yourself without memorizing the full process:
spec-manager guide "add user authentication" # prints the next useful step
spec-manager new feature --topic auth "User authentication"
spec-manager flow status --topic auth # see where the work is blocked
spec-manager view --topic auth # interactive browser
spec-manager project doctor # check setup and integrity
The full workflow is still available when you need it:
spec-manager spec new L1 --topic auth --title "User authentication"
spec-manager spec update auth-L1 --content ./l1.md --ai-summary "..." --change-summary "init"
spec-manager spec confirm auth-L1
spec-manager spec new L2 --topic auth --parent auth-L1 --title "Auth design"
spec-manager spec new L3 --topic auth --parent auth-L2.1 --title "JWT implementation"
spec-manager task create auth-L3.1.1 --plan ./plan.json
Think of this as optional depth. Most people should start with guide, new feature, or an AI agent prompt.
Core Ideas
- L1: what and why
- L2: technical design
- L3: implementation plan
- Task: agent execution with step records and verification
- Decision card: why an important choice was made
- Delta change: change an already shipped spec without losing history
Common Commands
| Command | Use it for |
|---|---|
spec-manager project init --name X | Create .spec-manager/ |
spec-manager project agents [--provider P] | Install agent workflow files |
spec-manager project doctor | Check setup and repository integrity |
spec-manager guide "request" | Get the next command for a request |
spec-manager new feature --topic T "Title" | Start a lightweight L1 |
spec-manager flow status --topic T | See progress and blockers |
spec-manager spec list | List specs |
spec-manager spec show <code> --include-content | Read a spec |
spec-manager task list --topic T | List tasks |
spec-manager decision list --topic T | List decisions |
Run any command with --help for details.
Files It Creates
my-project/
├── .spec-manager/
│ ├── config.yaml
│ ├── audit.json
│ └── incidents/
├── specs/<topic>/
│ ├── <L1-code>.md
│ ├── <L2-code>.md
│ ├── <L3-code>[-desc].md
│ ├── decisions/
│ │ └── DC-001.md
│ └── tasks/
│ └── <specCode>-T-001.json
├── changes/<name>/
└── archive/<name>/
Spec codes are readable by design: auth-L1, auth-L2.1, auth-L3.1.1-jwt.
Learn More
License
MIT