Run a full OpenSpec workflow from one request. Use when the user wants proposal, implementation, commits, spec sync, and archive handled as one resumable flow.
Run a full OpenSpec workflow from one request. Use when the user wants proposal, implementation, commits, spec sync, and archive handled as one resumable flow.
This repository-defined workflow is published as the openspec-oneshot skill and remains a local customization layered on top of upstream OpenSpec patterns.
The goal is to take one request and drive it through the normal OpenSpec workflow:
Create or continue the change proposal
Commit planning artifacts when apply is about to start
Apply the change and implement tasks
Sync delta specs and archive the change (including pre-archive checkpoint commit when needed)
Commit the archive result
If any stage is blocked, stop there, explain the blocker, and let the user resolve it. When the skill is run again, resume from the next incomplete stage instead of starting over.
Local Workflow Customizations
The steps labeled Local Customization are repository-specific additions layered on top of the upstream OpenSpec workflow. Keep them grouped when merging future upstream updates so the local workflow policy stays easy to review and reapply.
Store selection: If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run openspec store list --json to discover registered store ids, then pass --store <id> on the commands that read or write specs and changes (new change, status, instructions, list, show, validate, archive, doctor, context). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local openspec/ root.
Input: The user may provide freeform change text, a change name, or simply ask to resume the oneshot flow.
Workflow
1. Resolve whether this is a new run or a resume
Start with:
openspec list --json
If there is exactly one active change and the user asked to resume, continue that change.
If there is exactly one active change and the user gave no new change description, treat it as a resume.
If there is exactly one active change and the user gave new change text for a different effort, stop and tell them this workflow keeps one active change at a time; ask them to archive the existing change first.
If there are multiple active changes, use the AskUserQuestion tool to let the user choose which change to continue.
If there is no active change, treat the request as a fresh oneshot run and derive a kebab-case change name from the user's request text. If the request is too vague, ask:
"What change do you want to work on? Describe what you want to build or fix."
Always announce which change is being used and whether the skill is starting fresh or resuming.
1.5 Local Customization: compact session before a fresh oneshot run when helpful
Before starting a fresh oneshot run (no active change), prefer running /compact when conversation context is long or has drifted topics.
Keep this conditional, not mandatory.
If unresolved decisions or blockers are still only in chat and not captured in OpenSpec artifacts, capture those key points first, then compact.
If context is already concise and focused, proceed without compacting.
2. For a fresh run, create planning artifacts until apply-ready
Mark each completed task in the tasks file immediately.
Continue until all tasks are complete or a blocker is hit.
6. Archive the change with direct spec sync
Use the same archive-time behavior as the normal archive workflow:
Inspect artifactPaths.specs.existingOutputPaths from openspec status --change "<name>" --json.
If delta specs exist, sync them directly into openspec/specs/<capability>/spec.md.
Inspect tasks for incomplete checkboxes; if any remain, warn and ask for confirmation before archiving.
Create a pre-archive commit when relevant archive inputs are uncommitted. This includes uncommitted implementation work when apply finished without a checkpoint commit.
After any needed pre-archive commit, run the applicable local build and test checks for the repository when they exist.
If an applicable build or test check fails, warn and ask for confirmation before archiving anyway.
Move the change directory into openspec\changes\archive\YYYY-MM-DD-<name>\.
Create the post-archive commit for the synced specs and archived change move.
7. Pause cleanly on blockers
Stop and wait for the user when:
proposal creation needs clarification
an apply task is unclear
implementation reveals a design issue that should update the artifacts first
a required commit would capture unrelated work
a git or OpenSpec command fails
archive cannot proceed safely
When pausing, explain:
the current change
the current stage
what blocked progress
what needs to be resolved before rerunning the skill
8. Resume from the next incomplete stage
When the user reruns the skill after resolving a blocker:
inspect the active change with openspec list --json, openspec status --change "<name>" --json, openspec instructions apply --change "<name>" --json, and git --no-pager status --short
determine the first unfinished stage
continue from there instead of recreating proposal artifacts or reopening completed tasks
Examples:
Planning artifacts complete but tasks remain unchecked → resume in apply
Tasks complete but implementation changes are uncommitted → continue to archive and create the pre-archive checkpoint commit before sync/move
Specs synced but change directory not yet archived → resume in archive
