{ "schemaVersion": "1.0", "item": { "slug": "openspec-workflow", "name": "OpenSpec Workflow", "source": "tencent", "type": "skill", "category": "效率提升", "sourceUrl": "https://clawhub.ai/BobbyRadford/openspec-workflow", "canonicalUrl": "https://clawhub.ai/BobbyRadford/openspec-workflow", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/openspec-workflow", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openspec-workflow", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "references/archive-action.md", "references/review-loop.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "slug": "openspec-workflow", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:56:23.851Z", "expiresAt": "2026-05-07T16:56:23.851Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openspec-workflow", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openspec-workflow", "contentDisposition": "attachment; filename=\"openspec-workflow-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "openspec-workflow" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/openspec-workflow" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/openspec-workflow", "agentPageUrl": "https://openagent3.xyz/skills/openspec-workflow/agent", "manifestUrl": "https://openagent3.xyz/skills/openspec-workflow/agent.json", "briefUrl": "https://openagent3.xyz/skills/openspec-workflow/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "OpenSpec Workflow", "body": "Ship spec-driven changes autonomously with review quality gates." }, { "title": "Architecture", "body": "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.\n\nRoleWhoWhatOrchestratorYou (the agent running this skill)OpenSpec CLI, artifact drafting, review judgment, PR shippingReviewerClaude Code (or subagent)Codebase exploration, claim verification, artifact challengesImplementerClaude CodeTask implementation, code changes, commits\n\nWhy 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." }, { "title": "When to Use This Skill", "body": "Use OpenSpec when the change affects what the product does:\n\nNew features or capabilities\nRefactors that change behavior\nBreaking changes or migrations\nAnything that modifies or creates specs\n\nSkip OpenSpec, just ship a PR when the change is supplementary:\n\nExamples, tutorials, sample projects\nTypo fixes, README updates, comment tweaks\nCI/CD config (GitHub Actions, linting)\nDependency bumps\n\nThe key question: \"Does this change what the product does, or just add stuff around it?\"" }, { "title": "Prerequisites", "body": "openspec CLI installed (npm install -g @fission-ai/openspec)\nclaude CLI installed (Claude Code)\ngh CLI authenticated with repo access\nGit repo with openspec/ directory initialized\nWorking directory is the repo root (or a git worktree)" }, { "title": "Timeouts", "body": "When running this workflow as a sub-agent, set runTimeoutSeconds based on change size:\n\nChange typeTimeoutWhyDoc-only / trivial300 (5 min)1-2 artifacts, maybe skip review, quick implementationStandard code change900 (15 min)4 artifacts × Claude Code review + implementationLarge / multi-file1200 (20 min)Complex reviews, big implementation, possible re-reviews\n\nEach Claude Code invocation (review or implement) takes 1-3 minutes. A full workflow with 4 reviewed artifacts + implementation = 5-8 Claude Code calls minimum." }, { "title": "Quick Start", "body": "1. openspec new change \"\"\n2. For each artifact: draft → review loop → write\n3. Implement tasks\n4. Commit, push, open PR with \"OpenSpec change: \" in body" }, { "title": "Step 1: Create the Change", "body": "openspec new change \"\"\nopenspec status --change \"\"" }, { "title": "Step 2: Artifact Loop", "body": "For each artifact in order (typically: proposal → design → specs → tasks):\n\nopenspec instructions --change \"\"\n\nRead the template and dependencies. Draft the artifact content.\n\nThen decide: review or skip?\n\nSkip review if the artifact is genuinely trivial (one-liner, obvious config, mechanical rename). Log: Skipped review — trivial: .\nSend to review for anything with real design decisions, trade-offs, or ambiguity.\n\nSpawn 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.\n\nAfter writing the artifact, confirm progress:\n\nopenspec status --change \"\"\n\nContinue to the next artifact." }, { "title": "Step 3: Implement via Claude Code", "body": "Do not implement tasks directly. Delegate to Claude Code, which has full codebase context and can make changes safely.\n\n# Get the task list for Claude Code's prompt\ncat openspec/changes//tasks.md\n\nLaunch Claude Code in the repo (or worktree) with PTY and --dangerously-skip-permissions:\n\nexec 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.\n\nWhen completely finished, run: openclaw system event --text \\\"Done: implemented \\\" --mode now'\"\n\nMonitor via process action:log sessionId:. Claude Code will:\n\nRead the OpenSpec artifacts for context\nImplement each task\nMark [x] as it goes\nCommit the changes\n\nFor trivial changes (pure doc edits, one-line fixes), you may implement directly instead. Log: Implemented directly — trivial: ." }, { "title": "Step 4: Ship", "body": "Before committing, verify the change name matches the actual directory:\n\n# Get the exact change directory name\nCHANGE=$(ls openspec/changes/ | grep -v archive | head -1)\necho \"Change name: $CHANGE\"\n\nUse this exact name everywhere — commit message AND PR body:\n\ngit add -A\ngit commit -m \"(scope): (#)\n\nOpenSpec change: $CHANGE\"\ngit push origin \ngh pr create --repo --base main --head \\\n --title \": \" \\\n --body \"Closes #\n\nOpenSpec change: $CHANGE\"\n\nCritical: 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." }, { "title": "Step 5: Address PR Review Comments", "body": "After opening the PR, code review agents may leave comments. Monitor and respond:\n\n# Check for review comments\ngh pr view --repo --json reviews,comments\ngh api repos///pulls//comments\n\nFor each review comment:\n\nEvaluate — Is it significant? Does it catch a real bug, missing edge case, or design issue?\nIf significant: Fix it in the worktree, commit, push. The PR updates automatically.\n# Fix, then:\ngit add -A && git commit -m \"fix: address review — \"\ngit push origin \n\n\nIf not significant: Reply inline with your justification.\ngh api repos///pulls//comments//replies \\\n -f body=\"\"\n\nApply 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." }, { "title": "Step 6: Document & Report", "body": "Post the workflow log to the GitHub issue:\n\ngh issue comment --repo --body ''\n\nInclude: each artifact's draft, review challenges, revisions, skip decisions with reasoning, and final implementation notes.\n\nAlways end by linking the user to the issue and PR:\n\nIssue: https://github.com///issues/\nPR: https://github.com///pull/" }, { "title": "proposal.md", "body": "Why (1-2 sentences), What Changes (bullet list), Capabilities (new + modified specs), Impact\nList every spec that will be created or modified in Capabilities — this drives the specs artifact" }, { "title": "design.md", "body": "Context, Goals / Non-Goals, Decisions (with alternatives considered), Risks / Trade-offs\nSkip for trivial changes (pure doc fixes, one-line config changes)" }, { "title": "specs//spec.md", "body": "Delta format: ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements\nEvery requirement needs ### Requirement: + at least one #### Scenario:\nMODIFIED must include the full updated requirement text (not just the diff)\nUse existing spec names from openspec/specs/ for modified capabilities" }, { "title": "tasks.md", "body": "Numbered groups with checkboxes: - [ ] 1.1 Task description\nSmall enough to complete in one session\nOrdered by dependency" }, { "title": "GitHub Action: Auto-Archive on Merge", "body": "For repos that want automatic spec sync and archiving, add this workflow. See references/archive-action.md for the complete GitHub Action YAML.\n\nThe action:\n\nTriggers on PR merge\nExtracts change name from OpenSpec change: in PR body\nRuns openspec archive --yes on a new branch\nOpens a PR with the archive and spec sync changes\nDeletes the original merged branch" } ], "body": "OpenSpec Workflow\n\nShip spec-driven changes autonomously with review quality gates.\n\nArchitecture\n\nYou 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.\n\nRole\tWho\tWhat\nOrchestrator\tYou (the agent running this skill)\tOpenSpec CLI, artifact drafting, review judgment, PR shipping\nReviewer\tClaude Code (or subagent)\tCodebase exploration, claim verification, artifact challenges\nImplementer\tClaude Code\tTask implementation, code changes, commits\n\nWhy 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.\n\nWhen to Use This Skill\n\nUse OpenSpec when the change affects what the product does:\n\nNew features or capabilities\nRefactors that change behavior\nBreaking changes or migrations\nAnything that modifies or creates specs\n\nSkip OpenSpec, just ship a PR when the change is supplementary:\n\nExamples, tutorials, sample projects\nTypo fixes, README updates, comment tweaks\nCI/CD config (GitHub Actions, linting)\nDependency bumps\n\nThe key question: \"Does this change what the product does, or just add stuff around it?\"\n\nPrerequisites\nopenspec CLI installed (npm install -g @fission-ai/openspec)\nclaude CLI installed (Claude Code)\ngh CLI authenticated with repo access\nGit repo with openspec/ directory initialized\nWorking directory is the repo root (or a git worktree)\nTimeouts\n\nWhen running this workflow as a sub-agent, set runTimeoutSeconds based on change size:\n\nChange type\tTimeout\tWhy\nDoc-only / trivial\t300 (5 min)\t1-2 artifacts, maybe skip review, quick implementation\nStandard code change\t900 (15 min)\t4 artifacts × Claude Code review + implementation\nLarge / multi-file\t1200 (20 min)\tComplex reviews, big implementation, possible re-reviews\n\nEach Claude Code invocation (review or implement) takes 1-3 minutes. A full workflow with 4 reviewed artifacts + implementation = 5-8 Claude Code calls minimum.\n\nQuick Start\n1. openspec new change \"\"\n2. For each artifact: draft → review loop → write\n3. Implement tasks\n4. Commit, push, open PR with \"OpenSpec change: \" in body\n\nWorkflow\nStep 1: Create the Change\nopenspec new change \"\"\nopenspec status --change \"\"\n\nStep 2: Artifact Loop\n\nFor each artifact in order (typically: proposal → design → specs → tasks):\n\nopenspec instructions --change \"\"\n\n\nRead the template and dependencies. Draft the artifact content.\n\nThen decide: review or skip?\n\nSkip review if the artifact is genuinely trivial (one-liner, obvious config, mechanical rename). Log: Skipped review — trivial: .\nSend to review for anything with real design decisions, trade-offs, or ambiguity.\n\nSpawn 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.\n\nAfter writing the artifact, confirm progress:\n\nopenspec status --change \"\"\n\n\nContinue to the next artifact.\n\nStep 3: Implement via Claude Code\n\nDo not implement tasks directly. Delegate to Claude Code, which has full codebase context and can make changes safely.\n\n# Get the task list for Claude Code's prompt\ncat openspec/changes//tasks.md\n\n\nLaunch Claude Code in the repo (or worktree) with PTY and --dangerously-skip-permissions:\n\nexec 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.\n\nWhen completely finished, run: openclaw system event --text \\\"Done: implemented \\\" --mode now'\"\n\n\nMonitor via process action:log sessionId:. Claude Code will:\n\nRead the OpenSpec artifacts for context\nImplement each task\nMark [x] as it goes\nCommit the changes\n\nFor trivial changes (pure doc edits, one-line fixes), you may implement directly instead. Log: Implemented directly — trivial: .\n\nStep 4: Ship\n\nBefore committing, verify the change name matches the actual directory:\n\n# Get the exact change directory name\nCHANGE=$(ls openspec/changes/ | grep -v archive | head -1)\necho \"Change name: $CHANGE\"\n\n\nUse this exact name everywhere — commit message AND PR body:\n\ngit add -A\ngit commit -m \"(scope): (#)\n\nOpenSpec change: $CHANGE\"\ngit push origin \ngh pr create --repo --base main --head \\\n --title \": \" \\\n --body \"Closes #\n\nOpenSpec change: $CHANGE\"\n\n\nCritical: 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.\n\nStep 5: Address PR Review Comments\n\nAfter opening the PR, code review agents may leave comments. Monitor and respond:\n\n# Check for review comments\ngh pr view --repo --json reviews,comments\ngh api repos///pulls//comments\n\n\nFor each review comment:\n\nEvaluate — Is it significant? Does it catch a real bug, missing edge case, or design issue?\nIf significant: Fix it in the worktree, commit, push. The PR updates automatically.\n# Fix, then:\ngit add -A && git commit -m \"fix: address review — \"\ngit push origin \n\nIf not significant: Reply inline with your justification.\ngh api repos///pulls//comments//replies \\\n -f body=\"\"\n\n\nApply 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.\n\nStep 6: Document & Report\n\nPost the workflow log to the GitHub issue:\n\ngh issue comment --repo --body ''\n\n\nInclude: each artifact's draft, review challenges, revisions, skip decisions with reasoning, and final implementation notes.\n\nAlways end by linking the user to the issue and PR:\n\nIssue: https://github.com///issues/\nPR: https://github.com///pull/\nArtifact Guidelines\nproposal.md\nWhy (1-2 sentences), What Changes (bullet list), Capabilities (new + modified specs), Impact\nList every spec that will be created or modified in Capabilities — this drives the specs artifact\ndesign.md\nContext, Goals / Non-Goals, Decisions (with alternatives considered), Risks / Trade-offs\nSkip for trivial changes (pure doc fixes, one-line config changes)\nspecs//spec.md\nDelta format: ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements\nEvery requirement needs ### Requirement: + at least one #### Scenario:\nMODIFIED must include the full updated requirement text (not just the diff)\nUse existing spec names from openspec/specs/ for modified capabilities\ntasks.md\nNumbered groups with checkboxes: - [ ] 1.1 Task description\nSmall enough to complete in one session\nOrdered by dependency\nGitHub Action: Auto-Archive on Merge\n\nFor repos that want automatic spec sync and archiving, add this workflow. See references/archive-action.md for the complete GitHub Action YAML.\n\nThe action:\n\nTriggers on PR merge\nExtracts change name from OpenSpec change: in PR body\nRuns openspec archive --yes on a new branch\nOpens a PR with the archive and spec sync changes\nDeletes the original merged branch" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/BobbyRadford/openspec-workflow", "publisherUrl": "https://clawhub.ai/BobbyRadford/openspec-workflow", "owner": "BobbyRadford", "version": "1.0.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/openspec-workflow", "downloadUrl": "https://openagent3.xyz/downloads/openspec-workflow", "agentUrl": "https://openagent3.xyz/skills/openspec-workflow/agent", "manifestUrl": "https://openagent3.xyz/skills/openspec-workflow/agent.json", "briefUrl": "https://openagent3.xyz/skills/openspec-workflow/agent.md" } }