docs: migrate the change process to OpenSpec#121
Merged
Conversation
Postlog
force-pushed
the
migrate-to-openspec
branch
from
c22e26a to
48cdb09
Compare
Adopt OpenSpec (the spec-driven schema) as the planning and change-documentation process, replacing the ADR catalog (the CHANGELOG stays). Seed a full spec baseline under openspec/specs/ (12 capabilities, validated by `openspec validate --specs --strict`), add the /opsx:* workflow under .claude/ (narrow the blanket .claude gitignore to settings.local.json so the commands/skills are tracked), and rewrite the process in AGENTS.md / CONTRIBUTING.md / README.md. Remove the docs/decisions/ ADR catalog (kept in git history); the migration's own rationale lives in the archived change openspec/changes/archive/2026-06-28-adopt-openspec/. Co-Authored-By: Claude Opus 4.8 <[email protected]>
Postlog
force-pushed
the
migrate-to-openspec
branch
from
48cdb09 to
0fa2d10
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Adopt OpenSpec (the
spec-drivenschema) as the planning and change-documentation process, replacing the ADR catalog (theCHANGELOGstays). ADRs capture point-in-time decisions, but the project had no maintained, machine-checkable description of what the system currently does. OpenSpec gives us a living behavior contract (openspec/specs/) plus a structured change workflow (proposal/design/tasks+ spec deltas), with slash commands and a validating CLI.What changes
openspec/specs/<capability>/spec.mdfor 12 capabilities (admin-auth, admin-users, user-provisioning, nodes, fleet, mihomo-config, mihomo-rendering, config-ownership, subscription-delivery, rule-provider-mirror, database-migrations, platform), ~50 requirements in the requirement + WHEN/THEN scenario format. All passopenspec validate --specs --strict.openspec/config.yaml(project context + per-artifact rules) andopenspec/changes/(+archive/)./opsx:*workflow generated under.claude/(5 commands + 5 skills). The blanket.claudegitignore is narrowed to.claude/settings.local.jsonso the commands/skills are tracked and the workflow is reproducible for contributors, CI, and review.AGENTS.md,CONTRIBUTING.md,README.md, and theCHANGELOG.mdheader now point at OpenSpec instead of ADRs.docs/decisions/becomes a frozen historical archive;docs/decisions/0010-adopt-openspec.mdrecords the switch anddocs/decisions/README.mdmarks the freeze. Existing ADRs (0001–0009) are kept, immutable.Decisions (agreed up front)
CHANGELOGand existing ADRs stay..gitignorefixed so only genuinely-local files stay ignored.Notes
go build ./...andgo vet ./...are green (sanity only).#TBDreferences inCHANGELOG.md/ ADR-0010 will be replaced with this PR's number before merge.🤖 Generated with Claude Code