@buresmi7/agent-doc-rules-skill 0.8.1

package/docs/adoption.md

@@ -0,0 +1,144 @@
+# Adoption Guide
+
+Use this guide to add `agent-doc-rules` to an existing repository.
+
+The goal is a small setup:
+
+- one installed skill,
+- a concise `AGENTS.md`,
+- optional documentation checks,
+- a clear update path.
+
+## Install The Skill
+
+Install the published npm package from the repository root:
+
+```bash
+npx @buresmi7/agent-doc-rules-skill
+```
+
+The npm installer creates:
+
+- `.agents/skills/agent-doc-rules/`
+
+It copies only the public skill artifact, not this monorepo's E2E fixtures,
+support scripts, generated maintainer skills, or root docs.
+
+Use a tagged skill directory with the `skills` CLI when the consuming repository
+wants a `skills-lock.json` entry:
+
+```bash
+npx skills add https://github.com/<owner>/<repo>/tree/<tag>/packages/agent-doc-rules-skill --skill agent-doc-rules -a codex -y --copy
+```
+
+For local testing from this repository, install the working tree:
+
+```bash
+npx skills add ./packages/agent-doc-rules-skill --skill agent-doc-rules -a codex -y --copy
+```
+
+The `skills add` path should create:
+
+- `.agents/skills/agent-doc-rules/`
+- `skills-lock.json`
+
+Commit `skills-lock.json`. Do not edit generated skill files by hand unless the
+project intentionally vendors them.
+
+## Add Or Repair AGENTS.md
+
+Ask an agent to create or repair the root instructions:
+
+```text
+Use $agent-doc-rules to create a concise root AGENTS.md for this repository.
+```
+
+For a manual starting point, adapt
+[`../assets/templates/AGENTS.project.md`](../assets/templates/AGENTS.project.md).
+
+A good root `AGENTS.md` should include:
+
+- a short project orientation,
+- links to installed shared rules,
+- local source-of-truth docs,
+- narrow project-specific constraints,
+- verification commands.
+
+## Add Documentation Checks
+
+Install the deterministic validator when the project wants Markdown, security,
+and local link checks:
+
+```bash
+pnpm add -D @agent-doc-rules/docs-validator
+```
+
+Install the duplicate checker when the project also wants semantic overlap
+review:
+
+```bash
+pnpm add -D @agent-doc-rules/docs-duplicates
+```
+
+Add scripts like these:
+
+```json
+{
+  "scripts": {
+    "docs:markdown": "agent-doc-rules-docs markdown",
+    "docs:wording": "agent-doc-rules-docs wording",
+    "docs:security": "agent-doc-rules-docs security",
+    "docs:style": "agent-doc-rules-docs-duplicates style",
+    "docs:links": "agent-doc-rules-docs links",
+    "docs:duplicates": "agent-doc-rules-docs-duplicates check",
+    "docs:check": "agent-doc-rules-docs check && agent-doc-rules-docs-duplicates style && agent-doc-rules-docs-duplicates check"
+  }
+}
+```
+
+For starter config generation, use the `init` command documented in
+[docs-validator](../../docs-validator/README.md). See
+[Config Reference](config-reference.md) for supported keys.
+
+## Verify The Setup
+
+Run the checks that exist in the consuming repository. A common path is:
+
+```bash
+pnpm run docs:check
+```
+
+If the repository does not install the optional tools, ask the agent to name the
+nearest available Markdown, link, or documentation check before finishing docs
+changes.
+
+## Update The Skill
+
+Use the same install command with a newer package version or tag when the
+project wants to update `agent-doc-rules`. For npm installs, run:
+
+```bash
+npx @buresmi7/agent-doc-rules-skill@latest --force
+```
+
+Review the generated diff before committing. If the project uses
+`skills-lock.json`, review the lockfile change as well.
+
+For repositories that use `skills-lock.json`, treat lockfile changes as a review
+point. The lockfile should change only when the project accepts the new skill
+content.
+
+## Distribution Boundary
+
+The published skill artifact contains:
+
+- `SKILL.md`
+- `README.md`
+- `agents/`
+- `assets/`
+- `bin/`
+- `docs/`
+- `references/`
+
+It does not include this monorepo's root maintainer docs, E2E fixtures, support
+scripts, or generated project-scoped maintainer skills.

package/docs/config-reference.md

@@ -0,0 +1,208 @@
+# Config Reference
+
+`agent-doc-rules` documentation tools read `agent-doc-rules.config.json` from
+the repository root by default.
+
+The file may contain a top-level `docs` object:
+
+```json
+{
+  "docs": {
+    "include": ["*.md", "docs/**/*.md", "**/AGENTS.md"],
+    "exclude": ["node_modules/**", ".git/**", "dist/**", "coverage/**"],
+    "links": {
+      "skip": ["^https://example.invalid"],
+      "checkFragments": true
+    },
+    "wording": {
+      "writeGood": {
+        "passive": false,
+        "illusion": false,
+        "weasel": false,
+        "adverb": false,
+        "tooWordy": false,
+        "eprime": false,
+        "fail": false
+      },
+      "forbiddenTerms": [],
+      "allow": ["intentional example"]
+    },
+    "security": {
+      "allow": ["intentional fixture"]
+    },
+    "style": {
+      "includeReferences": false,
+      "maxUnits": 80,
+      "model": "gpt-5-nano",
+      "reasoningEffort": "low"
+    },
+    "duplicates": {
+      "includeReferences": false,
+      "includeSameFile": false,
+      "warnScore": 0.78,
+      "failScore": 0.92,
+      "minWords": 6,
+      "minChars": 40,
+      "maxCandidates": 50,
+      "ignorePairs": [],
+      "model": "gpt-5-nano",
+      "reasoningEffort": "low"
+    }
+  }
+}
+```
+
+CLI flags override config values. Config values override built-in defaults.
+
+## Shared Keys
+
+| Key | Type | Used By | Description |
+| --- | --- | --- | --- |
+| `docs.include` | string array | validator and duplicate checker | Markdown globs to include. |
+| `docs.exclude` | string array | validator and duplicate checker | Globs to ignore. |
+
+Default includes:
+
+```json
+[
+  "*.md",
+  "docs/**/*.md",
+  "**/AGENTS.md",
+  ".agents/skills/**/*.md",
+  "packages/**/*.md",
+  "rules/**/*.md",
+  ".codex/**/*.md"
+]
+```
+
+Default excludes:
+
+```json
+[
+  "node_modules/**",
+  ".git/**",
+  "dist/**",
+  "coverage/**",
+  ".tmp/**",
+  "repos/**",
+  "worktrees/**"
+]
+```
+
+## Link Keys
+
+`docs.links` configures `agent-doc-rules-docs links` and the link phase of
+`agent-doc-rules-docs check`.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `docs.links.include` | string array | Optional include override for link validation. |
+| `docs.links.exclude` | string array | Optional exclude override for link validation. |
+| `docs.links.skip` | string array | Linkinator skip regexes. |
+| `docs.links.checkFragments` | boolean | Whether to validate URL fragments. Defaults to `true`. |
+
+Use `--skip <regex>` for one-off skip patterns and `--no-fragments` when a
+repository has generated anchors the checker cannot resolve.
+
+## Wording Keys
+
+`docs.wording` configures `agent-doc-rules-docs wording` and the wording phase of
+`agent-doc-rules-docs check`.
+
+The validator runs `write-good` with a low-noise default profile. It skips
+fenced code blocks, inline code, and Markdown tables. Optional configured
+wording terms can still fail the check when a project has a phrase it must not
+use.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `docs.wording.include` | string array | Optional include override for wording validation. |
+| `docs.wording.exclude` | string array | Optional exclude override for wording validation. |
+| `docs.wording.writeGood` | object or `false` | `write-good` options. Set `fail: true` to make suggestions fail the command. Set `false` to disable `write-good`. |
+| `docs.wording.forbiddenTerms` | string or object array | Optional project-specific terms that should fail. Objects use `term` and optional `suggest`. |
+| `docs.wording.allow` | string array | Regexes for matching lines that should be ignored. |
+
+The default `write-good` profile disables noisy checks for passive voice,
+adverbs, weasel words, wordy phrases, lexical illusions, and E-Prime. Projects
+can enable any supported `write-good` check in `docs.wording.writeGood`.
+
+## Security Keys
+
+`docs.security` configures `agent-doc-rules-docs security` and the security
+phase of `agent-doc-rules-docs check`.
+
+The validator scans Markdown text and code blocks for high-risk instructions:
+remote code execution, secret disclosure, prompt-injection language, validation
+bypasses, backdoor-style guidance, remote images, tracking links, and encoded
+execution payloads.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `docs.security.include` | string array | Optional include override for security validation. |
+| `docs.security.exclude` | string array | Optional exclude override for security validation. |
+| `docs.security.allow` | string array | Regexes for matching lines that should be ignored. |
+
+Use `docs.security.allow` only for intentional fixture content or safety docs
+that need to show a risky pattern. Prefer rewriting examples so they do not look
+like instructions an agent should execute.
+
+## AI Style Keys
+
+`docs.style` configures `agent-doc-rules-docs-duplicates style`.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `docs.style.include` | string array | Optional include override for AI style review. |
+| `docs.style.exclude` | string array | Optional exclude override for AI style review. |
+| `docs.style.includeReferences` | boolean | Include `references/` directories. Defaults to `false`. |
+| `docs.style.minWords` | number | Minimum words in a sentence unit. |
+| `docs.style.minChars` | number | Minimum characters in a sentence unit. |
+| `docs.style.maxUnits` | number | Maximum sentence units sent to Codex. |
+| `docs.style.model` | string | Codex model for style review. |
+| `docs.style.reasoningEffort` | string | Codex reasoning effort. |
+
+## Duplicate Keys
+
+`docs.duplicates` configures `agent-doc-rules-docs-duplicates check`.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `docs.duplicates.include` | string array | Optional include override for duplicate review. |
+| `docs.duplicates.exclude` | string array | Optional exclude override for duplicate review. |
+| `docs.duplicates.includeReferences` | boolean | Include `references/` directories. Defaults to `false`. |
+| `docs.duplicates.includeSameFile` | boolean | Compare prose units from the same file. Defaults to `false`. |
+| `docs.duplicates.warnScore` | number | Minimum score for warning results. |
+| `docs.duplicates.failScore` | number | Minimum score for failure results. |
+| `docs.duplicates.minWords` | number | Minimum words in a prose unit. |
+| `docs.duplicates.minChars` | number | Minimum characters in a prose unit. |
+| `docs.duplicates.maxCandidates` | number | Maximum candidate pairs sent to Codex. |
+| `docs.duplicates.ignorePairs` | object array | File-pair regexes that should be ignored before AI review. |
+| `docs.duplicates.model` | string | Codex model for classification. |
+| `docs.duplicates.reasoningEffort` | string | Codex reasoning effort. |
+
+The duplicate checker skips code blocks and short noise before it builds
+candidates. It sends only candidate pairs to Codex.
+
+Use `ignorePairs` for expected overlaps such as E2E criteria repeating the rule
+under test or standalone templates sharing boilerplate. Each entry uses `left`
+and `right` regex strings matched against file paths; matching is symmetric.
+
+## Init Command
+
+Create a starter config:
+
+```bash
+agent-doc-rules-docs init
+```
+
+Preview it without writing:
+
+```bash
+agent-doc-rules-docs init --print
+```
+
+Overwrite an existing config only when the project has reviewed the replacement:
+
+```bash
+agent-doc-rules-docs init --force
+```

package/docs/context-placement.md

@@ -0,0 +1,147 @@
+# Context Placement
+
+Use this guide when deciding where project information should live. Agents that
+need only the short rule set should use
+[Documentation Architecture](../references/documentation-architecture.md).
+
+## Core Rule
+
+Put each fact in the smallest durable home that serves the right reader.
+
+If a fact is useful to humans, put it in human docs. If it changes agent
+behavior on every task, put it in `AGENTS.md`. If it describes a repeatable
+agent workflow, put it in a skill.
+
+## Placement Matrix
+
+| Home | Reader | Use For | Avoid |
+| --- | --- | --- | --- |
+| `README.md` | New human contributor | Project purpose, first useful action, canonical docs index, verified commands | Long runbooks, deep architecture, duplicated agent rules |
+| `docs/` | Human maintainer | Architecture, how-to guides, reference, decisions, release notes, troubleshooting | Short routing rules that agents need on every task |
+| `AGENTS.md` | Agent on every task | Local invariants, routing pointers, safety boundaries, verification commands | Long procedures, general documentation, copied reference text |
+| `.agents/skills/<name>/` | Agent on matching task | Repeatable workflows, specialized judgment, bundled templates or scripts | One-off notes, facts humans need first, secrets |
+| `references/` in a skill | Agent after skill triggers | Detailed rules, rubrics, examples, background | Always-needed instructions |
+| `assets/` in a skill | Agent after skill triggers | Templates, examples, reusable output material | Policy prose that should be in references |
+
+## README
+
+Use `README.md` as the human entry point.
+
+It should answer:
+
+- what the project is,
+- who should use it,
+- where the source of truth lives,
+- how to do the first useful action,
+- how to verify common changes.
+
+Move detail out when the README becomes a manual. Link to the nearest canonical
+doc instead of copying content.
+
+When creating more than one durable doc, add a compact canonical-docs section or
+sentence in the README that links to each canonical doc the reader needs first.
+
+Keep rationale, troubleshooting, release steps, and repair procedures out of the
+README unless they are one-line pointers. Put the durable content in `docs/` and
+link to it.
+
+If an inbox note says why a format, workflow, or architecture choice exists,
+the README may summarize that fact, but it must link to a `docs/` explanation or
+architecture page that owns the rationale.
+
+When triaging an inbox file such as `notes.md`, move every durable fact to its
+new canonical home. Then remove the inbox file or replace it with a short pointer
+that names those homes. Do not leave the original facts duplicated in the inbox.
+
+## Docs
+
+Use `docs/` for durable human-facing material.
+
+Good `docs/` content includes:
+
+- architecture decisions,
+- rationale for format or architecture choices,
+- setup details,
+- release procedures,
+- operational runbooks,
+- troubleshooting, including fixture failures and repair steps,
+- command and API reference,
+- explanations of trade-offs.
+
+Choose the document shape deliberately: tutorial, how-to, reference, or
+explanation.
+
+Keep explanation and repair content in `docs/` even when it starts as a short
+note. A format rationale belongs in a dedicated explanation or architecture page
+such as `docs/architecture.md` or `docs/output-format.md`, not as the main prose
+inside a schema, importer, command, or API reference. Put fixture repair notes
+beside the relevant troubleshooting material. `README.md` and reference docs may
+summarize and link to those pages, but should not be their canonical home.
+
+Use this placement even for one-sentence rationale notes. A short reason still
+needs a stable explanation home when the user asks to organize durable notes.
+
+## AGENTS.md
+
+Use `AGENTS.md` for always-loaded agent instructions.
+
+Good `AGENTS.md` content includes:
+
+- project orientation,
+- local constraints,
+- language rules,
+- safety boundaries,
+- links to canonical docs,
+- verification commands agents should know before editing,
+- links to troubleshooting docs when checks fail.
+
+Keep it short. Put troubleshooting procedures in docs or skills and link to
+them. Verification guidance should make skipped checks auditable by recording
+the blocker and what remains unverified.
+
+Do not place fixture-failure procedures directly in `AGENTS.md`; link to the
+troubleshooting or how-to document instead. Include the verification command and
+a short skipped-check note requirement.
+
+## Skills
+
+Use a skill when a repeated agent task needs more than a static instruction.
+
+Strong signals that information belongs in a skill:
+
+- the text says the workflow is repeated,
+- the workflow is meant for a coding agent or AI agent,
+- the workflow has ordered steps, inputs, outputs, and review rules,
+- the workflow needs bundled templates, references, or scripts.
+
+A good skill contains:
+
+- a clear trigger description,
+- a short workflow,
+- detailed references loaded only when needed,
+- templates or scripts when they reduce repeated work.
+
+When creating a skill from an existing README or doc, move the workflow into
+`.agents/skills/<name>/SKILL.md` and leave only a short link from human docs or
+`AGENTS.md`.
+
+When a project gets a new local skill, create or update `AGENTS.md` so agents
+can route to it from always-loaded context. Keep the `AGENTS.md` entry to one or
+two bullets and link to the skill instead of copying the workflow.
+
+Do not create a skill for facts that should be visible to humans first. Do not
+create a skill for one-off project notes or ordinary human runbooks.
+
+When a README contains an ordinary human runbook, move the detailed procedure to
+`docs/` and leave a short README pointer. The fact that a workflow has steps is
+not enough to make it a skill; the workflow must be meant for agents.
+
+## Review Questions
+
+Before adding information, ask:
+
+- Who needs this first: a human, every agent task, or only one agent workflow?
+- Will this fact stay true long enough to document?
+- Is there already a canonical home for it?
+- Would copying this text create two sources of truth?
+- Does this need to be always loaded, or can it be loaded on demand?

package/docs/recipes.md

@@ -0,0 +1,136 @@
+# Recipes
+
+These recipes mirror the behavior protected by the agent E2E scenarios in this
+repository. Use them as examples when applying `agent-doc-rules` to another
+project.
+
+## Create Basic Agent Instructions
+
+Prompt:
+
+```text
+Use $agent-doc-rules to create a concise root AGENTS.md for this repository.
+```
+
+Expected result:
+
+- the file starts with a short project orientation,
+- shared rules are linked instead of copied,
+- local source-of-truth docs are named,
+- verification commands come from local manifests or existing docs.
+
+## Leave Compliant Docs Alone
+
+Prompt:
+
+```text
+Use $agent-doc-rules to review this repository's docs and repair problems.
+```
+
+Expected result:
+
+- no repository diff when the docs are already acceptable,
+- a short note naming the checks or evidence used.
+
+This protects repositories from style-only churn.
+
+## Split A Bloated README
+
+Prompt:
+
+```text
+Use $agent-doc-rules to trim this README and move long-lived detail to the right docs.
+```
+
+Expected result:
+
+- README follows [`readme-rules.md`](../references/readme-rules.md),
+- architecture, operations, and troubleshooting move into `docs/`,
+- stale or unsupported commands are removed.
+
+## Place Notes In Canonical Homes
+
+Prompt:
+
+```text
+Use $agent-doc-rules to triage notes.md into README, docs, AGENTS, or a project skill.
+```
+
+Expected result:
+
+- human orientation moves to README,
+- rationale moves to an explanation or architecture doc,
+- agent-only routing moves to `AGENTS.md`,
+- agent-only workflow detail moves out of the note inbox,
+- the note inbox no longer carries duplicated durable facts.
+
+## Reject Unsupported Documentation Changes
+
+Prompt:
+
+```text
+Use $agent-doc-rules to update the README with the new supported Node.js version.
+```
+
+Expected result when local evidence disagrees:
+
+- no unsupported edit is applied,
+- the response names the conflicting manifest, config, source file, or doc,
+- the maintainer gets the smallest needed fix path.
+
+## Add Nested Agent Overrides
+
+Prompt:
+
+```text
+Use $agent-doc-rules to add directory-specific rules for the importer package.
+```
+
+Expected result:
+
+- root `AGENTS.md` points to the nested file,
+- nested `AGENTS.md` contains only directory-specific rules,
+- root instructions do not copy nested details.
+
+## Preserve Local Language Rules
+
+Prompt:
+
+```text
+Use $agent-doc-rules to rewrite these docs in the repository's required language.
+```
+
+Expected result:
+
+- prose follows the repository language rule,
+- file paths, commands, package names, and code identifiers stay unchanged,
+- the rewrite does not add generic setup or deploy steps.
+
+## Move Human Runbooks To Docs
+
+Prompt:
+
+```text
+Use $agent-doc-rules to clean up this README and AGENTS.md.
+```
+
+Expected result when the project has a human procedure:
+
+- the full runbook moves to a `docs/` how-to,
+- README links to the how-to,
+- `AGENTS.md` keeps only routing, constraints, and checks,
+- no project skill is created unless the workflow is specifically for agents.
+
+## Redact Sensitive Notes
+
+Prompt:
+
+```text
+Use $agent-doc-rules to move useful facts from notes.md into durable docs.
+```
+
+Expected result:
+
+- safe durable facts move to canonical homes,
+- customer names, emails, account IDs, private hosts, and tokens are not copied,
+- the resulting docs name sensitive categories instead of example values.

package/docs/tool-map.md

@@ -0,0 +1,65 @@
+# Tool Map
+
+Use this page to choose the smallest `agent-doc-rules` surface for a task.
+
+| Goal | Use | Why |
+| --- | --- | --- |
+| Create or repair `AGENTS.md` | `$agent-doc-rules` plus [`references/agents-rules.md`](../references/agents-rules.md) | Keeps always-loaded agent context short and local. |
+| Review an `AGENTS.md` file | `$agent-doc-rules` plus [`references/agents-rubric.md`](../references/agents-rubric.md) | Checks routing, scope, duplication, and verification guidance. |
+| Shape a README | `$agent-doc-rules` plus [`references/readme-rules.md`](../references/readme-rules.md) | Keeps the README as a human entry point. |
+| Review a README | `$agent-doc-rules` plus [`references/readme-rubric.md`](../references/readme-rubric.md) | Finds stale commands, missing orientation, placeholders, and overlong sections. |
+| Decide where a fact belongs | [`docs/context-placement.md`](context-placement.md) | Separates README, docs, `AGENTS.md`, skills, references, and templates. |
+| Repair bloated docs | [`references/doc-audit.md`](../references/doc-audit.md) | Moves durable facts to canonical homes and removes duplicated leftovers. |
+| Check factual claims | [`references/factual-review.md`](../references/factual-review.md) | Compares docs against local evidence and rejects unsupported edits. |
+| Review documentation security risks | [`references/security-review.md`](../references/security-review.md) and `agent-doc-rules-docs security` | Finds agent-instruction abuse, data leaks, validation bypasses, and tracking assets. |
+| Tighten prose | [`references/writing-style.md`](../references/writing-style.md) | Removes vague or generic text without inventing workflows. |
+| Check deterministic prose wording | `agent-doc-rules-docs wording` | Runs `write-good` and optional project wording rules against Markdown prose. |
+| Review sentence style | `agent-doc-rules-docs-duplicates style` | Uses Codex to review Markdown sentence units for clarity and plain language. |
+| Validate Markdown, security, and links | `agent-doc-rules-docs` | Runs deterministic Markdown, security, and local-link checks. |
+| Find likely duplicate docs | `agent-doc-rules-docs-duplicates` | Uses deterministic candidates before asking Codex to classify overlap. |
+
+## Command Split
+
+Use the deterministic validator first:
+
+```bash
+agent-doc-rules-docs check
+```
+
+Use duplicate review as a separate semantic gate:
+
+```bash
+agent-doc-rules-docs-duplicates check
+```
+
+The combined project script is usually:
+
+```bash
+pnpm run docs:check
+```
+
+## Agent Prompt Examples
+
+Create instructions:
+
+```text
+Use $agent-doc-rules to create a concise root AGENTS.md for this repository.
+```
+
+Review stale README commands:
+
+```text
+Use $agent-doc-rules to review this README for stale commands and unsupported setup steps.
+```
+
+Place facts from notes:
+
+```text
+Use $agent-doc-rules to move durable facts from notes.md into README, docs, AGENTS, or a project skill.
+```
+
+Run factual review:
+
+```text
+Use $agent-doc-rules to review these docs for contradictions and unsupported claims.
+```