Skip to content
Skills Library
Management & product · Planning

openspec

/openspec

Apply when creating, updating or referencing any spec, design, proposal, roadmap, or deferred or rejected idea under openspec/, when creating, validating or archiving an OpenSpec change, or when a scenario fails its check. Esposter's spec of record — the folders under openspec/, the specs and designs in them, and the changes that move them. The team's /opsx commands and stage map are the team kit's openspec skill, linked here rather than copied.

Repository
Esposter ↗
Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Apply when creating, updating or referencing any spec, design, proposal, roadmap, or deferred or rejected idea under openspec/, when creating, validating or archiving an OpenSpec change, or when a scenario fails its check. Esposter's spec of record — the folders under openspec/, the specs and designs in them, and the changes that move them. The team's /opsx commands and stage map are the team kit's openspec skill, linked here rather than copied.

Triggers from the description

s /opsx commands and stage map are the team kit
Original author description

Apply when creating, updating or referencing any spec, design, proposal, roadmap, or deferred or rejected idea under openspec/, when creating, validating or archiving an OpenSpec change, or when a scenario fails its check. Esposter's spec of record — the folders under openspec/, the specs and designs in them, and the changes that move them. The team's /opsx commands and stage map are the team kit's openspec skill, linked here rather than copied.

How it works

  1. Settled — do not re-propose
  2. The one status rule
  3. Process
  4. Rules
  5. Format
  6. Writing style
  7. Diagram mandate
  8. Standards vs feature pages
  9. Deep Dives
Original SKILL.md headings · 85 lines, 1,580 words
SKILL.md preview
---
name: openspec
description: Apply when creating, updating or referencing any spec, design, proposal, roadmap, or deferred or rejected idea under openspec/, when creating, validating or archiving an OpenSpec change, or when a scenario fails its check. Esposter's spec of record — the folders under openspec/, the specs and designs in them, and the changes that move them. The team's /opsx commands and stage map are the team kit's openspec skill, linked here rather than copied.
---

# OpenSpec in Esposter

`openspec/` is the one place a feature is described: what is built, what is designed and waiting, and what was deferred or rejected. GitHub renders it, diagrams included, so there is no docs site and no parallel tree anywhere else in the repo. The team's commands (`/opsx:*`) and stage map come from the team kit's `openspec` skill, installed on every machine, which owns them. This skill holds only what is specific to this repository. Anything explanatory goes here rather than into `.agents/`, which holds only what a machine consumes (`openspec/specs/architecture/agent-configuration/design.md`).

## Settled — do not re-propose

- **An in-app docs site.** The specs are read on GitHub, which draws their diagrams. A site rendering the same tree is a second build of the same text, and a second copy that can disagree with the specs.
- **A folder of changes per product.** The CLI reads `openspec/changes/` flat and refuses a nested change, so a change carries its area as its id's prefix (`<area>-<slug>`) and in `affected_areas`. The specs, deferred and rejected trees are per-area folders already.
- **An overview page above the areas** — the technologies and the problem each one solves, drawn as one architecture. `AGENTS.md` is that map already and is read every session: its opening names the stack and what each part of it serves, its table each package, its specifications section the four states of the tree, and its owners table the page or skill each subject lives on. A page above the area READMEs would be a third copy of the same routing, read by no agent before the one it repeats.
- **A common capability for what sibling specs share.** Each character's kit and each region's compute spec repeats its siblings' shape with its own strikes, cooldowns and passes, and an agent building one reads that one alone. A rule every sibling states word for word is the other case: it belongs to the capability owning its mechanism, as `openspec/specs/genshin/parity/passes/design.md` owns every region's passes, and is cut from the siblings.
- **Pinning the CLI to the version the team kit's setup checks.** The catalog takes the newest release, as for every dependency (the `dependency-updates` skill); the kit's check is the kit's to bump.
- **Exact counts of the tree, on the reading that adding a package or a workflow is a deliberate act.** Nobody treats that act as a prose edit, so the count goes stale like any other measurement (`references/repo-owned-facts.md`).

## The one status rule

**Where a folder lives states whether it is built.** Never mix built and unbuilt in one folder.

- `openspec/specs/<area>/<capability>/` describes **only what exists in code today**: `spec.md`, the requirements and scenarios of record, and `design.md`, how it works. If you cannot point at the file that implements a sentence, the sentence does not belong here. The area's `README.md` is its index.
- `openspec/changes/<area>-<slug>/` is designed and **not yet built**: `proposal.md`, `design.md`, `tasks.md` and a spec delta under `specs/<area>/<capability>/`. A program (`<area>-<name>-program/`) is the umbrella over the changes sharing its prefix.
- `openspec/changes/<area>-roadmap/` is the area's **open work**, its `tasks.md` a checkbox backlog. Check `deferred/` and `rejected/` before adding an item or a change — never re-argue a decided idea.
- `openspec/deferred/<area>/<idea>/` holds ideas chosen **not to build yet**, each with a revisit trigger; `openspec/rejected/<area>/<idea>/` holds ideas decided **against**. The CLI does not read either tree, so a deferred idea revived is moved into `changes/`.
- `openspec/changes/archive/` holds shipped changes. It is history: nothing rewrites it, and the prose checks skip it.

**Specs move with the code that changes them** — update the owning `design.md` and `spec.md` in the same change that ships the behaviour, and cover the full lifecycle it describes (creation _and_ cleanup or teardown), not just the happy path.

## Process

1. Start a change: `pnpm exec openspec new change <area>-<slug> --description "<one sentence>"`, then write the four artifacts and the metadata (`references/change-metadata.md`).
2. Validate: `pnpm exec openspec validate <id> --strict --no-interactive`.
3. Check the scenarios: `pnpm -C scripts exec vitest run src/services/openspec`. Every scenario reads as an optional GIVEN, one WHEN and one THEN, with AND after any of them.
4. Each task names the test it writes first, and each scenario is that test's name in the suite it lands in.
5. Once it ships: `pnpm exec openspec archive <id> --yes`. The archive merges the deltas into `openspec/specs/`, and the capability's `design.md` is rewritten as built in the same change (`references/page-shapes.md`, "Lifecycle map").

## Rules

- A requirement describes behaviour an outsider can observe. File paths, class names and library choices belong in `design.md`.
- A decision in `design.md` names the alternative it rejected and the reason it lost. A decision that overturns a settled one names the old direction as rejected, so it cannot quietly return.
- **One capability, change or idea per folder — never merged.** A feature starts as one capability and gains sub-capabilities only once they exist (`references/page-shapes.md`). A folder is removed only when its idea is superseded, never to tidy up — the supersession is recorded in `deferred/` or `rejected/`. Folder names are kebab-case.
- **A list of N peer features is N capabilities plus a derived index, never one page.** The character kits are one capability each under `specs/genshin/kits/`, with the framework and the table in its `README.md`.

## Format

- **Plain GFM in a `.md` file**, no frontmatter (`references/markdown-format.md`). A change's metadata is its `.openspec.yaml` (`references/change-metadata.md`).
- **Mechanical follow-through.** A backticked path or code name is a claim the tree holds it, checked by the workspace tests; a moved file, a renamed name and an added page each owe a step (`references/moves-and-renames.md`).
- **A revision re-reads the page's own summary** — the lead and the consequences, against what the body now says (`references/revisions.md`).
- **Tests enforce the structure** — links, diagram labels, cited paths, the change's model and the Manual verification shape fail `pnpm test` in `scripts` (`references/spec-tests.md`).

## Writing style

Write for a new engineer reading on GitHub, not for an agent grepping a repo:

- Prose first. Complete sentences; spell out a term on first use. Tables only for short enumerable facts (procedures, key files).
- **Magnitudes, not measurements** — a number that moves with routine work is written as its magnitude, never today's reading (`references/repo-owned-facts.md`).
- **Every line earns its place** — link a page that already says it, by a relative path with prose as the link text (`references/links-and-sources.md`).
- **A decision taken from outside the repo cites where it came from** in the design's `## Sources`, read before cited (`references/links-and-sources.md`).
- **Never write down what the repo can count**, and **never restate a version a manifest declares, or a value a constant owns — name where it lives** (`references/repo-owned-facts.md`).
- Self-contained over link-chained: a page must be understandable without following links; links add depth, never required context.
- **A `## Notes` bullet says what no other section of its page does** — a consequence, an exception, a trade it names the cost of; never a restatement, and never an unfixed defect, which is fixed or becomes a roadmap item (`references/notes-and-stale-prose.md`).
- Keep the **Key files** table in every design — path and one-line role. It is the bridge from the spec to the code, and how a change is sized.
- **No deprecated or stale content, ever.** When something is superseded, delete it and fix every reference in the same change — no deprecation stubs, no "moved to X" notices. Why-not rationale lives only in `deferred/` and `rejected/`.
- **Invert a tombstone, don't just delete it.** A stale passage is usually a live rule stated as the history of what it replaced; keep the reasoning, drop the past tense and the dead identifier (`references/notes-and-stale-prose.md`).

## Diagram mandate

**A design describing an interaction between three or more parts carries a Mermaid diagram, and the diagram carries a mechanism** — an order, a gate or a fan-out, never a catalog or a straight line drawn as boxes (`references/diagrams.md`).

## Standards vs feature pages

A repo-wide answer to a class of problem is a standard under `specs/architecture/`; an area's capability holds only its product's application (`references/page-shapes.md`).

## Deep Dives

- `references/page-shapes.md` — when creating a capability, a change, a roadmap item or a deferred or rejected idea and placing it in the tree: the layout, the design and proposal shapes, and the lifecycle map.
- `references/change-metadata.md` — when writing a change's `.openspec.yaml`: the model that wrote it and the fleet's fields.
- `references/area-passes.md` — when ideating, triaging, or sweeping a whole product area's specs, and when deciding how that sweep is committed.
- `references/diagrams.md` — when adding a diagram, judging whether a page owes one, or sweeping an area's diagrams.
- `references/moves-and-renames.md` — when moving a file, renaming a cited name, or adding a page: the sync command, the citation tests, and when a name is quoted rather than backticked.
- `references/notes-and-stale-prose.md` — when writing a `## Notes` bullet, or removing a passage describing what the repo no longer has.
- `references/markdown-format.md` — when writing a page's markdown: plain GFM, no frontmatter, and fence languages.
- `references/revisions.md` — when changing a decision in the middle of a page.
- `references/spec-tests.md` — when a spec test fails, or before adding a link, a path or a diagram.
- `references/repo-owned-facts.md` — when a page states a number, a count, a directory's contents, a version or a constant's value.
- `references/links-and-sources.md` — when linking another page, or citing where an outside decision came from.
Files in this package (12)
  • SKILL.md 11 KB
  • references/area-passes.md 3 KB
  • references/change-metadata.md 2 KB
  • references/diagrams.md 5 KB
  • references/links-and-sources.md 2 KB
  • references/markdown-format.md 1 KB
  • references/moves-and-renames.md 2 KB
  • references/notes-and-stale-prose.md 3 KB
  • references/page-shapes.md 11 KB
  • references/repo-owned-facts.md 3 KB
  • references/revisions.md 1 KB
  • references/spec-tests.md 2 KB

Versions

RepositoryScoreLicence
This page · Esposter/Esposter90Apache-2.0
TerminalSkills/skills100Apache-2.0
itechmeat/llm-code100MIT
ruan-cat/monorepo100MIT

Database snapshot: 13.11.2026 · package version 44a856bceaa3 (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-apply-change
    Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. Also use when the user says "openspec apply", "opsx apply", or "openspec implement".
  • 100openspec-apply-change
    Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. Also use when the user says "openspec apply", "opsx apply", or "openspec implement".
  • 90openspec-plan
    Create OpenSpec change proposals. Use when: user wants to plan a feature, create a proposal, or start a new OpenSpec change.
  • 100openspec-apply-change
    Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. Also use when the user says "openspec apply", "opsx apply", or "openspec implement".
  • 87openspec-superpowers-workflow
    MUST use whenever the user proposes / adds / refines a feature, runs any /opsx:* or openspec CLI command, mentions OpenSpec changes, asks to brainstorm design / plan tasks / implement a spec'd feature, handles PR review feedback on a spec'd feature, or asks to reconcile /…
  • 90openspeccer
    Use when the user wants to open or browse an OpenSpec project's dashboard, or asks which OpenSpec changes are in flight or how far along one is. Do NOT use for creating, editing, verifying or archiving changes; use the OpenSpec workflow skills for those.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.