Lifecycle

Versioning

Use SemVer for the plugin and docs lifecycle. The repo is not published as an internal npm package yet; package.json exists for scripts, workspace dependency locking, and CI.

• PATCH: wording, examples, references, validation scripts, or non-breaking hook/rule fixes.
• MINOR: new skills, new references, new optional guidance, or stricter checks that warn only.
• MAJOR: removed or renamed skills, changed skill invocation semantics, default-deny policies, or blocking hooks/rules that can break existing workflows.

Release Flow

1. Edit canonical sources.
2. Run npm run build.
3. Run npm run validate.
4. Run npm run docs:build.
5. Bump versions across root package, plugin manifests, docs package, and marketplaces.
6. Commit source and generated files together.
7. Tag as vX.Y.Z.
8. Publish a GitHub release with changed skills, guidance, policies, hooks, and docs.

CI Gate

The required gate is:

npm run release:check

This runs adapter generation, validates skills and policies, builds docs, and verifies generated files are current.

Maintenance Cadence

Review monthly:

• Skills with repeated manual corrections.
• Policies that blocked legitimate workflows.
• Hooks that add noise or slow down users.
• Docs pages that no longer match the generated outputs.

Do Not Add A Package Yet

Keep distribution plugin-first until there is real pain syncing generated files into many downstream repositories.

Add an internal package only when all of these are true:

• Multiple repos need pinned generated AGENTS.md, .codex/rules, hooks, or config.
• Renovate or Dependabot should raise automated upgrade PRs.
• A CLI sync command would replace repeated manual copy steps.

Until then, the plugin marketplace and docs site are enough.