Repository navigation
docs: adopt OpenSpec and restructure docs as a user manual - #19
Merged
Merged
Conversation
Seed nine capability specs under openspec/specs, derived from the current behaviour of the CLI and internal packages, as the baseline for spec-driven changes.
Give every subcommand its own page under docs/commands, add an index and a getting-started guide, and trim outfit-file.md to a file-format reference now that command walkthroughs live on the command pages and behavioural detail lives in openspec/specs. Link it all from the root README.
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
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.
Adopt OpenSpec for behavioural specs and rebuild the docs directory as a user manual.
Summary
openspec/) and seed nine capability specs — provider-catalog, provider-selection, outfit-files, alias-registry, harness-management, opencode-integration, pi-integration, local-serving, shell-completion — derived from the current implementation; all passopenspec validate --specs --strictdocs/as user documentation: every subcommand now has its own page underdocs/commands/, with a newdocs/README.mdindex and adocs/getting-started.mdend-to-end guidedocs/outfit-file.mdto a file-format reference — command walkthroughs moved to the command pages, behavioural detail now lives in the specs.claude/so contributors get the/opsx:*commandsImplementation details
The split of responsibilities is now:
openspec/specs/holds the behavioural contract (maintainer-facing, requirement/scenario format),docs/speaks to users, andAGENTS.mdkeeps the architecture map. The specs were seeded from the code itself (cmd/outfitand theinternal/packages) rather than from the docs, then cross-checked against the existingdocs/outfit-file.mdbefore it was trimmed.