# Metadata Align

> After a structural change (new service, new site, renamed package, new fleet entry), update every docs/registry/metadata surface that references the structure, in the same change — not a deferred doc-debt cleanup. Use when adding/moving/removing a service or site, when the architecture changes, or when a new feature should appear in the README/fleet registry/package metadata.

- Skill: `jcdavis131/metadata-align` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jcdavis131/metadata-align`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jcdavis131/metadata-align/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jcdavis131 (https://skillmd.com/u/jcdavis131)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/jcdavis131/metadata-align

---


# 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:

1. **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.
2. **Root `package.json` / `pyproject.toml`** — `description`, `repository`, `homepage`, workspaces if the package is a workspace member.
3. **Fleet / service registry** — `config/fleet.json` or equivalent: register the new entry with its path/domain/status.
4. **OKF / knowledge bundle** — the concept entry for the new component + the bundle log entry recording the change.
5. **Site list in `AGENTS.md` / `CLAUDE.md`** — if the project keeps a human/agent-facing site table, update it.
6. **CI / deploy config** — if the new service needs to be built/deployed, wire it into the pipeline now, not later.
7. **`specs/`** — if the change introduces a new feature, attach or create a spec (the repo's SDD rule).
8. **`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 in `specs/` 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`/`homepage` reflect 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 needs `gh`) as a "needs your input" item.