jcdavis131 Metadata Align
A new service that lands in code but not in the docs/registry is drift. The README lies, the fleet registry doesn't know about it, the package metadata is stale. Align every surface that references the structure in the same change, when context is loaded — not a painful doc-debt cleanup later.
The surfaces to check after a structural change
When a service / site / package is added, moved, or removed, walk this list:
- README — the architecture diagram/section, the feature list, the quick-start for the new component. The architecture diagram should map each site to its domain AND its role (e.g.
storefront (storefront.example.com) · hq (hq.example.com, org hub) · validation (cert-service) · research (research-portal)), so a reader gets the full topology in one line. - Root
package.json/pyproject.toml—description,repository,homepage, workspaces if the package is a workspace member. - Fleet / service registry —
config/fleet.jsonor equivalent: register the new entry with its path/domain/status. - OKF / knowledge bundle — the concept entry for the new component + the bundle log entry recording the change.
- Site list in
AGENTS.md/CLAUDE.md— if the project keeps a human/agent-facing site table, update it. - CI / deploy config — if the new service needs to be built/deployed, wire it into the pipeline now, not later.
specs/— if the change introduces a new feature, attach or create a spec (the repo's SDD rule).specs/README.md(the spec index) — keep the spec index statused: each spec row carries a status (Implemented/Draft) and, for drafts, the sign-off requirement ("Awaiting Operator sign-off on venture map + consent language"). A spec that lands inspecs/but not in the index is invisible; a spec whose status is stale misleads the next contributor.
The shape of the update
For each surface, make the smallest change that keeps it truthful:
- README architecture diagram: add the new box + its connection.
- README quick-start: the one command to run the new component (
uv run python -m observability serve, :3006). package.json:description/repository/homepagereflect the new scope.fleet.json:commerce: services/commerce— register path + status.- OKF: concept entry + bundle log line recording the addition.
Do it in the same change
The alignment belongs in the same commit/PR as the structural change (see logical-commit-split). A structural commit that doesn't update the docs/registry is a half-change. Reviewers should see the code and the docs move together.
Anti-patterns
- "I'll update the README in a follow-up." You won't; doc-debt accumulates silently.
- Updating the README but not
fleet.json. The fleet SDK doesn't pick up the new service → it's invisible to automation. - Updating the registry but not the OKF concept. The knowledge base drifts from the code.
- Skipping CI/deploy wiring. The service builds locally but isn't deployed → "works on my machine" forever.
- A big README rewrite when a one-line architecture addition suffices. Match the scope of the structural change.
Pair with
logical-commit-split— the docs/registry alignment is part of (or its own) logical commit alongside the structural change.match-conventions— mirror the existing registry entry shape when adding a new one.readiness-report— surface any metadata surface you couldn't update (e.g. GitHub repo description needsgh) as a "needs your input" item.