update-spec

name	update-spec
description	Use when OSS_SPEC.md has been edited. Bumps the spec version field, propagates the new mandate through validate.rs, tests, templates, docs, README, AGENTS.md, and the self-conformance test.

Updating OSS_SPEC.md

OSS_SPEC.md is the single source of truth for every mandate this CLI emits into bootstrapped projects and enforces in oss-spec validate. Because the spec is embedded into generated projects via the symlink templates/_common/OSS_SPEC.md -> ../../OSS_SPEC.md, every edit ripples outward. This skill exists to ensure the ripples land.

Tracking mechanism

.agent/skills/update-spec/.last-updated contains the git commit hash from the last successful run.

Discovery process

1. Read the baseline:

   BASELINE=$(cat .agent/skills/update-spec/.last-updated)
   

2. Check whether OSS_SPEC.md changed since the baseline:

   git diff --name-only "$BASELINE"..HEAD -- OSS_SPEC.md
   

3. Read the diff itself:

   git diff "$BASELINE"..HEAD -- OSS_SPEC.md
   

   Decide whether the change is:

   • Major — a breaking change to an existing mandate or a removed section.
   • Minor — a new section, a new mandate, or a new required file.
   • Patch — wording clarifications, typo fixes, examples.

Mapping table

What changed in OSS_SPEC.md	What else must change
Version field in YAML front matter	bump per semver — major / minor / patch
New required root file	src/validate.rs (required_files), templates/_common/<file>, README.md, tests
New required directory	src/validate.rs (required_dirs), templates/_common/<dir>/, tests
New required symlink	src/validate.rs (symlinks), src/bootstrap.rs::create_agents_symlinks (if rooted at AGENTS.md), tests
New §19 content rule	src/validate/content.rs (or appropriate submodule), tests/validate_test.rs, src/fix.rs if auto-fixable
New §20.5-style size/shape rule with opt-in exception marker	src/validate/content.rs (walker + marker regex), tests/validate_test.rs, prompts/fix-conformance/<next>.md (scope of auto-fix), templates/_common/AGENTS.md.tmpl (contributor guidance)
New required workflow	src/validate/structural.rs (required_workflows), templates/_common/.github/workflows/<file>.tmpl, tests
New required agent skill	src/validate/agent_skills.rs::check, templates/_common/.agent/skills/<name>/, tests
Spec-wide guidance touching AGENTS.md	templates/_common/AGENTS.md.tmpl, this repo's AGENTS.md
README-visible change	README.md (run update-readme afterwards)
Docs-visible change	docs/ (run update-docs afterwards)

Update checklist

• Bump the version: field in the YAML front matter (major/minor/patch)

• Walk the mapping table — update every affected file

• Update CHANGELOG.md? No — it is generated at release time

• Run make fmt, make lint, make test

• Run oss-spec validate . — the self-conformance test must still pass

• Run update-readme and update-docs skills if they are now stale

• Write the new baseline:

  git rev-parse HEAD > .agent/skills/update-spec/.last-updated
  

Verification

1. cargo test -p oss-spec (the full suite)
2. oss-spec validate . against a freshly bootstrapped demo repo
3. Confirm the new spec version renders in README.md and (if applicable) the website
4. Confirm .last-updated was rewritten

Skill self-improvement

1. Grow the mapping table with every new propagation path you discover.
2. Record any cross-cutting invariant (e.g. "adding X to §A also requires Y in §B").
3. Commit the skill edit alongside the spec change so the propagation knowledge is captured.