openspec-bootstrap

The config steers every artifact agents write later. Its main job is keeping a change's artifacts at the outcome level. Artifacts that prescribe implementation detail go stale as soon as the implementation drifts, and agents then spend effort resyncing them. The template's context states that principle, with contracts as the one exception.

Workflow

1. Create a task per step below, phrased with its completion criterion, then work them to completion.
2. If openspec/ is missing, run openspec init --tools <the agents this repo uses>. Done when openspec/config.yaml exists.
3. Read the README, CLAUDE.md/AGENTS.md, the build entrypoint (Makefile or similar) and any planning or decision docs. Done when you can name what the project is, its hard constraints and where decisions live.
4. Copy assets/schemas/lean/ from this skill's directory to the project as openspec/schemas/lean/. It is spec-driven trimmed to outcome-level sections, with each fact held in one artifact. Done when openspec schema validate lean passes.
5. Copy assets/config.yaml from this skill's directory to the project as openspec/config.yaml, then fill it in.

• Keep it short. Include only what agents must take into account when working with OpenSpec in this project.
• Add a repo-specific rule only when the repo's docs show it needs one.
• If a config with real content already exists, merge into it instead: keep its repo-specific facts and replace rules that prescribe internal code.
• Delete any placeholder line you can't fill and note it for step 8.
• Done when rg -n '<[^>]+>' openspec/config.yaml finds nothing.

1. Check every rule you wrote against the template's context and the lean schema's instructions. Remove any rule that tells future agents to prescribe implementation detail, restates a schema instruction, or adds a section to every change.
2. Confirm the YAML parses: python3 -c 'import yaml,sys; yaml.safe_load(open(sys.argv[1]))' openspec/config.yaml.
3. Report the deleted placeholders to the user as questions rather than guessing values.

Gotchas

• Rules are appended to the schema's artifact instructions (openspec/schemas/lean/schema.yaml). Those already cover spec scope, user decisions, per-task verification, per-group tests and size targets. Write rules only for what the repo needs beyond them. A rule that contradicts the schema gets half-followed; edit the project's schema copy instead.
• Every rule tends to add a section to every change. Prefer limits ("only when ...") to requests ("include ...").
• Size targets in lines don't bind: agents write long lines. Use words.
• lean is a fork of OpenSpec 1.15.0's spec-driven. After an OpenSpec upgrade, compare it with openspec schema fork spec-driven output and carry over upstream fixes. lean keeps prose unwrapped while upstream wraps it, so compare with git diff --no-index --word-diff.
• context should point to files (CLAUDE.md, decision docs) rather than copying their commands or facts, which then drift.
• operations supports only apply and archive. OpenSpec only warns about other keys at instruction time, so a YAML parse misses them.
• Explore reads only context and rules. Behaviour wanted outside a single artifact or apply/archive goes in context.
• Archive blocks on unchecked task boxes, so the template's Human checks rule uses plain bullets. Keep that wording when merging into an existing config.
• Sub-agents never read the config. Rules they must follow go in apply guidance as something the main agent puts in each brief.
• Changes already in flight keep their current artifacts. The new rules apply to new changes.