Canonical Repo Structure

Canonical Repo Structure

Concept of the skill

A repository is a map of ownership. Each artifact has one canonical source, zero or more generated projections, and at most one compatibility path per runtime that truly needs the old entrypoint.

Coverage

• Choosing the owning repo and canonical path before creating, moving, or deleting scripts, commands, prompts, docs, generated artifacts, skills, and compatibility entrypoints
• Separating authored source from generated projections so agents edit the real source and regenerate the output
• Preventing duplicate implementations: update the owner, convert one necessary compatibility path into a thin registered shim, or remove the extra path
• Deciding whether a legacy artifact is live, deprecated, confirmed dead, generated, historical, or a runtime-required compatibility entrypoint
• Deleting confirmed-dead code to git history instead of preserving _archive/, .legacy, commented-out blocks, or "kept just in case" copies
• Recording deprecation/removal reasons in the owning changelog with a date plus time-of-day when the owning repo requires timestamped prose
• Updating live references after moves/deletions while leaving frozen historical records accurate
• Committing path-limited in the repo that owns the changed files

Philosophy of the skill

A repo is not just storage. It is an operating map for future agents. When one command body lives in three places, no reader knows which behavior is real. When generated output is hand-edited, the next generation run destroys the change. When dead code is moved into _archive/, every grep, router, audit, and cold-start reader has to rediscover that the file is dead.

Canonical organization is therefore a reliability feature. The correct tree is not the smallest tree; it is the tree where source, generated output, compatibility paths, and historical records are visibly different. Preserve live capability, preserve historical recovery in git, and remove dead weight from the live working tree.

Workflow

1. Identify the artifact and owning repo. Run git rev-parse --show-toplevel from the path you will touch. For nested repos, commit in the nearest owning repo, not in the parent that happens to list or ignore the path.
2. Find existing owners before adding a new path. Search names, commands, imports, package scripts, docs, and registries. If an owner exists, update that owner instead of copying it.
3. Classify the path.
   • Authored source: human-edited truth. Keep one canonical file.
   • Generated projection: regenerated from source. Do not hand-edit; update the generator or source.
   • Compatibility path: runtime-required entrypoint that delegates to canonical source. Register it and keep it thin.
   • Frozen historical record: changelog, ADR, report, or archived analysis that describes past state. Do not rewrite it to pretend history changed.
   • Confirmed-dead artifact: no live consumer and no current contract. Remove it from the tree.
4. Choose the canonical home from the owner map. Use the project AGENTS.md, implementation-ownership registry, document-routing table, package entrypoints, and runtime constraints. If a runtime can only read a specific path, leave a minimal shim there and put the logic in the canonical project-owned path.
5. Verify before deprecating or deleting. Grep live code, docs, scripts, package files, command manifests, and routing registries. Exclude frozen historical records from the live-dependency decision. A historical mention proves the artifact existed; it does not prove the artifact is still live.
6. Remove confirmed-dead implementation code to git history. Use git rm for tracked files. Do not move dead code to an archive folder or leave commented-out code. Record what was removed, why it was dead, the replacement or shim target if one exists, and a recovery command such as git log --all --oneline -- <path> followed by git checkout <sha>^ -- <path>.
7. Update live references in the same change. Grep *.md, *.sh, *.json, package scripts, command manifests, and owning docs for the old path/name. Fix live references; leave changelog/ADR/report mentions alone unless they are themselves wrong.
8. Commit only the owned paths. Use path-limited commits in the repo that owns the files. If multiple repos changed, create separate commits per repo.

Placement Rules

Keep, Shim, Or Remove

Deprecation And Removal Discipline

• Deprecation is caused by a replacement, direction change, or completed migration. It is not caused by age alone.
• The live tree carries current source, current shims, current generated outputs, and current docs. Prior implementations live in git history.
• A deprecated compatibility path that stays callable must be registered with its canonical target, status, removal condition, and required delegation/import target.
• A removed implementation path should be listed in the owning removed-path registry when such a registry exists, so it is not silently resurrected.
• Changelog entries for deprecation/removal name the artifact, why it changed, the replacement or shim target, and how to recover it from git.
• When the owning project requires timestamped prose, use date plus time-of-day, for example 2026-06-07T14:32+02:00, not just 2026-06-07.

Verification

• The nearest git repo owner was verified for every changed path
• Existing owners and duplicate paths were searched before adding a new artifact
• Authored source and generated projections are visibly separated
• Any compatibility path is registered, minimal, and delegates to the canonical path
• Confirmed-dead code was removed from the live tree rather than archived in-place
• Live references to moved/deleted paths were updated; frozen historical references were left intact unless wrong
• The owning changelog or lifecycle registry records deprecation/removal reason and recovery path when required
• Path-limited commits were used in the owning repo, with separate commits for separate repos

Do NOT Use When

Key Sources

• AGENTS.md - repo ownership, document routing, and implementation ownership rules
• docs/reference/implementation-ownership.md - canonical implementation registry and compatibility-shim contract
• docs/reference/artifact-lifecycle-contract.md - lifecycle metadata and changelog discipline for non-skill artifacts
• .claude/rules/delete-dont-archive.md - confirmed-dead code is deleted to git history, not archived in the tree
• skill-graph/AGENTS.md - Skill Graph canonical-location rule, delete-to-git-history directive, and timestamped changelog requirement
• skill-graph/SKILL_GRAPH.md - Skill Graph source vs generated marketplace distinction
• docs/reference/documentation-standards.md - one canonical source per fact and generated/reference verification gates