Spectrum - Plugin for Spec-Driven Development

This plugin starts from the premise that, in an era when AI coding agents can produce code rapidly, the artifact that needs to live the longest and be configuration-managed most carefully is not the code itself but the specification of what to build. Spectrum pins requirements down in Spec.md, refines them into Plan.md, and then carries that work all the way through platform-specific implementation and verification.

In other words, Spectrum is a tool that helps you keep Spec as the source of truth in an "agent implements it for you" development environment. Implementations may change, but a feature's intent, boundaries, acceptance criteria, and UI/data/interface contracts stay in the Spec, flow through the Plan, and land as executable units of work.

Product Development Cycle

Spectrum assumes the following product development cycle:

Spec
  -> Spec Review
  -> Plan
  -> Plan Review
  -> Execute
  -> Sync
  -> Spec

The important point is that the cycle starts and ends with Spec.

• Spec: source of truth defining the feature's purpose, requirements, contracts, and edge cases
• Spec Review: stage that reduces ambiguity, omissions, and mismatches against design/prototype
• Plan: stage that decomposes the Spec into concrete units of work and verification steps
• Plan Review: stage that audits implementation order, dependencies, risks, and missing tasks before execution
• Execute: stage that implements the actual code following the Plan
• Sync: stage that reflects the implementation back into the Spec to reduce drift between docs and code

In short, Spectrum is not a "write the doc once and discard" workflow — it is a plugin that creates a development loop where planning, implementation, review, and synchronization keep cycling around the Spec.

Why Spec-Driven Development

• The faster AI generates code, the more important the reference document for requirements and decisions becomes.
• Spec.md is the source of truth that captures a feature's purpose, requirements, edge cases, dependencies, and UI/data contracts.
• Plan.md is the execution plan that translates the Spec into concrete tasks, dependencies, and verification steps.
• Implementation follows Spec and Plan, and the result is synced back into the Spec so that documentation and code do not drift apart.

Workflow

Requirement / Design / Existing Code
  -> /spec
  -> /spec-review
  -> specs/<feature>/Spec.md
  -> /plan
  -> /plan-review
  -> specs/<feature>/Plan.md
  -> /exec-task
  -> implementation
  -> /review-changes
  -> /sync-spec
  -> Spec updated as source of truth

The default flow is Spec -> Spec Review -> Plan -> Plan Review -> Execute -> Sync -> Spec.

• /spec: creates or supplements Spec.md based on requirements, documents, design links, and existing code analysis.
• /spec-review: reviews the Spec for ambiguity and omissions to refine the reference document before implementation.
• /plan: reads the Spec and explores the codebase to produce Plan.md.
• /plan-review: audits the Plan for executability, missing tasks, ordering, and dependencies.
• /exec-task: implements the Plan's tasks in dependency order.
• /sync-spec: reflects the implementation back into the Spec so the document and the actual behavior stay aligned.

You can additionally use the following supplementary flow when needed:

• /review-changes: summarizes and reviews changes after implementation.

This workflow operates with the same philosophy on both Claude Code and Codex CLI, and uses state persistence and quality gates to iteratively refine the document until it reaches a sufficient level of detail.

Core Commands

/spec -> /spec-review -> /plan -> /plan-review -> /exec-task -> /sync-spec

after execute:
/review-changes -> /qcommit -> /pr

The most important loop in this README is /spec -> /spec-review -> /plan -> /plan-review -> /exec-task -> /sync-spec. Depending on the project and the target of the work, Spectrum detects mobile, web, backend, or general software (library/CLI/SDK) characteristics and applies the appropriate team skills and verification flow.

Single / Batch Mode

Many Spectrum skills support both Single mode and Batch mode.

• Single mode: pass a path directly to process a single Spec.md or Plan.md.
• Batch mode: omit the argument and the skill will either auto-collect modified documents or sweep all of specs/, depending on its role.

Batch mode usually behaves in one of two ways:

1. Document creation/review skills use git diff --name-only HEAD to find modified Spec.md or Plan.md files before commit, and fall back to scanning all of specs/ if none are found.
2. Skills that need to walk the entire reference document set iterate through specs/ directly to find their targets.
3. When multiple features are in scope, the skill processes them one at a time in order and prints a final summary at the end.

This means on a branch that touches several features, you don't have to feed each path one by one — you can immediately run flows like "advance the next stage for every Spec/Plan changed in this round" or "re-walk all Specs as the reference document set."

The main Batch mode targets:

Command	Batch mode target
/spec-review	sequentially review modified specs/*/Spec.md
/plan	sequentially write Plan.md based on modified specs/*/Spec.md
/plan-review	sequentially review modified specs/*/Plan.md
/exec-task	sweep every Plan.md under specs/ and sequentially run only the Plans that still have incomplete tasks

/exec-task differs from a typical git diff-based Batch in that its primary mode is sweeping the whole specs/ tree to find work.

• /exec-task walks every Plan under specs/ and selects only those with [ ] tasks remaining for sequential execution.

• If Spec.md files already exist under specs/: it runs in Batch mode and reviews each Spec sequentially.

• If specs/ is missing or empty: it runs in Discovery mode and identifies feature units from the webapp to create new Specs.

For example, if Plans for auth, dashboard, and settings all exist under specs/ and only two of them still have unfinished tasks, running /exec-task alone will pick exactly those two Plan.md files and implement them sequentially.

Directory Convention

The default Spec/Plan workflow uses specs/ as the base path:

specs/<feature>/
├── Spec.md
└── Plan.md

• Spec.md: reference document holding requirements, intent, contracts, and edge cases
• Plan.md: execution document holding implementation steps, tasks, dependencies, and verification

Other paths work too, but the batch modes of many skills look under specs/ first by default.

Installation

Claude Code

/plugin marketplace add https://github.com/CHOIMINSEOK/Spectrum
/plugin install spectrum

Codex CLI

./install.sh

What install.sh does:

1. Symlinks each skill under codex/skills/ into ~/.codex/skills/
2. Symlinks each codex/agents/spectrum-*.toml into ~/.codex/agents/
3. Replaces the placeholder in hooks/codex-hooks.json with absolute paths and merges the entries into ~/.codex/hooks.json (existing user hooks are preserved)
4. Codex automatically discovers skills/agents/hooks from those locations

To uninstall, run ./uninstall.sh (it only removes the symlinks and hook entries that Spectrum installed).

MCP / User Environment

./setup.sh

What setup.sh does:

1. Creates and normalizes ~/.claude/.mcp.json
2. Registers the mobile-mcp MCP server

External Dependencies

Spectrum makes heavy use of MCP servers and user-scope skills that live outside the plugin. Missing pieces only disable the corresponding features, but the workflow becomes much less effective without them.

The Claude Code plugin system does not support auto-installing or declaring user-scope skills or MCP servers via dependencies in plugin.json, so manual installation is required.

Required External Skills

Spectrum's domain guides and task-executor agents call these directly. All are officially distributed through vercel-labs/agent-skills — install them all at once via the npx skills tool.

npx skills add vercel-labs/agent-skills

After installation, the following names appear under ~/.claude/skills/ (the tool automatically prefixes them with vercel-):

Installed name	Used when	Referenced by
vercel-react-best-practices	invoked before React/Next.js work (pattern reference)	task-executor-web, web-team, domains/web.md
vercel-react-native-skills	invoked before React Native/Expo work	task-executor-rn, rn-team, domains/mobile.md
vercel-react-view-transitions	when implementing web page / state transition animations	domains/web.md
web-design-guidelines	web UI review / a11y audit	domains/web.md, /web-team QA

Verify installation:

ls ~/.claude/skills/ | grep -E "vercel-|web-design"

Source: vercel-labs/agent-skills (officially distributed by Vercel Engineering).

Required MCP Servers

The QA stage of *-team skills and several review skills assume MCP calls. Register them via ./setup.sh or by editing ~/.claude/.mcp.json manually.

MCP	Purpose	Used by
mobile-mcp	iOS/Android simulator control (launch app, screenshots, tap/swipe)	/rn-team QA
Playwright	web page rendering / capture / responsive / a11y verification	/web-team QA

Install / verify: running ./setup.sh registers mobile-mcp automatically. Playwright is provided as an MCP server through the playwright@claude-plugins-official plugin (claude plugin install playwright@claude-plugins-official).

Optional MCP / External Resources

Optional dependencies used only in part of the workflow. No need to install if you don't use the corresponding skill.

Resource	Purpose	Used by
frontend-design@claude-plugins-official plugin	high-quality frontend UI generation helper	callable during web domain work

Recommended External Plugins

Official plugins used for QA verification and UI/design work. Not needed if you don't work in those domains.

Plugin	Purpose	Install command
playwright@claude-plugins-official	web QA (provides Playwright MCP)	claude plugin install playwright@claude-plugins-official
figma@claude-plugins-official	design integration (provides Figma MCP)	claude plugin install figma@claude-plugins-official
context7@claude-plugins-official	library documentation lookup	claude plugin install context7@claude-plugins-official

Install Summary

# 1. Register MCP servers (mobile-mcp)
./setup.sh

# 2. Bulk-install Vercel skills
npx skills add vercel-labs/agent-skills

# 3. Add plugins for web/design work, if needed
claude plugin install playwright@claude-plugins-official
claude plugin install figma@claude-plugins-official
claude plugin install context7@claude-plugins-official

Missing skills/MCPs only fail when the matching feature is invoked. There is no automatic warning at session start, so use this table as a checklist.

Project Initialization

When attaching the Spectrum workflow to a project, prepare the following directly at the project root.

Base Directories

mkdir -p specs

Git Ignore

Add the following to your project's .gitignore so local execution artifacts don't end up in git:

.spectrum/

.spectrum/ stores local artifacts like review reports, screenshots, and session state.

Recommended Order

1. Create specs/ at the project root.
2. Add .spectrum/ to the project's .gitignore.
3. Run ./setup.sh from the user environment to prepare the MCP configuration.

When to Re-Apply

• If the repository path changes: re-run ./install.sh.
• If skills are added/removed: re-run ./install.sh.
• If local changes are not picked up by Claude: start a new session.
• If changes are not picked up by Codex: start a new session.

Repository Layout

.claude-plugin/          # Claude Code plugin manifest
.codex-plugin/           # Codex CLI plugin manifest

claude/
└── skills/              # Claude Code skills

codex/
└── skills/              # Codex CLI skills

hooks/
├── claude-hooks.json    # Claude Code plugin hooks
└── codex-hooks.json     # Codex CLI plugin hooks

scripts/                 # hook execution scripts
specs/                   # per-feature Spec.md / Plan.md

License

MIT — see LICENSE.