docs: convert repository to the standard layout - #450
Merged
Conversation
osapi was the only repository with neither a root CONTRIBUTING.md nor an AGENTS.md, a 917-line CLAUDE.md, and three competing contributing documents. Contributing content now has one home at the root. The 917 lines of CLAUDE.md split by audience: contributor conventions to CONTRIBUTING.md, agent-specific guidance to AGENTS.md, and the nine-step domain walkthrough to the docs site as its own page. CLAUDE.md is a pointer. Code standards point at the go-code-standards capability rather than restating it. Only the conventions specific to osapi -- logging, lifecycle, filesystem access -- are stated here. docs/CONTRIBUTING.md and the two stale osapi-ui leftovers under ui/docs/ are removed; ui/docs/architecture.md stays because it holds a component reference the site does not. Implements standardize-repository-layout task 4.5 and specify-documentation-homes task 3.6. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every other repository importing the md justfile module declares uv; osapi did not, so `just md-fmt` resolved uvx from whatever the developer happened to have installed. The markdown-lint workflow provisions it through astral-sh/setup-uv, so both paths now float the latest release and agree. Satisfies the repo-standards requirement that a tool a repository invokes is declared in .mise.toml. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## main #450 +/- ##
=======================================
Coverage 99.94% 99.94%
=======================================
Files 484 484
Lines 24935 24935
=======================================
Hits 24921 24921
Misses 14 14 Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
retr0h
added a commit
to osapi-io/specs
that referenced
this pull request
Aug 16, 2026
osapi's conversion (osapi-io/osapi#450) closes the task that blocked three other changes: it was the only repository with neither a root CONTRIBUTING.md nor an AGENTS.md. Verification found five things the task lists asserted but nobody had checked. Four now pass: the required files, the absent docs/contributing and docs/development, the archived deprecated repositories, and the react module already taking its directory as configuration. One did not -- specs/LICENSE carried a differently titled and wrapped variant, replaced here with the canonical copy. Four remain open with the reason recorded rather than the box ticked: redocly is invoked but undeclared, three mocks are hand-written, go is pinned locally and floating in CI, and the export_test.go audit has not been done. Task 6.1 is dropped: osapi-io-taskfiles is archived and cannot be pushed to, and the archived state is accepted as the deprecation signal. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This was referenced Aug 16, 2026
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.
Implements
standardize-repository-layouttask 4.5 andspecify-documentation-homestask 3.6 from osapi-io/specs.osapiwas the only repository with neither a rootCONTRIBUTING.mdnor anAGENTS.md, a 917-lineCLAUDE.md, and three competing contributing documents.What moved
CLAUDE.md— dev reference, code style, branching, commitsCONTRIBUTING.mdCLAUDE.md— "Adding a New API Domain" (steps 0–8)docs/docs/sidebar/development/adding-an-api-domain.mdCLAUDE.md— UI conventions, block/stack vocabularydocs/docs/sidebar/development/ui-development.mdCLAUDE.md— tool invocation, commit trailer, task trackingAGENTS.mddocs/docs/sidebar/development/{development,testing,contributing}.mddocs/docs/sidebar/development/contributing.md— block/component proceduresui-development.mdCLAUDE.mdis now a pointer toAGENTS.md, matching every other repository.Code standards
CONTRIBUTING.mdpoints at thego-code-standardscapability rather than restating it, which is whatspecify-go-code-standardstask 2.5 asks for and what keeps3.6("no shared convention stated in two places") satisfiable. Only conventions specific to osapi — logging, lifecycle, filesystem access — are stated here.Removals
docs/CONTRIBUTING.md— a generic fork-and-PR primer referenced by nothing.ui/docs/contributing.md,ui/docs/development.md— stale osapi-ui leftovers naming a repository that no longer exists and recipes that no longer exist (just dev).ui/docs/architecture.mdis kept: it holds a UI-primitives table,Textvariant reference, and hooks table that the site'sui.mddoes not. Folding it in isspecify-documentation-homeswork, not layout work.Verification
just md-fmt-check— passesjust docusaurus-fmt-check— passesjust docusaurus-build— passes (no broken links)Docs-only; no Go code touched.
🤖 Generated with Claude Code