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

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

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

• Methodology
• Rules
• Templates
• Decision template

License

MIT