openspec-workflowAutonomous spec-driven development with OpenSpec CLI and Claude Code. You orchestrate (draft artifacts, make judgment calls, ship PRs) while Claude Code revi...
Install via ClawdBot CLI:
clawdbot install BobbyRadford/openspec-workflowShip spec-driven changes autonomously with review quality gates.
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.
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?"
openspec CLI installed (npm install -g @fission-ai/openspec)claude CLI installed (Claude Code)gh CLI authenticated with repo accessopenspec/ directory initializedWhen 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.
1. openspec new change "<name>"
2. For each artifact: draft → review loop → write
3. Implement tasks
4. Commit, push, open PR with "OpenSpec change: <name>" in bodyopenspec new change "<kebab-case-name>"
openspec status --change "<name>"For each artifact in order (typically: proposal → design → specs → tasks):
openspec instructions <artifact-id> --change "<name>"Read the template and dependencies. Draft the artifact content.
Then decide: review or skip?
Skipped review — trivial: .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 "<name>"Continue to the next artifact.
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/<name>/tasks.mdLaunch Claude Code in the repo (or worktree) with PTY and --dangerously-skip-permissions:
exec pty:true workdir:<repo-path> background:true command:"claude --dangerously-skip-permissions -p 'Implement these tasks from openspec/changes/<name>/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 <name>\" --mode now'"Monitor via process action:log sessionId:. Claude Code will:
[x] as it goesFor trivial changes (pure doc edits, one-line fixes), you may implement directly instead. Log: Implemented directly — trivial: .
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 "<type>(scope): <description> (#<issue>)
OpenSpec change: $CHANGE"
git push origin <branch>
gh pr create --repo <owner/repo> --base main --head <branch> \
--title "<type>: <description>" \
--body "Closes #<issue>
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.
After opening the PR, code review agents may leave comments. Monitor and respond:
# Check for review comments
gh pr view <number> --repo <owner/repo> --json reviews,comments
gh api repos/<owner>/<repo>/pulls/<number>/commentsFor each review comment:
# Fix, then:
git add -A && git commit -m "fix: address review — <what changed>"
git push origin <branch>
gh api repos/<owner>/<repo>/pulls/<number>/comments/<comment-id>/replies \
-f body="<your justification>"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.
Post the workflow log to the GitHub issue:
gh issue comment <number> --repo <owner/repo> --body '<workflow log>'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:
https://github.com///issues/ https://github.com///pull/ ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements### Requirement: + at least one #### Scenario:openspec/specs/ for modified capabilities- [ ] 1.1 Task descriptionFor repos that want automatic spec sync and archiving, add this workflow. See references/archive-action.md for the complete GitHub Action YAML.
The action:
OpenSpec change: in PR bodyopenspec archive --yes on a new branchGenerated Feb 24, 2026
A software team needs to add a new REST API endpoint to their microservice. Using OpenSpec Workflow, they draft a proposal outlining the endpoint's purpose, a design detailing request/response schemas, specs for validation logic, and tasks for implementation. Claude Code reviews each artifact against the existing codebase to ensure consistency and then implements the changes, resulting in a PR with full spec documentation.
An e-commerce platform plans to refactor a legacy payment processing module to improve performance and maintainability. The orchestrator creates OpenSpec artifacts to define the refactor's scope, design patterns, and migration steps. Claude Code reviews the artifacts to verify feasibility and avoid breaking changes, then implements the refactor with automated tests, ensuring a smooth transition.
A healthcare startup needs to migrate patient data to a new database schema without downtime. They use OpenSpec Workflow to draft a proposal for the migration strategy, design for data mapping and validation, specs for rollback procedures, and tasks for execution. Claude Code reviews the artifacts to assess risks and implements the migration scripts, with the orchestrator overseeing the PR and deployment.
A mobile app development team wants to introduce push notification capabilities to their backend service. They employ OpenSpec Workflow to create artifacts covering the feature's requirements, design for notification queues, specs for user preferences, and tasks for integration. Claude Code reviews each step against the existing infrastructure and implements the feature, ensuring compatibility with the app's frontend.
A fintech company aims to enhance security by adding multi-factor authentication (MFA) to their application. Using OpenSpec Workflow, they draft artifacts for the security proposal, design for MFA flow and storage, specs for compliance checks, and tasks for implementation. Claude Code reviews the artifacts to identify vulnerabilities and implements the changes, with the orchestrator managing the PR and CI/CD pipeline.
Companies building SaaS products use OpenSpec Workflow to manage feature development and updates autonomously. The orchestrator drafts specs for new features, Claude Code reviews and implements them, and PRs are shipped with auto-archived artifacts, reducing manual oversight and accelerating release cycles.
Development agencies adopt OpenSpec Workflow to deliver client projects with structured spec-driven processes. They use it to create proposals, designs, and task breakdowns, with Claude Code handling implementation reviews, ensuring high-quality deliverables and transparent client communication through artifact tracking.
Open-source maintainers leverage OpenSpec Workflow to manage contributions and refactors in community-driven repositories. The orchestrator handles spec drafting and PR management, while Claude Code reviews and implements changes, streamlining collaboration and maintaining code quality with automated CI checks.
💬 Integration Tip
Ensure all CLI tools (openspec, claude, gh) are installed and authenticated, and run the workflow from the repo root to avoid path issues during artifact creation and implementation.
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
Provides a 7-step debugging protocol plus language-specific commands to systematically identify, verify, and fix software bugs across multiple environments.
A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).
Write, run, and manage unit, integration, and E2E tests across TypeScript, Python, and Swift using recommended frameworks.
Control and operate Opencode via slash commands. Use this skill to manage sessions, select models, switch agents (plan/build), and coordinate coding through Opencode.
Coding style memory that adapts to your preferences, conventions, and patterns for consistent coding.