specs-workflow

English | 中文

Spec-driven, rolling-wave workflow for AI coding assistants. Before code is written, every module gets requirements.md, design.md, tasks.md, and CHANGELOG.md under .agents/specs/, kept traceable to each other and synced through .agents/specs/index.md. Plans detail only the current wave (through the next Checkpoint) and are re-planned at every checkpoint; design is written in two zones — stable parts (overview, architecture, cross-module interfaces, high-risk properties) committed up front, component internals filled just-in-time. .agents/specs/index.md is a progressive-disclosure index: a top status bar (done/blocked, dependency-derived next task and next gate), a module status table with Progress, and a horizon-view Task Summary let the agent pick which tasks to execute; module documents are loaded on demand — only for the modules the current task touches. tasks.md checkboxes are the single source of task status; the index is a derived rollup.

This repo is a portable distribution: one skill + one compact ruleset, shipped as thin adapters for multiple AI CLI tools.

What's in the box

• skills/specs-workflow/ — the full skill (SKILL.md + references/ with file templates, prompting guidance, quality checklists, and a traceability example). Loaded on demand by skill-capable agents.
• commands/*.toml — canonical command prompts (Gemini CLI custom commands).
• rules/specs-workflow.md — canonical compact always-on ruleset (mandatory rules + document formats + prohibitions).
• skills-zh/ — the complete Chinese mirror of the skill (SKILL.zh.md + references/*.zh.md) and the ruleset (rules/specs-workflow.zh.md); kept in sync and checked by scripts/check-sync.js.
• Adapters — tool-specific copies of the above.

Install

Tool	How	What you get
Claude Code (plugin)	/plugin marketplace add xypur/specs-workflow, then /plugin install specs-workflow@specs-workflow	The five slash commands + the specs-workflow skill + hooks, one command, no file copying
opencode	Copy .opencode/commands/*.md into the project's .opencode/commands/ (or global ~/.config/opencode/commands/)	/specs, /specs-init, /specs-requirements, /specs-design, /specs-tasks
Claude Code	Copy .claude/commands/*.md into the project's .claude/commands/	Same five slash commands
Gemini CLI	Copy commands/*.toml into the project's commands/	Same five slash commands
Cursor	Copy .cursor/rules/specs-workflow.mdc into the project's .cursor/rules/	Always-on spec-first rule
Cline	Copy .clinerules/specs-workflow.md into the project's .clinerules/	Always-on spec-first rule
Other hosts (Windsurf, Kiro, Qoder, …)	Copy the body of rules/specs-workflow.md into the host's own rule file	Always-on spec-first rule
GitHub Copilot	Copy .github/copilot-instructions.md into the repo	Repo-wide spec-first instructions
AGENTS.md hosts (Amp, Zed, Jules, Codex extension, Antigravity, CodeWhale, …)	Copy the marked ruleset section from the repo's AGENTS.md into your project's (or global) AGENTS.md	Always-on spec-first rules for any host that auto-reads AGENTS.md
Generic agents	Copy rules/specs-workflow.md or load skills/specs-workflow/SKILL.md	Ruleset or full skill

Skill

Install the full specs-workflow skill with the Skills CLI:

npx skills add https://github.com/xypur/specs-workflow --skill specs-workflow

The skill itself works in any skill-capable host (Claude Code, Codex, opencode, Gemini, Qoder, Devin, etc.): register skills/specs-workflow/ as a skill and it activates on .agents/specs/ work.

Uninstall (plugins)

Host	Command
Claude Code	/plugin remove specs-workflow
Copy-install hosts	Delete the copied rule/command file

See docs/agent-portability.md for the full host → file mapping.

Commands

Command	What it does
/specs <description>	Unified entry: describe the feature, creates all four spec documents for the derived module in one pass with the current wave detailed. The commands below are the step-by-step / single-document variants.
/specs-init	Bootstrap .agents/specs/ (index with status bar + status table + task summary + dependencies)
/specs-requirements <module>	Create/update a module's requirements.md
/specs-design <module>	Create/update a module's design.md
/specs-tasks <module>	Create/update a module's tasks.md

/specs takes a free-text <description> of the feature; if omitted, the agent asks for it. The <module> commands each take a module name; if omitted, the agent asks for it.

Development

The derived adapters must stay aligned with the canonical sources:

node scripts/check-sync.js   # or: npm test

The check verifies (a) every rule adapter body equals rules/specs-workflow.md (including the marked ruleset section in this repo's own AGENTS.md), (b) every .opencode/ and .claude/ command equals its commands/*.toml prompt using the host argument variable, and (c) every Chinese mirror under skills-zh/ matches its English doc by section and code-fence counts. For a consumer project, run node scripts/validate-specs.js <project-root> to check .agents/specs structure, requirement references, rolling-wave task structure, optional dependency graphs, and forbidden versioned design files.