docs(bluecraft-agentic-docs): refine documentation structure terminology and patterns

Update skill definition and templates to use "references" instead of "routing"
throughout, clarify the root AGENTS.md as the entry document for agent-docs, and
add explicit linking patterns guidance. Improve template wording to emphasize
directional, explicit references and minimal reference depth.

- Rename and expand linking patterns reference
- Update SKILL.md trigger conditions and core rules
- Refine child doc template compatibility note
- Update refactor checklist to focus on reference depth
- Simplify root AGENTS.md template structure

skills/bluecraft-agentic-docs/SKILL.md

@@ -7,7 +7,7 @@ description: Use when creating, updating, splitting, merging, reviewing, auditin
 
 ## Overview
 
-Use this skill to maintain agent-facing documentation trees centered on the `AGENTS.md` at the root of the current Git working tree and child instruction documents in `agent-docs/`.
+Use this skill to maintain agent-facing documentation trees centered on the `AGENTS.md` at the root of the current Git working tree and the applicable `agent-docs/` documents.
 
 Treat covered documents as instruction documents. If one applies in scope, it must be followed, not treated as optional background reading.
 
@@ -17,7 +17,7 @@ Use this skill when a task involves any of the following:
 
 - creating or editing the `AGENTS.md` at the root of the current Git working tree
 - creating, editing, splitting, merging, or deleting Markdown files inside any `agent-docs/` directory
-- changing routing between `AGENTS.md` and `agent-docs/` files
+- changing explicit references between `AGENTS.md` and `agent-docs/` files
 - auditing whether an agentic documentation tree is coherent, minimal, and fully connected
 
 Do not use this skill for end-user documentation, product manuals, README content that is not part of the agentic documentation tree, or project-specific business rules that do not govern agent-facing docs.
@@ -33,19 +33,19 @@ Do not use this skill for end-user documentation, product manuals, README conten
 - When referencing repository files from `AGENTS.md` or `agent-docs/`, prefer plain repository-relative paths in backticks such as `agent-docs/example.md`, not Markdown links.
 - Do not embed machine-local absolute filesystem paths such as `/home/...`.
 - Do not mix general agentic-documentation rules with project-specific business rules, product instructions, media planning, or end-user documentation guidance in the same general-purpose file.
-- Treat the `AGENTS.md` at the root of the current Git working tree as the primary routing entrypoint.
+- Treat the `AGENTS.md` at the root of the current Git working tree as the root entry document for the repository's `agent-docs`.
 - Keep common, repository-wide constraints in that root `AGENTS.md`.
 - In monorepos, keep common constraints in the root `AGENTS.md` and place subproject-specific constraints in the relevant `agent-docs/` directory near that subproject.
 - Put project-specific or topic-specific constraints in the relevant child documents under `agent-docs/`.
-- The root `AGENTS.md` should reference only the instruction documents that are actually needed as next-step routing targets.
+- The root `AGENTS.md` should reference only the `agent-docs` documents that are actually required for the next editing decision.
 - The combined set of the root `AGENTS.md` and active `agent-docs/` files should form a connected documentation tree.
 - Each active instruction document must be reachable through explicit references from the root entrypoint.
 - Do not leave orphan instruction documents.
 - Keep one authoritative home for each rule; link instead of duplicating.
-- When a file, path, or rule is obsolete, remove or update it in the same change instead of leaving stale routing behind.
+- When a file, path, or rule is obsolete, remove or update it in the same change instead of leaving stale references behind.
 - Prefer stable, semantic filenames.
 - Unless a specific instruction explicitly defines another base path, treat every path mentioned in the conversation or in agentic documentation as relative to the root of the current Git working tree, not relative to the current file.
-- Make routing directional and explicit: a parent document should point to the child documents that refine it.
+- Keep references directional and explicit: a parent document should point to the child documents that refine it.
 - Match the child document shape to the document's job. Do not force inventory or registry documents into the same structure as rule or policy documents.
 
 ## Workflow
@@ -54,7 +54,7 @@ Do not use this skill for end-user documentation, product manuals, README conten
 
 Choose the smallest accurate category:
 
-- root routing change
+- root entry or cross-reference change
 - repository-wide constraint change
 - child instruction document change
 - documentation-tree refactor
@@ -73,19 +73,19 @@ If a document spends most of its space enumerating items to maintain, do not for
 
 Use this placement standard:
 
-- Root `AGENTS.md`: routing entrypoint and repository-wide constraints
+- Root `AGENTS.md`: root entry document and repository-wide constraints
 - `agent-docs/` child docs: scoped instructions for a topic, project area, or workflow
 
 If a rule only matters within one child topic, do not keep it in the root file.
 
-4. Update routing explicitly.
+4. Update explicit references.
 
 - Add or adjust references from the root file to the necessary child files.
-- If a child file introduces narrower subtopics, route to them explicitly.
-- Avoid extra routing layers unless they materially reduce ambiguity.
-- When moving project-specific constraints out of the root `AGENTS.md`, replace them with an explicit route to the new child document instead of leaving the route implicit.
+- If a child file introduces narrower subtopics, point to them explicitly.
+- Avoid extra reference layers unless they materially reduce ambiguity.
+- When moving project-specific constraints out of the root `AGENTS.md`, replace them with an explicit reference to the new child document instead of leaving the reference implicit.
 
-See `references/routing-patterns.md` for routing patterns and anti-patterns.
+See `references/agent-docs-linking-patterns.md` for reference patterns and anti-patterns.
 
 5. Remove stale structure.
 
@@ -102,7 +102,7 @@ See `references/routing-patterns.md` for routing patterns and anti-patterns.
 - Use standard Markdown headings and lists unless a narrower instruction requires another structure.
 - Treat inventory entry fields as a recommended starter shape, not a fixed schema. Keep only the fields that materially help maintainers scan and update the inventory.
 
-Adapt the wording to the repository, but preserve the routing and scope model.
+Adapt the wording to the repository, but preserve the explicit-reference and scope model.
 
 7. Verify.
 
@@ -120,7 +120,7 @@ Use `references/refactor-checklist.md` as the final pass.
 - Rule child template: `references/rule-doc-template.md`
 - Inventory child template: `references/inventory-doc-template.md`
 - Child template chooser: `references/child-doc-template.md`
-- Routing patterns: `references/routing-patterns.md`
+- Linking patterns: `references/agent-docs-linking-patterns.md`
 - Refactor checklist: `references/refactor-checklist.md`
 
 Read only the reference files needed for the current task.
@@ -130,7 +130,7 @@ Read only the reference files needed for the current task.
 - Does each covered document own one clear topic?
 - Does the filename clearly express the document's purpose?
 - Does the opening explain the document's purpose, trigger, and in-scope follow requirement?
-- Is the `AGENTS.md` at the root of the current Git working tree still the primary routing entrypoint?
+- Is the `AGENTS.md` at the root of the current Git working tree still the root entry document?
 - Is every active `agent-docs/` file reachable from the root through explicit references?
 - Are obsolete paths, filenames, and documents removed?
 - Were obsolete index layers removed?

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

@@ -1,4 +1,4 @@
-# Routing Patterns
+# `agent-docs` Linking Patterns
 
 ## Preferred Patterns
 
@@ -7,7 +7,7 @@
 Use when the repository has a small set of clearly separate instruction topics.
 
 ```md
-# Required Instructions Before Editing
+# Read Required `agent-docs` Before Editing
 
 - Read and follow `agent-docs/topic-a.md` when ...
 - Read and follow `agent-docs/topic-b.md` when ...
@@ -15,7 +15,7 @@ Use when the repository has a small set of clearly separate instruction topics.
 
 ### Root -> Project Doc -> Leaf Docs
 
-Use when one project-specific document can route to several closely related leaf docs.
+Use when one project-specific document should explicitly reference several closely related leaf docs.
 
 ```md
 AGENTS.md
@@ -24,7 +24,7 @@ AGENTS.md
       -> agent-docs/topic-b.md
 ```
 
-Use this only when the intermediate layer reduces ambiguity or repeated routing text.
+Use this only when the intermediate layer reduces ambiguity or repeated cross-reference text.
 
 ### Root -> Subproject `agent-docs/`
 
@@ -42,15 +42,15 @@ Common rules stay in the root `AGENTS.md`. Subproject-specific rules stay near t
 
 - 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 routing reason
+- 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 route to the new child file
+- 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
 
-## Routing Rule
+## 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 path from the root `AGENTS.md` to that document.
+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 route only to the next instruction documents that are actually needed. Do not add unnecessary next-step links just for completeness.
+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.

skills/bluecraft-agentic-docs/references/child-doc-template.md

@@ -16,4 +16,4 @@ Use this reference when you know you are editing a Markdown file inside `agent-d
 
 ## Compatibility Note
 
-Older repositories may still refer to `references/child-doc-template.md` as the default child template. Keep this file as the entrypoint, but route new work to the specific template that matches the document's job.
+Older repositories may still refer to `references/child-doc-template.md` as the default child template. Keep this file as the entrypoint, but point new work to the specific template that matches the document's job.

skills/bluecraft-agentic-docs/references/refactor-checklist.md

@@ -5,7 +5,7 @@ Use this checklist after changing the root `AGENTS.md` or any file in `agent-doc
 - Does each covered document own one clear topic?
 - Does each filename clearly express the document's purpose?
 - Does each opening explain purpose, trigger, and that the document must be followed in scope?
-- Is the `AGENTS.md` at the root of the current Git working tree still the primary routing entrypoint?
+- Is the `AGENTS.md` at the root of the current Git working tree still the root entry document?
 - Does every active `agent-docs/` file have an explicit path from the root?
 - Does each child doc use the right shape for its job: rule doc versus inventory doc?
 - Did you remove stale references, filenames, and replaced paths?
@@ -15,5 +15,5 @@ Use this checklist after changing the root `AGENTS.md` or any file in `agent-doc
 - Is the default path basis still the root of the current Git working tree unless explicitly overridden?
 - Are repository-wide constraints still in the root file?
 - Are topic-specific constraints still in child docs?
-- Did you keep routing depth minimal?
+- Did you keep reference depth minimal?
 - If the repository has a validation command, did you run it?

skills/bluecraft-agentic-docs/references/root-agents-template.md

@@ -7,7 +7,7 @@ Use this structure for the `AGENTS.md` at the root of the current Git working tr
 ```md
 # Root Entry
 
-- State that this file is the primary routing entrypoint for the repository's agentic documentation tree.
+- State that this file is the root entry for the repository's `agent-docs`.
 - Define the default path basis.
 
 # Common Constraints
@@ -15,9 +15,9 @@ Use this structure for the `AGENTS.md` at the root of the current Git working tr
 - Keep repository-wide rules here.
 - Do not repeat topic-specific rules that belong in child docs.
 
-# Required Instructions Before Editing
+# Read Required `agent-docs` Before Editing
 
-- Route to the required child instruction docs.
+- List the required `agent-docs` explicitly.
 - Use explicit "Read and follow ..." wording.
 ```
 
@@ -25,6 +25,6 @@ Use this structure for the `AGENTS.md` at the root of the current Git working tr
 
 - Keep this file short.
 - Treat this file as an instruction document, not a passive index.
-- Route to child docs only when they are actually needed.
-- When routing to child docs, write repository-relative paths in backticks such as `agent-docs/example.md`, not Markdown links or machine-local absolute filesystem paths.
+- Reference child docs only when they are actually needed.
+- When referring to child docs, write repository-relative paths in backticks such as `agent-docs/example.md`, not Markdown links or machine-local absolute filesystem paths.
 - Do not turn the root file into a dump of all topic-specific rules.