diff --git a/skills/agent-docs-audit/SKILL.md b/skills/agent-docs-audit/SKILL.md new file mode 100644 index 0000000..5cdc47a --- /dev/null +++ b/skills/agent-docs-audit/SKILL.md @@ -0,0 +1,44 @@ +--- +name: agent-docs-audit +description: Use when auditing AGENTS.md or agent-docs without editing files, especially for instruction quality review, adherence-risk assessment, findings-first reports, or rationality critiques. +--- + +# Agent Docs Audit + +## Overview + +Use this skill for read-only assessment of AGENTS and `agent-docs`. The output should prioritize findings, evidence, residual risks, and adherence impact instead of proposing patches first. + +## When to Use + +- The user asks for a review, audit, rationality check, or instruction-adherence assessment +- The user asks what remains wrong after a refactor +- The user asks why agents still fail to follow the docs +- The task is to list bugs, risks, or remaining problems before making changes + +Do not use this skill as the main workflow when the task is to edit files. Switch to `agent-docs-refactor` for that. + +## Workflow + +1. Read the root `AGENTS.md` and every active child doc in scope. +2. Read `../agent-docs/references/audit-checklist.md`. +3. Use `../agent-docs/references/refactor-checklist.md` as the structural baseline. +4. Separate observed facts from inferences: + - observed facts: file contents, references, checklists, routing text, command output + - inferences: likely adherence impact, likely confusion points, likely maintenance risk +5. Evaluate: + - routing clarity + - single authoritative rule ownership + - shape fitness: rule doc vs inventory doc + - instruction density and likely adherence load + - residual cycles or secondary-index behavior +6. Report findings first, ordered by severity. + +## Reporting + +- Findings first +- Then open questions or assumptions +- Then an adherence assessment +- Then any optional summary + +If no findings are discovered, state that explicitly and mention residual risks or coverage limits. diff --git a/skills/agent-docs-audit/agents/openai.yaml b/skills/agent-docs-audit/agents/openai.yaml new file mode 100644 index 0000000..b4656a6 --- /dev/null +++ b/skills/agent-docs-audit/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Audit agent-docs" + short_description: "Review agent-docs quality and adherence" + default_prompt: "Use $agent-docs-audit to evaluate AGENTS.md and agent-docs for instruction quality, routing clarity, and adherence risk." diff --git a/skills/agent-docs-consistency/SKILL.md b/skills/agent-docs-consistency/SKILL.md new file mode 100644 index 0000000..c7873cb --- /dev/null +++ b/skills/agent-docs-consistency/SKILL.md @@ -0,0 +1,41 @@ +--- +name: agent-docs-consistency +description: Use when checking the AGENTS.md and agent-docs graph for reachability, cycles, depth, duplicate authority, routing clarity, or rule-doc versus inventory-doc consistency. +--- + +# Agent Docs Consistency + +## Overview + +Use this skill for structural consistency checks across AGENTS and `agent-docs`. It focuses on the document graph and authority model, not repository behavior. + +## When to Use + +- The user asks whether there are cycles +- The user asks for document depth or routing structure +- The user asks whether two docs both own the same rule +- The user asks whether a doc has become a secondary router or mixed-shape document + +## Workflow + +1. Read the root `AGENTS.md`. +2. Read the active child docs in scope. +3. Read `../agent-docs/references/consistency-checklist.md`. +4. Inspect: + - root reachability + - shortest routing depth + - direct cycles and high-noise cross-links + - duplicate authority candidates + - out-degree hotspots + - rule-doc vs inventory-doc shape mismatches +5. Distinguish: + - blocking or high-noise structural problems + - acceptable cross-references +6. Report the structural findings without drifting into repository implementation review. Use `agent-docs-repo-alignment` for repo-fact comparison. + +## Output + +- Reachability summary +- Cycle summary +- Duplicate-authority or shape findings +- Residual risk assessment diff --git a/skills/agent-docs-consistency/agents/openai.yaml b/skills/agent-docs-consistency/agents/openai.yaml new file mode 100644 index 0000000..159fdde --- /dev/null +++ b/skills/agent-docs-consistency/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Check agent-doc consistency" + short_description: "Check graph and authority consistency" + default_prompt: "Use $agent-docs-consistency to inspect the agent-doc graph for reachability, cycles, duplicate authority, and shape mismatches." diff --git a/skills/agent-docs-refactor/SKILL.md b/skills/agent-docs-refactor/SKILL.md new file mode 100644 index 0000000..0b7efa0 --- /dev/null +++ b/skills/agent-docs-refactor/SKILL.md @@ -0,0 +1,57 @@ +--- +name: agent-docs-refactor +description: Use when creating, updating, splitting, merging, rerouting, renaming, or deleting AGENTS.md and agent-docs, especially when references, child docs, or document responsibilities must change together. +--- + +# Agent Docs Refactor + +## Overview + +Use this skill to edit the root `AGENTS.md` or files under `agent-docs/`. It is the production workflow for restructuring the document tree while preserving explicit routing and single-home rule ownership. + +## When to Use + +- The user asks to optimize, refactor, split, merge, or rewrite AGENTS or `agent-docs` +- A rule must move from one document to another +- A new child doc must be introduced or an obsolete one removed +- Cross-references, routing text, and checklists must be updated together + +## Workflow + +1. Read the root `AGENTS.md` and affected child docs. +2. Read the smallest relevant references from `../agent-docs/references/`: + - `root-agents-template.md` + - `rule-doc-template.md` + - `inventory-doc-template.md` + - `child-doc-template.md` + - `linking-patterns.md` + - `refactor-checklist.md` +3. Decide the target shape before editing: + - keep as one rule doc + - split rule doc from inventory + - merge overlapping docs + - delete obsolete leaf doc +4. Apply edits so that: + - the root remains the starting point + - every active child doc remains reachable from the root + - each rule has one authoritative home + - stale references are removed in the same change +5. If the change alters routing, authority ownership, or document shape, hand off to `agent-docs-consistency`. +6. If the change alters claims that depend on repository facts, hand off to `agent-docs-repo-alignment`. +7. Finish with `agent-docs-verification`. + +## Refactor Rules + +- Prefer the smallest change that reduces ambiguity or maintenance cost. +- Do not split only for symmetry. +- Do not split when one short document already governs one clear topic. +- Do not keep a child doc that is no longer reachable from the root. +- Do not leave topic-specific rules in the root file once a narrower child doc exists. +- Do not let inventory docs become policy docs. +- Do not add an intermediate file that only repeats links without adding scope or decision logic. +- Do not create a new child doc unless it reduces ambiguity, repetition, or maintenance cost. +- In monorepos, keep common constraints in the root file and keep project-specific rules in documents near that project instead of the general rules layer. +- Do not mix general agent-doc governance with business rules, product instructions, or end-user documentation. +- Titles and filenames should state purpose directly. +- Each opening should explain purpose, trigger, and that the document must be followed in scope. +- Use repository-relative paths in backticks when referencing repo files from AGENTS or `agent-docs`. diff --git a/skills/agent-docs-refactor/agents/openai.yaml b/skills/agent-docs-refactor/agents/openai.yaml new file mode 100644 index 0000000..9c30024 --- /dev/null +++ b/skills/agent-docs-refactor/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Refactor agent-docs" + short_description: "Edit or restructure agent-docs" + default_prompt: "Use $agent-docs-refactor to create, split, merge, reroute, or rewrite AGENTS.md and agent-docs, including necessary follow-up consistency, repo-alignment, and verification steps." diff --git a/skills/agent-docs-repo-alignment/SKILL.md b/skills/agent-docs-repo-alignment/SKILL.md new file mode 100644 index 0000000..ef906bd --- /dev/null +++ b/skills/agent-docs-repo-alignment/SKILL.md @@ -0,0 +1,41 @@ +--- +name: agent-docs-repo-alignment +description: Use when checking whether AGENTS.md and agent-docs still match repository facts such as scripts, ports, directory structure, contract ownership, runtime behavior, or verification commands. +--- + +# Agent Docs Repo Alignment + +## Overview + +Use this skill to compare AGENTS and `agent-docs` against the real repository. It detects drift between documentation and code, config, scripts, tests, and folder structure. + +## When to Use + +- The user asks whether docs still match the repository +- A doc mentions commands, ports, packages, stack choices, routes, DTO ownership, or runtime behavior +- A previous audit found wording that might be stale +- A refactor changed scripts or layout and the docs may need follow-up updates + +## Workflow + +1. Read the docs in scope. +2. Read `../agent-docs/references/repo-alignment-checklist.md`. +3. Inspect the repository facts relevant to the claim: + - scripts and `package.json` + - ports and proxy config + - directory and package structure + - shared contracts and DTO ownership + - tests or verification commands + - runtime and thread-sync code paths when relevant +4. Record observed facts first. +5. Compare doc claims against repo facts. +6. Report: + - confirmed matches + - must-fix drift + - wording drift or ambiguity + +## Boundary + +- This skill checks docs against repo facts. +- It does not replace structural graph checks from `agent-docs-consistency`. +- It does not perform the actual doc rewrite; use `agent-docs-refactor` for that. diff --git a/skills/agent-docs-repo-alignment/agents/openai.yaml b/skills/agent-docs-repo-alignment/agents/openai.yaml new file mode 100644 index 0000000..d9cd486 --- /dev/null +++ b/skills/agent-docs-repo-alignment/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Check agent-doc repo alignment" + short_description: "Compare agent-docs against repo facts" + default_prompt: "Use $agent-docs-repo-alignment to compare AGENTS.md and agent-docs against the repository facts: code, scripts, structure, and configuration." diff --git a/skills/agent-docs-verification/SKILL.md b/skills/agent-docs-verification/SKILL.md new file mode 100644 index 0000000..7137742 --- /dev/null +++ b/skills/agent-docs-verification/SKILL.md @@ -0,0 +1,56 @@ +--- +name: agent-docs-verification +description: Use when AGENTS.md or agent-docs have been changed and you need post-change validation evidence such as diff cleanliness, routing checks, cycle checks, or summary of what was verified. +--- + +# Agent Docs Verification + +## Overview + +Use this skill after changing AGENTS or `agent-docs` to gather verification evidence and report exactly what was checked. It is the completion gate for documentation-tree changes. + +## When to Use + +- A doc refactor is complete and needs verification +- The user asks whether the change is really done +- You need to summarize what was validated versus what was not + +## Workflow + +1. Read `../agent-docs/references/verification-checklist.md`. +2. If the change edited this skill suite itself, also read `../agent-docs/references/skill-maintenance-checklist.md`. +3. Run the strongest repository validation that actually applies. +4. At minimum for docs-only work: + - run `git diff --check` +5. When the change touched routing or structure, also re-check: + - root reachability + - stale references + - direct cycles if relevant + - duplicate authority or document-shape regressions when relevant +6. When the change touched repository-dependent claims, confirm those claims against current files, config, scripts, or command output rather than memory. +7. Treat the following as behavior-check-required changes: + - root routing changes + - child-doc reference changes + - conflict-resolution changes + - workflow changes that affect required follow-up skills such as `refactor -> consistency -> repo-alignment -> verification` +8. For behavior-check-required changes, run a small behavior check with 1 to 3 representative prompts and inspect whether the agent: + - reads the root entrypoint before choosing a specialized workflow + - follows the intended route and required follow-up checks + - escalates duplicate-authority or routing ambiguity instead of guessing + - states any unverified remainder explicitly +9. When the change edited the `agent-docs` skill suite itself, also confirm: + - each `agents/openai.yaml` still matches its `SKILL.md` + - every shared reference still has a direct reference path from the relevant skill + - no stale filenames, old skill names, or outdated terms remain after renames or splits + - one concept still uses one term across `SKILL.md`, `agents/openai.yaml`, and `references/` +10. Report command evidence and exact scope: + - what was verified + - what was not verified + - whether the claim is limited to docs structure only + - whether representative behavior was checked or only static structure was reviewed + +## Reporting Rules + +- Do not say a change is complete without fresh evidence from the current turn. +- Name the commands that were run. +- If only a minimum docs-only gate was available, say so explicitly. diff --git a/skills/agent-docs-verification/agents/openai.yaml b/skills/agent-docs-verification/agents/openai.yaml new file mode 100644 index 0000000..3bb740b --- /dev/null +++ b/skills/agent-docs-verification/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Verify agent-doc changes" + short_description: "Run post-change validation for agent-docs" + default_prompt: "Use $agent-docs-verification to run post-change validation for AGENTS.md and agent-docs and summarize the evidence." diff --git a/skills/agent-docs/SKILL.md b/skills/agent-docs/SKILL.md new file mode 100644 index 0000000..739e9ad --- /dev/null +++ b/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. diff --git a/skills/agent-docs/agents/openai.yaml b/skills/agent-docs/agents/openai.yaml new file mode 100644 index 0000000..af11ff0 --- /dev/null +++ b/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." diff --git a/skills/agent-docs/references/audit-checklist.md b/skills/agent-docs/references/audit-checklist.md new file mode 100644 index 0000000..ee6b92b --- /dev/null +++ b/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? diff --git a/skills/agent-docs/references/child-doc-template.md b/skills/agent-docs/references/child-doc-template.md new file mode 100644 index 0000000..3099e78 --- /dev/null +++ b/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. diff --git a/skills/agent-docs/references/consistency-checklist.md b/skills/agent-docs/references/consistency-checklist.md new file mode 100644 index 0000000..c3d0765 --- /dev/null +++ b/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? diff --git a/skills/agent-docs/references/inventory-doc-template.md b/skills/agent-docs/references/inventory-doc-template.md new file mode 100644 index 0000000..a4f9232 --- /dev/null +++ b/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 +# + + + +## Applies To + +- + +## Does Not Apply To + +- + +## Maintenance Rules + +- + +## Reclassification Rules + +- +- +- + +## Entries + +### + +#### + + + +Source: +- + +Status: +- + +Notes: +- + +## Maintenance Checklist + +- +``` + +## 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. diff --git a/skills/agent-docs/references/linking-patterns.md b/skills/agent-docs/references/linking-patterns.md new file mode 100644 index 0000000..2f9f79d --- /dev/null +++ b/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. diff --git a/skills/agent-docs/references/refactor-checklist.md b/skills/agent-docs/references/refactor-checklist.md new file mode 100644 index 0000000..1ac2ed4 --- /dev/null +++ b/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? diff --git a/skills/agent-docs/references/repo-alignment-checklist.md b/skills/agent-docs/references/repo-alignment-checklist.md new file mode 100644 index 0000000..4b518e8 --- /dev/null +++ b/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? diff --git a/skills/agent-docs/references/root-agents-template.md b/skills/agent-docs/references/root-agents-template.md new file mode 100644 index 0000000..9c73162 --- /dev/null +++ b/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. diff --git a/skills/agent-docs/references/rule-doc-template.md b/skills/agent-docs/references/rule-doc-template.md new file mode 100644 index 0000000..972818c --- /dev/null +++ b/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 +# + + + +## Applies To + +- + +## Does Not Apply To + +- + +## Authority + +- + +## + +- + +## Edge Cases + +- + +## Failure Modes + +- + +## Checklist + +- +``` + +## 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. diff --git a/skills/agent-docs/references/skill-maintenance-checklist.md b/skills/agent-docs/references/skill-maintenance-checklist.md new file mode 100644 index 0000000..2db5054 --- /dev/null +++ b/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? diff --git a/skills/agent-docs/references/verification-checklist.md b/skills/agent-docs/references/verification-checklist.md new file mode 100644 index 0000000..fd744b8 --- /dev/null +++ b/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?