specdo

SpecDo lifecycle skill bundle for AI coding agents

English | 中文

English

What is this?

SpecDo turns your AI coding agent into a more disciplined software engineering workflow. It installs a lifecycle skill chain — from brainstorming to archive — with structured thinking, machine-verifiable evidence gates, and explicit JSON handoff contracts. Verification is an apply-internal evidence gate: it returns to specdo-apply, and specdo-apply then routes to task completion, sync readiness, or archive readiness.

brainstorming → explore → propose → apply → sync → archive
                              │
                              └─ wrapper gates, including verification, return to apply

Each lifecycle step is backed by machine-readable contracts, quality gates, and evidence checkpoints so outputs can be reviewed and replayed more reliably.

Requirements

| Dependency | Version | Note | |---|---|---| | Node.js | ≥ 18 | Required for the CLI | | Python | ≥ 3.8 | Required when running SpecDo skill gates and lifecycle scripts. Examples use python3; on Windows use py -3 or an equivalent Python launcher. |

Installation

npm install -g specdo

Verify it works:

specdo --version
specdo list            # preview all skills and the lifecycle chain

Quick Start

# Project-level install (recommended)
cd your-project
specdo init claude

# Global install — all projects share the same skills
specdo init claude -g

# Multiple agents at once
specdo init claude,qoder,cursor

# CI / scripts — skip confirmation prompts
specdo init claude --yes

Supported Agents

| Agent | Install path (project) | Install path (global) | |---|---|---| | claude | .claude/skills/ | ~/.claude/skills/ | | qoder | .qoder/skills/ | ~/.qoder/skills/ | | cursor | .cursor/skills/ | ~/.cursor/skills/ | | cline | .cline/skills/ | ~/.cline/skills/ | | codex | .codex/skills/ | ~/.codex/skills/ | | goose | .goose/skills/ | ~/.goose/skills/ | | kilo | .kilo/skills/ | ~/.kilo/skills/ | | opencode | .opencode/skills/ | ~/.opencode/skills/ | | unknown | .agents/skills/ | ~/.agents/skills/ |

Built-in typo correction — specdo init clude will ask if you meant claude.

What Gets Installed

After specdo init claude, your skills directory will contain this abridged tree:

.claude/skills/
├── specdo-apply/SKILL.md          # Orchestrate task implementation
├── specdo-archive/SKILL.md        # Close & archive a completed change
├── specdo-brainstorming/SKILL.md  # Clarify unclear requirements
├── specdo-debugging/SKILL.md      # Root-cause analysis on failures
├── specdo-explore/SKILL.md        # Analyze repo & existing artifacts
├── specdo-parallel-agents/SKILL.md # Fully independent domain parallelism
├── specdo-propose/SKILL.md        # Create proposal / design / tasks / delta specs
├── specdo-receive-code-review/SKILL.md # Process review feedback
├── specdo-request-code-review/SKILL.md # Submit code for review
├── specdo-lifecycle/              # Lifecycle contract and shared library scripts
│   ├── SKILL.md                   # Canonical lifecycle contract
│   ├── scripts/                   # Shared Python library modules (_lifecycle.py, _artifact_quality.py, etc.)
│   └── reference/                 # Artifact format, quality gates
├── specdo-subagent-development/SKILL.md # Coordinated multi-task execution
├── specdo-sync/SKILL.md           # Promote delta specs → main spec library
├── specdo-tdd/SKILL.md            # Test-driven implementation
└── specdo-verification/SKILL.md   # Produce evidence gate payload

Important: specdo-lifecycle/ and all specdo-*/ directories must stay together at the same level. Skill files reference ../specdo-lifecycle/SKILL.md for the shared contract. Some skills include their own scripts/ and reference/ directories; shared Python libraries live in specdo-lifecycle/scripts/.

CLI Commands

specdo init <agent[,agent2,...]>   Install the skill bundle
specdo list                        List bundled skills with descriptions
specdo --version                   Print version
specdo --help                      Show help

Options for init:
  -g, --global     Install under home directory instead of cwd
  --force          Reinstall even if same version is already installed
  --dry-run        Preview the target path and file operations without writing
  -y, --yes        Skip confirmation prompts (use in scripts / CI)

Lifecycle Skills

| Skill | Role | Description | |---|---|---| | specdo-brainstorming | Clarify | Stabilize fuzzy intent before formalization | | specdo-explore | Analyze | Read code, artifacts, and workspace state | | specdo-propose | Formalize | Write proposal, design, tasks, and delta specs | | specdo-apply | Orchestrate | Dispatch tasks to wrapper skills below |

Wrapper skills (orchestrated by specdo-apply and legal wrapper handoffs; direct use requires a resolved active apply payload):

| Wrapper | Responsibility | |---|---| | specdo-tdd | Test-first implementation of a single task | | specdo-subagent-development | Coordinated multi-task execution | | specdo-parallel-agents | Independent domain parallelism | | specdo-debugging | Root-cause analysis on failures | | specdo-request-code-review | Submit work for review | | specdo-receive-code-review | Ingest review feedback | | specdo-verification | Produce machine-evidence payload and return it to apply |

Lifecycle closing skills:

| Skill | Description | |---|---| | specdo-sync | Merge delta specs into the main spec library | | specdo-archive | Close the change with a full evidence trail |

Lifecycle Chain

specdo-brainstorming     Clarify fuzzy intent
        │
        ▼
specdo-explore           Analyze repo & existing artifacts
        │
        ▼
specdo-propose           Create proposal / design / tasks / delta specs
        │
        ▼
specdo-apply             Implement (orchestrates wrapper skills)
  ├─ specdo-tdd                     Test-driven implementation
  ├─ specdo-subagent-development    Coordinated multi-task execution
  ├─ specdo-parallel-agents         Independent domain parallelism
  ├─ specdo-debugging               Root-cause analysis on failures
  ├─ specdo-request-code-review     Submit code for review
  ├─ specdo-receive-code-review     Process review feedback
  └─ specdo-verification            Evidence gate payload, then returns to apply
        │
        ├─ task_completion  → mark task complete and re-resolve work
        ├─ sync_readiness   → specdo-sync
        └─ archive_readiness → specdo-archive
        │
        ▼
specdo-sync              Promote delta specs → main spec library when needed
        │
        ▼
specdo-archive           Close & archive the completed change

Updating

npm update -g specdo
cd your-project
specdo init claude --force

License

MIT — © MoonCoder-HAPPY

中文

这是什么？

SpecDo 把你的 AI 编程助手接入更有纪律的软件工程流程。从头脑风暴到归档，它提供结构化思维、机器可验证的证据门禁，以及明确的 JSON 交接契约。验证是 apply 内部证据门禁：specdo-verification 产出 payload 后回到 specdo-apply，再由 specdo-apply 路由到任务完成、同步就绪或归档就绪。

brainstorming → explore → propose → apply → sync → archive
                              │
                              └─ wrapper 门禁（含 verification）回到 apply
（头脑风暴 → 探索 → 提案 → 实施 → 同步 → 归档）

每一步都由机器可读的契约、质量门禁和证据检查点支撑。

环境要求

| 依赖 | 版本 | 说明 | |---|---|---| | Node.js | ≥ 18 | CLI 运行必需 | | Python | ≥ 3.8 | 运行 SpecDo skill 门禁和生命周期脚本时需要；示例使用 python3，Windows 可用 py -3 或等效 Python 启动器 |

安装

npm install -g specdo

验证安装：

specdo --version
specdo list            # 预览所有技能及生命周期链路

快速开始

# 项目级安装（推荐）
cd your-project
specdo init claude

# 全局安装 — 所有项目共享同一套技能
specdo init claude -g

# 一次安装多个 agent
specdo init claude,qoder,cursor

# CI / 脚本场景 — 跳过确认提示
specdo init claude --yes

支持的 Agent

| Agent | 安装路径（项目级） | 安装路径（全局） | |---|---|---| | claude | .claude/skills/ | ~/.claude/skills/ | | qoder | .qoder/skills/ | ~/.qoder/skills/ | | cursor | .cursor/skills/ | ~/.cursor/skills/ | | cline | .cline/skills/ | ~/.cline/skills/ | | codex | .codex/skills/ | ~/.codex/skills/ | | goose | .goose/skills/ | ~/.goose/skills/ | | kilo | .kilo/skills/ | ~/.kilo/skills/ | | opencode | .opencode/skills/ | ~/.opencode/skills/ | | 未知 | .agents/skills/ | ~/.agents/skills/ |

内置拼写纠错 — 输入 specdo init clude 会询问你是否想输入 claude。

安装内容

执行 specdo init claude 后，skills 目录大致如下：

.claude/skills/
├── specdo-apply/SKILL.md          # 编排任务实施
├── specdo-archive/SKILL.md        # 关闭并归档已完成的变更
├── specdo-brainstorming/SKILL.md  # 澄清不明确的需求
├── specdo-debugging/SKILL.md      # 失败根因分析
├── specdo-explore/SKILL.md        # 分析仓库和已有 artifact
├── specdo-parallel-agents/SKILL.md # 完全独立的领域并行
├── specdo-propose/SKILL.md        # 创建 proposal / design / tasks / delta specs
├── specdo-receive-code-review/SKILL.md # 处理代码审查反馈
├── specdo-request-code-review/SKILL.md # 提交代码审查请求
├── specdo-lifecycle/              # 生命周期契约和共享库脚本
│   ├── SKILL.md                   # 权威生命周期契约
│   ├── scripts/                   # 共享 Python 库模块（_lifecycle.py、_artifact_quality.py 等）
│   └── reference/                 # Artifact 格式、质量门禁
├── specdo-subagent-development/SKILL.md # 协调式多任务执行
├── specdo-sync/SKILL.md           # 将 delta specs 合并到主 spec 库
├── specdo-tdd/SKILL.md            # 测试驱动开发
└── specdo-verification/SKILL.md   # 生成机器证据门禁 payload

重要： specdo-lifecycle/ 和所有 specdo-*/ 目录必须保持同级。技能文件通过 ../specdo-lifecycle/SKILL.md 引用共享契约。部分技能包含自己的 scripts/ 和 reference/ 目录；共享 Python 库在 specdo-lifecycle/scripts/。

CLI 命令

specdo init <agent[,agent2,...]>   安装技能集
specdo list                        列出本包内置技能及链路说明
specdo --version                   打印版本号
specdo --help                      显示帮助信息

init 选项：
  -g, --global     安装到用户主目录而非当前项目目录
  --force          即使同版本已安装也强制覆盖
  --dry-run        仅预览目标路径和文件操作，不写入文件
  -y, --yes        跳过确认提示（用于脚本 / CI 场景）

生命周期技能

| 技能 | 角色 | 描述 | |---|---|---| | specdo-brainstorming | 澄清 | 在正式立项前稳定模糊意图 | | specdo-explore | 分析 | 阅读代码、artifact 和工作区状态 | | specdo-propose | 形式化 | 撰写 proposal、design、tasks 和 delta specs | | specdo-apply | 编排 | 将任务分派给下方的 wrapper 技能 |

Wrapper 技能（由 specdo-apply 和合法 wrapper handoff 编排；直接使用必须携带已解析的 active apply payload）：

| Wrapper 技能 | 职责 | |---|---| | specdo-tdd | 单个任务的测试优先实现 | | specdo-subagent-development | 协调式多任务执行 | | specdo-parallel-agents | 独立领域并行 | | specdo-debugging | 失败根因分析 | | specdo-request-code-review | 提交代码审查请求 | | specdo-receive-code-review | 处理审查反馈 | | specdo-verification | 生成机器证据 payload，并回到 apply |

生命周期收尾技能：

| 技能 | 描述 | |---|---| | specdo-sync | 将 delta specs 合并到主 spec 库 | | specdo-archive | 附带完整证据链关闭变更 |

生命周期链路

specdo-brainstorming     澄清模糊意图
        │
        ▼
specdo-explore           分析仓库和已有 artifact
        │
        ▼
specdo-propose           创建 proposal / design / tasks / delta specs
        │
        ▼
specdo-apply             实施（编排 wrapper 技能）
  ├─ specdo-tdd                     测试驱动实现
  ├─ specdo-subagent-development    协调式多任务执行
  ├─ specdo-parallel-agents         独立领域并行
  ├─ specdo-debugging               失败根因分析
  ├─ specdo-request-code-review     提交代码审查
  ├─ specdo-receive-code-review     处理审查反馈
  └─ specdo-verification            证据门禁 payload，然后回到 apply
        │
        ├─ task_completion  → 标记任务完成并重新解析剩余工作
        ├─ sync_readiness   → specdo-sync
        └─ archive_readiness → specdo-archive
        │
        ▼
specdo-sync              必要时将 delta specs 合并到主 spec 库
        │
        ▼
specdo-archive           关闭并归档已完成的变更

更新

npm update -g specdo
cd your-project
specdo init claude --force

许可证

MIT — © MoonCoder-HAPPY