split agent-docs skills

skills/agent-docs/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: agent-docs
+description: Use when a task involves AGENTS.md or agent-docs and you need to choose the correct specialized workflow for auditing, refactoring, consistency checks, repo alignment, or verification.
+---
+
+# Agent Docs
+
+## Overview
+
+Use this skill as the entrypoint for AGENTS.md and `agent-docs/` work. It routes the task to the narrowest specialized skill and points to the shared templates and checklists under `references/`.
+
+Treat covered files as required instructions. If one applies in scope, it must be followed, not treated as optional background reading.
+
+## When to Use
+
+- The user asks to create, update, split, merge, delete, or refactor `AGENTS.md` or `agent-docs/`
+- The user asks whether the instruction tree is rational, consistent, or easy for agents to follow
+- The user asks whether agent docs match repository reality
+- The user asks for post-change validation of AGENTS or `agent-docs`
+
+Do not use this skill as the main workflow when the task is already clearly one of the specialized categories below. Switch directly to the matching skill.
+Do not use it for end-user documentation, product manuals, or README content that is not part of AGENTS or `agent-docs`.
+
+## Quick Triage
+
+1. Identify the concrete scope first:
+   - root `AGENTS.md` only
+   - one or more child docs under `agent-docs/`
+   - both root and child docs
+   - documentation-tree refactor
+2. Then choose the narrowest workflow:
+   - read-only rationality or adherence review
+   - structural graph or authority inspection
+   - repository-fact comparison
+   - document editing with follow-up checks
+
+## Routing
+
+- Use `agent-docs-audit` when the task is read-only evaluation: rationality review, instruction-adherence assessment, problem listing, or findings-first reporting.
+- Use `agent-docs-refactor` when the task requires editing files: create, split, merge, reroute, rename, delete, or rewrite `AGENTS.md` or `agent-docs`.
+- Use `agent-docs-consistency` when the task is structural inspection: reachability, cycles, depth, duplicate authority, or rule-doc vs inventory-doc shape checks.
+- Use `agent-docs-repo-alignment` when the task asks whether AGENTS or `agent-docs` match repository facts such as scripts, ports, directories, DTO ownership, or runtime behavior.
+- Use `agent-docs-verification` when the task is to validate a completed doc change and summarize the verification evidence.
+- After `agent-docs-refactor`, also use `agent-docs-consistency` when routing, authority ownership, reference depth, or document shape changed.
+- After `agent-docs-refactor`, also use `agent-docs-repo-alignment` when the edited docs make claims about repository facts or when stale wording may depend on current code, config, or commands.
+- Finish edited work with `agent-docs-verification`. Verification is the completion gate, not a substitute for structural or repo-fact review.
+
+## Conflict Resolution
+
+- Prefer the most specific applicable document over a broader one.
+- Prefer a child doc's scoped rule over a general reminder in the root file.
+- Prefer a document with explicit `Applies To` coverage over background wording that only mentions the topic indirectly.
+- Prefer rule-doc behavior constraints over inventory entry wording when both mention the same topic.
+- If two active docs both appear to own the same rule, treat that as duplicate authority and route to `agent-docs-consistency` or `agent-docs-refactor` instead of guessing.
+- If two active docs are equally specific and both explicitly apply, treat that as unresolved duplicate authority and report the ambiguity instead of choosing one.
+
+## Which Reference To Read
+
+- Root `AGENTS.md` update: read `references/root-agents-template.md`.
+- Child rule or policy doc: read `references/rule-doc-template.md`.
+- Child inventory or registry doc: read `references/inventory-doc-template.md`.
+- Unsure whether a child doc is a rule doc or inventory doc: read `references/child-doc-template.md`.
+- Cross-reference or document-tree change: read `references/linking-patterns.md`.
+
+## Shared References
+
+Read only the files needed for the current task.
+
+- Root doc template: `references/root-agents-template.md`
+- Rule doc template: `references/rule-doc-template.md`
+- Inventory doc template: `references/inventory-doc-template.md`
+- Child doc chooser: `references/child-doc-template.md`
+- Linking patterns: `references/linking-patterns.md`
+- Refactor checklist: `references/refactor-checklist.md`
+- Audit checklist: `references/audit-checklist.md`
+- Consistency checklist: `references/consistency-checklist.md`
+- Repo-alignment checklist: `references/repo-alignment-checklist.md`
+- Verification checklist: `references/verification-checklist.md`
+- Skill-maintenance checklist: `references/skill-maintenance-checklist.md`
+
+## Shared Constraints
+
+- Treat the root `AGENTS.md` as the starting point for required `agent-docs`.
+- Keep one authoritative home for each rule.
+- Keep repository-wide rules in the root file and topic-specific rules in child docs.
+- In monorepos, keep common constraints in the root file and put subproject-specific rules in the relevant nearby docs.
+- Match document shape to job: use rule docs for policy and inventory docs for maintained classifications or registries.
+- Remove stale references and obsolete files in the same change when restructuring the tree.
+- Write for maintainers. State actions, constraints, and decision criteria directly.
+- Rules should be actionable, not slogan-like.
+- Prefer standard Markdown headings and lists over wrapper tags for structure.
+- Keep the root focused on the next reading decision and list only the child docs that are actually needed.
+- Keep references directional and explicit: parent docs point to the child docs that refine them.
+- Prefer stable, semantic filenames and direct titles that state purpose.
+- When referencing repository files from AGENTS or `agent-docs`, use repository-relative paths in backticks, not Markdown links or machine-local absolute paths.
+- Do not mix general agent-doc governance with project-specific business rules, product manuals, media planning, or end-user documentation in the same general-purpose document.
+- Unless a document explicitly says otherwise, treat paths as relative to the root of the current Git worktree.

skills/agent-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Maintain agent-docs"
+  short_description: "Route agent-docs maintenance work"
+  default_prompt: "Use $agent-docs to route AGENTS.md and agent-docs maintenance tasks to the correct specialized skill and required follow-up checks."

skills/agent-docs/references/audit-checklist.md

@@ -0,0 +1,14 @@
+# Audit Checklist
+
+Use this checklist for read-only audits of `AGENTS.md` and `agent-docs/`.
+
+- Is the root `AGENTS.md` still the clear entrypoint?
+- Can a maintainer tell which document to read first for each common task?
+- Does any document act like a secondary router without enough reason?
+- Does each rule appear to have one authoritative home?
+- Does any inventory document contain policy language that should live in a rule doc?
+- Does any general-purpose agent-doc mix in project-specific business rules, product instructions, or end-user documentation?
+- Do key workflow docs state their edge cases and failure modes clearly enough that an agent would not have to infer them?
+- Are there residual cycles or cross-links that materially increase adherence cost?
+- Which findings are observed facts, and which are inferences about adherence risk?
+- If there are no concrete findings, what residual risks remain?

skills/agent-docs/references/child-doc-template.md

@@ -0,0 +1,19 @@
+# Child `agent-docs/` Template Chooser
+
+Use this reference when you know you are editing a Markdown file inside `agent-docs/`, but still need to decide which child template fits.
+
+## Choose The Smallest Matching Template
+
+- Use `rule-doc-template.md` for instructions, constraints, policy, decision criteria, or workflow guidance.
+- Use `inventory-doc-template.md` for maintained lists, registries, migration queues, or cleanup backlogs.
+- Split the document if one file tries to serve both purposes and the split would reduce ambiguity.
+
+## Quick Tests
+
+- If the document mainly tells maintainers what to do and what to avoid, use the rule template.
+- If the document mainly tracks entries that need to be updated over time, use the inventory template.
+- If the document has a long list of repeated entries under one governing policy, keep the policy brief and let the inventory structure carry the list.
+
+## 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 point new work to the specific template that matches the document's job.

skills/agent-docs/references/consistency-checklist.md

@@ -0,0 +1,12 @@
+# Consistency Checklist
+
+Use this checklist for structural inspection of the AGENTS and `agent-docs` graph.
+
+- Is every active child document directly or indirectly reachable from the root?
+- What is the shortest routing depth for each child doc?
+- Are there direct cycles? If so, which ones are harmless and which ones are noisy?
+- Does any document have unusually high out-degree and behave like a secondary index?
+- Does any intermediate document only restate links without adding scope or decision logic?
+- Is any rule likely owned by more than one active document?
+- Does each document's actual shape still match its declared job: root, rule doc, or inventory?
+- Are there stale references to deleted or renamed docs?

skills/agent-docs/references/inventory-doc-template.md

@@ -0,0 +1,63 @@
+# Inventory `agent-docs/` Template
+
+Use this structure for Markdown files inside `agent-docs/` when the document's main job is to track a maintained set of entries: media plans, registries, migration queues, or cleanup lists.
+
+## Recommended Shape
+
+```md
+# <Document Title>
+
+<Opening statement: what this inventory tracks, when it should be used or updated, and that it must be followed in scope.>
+
+## Applies To
+
+- <tasks that require reading or updating this inventory>
+
+## Does Not Apply To
+
+- <tasks that belong in a rule doc, public docs, or another inventory>
+
+## Maintenance Rules
+
+- <how to add, update, remove, or rewrite entries>
+
+## Reclassification Rules
+
+- <when an entry changes status or grouping>
+- <when repeated notes should become policy in a rule doc>
+- <when this inventory should split or link to a narrower rule doc>
+
+## Entries
+
+### <Grouping Heading>
+
+#### <Entry Title>
+
+<Recommended fields; keep only the ones that materially help maintainers.>
+
+Source:
+- <path or owning document>
+
+Status:
+- <planned / in progress / complete / remove / optional>
+
+Notes:
+- <what to capture, why it matters, or what to clean up>
+
+## Maintenance Checklist
+
+- <questions for keeping the inventory current and unambiguous>
+```
+
+## Notes
+
+- Prefer an inventory template when the document is mostly a maintained list rather than a rules essay.
+- Start with a small field set. `Source`, `Status`, and `Notes` are common defaults, not mandatory fields.
+- Add, rename, or remove entry fields to match the repository's actual maintenance needs.
+- Keep entry fields stable enough within one document that maintainers can scan and update them consistently.
+- Use grouping headings only when they materially improve navigation.
+- Separate durable maintenance rules from the entries themselves.
+- If the governing policy becomes large, move it to a rule doc and link to it from the inventory.
+- Add `Reclassification Rules` when entry state changes or repeated review decisions would otherwise stay implicit.
+- Write for maintainers and make update decisions explicit.
+- If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths.

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

@@ -0,0 +1,62 @@
+# Linking Patterns
+
+## Preferred Patterns
+
+### Root -> Topic Docs
+
+Use when the repository has a small set of clearly separate instruction topics.
+
+```md
+# 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.
+
+```md
+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.
+
+```md
+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.

skills/agent-docs/references/refactor-checklist.md

@@ -0,0 +1,27 @@
+# Refactor Checklist
+
+Use this checklist after changing the root `AGENTS.md` or any file in `agent-docs/`.
+
+- 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 root `AGENTS.md` still the starting point for required `agent-docs`?
+- 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?
+- Did you delete or update any `agent-docs` file that is no longer referenced from the root `AGENTS.md`?
+- Did you avoid duplicating the same rule across multiple active docs?
+- Did you avoid mixing long entry inventories into rule docs when a separate inventory would be clearer?
+- Did you avoid adding an intermediate router or index doc that only repeats links?
+- If you split a doc, did the split reduce ambiguity, repetition, or maintenance cost?
+- If a document grew broader, did you check whether it now owns more than one real decision surface and should be split?
+- If a workflow is fragile or easy to misapply, did you add explicit edge cases or failure modes instead of hiding them in prose?
+- 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?
+- Are project-specific rules still kept in project-specific documents rather than the general rules layer?
+- Did you avoid mixing general agent-doc governance with project-specific business rules or end-user documentation?
+- Do repository file references still use plain repository-relative paths in backticks rather than Markdown links or machine-local absolute paths?
+- Did you keep reference depth minimal?
+- Does the root still act like a route map instead of a topic dump?
+- If the repository has a validation command, did you run it?

skills/agent-docs/references/repo-alignment-checklist.md

@@ -0,0 +1,12 @@
+# Repo Alignment Checklist
+
+Use this checklist when comparing AGENTS or `agent-docs` against repository facts.
+
+- Which exact doc claims depend on repository reality?
+- Which repository files or commands provide the authoritative fact for each claim?
+- Do the rule docs expose enough authority or source-of-truth anchors that a maintainer can verify the claim without guessing?
+- Do scripts, ports, paths, or package names still match the docs?
+- Do the documented verification commands still match actual script behavior?
+- Do layering, contract-boundary, or runtime-topology claims still match code structure?
+- Which mismatches are must-fix drift versus wording cleanup?
+- Are the conclusions grounded in current files and command output rather than memory?

skills/agent-docs/references/root-agents-template.md

@@ -0,0 +1,38 @@
+# Root `AGENTS.md` Template
+
+Use this structure for the `AGENTS.md` at the root of the current Git working tree.
+
+## Recommended Shape
+
+```md
+# Root AGENTS.md
+
+- State that this file is the starting point for the repository's required `agent-docs`.
+- Define the default path basis.
+
+# Common Constraints
+
+- Keep repository-wide rules here.
+- Do not repeat topic-specific rules that belong in child docs.
+
+# Required `agent-docs` Before Editing
+
+- List the required `agent-docs` explicitly.
+- Use explicit "Read and follow ..." wording.
+```
+
+## Notes
+
+- Keep this file short.
+- Treat this file as an instruction document, not a passive index.
+- Reference child docs only when they are actually needed.
+- Write for maintainers and keep decisions explicit.
+- 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.
+- If the root starts collecting multiple topic-specific rule blocks, split them into child docs and keep only the routing decision here.
+
+## Complexity Budget
+
+- Keep the root focused on three jobs only: entrypoint, repository-wide constraints, and next-step routing.
+- If a root section starts carrying topic-specific decision logic, move that logic to a child doc and leave only the routing cue behind.
+- Treat multiple topic-specific rule blocks in the root as a refactor trigger, not as a sign to keep extending the root file.

skills/agent-docs/references/rule-doc-template.md

@@ -0,0 +1,51 @@
+# Rule `agent-docs/` Template
+
+Use this structure for Markdown files inside `agent-docs/` when the document's main job is to govern behavior: rules, policy, constraints, decision criteria, or workflow guidance.
+
+## Recommended Shape
+
+```md
+# <Document Title>
+
+<Opening statement: what this doc governs, when it applies, and that it must be followed in scope.>
+
+## Applies To
+
+- <specific task or document types>
+
+## Does Not Apply To
+
+- <out-of-scope task or document types>
+
+## Authority
+
+- <source of truth: owning doc, repository path, command, or code area>
+
+## <Rule Section>
+
+- <instructions>
+
+## Edge Cases
+
+- <exceptions, ambiguous cases, or branch conditions>
+
+## Failure Modes
+
+- <what usually goes wrong and how to recover>
+
+## Checklist
+
+- <validation questions>
+```
+
+## Notes
+
+- Make the scope explicit.
+- Keep the document responsible for one topic.
+- Use semantic filenames and headings.
+- Write for maintainers. State actions, constraints, and decision criteria directly.
+- If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths.
+- State the user or maintainer decision directly: what to do, what to avoid, and how to choose.
+- Add `Authority` when the rule depends on a repository fact, owning document, or other source of truth that later reviews must verify.
+- Add `Edge Cases` and `Failure Modes` when the workflow is easy to misapply or the scope boundary is easy to misunderstand.
+- Prefer linking to inventories, examples, or narrower child docs instead of embedding long registries inline.

skills/agent-docs/references/skill-maintenance-checklist.md

@@ -0,0 +1,9 @@
+# Skill Maintenance Checklist
+
+Use this checklist when editing the `agent-docs` skill suite itself: any `SKILL.md`, `agents/openai.yaml`, or shared file under `references/`.
+
+- Does each `agents/openai.yaml` still match the skill title, scope, and trigger language in the corresponding `SKILL.md`?
+- Is every file in `references/` directly referenced from the router skill or the specialized skill that requires it?
+- Are there stale filenames, old skill names, or outdated terms left behind after renames or splits?
+- Does one concept still use one term across `SKILL.md`, `agents/openai.yaml`, and `references/`?
+- If a shared checklist or template changed, do the affected skills still point to the right file and workflow step?

skills/agent-docs/references/verification-checklist.md

@@ -0,0 +1,12 @@
+# Verification Checklist
+
+Use this checklist after changing `AGENTS.md` or `agent-docs/`.
+
+- Did you run the strongest repository validation that actually applies?
+- For docs-only work with no stronger validator, did you at least run `git diff --check`?
+- If routing changed, did you re-check root reachability?
+- If cross-links changed, did you re-check for stale references or direct cycles where relevant?
+- If root routing, child references, conflict rules, or required follow-up workflow changed, did you test 1 to 3 representative prompts?
+- Did those representative prompts confirm that the agent read the root entrypoint first, chose the intended specialized workflow, ran required follow-up checks, and surfaced ambiguity instead of guessing?
+- Does the completion claim match the commands actually run?
+- If part of the change was not verified, is that limitation stated explicitly?