convez.ai
AgenteAutomaçãoIntermediário
loki-ai-ch

spec-manager

loki-ai-ch/spec-manager

Workflow local para specs rastreáveis em projetos com AI coding agents

Ver no GitHub
BomPluginScore · de 0 a 100

Agent 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-manager

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
5
Forks
0
Acompanhando
1
Saúde
100%
Último commit
há 4 meses
Versão
v0.4.11
Issues abertas
0
Contribuidores
1

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

npm version CI License: MIT

中文说明

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
ProviderEntry pointFiles
Claude CodeNative skillCLAUDE.md, .claude/skills/spec-manager/
CodexAGENTS.md workflow capsuleAGENTS.md
OpenCodeAGENTS.md workflow capsuleAGENTS.md
MiMo-CodeAGENTS.md workflow capsuleAGENTS.md
CodeBuddyNative skillCODEBUDDY.md, .codebuddy/skills/spec-manager/
CursorProject rules.cursorrules
WindsurfProject 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

CommandUse it for
spec-manager project init --name XCreate .spec-manager/
spec-manager project agents [--provider P]Install agent workflow files
spec-manager project doctorCheck 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 TSee progress and blockers
spec-manager spec listList specs
spec-manager spec show <code> --include-contentRead a spec
spec-manager task list --topic TList tasks
spec-manager decision list --topic TList 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

Ver o original no GitHub

Bom para

Relacionados