openspec-workflow
Skill0 starsChanged 4 days agoApache-2.0View on GitHub
OpenSpec carrier — creates, validates, and archives OpenSpec changes inside pull or merge requests and installs the automation that guards them on GitHub or GitLab. Use when a project that runs OpenSpec asks to create, validate, or archive a change; asks what must happen before its request can merge or how a change is approved; asks why a spec:* label changed or why the archive check has not reported; or wants the validation, archive check, or approval labels wired into CI or repaired. Not for choosing a spec framework, whether to adopt spec-driven development, recording the project's spec rules, or Spec-Kit.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- thistleknot/skillstheir own version, first seen Nov 8, 2026
- cedaniel200/atlas-templatetheir own version, first seen Nov 1, 2026
- AVANT-ICONIC/gpt-webui-skillstheir own version, first seen Oct 13, 2026
- AVANT-ICONIC/skillstheir own version, first seen Oct 13, 2026
- nb-99/skillektiontheir own version, first seen Aug 19, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- cedaniel200/atlas-template★ 3same name
- nb-99/skillektion★ 1same name
- AVANT-ICONIC/gpt-webui-skills★ 0same name
- AVANT-ICONIC/skills★ 0same name
- thistleknot/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository27 other files it gives its agents.
- AGENTS.mdAGENTS.md
- github-project-workflowSkill
- human-writingSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- openspec-update-changeSkill
- plugin-developmentSkill
- authority-buildingSkill
- completion-buildingSkill
- entropy-buildingSkill
- environment-buildingSkill
- feedback-buildingSkill
- gates-buildingSkill
- harness-architectureSkill
- harness-auditSkill
- harness-buildSkill
- harness-designSkill
- harness-extractSkill
- harness-mdSkill
- knowledge-buildingSkill
- lightweight-spec-workflowSkill
- project-skill-buildingSkill
- spec-driven-developmentSkill
- spec-kit-workflowSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. 0 are common, 11 are distinctive, and 12 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
11
Distinctive
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Ask the user about every point where two readings would lead to different work: present one recommended option with its reason and the …
- Distinctive: line 47
When a step is blocked on a decision only the user can make, continue with every step that does not depend on it and add the blocked item …
- Very specific: line 89
Every operation the OpenSpec CLI has a command for (init, new change, validate, archive, show, status) runs through that command.
- Very specific: line 91
Before the first use in a session read openspec --help and the subcommand's --help.
- Very specific: line 94
Never create a change directory or its .openspec.yaml by hand.
- Very specific: line 95
If openspec is not on PATH: say the CLI is missing, name it as the prerequisite the project must provide, point at the tool's own …
- Very specific: line 110
When that person adds it, the workflow records the approver, the commit, and a hash of the package (every file of the unarchived change …
- Distinctive: line 123
The archive is the freeze: Never edit anything under the archive directory.
- Very specific: line 145
Read the contract, openspec/config.yaml, and the CLI's help.
- Very specific: line 168
Create the change with openspec new change <name> (or the tool's own propose skill), then write the proposal, the delta specs, and the …
- Very specific: line 171
Read references/artifact-roles.md when writing or reviewing any of them.
- Distinctive: line 211
When the last task is verified, validate strictly and mark the request ready.
- Very specific: line 241
When an archive, the validation, or the commit fails partway, it restores openspec/ to HEAD and says so, so nothing stays half-archived.
- Distinctive: line 244
When the cause is in the approved package (the proposal, a delta spec, the design), the fix changes what was approved: show the edit and …
- Very specific: line 247
After a successful run, a second run exits 0 with nothing to do.
- Very specific: line 249
Run scripts/spec_changes.py with --help first when an option is unclear.
- Distinctive: line 270
Ask only when neither can be read (recommend GitHub and the current branch) or the user's stated target differs from what you observed.
- Very specific: line 283
Ask whether to deposit assets/spec_changes.py as the project's scripts/spec_changes.py with its test as is (the default when the agreed …
- Distinctive: line 289
Read references/github.md when the platform is GitHub.
- Distinctive: line 291
Read references/gitlab.md when the platform is GitLab.
- Distinctive: line 293
Read references/config-yaml.md when recording the artifact rules.
- Distinctive: line 296
When the project has a label-sync tool, print its dry-run plan of the additions and removals against the remote, apply it through that tool …
- Distinctive: line 344
Never rename one into the other.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OpenSpec Workflow
This skill carries one OpenSpec change through a pull or merge request:
the approval package before the tasks, implementation, ready before archive,
and the archive inside the request after the review closes,
so the default branch never holds an unarchived change.
It also installs the check, the withheld archive check, and the spec:*
labels that make those gates visible.
Rules on every step
Observe, then ask. Settle a fact from the repository when it can be observed there (tools in use, directories, commands, history). Ask the user about every point where two readings would lead to different work: present one recommended option with its reason and the alternatives in a sentence each, then wait for the choice. Challenge a choice once when the evidence contradicts it; after that the choice binds every later step.
Nothing lands before agreement. Step 8 creates or changes no file in the project until the user has approved the plan that names it; an inspection step reads and reports, it never writes. An approved plan authorises the files it names and nothing else: publishing anything outside the repository, changing a remote setting, deleting work, and widening what agents may do on their own are each a separate, explicit decision by the user, taken when that step is reached.
<!-- shared:pending-decisions -->When a step is blocked on a decision only the user can make, continue with every step that does not depend on it and add the blocked item to a pending decisions list. Each item states: what is blocked and why; the options; the recommended option and its reason; which finished work each option would change. Present the list once, at the end or when nothing else can proceed, never one question at a time.
<!-- /shared:pending-decisions --><!-- shared:management-code-ownership -->A script, hook, check, CI step, or task-runner recipe written into the target project is the project's own management code: written for its role in the language the project agreed to, readable first, failing with a message that names what to fix, with no fallback that hides an unexpected error, and never calling a script inside a skill directory. Tell the user that later fixes to this plugin do not reach the delivered copy.
<!-- /shared:management-code-ownership -->Precedence. An explicit user instruction,
then the project's specification contract
(the file the agent entrypoint names for spec work,
often .agents/knowledge/spec-workflow.md), then the defaults below.
The contract is the working copy of these rules;
a HARNESS.md the project keeps holds the design behind it and is not opened
for a change. Every reply that applies a rule says which source it came from
("the contract says a maintainer archives", "no contract rule;
the default applied").
| Point | Default when the contract is silent |
| Approval mode | conversational: the user states approval and the agent records it in the request description; recommend recorded (spec:approved plus the label workflow) when more than one person approves or agents run unattended |
| Design | warranted when more than one reasonable approach exists or the change touches structure, interfaces, dependencies, or files outside the record; none for a wording change |
| Archive executor | the implementer archives, after the review closes, by the tool's non-interactive archive command, and on a fork's branch a maintainer does so |
Where the contract is silent on a point the work at hand depends on, ask with the default as the recommendation and its reason, and wait; never choose silently. When a default applied, say so and name the skill that owns the Completion layer as the way to record another rule. If the user declines that handoff, proceed on the defaults, say which ones applied, and list the contract update as remaining work.
The CLI owns the tree.
Every operation the OpenSpec CLI has a command for (init, new change, validate,
archive, show, status) runs through that command.
Before the first use in a session read openspec --help
and the subcommand's --help; when a remembered command is not listed,
use the one the help lists.
Never create a change directory or its .openspec.yaml by hand.
If openspec is not on PATH: say the CLI is missing,
name it as the prerequisite the project must provide,
point at the tool's own documentation without printing an install command,
create nothing, and add the blocked step to the pending decisions.
Strict validation cadence.
Run openspec validate --all --strict --no-interactive
after each artifact edit, before publishing the draft,
before marking the request ready, and after archiving.
Fix every error or warning your edit caused before going on.
Labels are read, never set. In recorded mode spec:pending,
spec:approved, and spec:archived are state the label workflow keeps
from the tree and an approval record. Never add or remove one;
only a person with write permission adds spec:approved.
When that person adds it, the workflow records the approver, the commit,
and a hash of the package
(every file of the unarchived change except tasks.md) in a comment;
an edit to the package changes the hash, the record no longer matches,
and the workflow drops spec:approved and puts spec:pending back until
that person re-adds the label after reading the new version.
Asked to add it to your own request:
decline, say a person with write permission adds it and the workflow records it,
and put the step in the pending decisions.
A conversational-mode project records approval in the conversation
and carries no spec:* labels; for the recorded mode,
name the skill that owns the Completion layer.
The archive is the freeze. Never edit anything under the archive directory; a behaviour that must change gets a new change. A commit after the archive commit means the approved version no longer exists: say so and ask for the gate again before pushing or handing over.
Hand off by role, never by name: whether or how strictly to adopt spec-driven development and what a good specification answers go to the skill that teaches spec-driven development; setting or changing the approval mode, the design rule, or the archive executor goes to the skill that owns the Completion layer; the checks workflow and its gate to the skill that owns the Gates layer; remote label sync tooling to the skill that owns the Authority layer, which covers the platform lifecycle. Answer no practice-level question yourself.
Workflow
Steps 1–7 carry a change; step 8 installs or repairs the automation. Enter at the step the request names, after step 1.
1. Settle the rules and the tool
Read the contract, openspec/config.yaml, and the CLI's help.
Note the approval mode, the design rule,
and the archive executor with their source;
ask for any the work depends on that is missing.
Done when: each of the three is stated with its source, and the CLI is present (or its absence is in the pending decisions).
2. Decide whether the change needs a delta spec
Product behaviour gets a change with delta specs.
A change to the project's own harness, tooling, checks, workflows,
or documents gets none:
say no delta spec applies and recommend no change record,
because the harness is covered by its checks and a spec would be a second copy;
ask whether the user wants a recorded design anyway. If they do:
create the change with the CLI,
add skip_specs: true to the .openspec.yaml it wrote,
and write a proposal with Acceptance, a design only when the rule warrants one,
tasks only after approval, and no delta spec.
3. Write the approval package
Create the change with openspec new change <name>
(or the tool's own propose skill), then write the proposal, the delta specs,
and the design when the rule warrants one.
Read references/artifact-roles.md when writing or reviewing any of them.
The proposal ends with ## Acceptance holding Becomes true
and Stays true, so the end is checkable before any code is written;
every design Goal and Non-Goal carries a "Checked by" clause
and decisions name their rejected alternatives, with no steps.
A task list the propose step generated stays a draft:
it is after-approval material.
Done when: strict validation passes and the package meets the formats above,
with any not-yet-checkable Acceptance item named,
and every delta spec that creates a capability opens with a ## Purpose
of at least 50 characters
(validation passes without it now and fails after the archive).
4. Publish the package and wait for the first gate
Open the draft request with the proposal, delta specs, and design;
its description links the change and states that the task list follows approval,
since approval covers the outcome and the bounds of the approach, not the steps.
The gate is the contract's:
in recorded mode a person with write permission adds spec:approved;
in conversational mode the user says the package
is approved and the agent records that in the request description,
waiting for no label. Asked for the tasks before the gate closes:
say they follow the gate, name the gate that is open, and write none.
Done when: the gate the contract defines has closed.
5. Finish the tasks and implement
Finish tasks.md (each task names its verification), validate strictly,
and implement task by task.
Tick a task only after its verification ran and passed;
asked to tick one whose check has not run, run it or ask for it to be run first.
Done when: every task in tasks.md is ticked,
each after its named verification ran and passed, and strict validation passes.
6. Mark the request ready; archive nothing
When the last task is verified, validate strictly and mark the request ready. Asked to archive and mark ready in one go: mark it ready, archive nothing, and say the archive happens after the review closes. In recorded mode explain the withheld check: the required archive check does not report while a related change is unarchived on a ready request, so the merge stays blocked with nothing red, and the archive commit is what lets it report. On a draft the check job only warns and the required name stays unreported too, so a success on the draft's head cannot carry over once it is marked ready; a draft cannot merge, so the withholding blocks only once the request is ready.
Done when: the request is ready and the change is still unarchived.
7. Archive after the review closes
Refuse to archive a change with an unticked task: name the open task and archive nothing. Then follow the executor from step 1:
Implementer (and the branch is not a fork's): on the request's branch, run this skill's script, which archives every related change, validates strictly, and commits:
python3 <this skill's directory>/scripts/spec_changes.py archive \ --base origin/<target> --head HEAD --message "<message in the project's convention>"While a task is open or a path under
openspec/is uncommitted it exits 1 naming it and changes nothing. When an archive, the validation, or the commit fails partway, it restoresopenspec/to HEAD and says so, so nothing stays half-archived; fix the cause and run it again. When the cause is in the approved package (the proposal, a delta spec, the design), the fix changes what was approved: show the edit and get the approval again before committing it. After a successful run, a second run exits 0 with nothing to do. Report the validation result and the commit. Run scripts/spec_changes.py with--helpfirst when an option is unclear.- Maintainer, or a fork's branch: archive nothing.
Report the change ready for that person and list their step
with the tool's own commands, since they do not have this skill's script:
first confirm every task in each change's
tasks.mdis ticked, because--yesarchives with open tasks; then per changeopenspec archive <name> --yes(add--skip-specswhen its.openspec.yamlhasskip_specs: true); thenopenspec validate --all --strict --no-interactive; then commit and push.
Done when: the archive commit is on the branch, strict validation passes on the archived tree, and (recorded mode) the required check reports; or the step is handed to the named person.
8. Install or repair the automation
- State the platform and default branch read from the remote (
git remote -v,git symbolic-ref refs/remotes/origin/HEAD). Ask only when neither can be read (recommend GitHub and the current branch) or the user's stated target differs from what you observed. - Find the project's checks workflow and its gate (GitHub)
or
.gitlab-ci.yml(GitLab). If there is none to join, say so and recommend routing to the skill that owns the Gates layer to build it first, because the checks workflow and its gate belong there. The alternative, if the user agrees: create a minimal checks workflow (pull_requestpluspushto the default branch, top-levelpermissions: {}, a gate job) that holds the two jobs. Install nothing before the choice. - Ask whether to deposit assets/spec_changes.py
as the project's
scripts/spec_changes.pywith its test as is (the default when the agreed management language is Python) or to treat it as a reference implementation to rewrite in that language. Write nothing until the user chooses. - Present the plan naming every file; after approval:
- Read references/github.md when the platform is GitHub.
- Read references/gitlab.md when the platform is GitLab.
- Read references/config-yaml.md when recording the artifact rules; propose them and write them only after the user confirms.
- Labels: merge the
spec:*rows into the project's existing label file. When the project has a label-sync tool, print its dry-run plan of the additions and removals against the remote, apply it through that tool only after the user approves, then read the remote's labels back and report them. With no such tool, show the additions the merged rows imply against the remote (gh label listor the platform's label page), install none, name the skill that owns the Authority layer, and list the sync as remaining work. - Maintainer-only settings (the required check, rulesets,
"Pipelines must succeed",
GitLab's
SPEC_LABELS_TOKENand pipeline schedule) go to the pending decisions with the recommended value; continue with everything else. A check the platform has never observed blocks every request once required, so sequence a green run first. - GitLab: tell the user that labels and approvals take effect on the next pipeline on the default branch, which the schedule runs.
Decline an archive bot (no platform token can push to a fork,
and that job would be the only one with write access to contents;
point at the archive command) and comment commands
(point at status run locally or in the check job's log).
Done when: the check job is in the checks workflow and the gate's dependencies,
the label workflow (GitHub) or jobs fragment (GitLab) exists,
the label rows are merged,
scripts/spec_changes.py and its test are the project's own,
the artifact rules are recorded, every action is SHA-pinned,
every job declares its permissions,
no job holding a writable token checks out or runs the head,
and the required check and the label sync are in the pending decisions.
9. Report
End with the rules applied and their source, the state of the request and of the change record, the check's state, and the pending decisions list.
Gotchas
openspec archive <name> --yesarchives a change with open tasks after a one-line warning; the bundled script refuses first, so prefer it over the bare command.- The archive directory name carries the date, so the change link in the request description changes after archiving; both forms are valid.
- A tool's lowercase
design.mdis a technical design; a rootDESIGN.mdis a different, visual-design format. Never rename one into the other.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

