OpenSpec Workflow

OpenSpec Workflow

Ship spec-driven changes autonomously with review quality gates.

Architecture

You are the orchestrator. You serve as the "human in the loop" — you make judgment calls, draft spec artifacts, process review feedback, and decide what ships. Claude Code is your hands — it explores the codebase, reviews with real code context, and implements tasks.

| Role | Who | What | |------|-----|------| | Orchestrator | You (the agent running this skill) | OpenSpec CLI, artifact drafting, review judgment, PR shipping | | Reviewer | Claude Code (or subagent) | Codebase exploration, claim verification, artifact challenges | | Implementer | Claude Code | Task implementation, code changes, commits |

Why this split: The OpenSpec CLI is designed for scripting and automation — perfect for an orchestrator. Claude Code gets full codebase context automatically — perfect for review and implementation. The interactive plugin adds friction that doesn't help when an AI is the decision-maker.

When to Use This Skill

Use OpenSpec when the change affects what the product *does*:

Skip OpenSpec, just ship a PR when the change is supplementary:

The key question: *"Does this change what the product does, or just add stuff around it?"*

Prerequisites

Timeouts

When running this workflow as a sub-agent, set runTimeoutSeconds based on change size:

| Change type | Timeout | Why | |-------------|---------|-----| | Doc-only / trivial | 300 (5 min) | 1-2 artifacts, maybe skip review, quick implementation | | Standard code change | 900 (15 min) | 4 artifacts × Claude Code review + implementation | | Large / multi-file | 1200 (20 min) | Complex reviews, big implementation, possible re-reviews |

Each Claude Code invocation (review or implement) takes 1-3 minutes. A full workflow with 4 reviewed artifacts + implementation = 5-8 Claude Code calls minimum.

Quick Start

1. openspec new change ""
2. For each artifact: draft → review loop → write
3. Implement tasks
4. Commit, push, open PR with "OpenSpec change: " in body

Workflow

Step 1: Create the Change

openspec new change ""
openspec status --change ""

Step 2: Artifact Loop

For each artifact in order (typically: proposal → design → specs → tasks):

openspec instructions  --change ""

Read the template and dependencies. Draft the artifact content.

Then decide: review or skip?

Spawn reviewers as subagents with the repo path so they can explore the codebase independently — read files, grep for patterns, verify "no code changes" claims. Don't just paste the artifact; give them the tools to challenge it. See references/review-loop.md for the full protocol and prompt template.

After writing the artifact, confirm progress:

openspec status --change ""

Continue to the next artifact.

Step 3: Implement via Claude Code

Do not implement tasks directly. Delegate to Claude Code, which has full codebase context and can make changes safely.

# Get the task list for Claude Code's prompt
cat openspec/changes//tasks.md

Launch Claude Code in the repo (or worktree) with PTY and --dangerously-skip-permissions:

exec pty:true workdir: background:true command:"claude --dangerously-skip-permissions -p 'Implement these tasks from openspec/changes//tasks.md. Read the tasks file, the proposal, design, and specs in that change directory for full context. Mark tasks complete as you go. Commit when done.
When completely finished, run: openclaw system event --text \"Done: implemented \" --mode now'"

Monitor via process action:log sessionId:. Claude Code will:

For trivial changes (pure doc edits, one-line fixes), you may implement directly instead. Log: Implemented directly — trivial: .

Step 4: Ship

Before committing, verify the change name matches the actual directory:

# Get the exact change directory name
CHANGE=$(ls openspec/changes/ | grep -v archive | head -1)
echo "Change name: $CHANGE"

Use this exact name everywhere — commit message AND PR body:

git add -A
git commit -m "(scope):  (#)
OpenSpec change: $CHANGE"
git push origin 
gh pr create --repo  --base main --head  \
  --title ": " \
  --body "Closes #
OpenSpec change: $CHANGE"

Critical: The OpenSpec change: in the PR body must exactly match the directory name under openspec/changes/. The auto-archive GitHub Action uses this to locate the change. A mismatch means the archive silently skips. Always verify with ls openspec/changes/ before writing the PR body.

Step 5: Address PR Review Comments

After opening the PR, code review agents may leave comments. Monitor and respond:

# Check for review comments
gh pr view  --repo  --json reviews,comments
gh api repos///pulls//comments

For each review comment:

1. Evaluate — Is it significant? Does it catch a real bug, missing edge case, or design issue? 2. If significant: Fix it in the worktree, commit, push. The PR updates automatically.

   # Fix, then:
   git add -A && git commit -m "fix: address review — "
   git push origin 
   

   gh api repos///pulls//comments//replies \
     -f body=""
   

Apply the same judgment rules as the artifact review loop: accept valid concerns, reject with reasoning, partially accept where appropriate. Don't blindly apply every suggestion — you're the decision-maker.

Step 6: Document & Report

Post the workflow log to the GitHub issue:

gh issue comment  --repo  --body ''

Include: each artifact's draft, review challenges, revisions, skip decisions with reasoning, and final implementation notes.

Always end by linking the user to the issue and PR:

Artifact Guidelines

proposal.md

design.md

specs/\/spec.md

tasks.md

GitHub Action: Auto-Archive on Merge

For repos that want automatic spec sync and archiving, add this workflow. See references/archive-action.md for the complete GitHub Action YAML.

The action: 1. Triggers on PR merge 2. Extracts change name from OpenSpec change: in PR body 3. Runs openspec archive --yes on a new branch 4. Opens a PR with the archive and spec sync changes 5. Deletes the original merged branch

1. openspec new change ""
2. For each artifact: draft → review loop → write
3. Implement tasks
4. Commit, push, open PR with "OpenSpec change: " in body