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

Artifact kind	Canonical home	Compatibility rule
Project-specific system code	Owning project repo, usually under lib/, scripts/, bin/, or the project-specific command/prompt directory	Leave a shim only when a runtime mechanically resolves from a fixed path
Individual skill content	skills/skills/<subject>/<skill-name>/SKILL.md plus sibling artifacts	Do not author skill content in generated marketplace exports
Skill Graph schema, audit, prompt, and tooling system code	skill-graph/ paths owned by the Skill Graph project	Runtime command files outside skill-graph/ carry only pointer/delegation text when required
Generated manifests, indexes, exports, and status files	Generated by their named script	Regenerate from source; do not patch by hand unless the generator is the thing being fixed
Documentation truth	The owning doc named by the routing table	Indexes and pointer files link to the owner; they do not duplicate the body
Removed or superseded code	Git history, changelog explanation, and optional removed-path registry	No _archive/, .legacy, or commented-out implementation body in the live tree

Keep, Shim, Or Remove

Evidence	Action
Live imports, package scripts, runtime command resolution, tests, or documented user entrypoint still call the path	Keep it or convert it into a thin shim after moving logic
Path exists only for a runtime that cannot resolve the canonical location	Keep a registered shim with no business logic and a documented removal condition
Path is generated from a source file	Delete manual edits, fix source/generator, and regenerate
Only frozen historical records mention it	Remove the live artifact and leave the historical records unchanged
No live references, job complete, superseded owner wired, or one-shot migration finished	git rm, update changelog/registry as required, and record recovery command
You cannot prove whether it is live	Keep it for now and flag the uncertainty; do not guess-delete

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

Use instead	When
version-control	The task is choosing branch strategy, rebase vs merge, release tags, commit boundaries, or worktree lifecycle without changing canonical artifact ownership.
refactor	The task is behavior-preserving code restructuring inside an already canonical implementation path.
doc-updater	The task is only routing a code change to its owning docs and verifying docs changed in the same commit.
taxonomy-design	The task is only designing categories, facets, controlled vocabularies, or classification assignment rules.
code-review	The task is reviewing a PR/diff holistically for bugs, security, performance, and tests.

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