bluecraft/skills/agent-docs/references/linking-patterns.md

Linking Patterns

Preferred Patterns

Root -> Topic Docs

Use when the repository has a small set of clearly separate instruction topics.

# Required `agent-docs` Before Editing

- Read and follow `agent-docs/topic-a.md` when ...
- Read and follow `agent-docs/topic-b.md` when ...

Root -> Project Doc -> Leaf Docs

Use only when the intermediate layer reduces ambiguity or repeated cross-reference text.

AGENTS.md
  -> agent-docs/project-guidelines.md
      -> agent-docs/topic-a.md
      -> agent-docs/topic-b.md

Root -> Subproject agent-docs/

Use in monorepos when a subproject has its own scoped instruction set.

AGENTS.md
  -> apps/docs/agent-docs/project-guidelines.md
  -> services/api/agent-docs/backend-guidelines.md

Common rules stay in the root AGENTS.md. Subproject-specific rules stay near the subproject they govern.

Anti-Patterns

• Root file linking to every leaf doc in a large tree without grouping
• Child docs that are never reachable from the root
• Topic-specific rules stored in the root file without a reference reason
• Extra index files that only restate links without adding scope or decision logic
• Moving rules out of the root file without leaving an explicit reference to the new child file
• Keeping monorepo-wide and subproject-specific constraints mixed together in the same root section when they can be separated cleanly

Explicit Reference Rule

Parent documents should point to the child documents that refine them.

If a child document exists and is active, there must be an explicit reference path from the root AGENTS.md to that document.

The root AGENTS.md should list only the next agent-docs documents that are actually needed. Do not add unnecessary next-step links just for completeness.

Conflict Resolution Rule

• More specific scope beats broader scope.
• A child doc with explicit task scope beats a generic note in the root file.
• A rule doc's behavior rule beats an inventory entry's shorthand wording.
• If two active docs both read like authoritative owners for the same rule, do not improvise a priority. Treat it as duplicate authority and refactor the tree.
• If two sibling docs are equally specific and both explicitly apply, do not break the tie by tone or wording. Report the ambiguity and refactor the tree.