OpenSpec Workflow

Autonomous spec-driven development with OpenSpec CLI and Claude Code. You orchestrate (draft artifacts, make judgment calls, ship PRs) while Claude Code revi...

Security Scan

The skill's instructions legitimately describe an automated spec-driven code workflow, but the runtime instructions require powerful CLIs and permission-bypassing flags that are not declared in the registry metadata — the mismatch and use of --dangerously-skip-permissions/subagent repo access are noteworthy risks the user should review before installing.

Purpose & Capability

The skill's stated purpose (orchestrating OpenSpec + Claude Code workflows) matches the actions described in SKILL.md (drafting artifacts, spawning reviewers, implementing tasks, opening PRs). However, the registry metadata lists no required binaries or credentials while the SKILL.md explicitly requires openspec, claude, gh, and git — a metadata/instruction mismatch that reduces transparency.

Instruction Scope

SKILL.md instructs the agent to spawn reviewers/subagents with full repo path access, let Claude Code read/grep any file in the repository, and to run Claude with --dangerously-skip-permissions and PTY-backed exec. Those instructions grant wide read/write access to repository contents and ask the agent to run commands that bypass normal permission controls — appropriate for an automated implementer but high-risk if untrusted or run in a sensitive repo.

Install Mechanism

There is no install spec and the skill is instruction-only, so nothing will be downloaded or written by the skill bundle itself. This minimizes supply-chain install risk, but the instructions do depend on external CLIs being present on the host (openspec, claude, gh, npm for installation), which the metadata does not declare.

Credentials

The registry asserts no required env vars or credentials, yet SKILL.md requires an authenticated gh CLI (and implicitly a GitHub token for some flows), the claude CLI (which needs credentials), and npm-installed openspec. The workflow and reference GitHub Action also rely on GH_TOKEN/secrets in practice. The skill asks for access to credentials and repo contents without declaring them, which is disproportionate to what's presented in the registry metadata.

Persistence & Privilege

The skill does not request always:true and does not modify other skills' configs. Still, it instructs autonomous invocations (spawn reviewers, run Claude Code) and uses flags that bypass permissions. While autonomous invocation is platform-default, combining that with permission-skipping and subagent repo access increases blast radius — consider limiting autonomy or human confirmation for risky steps.

What to consider before installing

This skill is coherent as an automated spec-driven workflow, but several warning signs deserve attention before installing: - Metadata mismatch: The skill metadata declares no required binaries or credentials while the SKILL.md expects openspec, claude, gh, git, and an authenticated gh CLI — ask the publisher to update registry fields to reflect real requirements. - Permission-bypass flag: The guide explicitly runs Claude with --dangerously-skip-permissions and spawns subagents with full repo paths. That gives the implementer broad read/write access and can bypass platform safety checks — only run in repositories you fully control and audit first. - Credential scope: Limit tokens to least privilege (narrow GitHub repo scopes, avoid org-wide tokens). Prefer ephemeral tokens or require human approval for push/PR creation. - Audit repo for secrets: Before giving any subagent or external CLI access, scan the repo for secrets or sensitive files that could be exposed by an automated reviewer. - Operational controls: If you choose to use this skill, require interactive/human confirmation for commits and PR creation, or run in an isolated CI environment. Consider running claude and openspec in a sandbox/worktree instead of on your primary working copy. If the publisher cannot or will not correct the metadata to list required CLIs and credential needs, treat installation with extra caution or avoid installing into sensitive environments.

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:

• New features or capabilities
• Refactors that change behavior
• Breaking changes or migrations
• Anything that modifies or creates specs

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

• Examples, tutorials, sample projects
• Typo fixes, README updates, comment tweaks
• CI/CD config (GitHub Actions, linting)
• Dependency bumps

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

Prerequisites

• openspec CLI installed (npm install -g @fission-ai/openspec)
• claude CLI installed (Claude Code)
• gh CLI authenticated with repo access
• Git repo with openspec/ directory initialized
• Working directory is the repo root (or a git worktree)

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 "<name>"
2. For each artifact: draft → review loop → write
3. Implement tasks
4. Commit, push, open PR with "OpenSpec change: <name>" in body

Workflow

Step 1: Create the Change

openspec new change "<kebab-case-name>"
openspec status --change "<name>"

Step 2: Artifact Loop

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?

• Skip review if the artifact is genuinely trivial (one-liner, obvious config, mechanical rename). Log: Skipped review — trivial: <reason>.
• Send to review for anything with real design decisions, trade-offs, or ambiguity.

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.

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/<name>/tasks.md

Launch 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:<id>. Claude Code will:

• Read the OpenSpec artifacts for context
• Implement each task
• Mark [x] as it goes
• Commit the changes

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

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 "<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: <name> 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 <number> --repo <owner/repo> --json reviews,comments
gh api repos/<owner>/<repo>/pulls/<number>/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 — <what changed>"
   git push origin <branch>
   

3. If not significant: Reply inline with your justification.

   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.

Step 6: Document & Report

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:

• Issue: https://github.com/<owner>/<repo>/issues/<number>
• PR: https://github.com/<owner>/<repo>/pull/<number>

Artifact Guidelines

proposal.md

• Why (1-2 sentences), What Changes (bullet list), Capabilities (new + modified specs), Impact
• List every spec that will be created or modified in Capabilities — this drives the specs artifact

design.md

• Context, Goals / Non-Goals, Decisions (with alternatives considered), Risks / Trade-offs
• Skip for trivial changes (pure doc fixes, one-line config changes)

specs/<capability>/spec.md

• Delta format: ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements
• Every requirement needs ### Requirement: <name> + at least one #### Scenario:
• MODIFIED must include the full updated requirement text (not just the diff)
• Use existing spec names from openspec/specs/ for modified capabilities

tasks.md

• Numbered groups with checkboxes: - [ ] 1.1 Task description
• Small enough to complete in one session
• Ordered by dependency

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: <name> 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