run-spec-loop
/run-spec-loop
[Orbit 1.6.2 Specification] OpenSpec loop: proposal → delta → code → map → archive; switched on by repository signals. Use when: «openspec», «спека раньше кода», «оформи изменение», «обнови спеку и карту», «spec-driven»; spec-driven development.
- Author
- tojim00d ↗
- Repository
- Orbit-skills ↗
- Licence
- MIT
- Last repository change
- 09.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
[Orbit 1.6.2 Specification] OpenSpec loop: proposal → delta → code → map → archive; switched on by repository signals. Use when: «openspec», «спека раньше кода», «оформи изменение», «обнови спеку и карту», «spec-driven»; spec-driven development.
Original author description
[Orbit 1.6.2 Specification] OpenSpec loop: proposal → delta → code → map → archive; switched on by repository signals. Use when: «openspec», «спека раньше кода», «оформи изменение», «обнови спеку и карту», «spec-driven»; spec-driven development.
How it works
- When to use
- Inputs
- Procedure
- Output
- Check
- Example
- Pitfalls
- Portability
- What's improved vs the source
- Based on
SKILL.md preview
---
name: run-spec-loop
description: '[Orbit 1.6.2 Specification] OpenSpec loop: proposal → delta → code → map → archive; switched on by repository signals. Use when: «openspec», «спека раньше кода», «оформи изменение», «обнови спеку и карту», «spec-driven»; spec-driven development.'
---
# run-spec-loop — the "spec → code → map" loop on OpenSpec
> **Orbit · ① Understand · step 1.6.2 Specification**
> **Input:** an agreed spec — from `write-spec`
> **Output:** `openspec/changes/<id>/` merged after archive → next `plan-steps`
> **Works with:** `project-map`, `commit-clean`, `trace-impact`, `prove-done`
> **Shared rules:** reply in the user's language; generated artifacts default to English; artifacts go to `.orbit/` and `openspec/` (contract: `ARTIFACTS.md`).
The backbone of the pack: links **Understand** (spec) with **Build** (code) and **Operate** (map). Principle: **spec before code, map right after code.**
## When to use
- A behavior, contract, deploy config or module structure changes.
- The repo already has `openspec/`, a project map, or a rule in `AGENTS.md`/`CLAUDE.md` — then the loop is mandatory.
- A change was agreed in a spec and must be turned into tasks, code and a map update.
- Someone asks "where is the spec for this?" or the map is visibly stale.
- Before `plan-steps`, so tasks are derived from the delta rather than from chat.
Do **not** use the ceremony for typos, formatting, comments or behavior-preserving renames — but still check that the map isn't stale.
## Inputs
- the spec from `write-spec`; `.orbit/task/<id>/brief.md` and `requirements.md`;
- `openspec/project.md` and `openspec/specs/` — conventions and current truth;
- the project map directory (where `project-data.js` lives, often `docs/project-map/`);
- `.orbit/task/<id>/risks.md` and `plan.md` if they exist;
- the repo rules in `AGENTS.md` / `CLAUDE.md` / `CONTRIBUTING.md`.
If `openspec/` is missing and the work is significant, offer once to set it up (`openspec init` with consent). No consent → work without it and do not ask again. If the spec is missing, run `write-spec` first.
## Procedure
1. **Decide whether the loop is on**, by looking at the repository — not at the project name.
```bash
ls -d openspec 2>/dev/null # OpenSpec
find . -name project-data.js -not -path '*/node_modules/*' -not -path '*/.git/*' # project map
grep -il "openspec\|project-map\|карт" AGENTS.md CLAUDE.md CONTRIBUTING.md 2>/dev/null # repo rules
```
| Found | Action |
|---|---|
| `openspec/` **or** a map **or** a rule in AGENTS.md/CLAUDE.md | The loop rule is **mandatory** (below) |
| Nothing, work is significant (feature, behavior, contract, migration) | Offer once to set up OpenSpec and a map. No consent → work without them, don't ask again |
| Nothing, small edit | No ceremony, just do it |
2. **Write the proposal** `openspec/changes/<id>/proposal.md`: Why (1–3 sentences), What changes, Impact. No OpenSpec in the repo → `openspec init` (with consent, `stay-in-scope`). No CLI → create the files by hand.
3. **Write the spec delta and tasks.** `specs/<capability>/spec.md` with ADDED / MODIFIED / REMOVED, and a numbered `tasks.md`. Every requirement needs at least one WHEN/THEN scenario:
```markdown
### Requirement: Ingress timeout comes from values
The chart SHALL take the ingress timeout from `ingress.timeoutSeconds`.
#### Scenario: value set
- **WHEN** `ingress.timeoutSeconds: 120`
- **THEN** annotation `nginx.ingress.kubernetes.io/proxy-read-timeout` equals `"120"`
```
**Check:** `openspec validate <id> --strict` before showing it.
4. **Get agreement.** Show the proposal and the delta. Code starts after "yes"; questions go back to `write-spec`.
5. **Code to the spec.** `plan-steps` → `test-first` → `run-plan`. A test is a spec scenario. If code diverges, fix the spec first — never let code and spec drift.
6. **Update the map in the same change.** Add nodes, links, scenarios and files; edit `project-data.js`, rebuild, and include the built `project.html` in the change. The map directory is where `project-data.js` was found.
```bash
python3 <map-dir>/build.py
```
7. **Verify and archive.** `prove-done` → `openspec archive <id>` (the delta merges into `specs/`). Unfinished items (plans, operational steps, another team's work) stay as open items in `tasks.md` — never silently skipped.
8. **Keep the loop rule.** **Every change → OpenSpec entry + project map update**, in the same commit or right after, before push. "Every change" = any change of behavior, contract (API, event, DB schema), deploy config, module structure, or what the map shows. Only typos, formatting, comments and behavior-preserving renames may skip the OpenSpec entry — and they still need the map checked for staleness.
## Output
```
openspec/
project.md project context, conventions
specs/<capability>/spec.md current requirements (truth "as is")
changes/<change-id>/
proposal.md why and what changes
tasks.md work checklist
design.md (opt.) technical decisions
specs/<capability>/spec.md requirement delta: ADDED / MODIFIED / REMOVED
```
The change directory is the artifact; the archived delta is the durable result. The diagram is the loop in one picture:
```
proposal + spec delta ① Understand — agreed what changes
↓
code + tests by scenario ② Build — small steps, verified
↓
map + validate + archive ③ Operate — recorded and explained
```
## Check
```bash
test -d openspec/changes/<id> && ls openspec/changes/<id>
openspec validate <id> --strict # zero errors
grep -c '^### Requirement:' openspec/changes/<id>/specs/*/spec.md
grep -c '^- \*\*WHEN\*\*' openspec/changes/<id>/specs/*/spec.md
grep -n 'ADDED\|MODIFIED\|REMOVED' openspec/changes/<id>/specs/*/spec.md | head
git status --short # change dir + map + code together
```
Pass rule: `openspec validate <id> --strict` passes; every requirement has at least one WHEN/THEN; `tasks.md` has no silently dropped item; the map was rebuilt in the same change when it exists; after archive, `openspec/specs/` contains the merged requirement. Record the validation output in `.orbit/task/<id>/evidence.md` (`prove-done`).
## Example
```text
Repo has openspec/ and docs/project-map/project-data.js → loop is mandatory.
Task: ingress timeout must come from Helm values.
1. proposal.md: why (prod timeout hardcoded at 60 s), what (new value), impact (chart only).
2. delta: ### Requirement … SHALL take from ingress.timeoutSeconds + one WHEN/THEN scenario.
3. openspec validate change-142 --strict → ok; show proposal to the platform owner.
4. "yes" → plan-steps; test-first writes the scenario as a helm template assertion.
5. Code: values.yaml + ingress template; run-plan; test green.
6. Map: edit docs/project-map/project-data.js (chart node → values link), python3 build.py,
built project.html added to the same change.
7. prove-done records: validate ok, test output, rendered annotation 120.
8. openspec archive change-142; delta merged into specs/networking/spec.md; commit per commit-clean.
```
## Pitfalls
- **Deciding by project name.** The loop switches on repository signals (`openspec/`, a map, a rule), not on what the project is called; run the three probes first.
- **Code first, spec later.** A retroactive spec describes what was built, including its bugs. Write the delta before the code.
- **A stale map.** Updating nodes weeks later loses the edge that motivated the change. Rebuild the map in the same change.
- **`openspec validate` skipped.** Validation errors surface at archive time, after code review — run it before showing the proposal.
- **Silently dropped tasks.** Remaining tasks go into `tasks.md` as open items; an archive with hidden work is a lie.
- **Upgrading dependencies or touching prod "while here".** Out of scope by `stay-in-scope`; a separate change, a separate loop.
## Portability
Markdown plus the OpenSpec CLI when available — any agent and model can run it. Without the CLI, create `openspec/` files by hand and treat `validate` as a manual checklist against the same rules; map rebuild is a plain `python3 build.py`. Without subagents, do proposal → delta → code → map → archive inline; the artifacts are the state. No Claude Code features are required.
## What's improved vs the source
- The loop rule switches on by repository signals (`openspec/`, a map, or a rule in AGENTS.md), not by project name.
- "Every change" is defined precisely, along with what may skip an OpenSpec entry.
- The map is updated in the same change as the code — spec, code and diagram don't drift.
- Validation is part of the flow before agreement, not a surprise at archive time.
- The loop is drawn as one picture, so a new team member sees "understand → build → operate" in the artifact.
## Based on
- Orbit's own skill.
Versions
The database has no other skills named run-spec-loop.
Database snapshot: 13.11.2026 · package version bc99550977bc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100openspec
OpenSpec is a command-line tool plus a set of slash commands that make an AI coding agent write a reviewable plan — proposal, requirements with scenarios, design and task list — before it changes any code. Use when a user asks to set up spec-driven development, run openspec… - 100spec-design
Write OpenSpec design.md and tasks.md artifacts. TRIGGER when: producing a technical design or task checklist for a spec-driven feature. SKIP: writing proposal.md (use spec-research); executing tasks.md (use spec-develop). - 100commercetools-spec-driven-development
Wire the commercetools skills into a spec-driven development framework — GitHub Spec Kit (.specify/), OpenSpec (openspec/), or BMad Method (_bmad/). Use when user wants to set up or check the status of a spec-driven development framework that touches commercetools. - 100spec-verify
Check that an OpenSpec change's implementation actually matches its spec, before anything is archived - artifact validity via `openspec validate --strict`, the repo's own verify gate run for real, and scenario-by-scenario conformance against the spec delta. Read-only: it… - 100openspec-plus-spec
MANDATORY skill that activates whenever the OpenSpec specification phase begins. Triggers: /opsx-new or /opsx-continue runs; openspec-new-change, openspec-continue-change, or openspec-explore is active; `openspec instructions spec` or `openspec instructions specs` is invoked; or… - 100spec-driven-development
Use when the user explicitly asks to work in spec-driven mode (spec-driven, «по спекам», «заведи спеку», «ведём спеку»), or asks where the spec, plan, decisions or known problems for a task live. Covers a separate specs repository rooted at SPECS_ROOT — work-unit folders, stage…