@buresmi7/agent-doc-rules-skill 0.8.1

package/README.md

@@ -0,0 +1,250 @@
+# Agent Doc Rules Skill
+
+`agent-doc-rules` is an Agent Skill for repository documentation and agent
+context architecture.
+
+Use it when a project needs to decide what belongs in human documentation, what
+belongs in always-loaded agent instructions, and what should become a
+task-specific skill for agents.
+
+## What It Does
+
+- Keeps `AGENTS.md` short, local, and useful for agent routing.
+- Shapes `README.md` as a human entry point, not a full manual.
+- Separates long-lived docs from task-specific agent workflows.
+- Reviews repository docs for false, contradictory, unsupported, stale, or
+  misleading claims.
+- Reviews agent-facing docs for data leaks, prompt-injection language,
+  validation bypasses, and backdoor-style guidance.
+- Applies plain-English writing rules to repository documentation.
+- Uses progressive disclosure so detailed rules live in references, not in the
+  always-loaded skill entry point.
+
+## Install
+
+Install from npm into the current Codex project:
+
+```bash
+npx @buresmi7/agent-doc-rules-skill
+```
+
+Replace an existing project install:
+
+```bash
+npx @buresmi7/agent-doc-rules-skill install --force
+```
+
+The npm installer copies only the skill artifact into
+`.agents/skills/agent-doc-rules/`. It does not copy this monorepo's E2E
+fixtures, support scripts, generated maintainer skills, or root docs.
+
+Install a tagged skill directory with the `skills` CLI when a consuming project
+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
+```
+
+Install the local working tree for development:
+
+```bash
+npx skills add ./packages/agent-doc-rules-skill --skill agent-doc-rules -a codex -y --copy
+```
+
+For project-scoped Codex installs, the skill is installed under
+`.agents/skills/agent-doc-rules/`.
+
+Install optional documentation validation tools:
+
+```bash
+pnpm add -D @agent-doc-rules/docs-validator @agent-doc-rules/docs-duplicates
+```
+
+Recommended scripts:
+
+```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"
+  }
+}
+```
+
+## Usage
+
+Ask the agent to use the skill by name.
+
+Main examples:
+
+```text
+Use $agent-doc-rules to create a concise root AGENTS.md for this repository.
+```
+
+```text
+Use $agent-doc-rules to review this README for stale commands and duplicated rules.
+```
+
+```text
+Use $agent-doc-rules to review these docs for factual accuracy, contradictions,
+and unsupported claims.
+```
+
+```text
+Use $agent-doc-rules to decide whether this note belongs in README.md,
+AGENTS.md, docs/, or a task-specific skill.
+```
+
+```text
+Use $agent-doc-rules to add a project-specific documentation overlay.
+```
+
+Common tasks:
+
+- create or repair `AGENTS.md`,
+- write or review a README,
+- decide whether information belongs in docs, `AGENTS.md`, or a skill,
+- add a project-specific documentation overlay,
+- review agent-facing docs for security risks,
+- review docs for factual accuracy, plain English, and duplicated rules.
+
+## Adoption And Tools
+
+- [Adoption Guide](docs/adoption.md) shows the smallest setup for consuming
+  repositories.
+- [Tool Map](docs/tool-map.md) maps common documentation tasks to the right
+  skill reference or CLI.
+- [Config Reference](docs/config-reference.md) documents
+  `agent-doc-rules.config.json`.
+- [Recipes](docs/recipes.md) gives before-and-after patterns based on the E2E
+  scenarios.
+
+## Feature Guide
+
+- [Agent Instructions](#agent-instructions)
+- [README Shaping](#readme-shaping)
+- [Documentation Placement](#documentation-placement)
+- [Documentation Repair](#documentation-repair)
+- [Factual Documentation Review](#factual-documentation-review)
+- [Documentation Security Review](#documentation-security-review)
+- [Plain-English Cleanup](#plain-english-cleanup)
+- [Validation Tools](#validation-tools)
+- [Starter Templates](#starter-templates)
+- [Adoption Docs](#adoption-docs)
+
+### Agent Instructions
+
+Create or repair `AGENTS.md` files so agents get a brief project orientation,
+short routing rules, local constraints, nested instruction pointers, and
+verification commands. The detailed rules live in
+[`references/agents-rules.md`](references/agents-rules.md), with review checks
+in [`references/agents-rubric.md`](references/agents-rubric.md).
+
+### README Shaping
+
+Keep README files useful as human entry points. The skill trims runbooks,
+removes stale commands, and links to deeper docs instead of copying detail into
+the README. See [`references/readme-rules.md`](references/readme-rules.md) and
+[`references/readme-rubric.md`](references/readme-rubric.md).
+
+### Documentation Placement
+
+Decide whether a fact belongs in `README.md`, `docs/`, `AGENTS.md`, a skill,
+or a skill reference. The compact rule set is
+[`references/documentation-architecture.md`](references/documentation-architecture.md);
+the fuller guide is [`docs/context-placement.md`](docs/context-placement.md).
+
+### Documentation Repair
+
+Move bloated, stale, duplicated, or inbox-style documentation into the right
+canonical home. The audit workflow lives in
+[`references/doc-audit.md`](references/doc-audit.md).
+
+### Factual Documentation Review
+
+Check documentation claims against project evidence before editing. If a
+requested change conflicts with local manifests, source files, configs, tests,
+or canonical docs, the skill tells the agent to report the conflict instead of
+writing unsupported text. See
+[`references/factual-review.md`](references/factual-review.md).
+
+### Documentation Security Review
+
+Review agent-facing docs as instructions that can influence future edits. The
+security checklist covers data exfiltration, remote execution, credential
+handling, prompt-injection language, validation bypasses, backdoor-style
+guidance, remote tracking assets, and encoded payloads. See
+[`references/security-review.md`](references/security-review.md).
+
+### Plain-English Cleanup
+
+Rewrite repository documentation in direct, specific language. The skill cuts
+padding, avoids generic AI phrasing, and keeps the reader's task first. See
+[`references/writing-style.md`](references/writing-style.md).
+
+### Validation Tools
+
+Use the optional CLIs to check Markdown, deterministic prose wording,
+deterministic security patterns, AI sentence style, local links, and likely
+duplicate documentation passages. Duplicate review supports
+`docs.duplicates.ignorePairs` for narrow, documented overlaps such as E2E
+criteria repeating the rule under test. The validation guidance lives in
+[`references/validation.md`](references/validation.md).
+
+### Starter Templates
+
+Start new agent instruction files from the templates in
+[`assets/templates/`](assets/templates/) instead of copying unrelated project
+rules.
+
+### Adoption Docs
+
+Use the product docs when rolling the skill into another repository:
+
+- [Adoption Guide](docs/adoption.md)
+- [Tool Map](docs/tool-map.md)
+- [Config Reference](docs/config-reference.md)
+- [Recipes](docs/recipes.md)
+
+## Context Placement
+
+Context placement decides the durable home for each project fact.
+
+Use:
+
+- `README.md` for human orientation and first useful commands,
+- `docs/` for long-lived explanations, how-to guides, references, and runbooks,
+- `AGENTS.md` for short always-loaded agent routing and local invariants,
+- `.agents/skills/<name>/` for repeated task workflows that agents should load
+  only when relevant,
+- `references/` inside a skill for detailed rules loaded on demand,
+- `assets/` inside a skill for templates and reusable output material.
+
+See [Context Placement](docs/context-placement.md) for the full model.
+
+## Influences
+
+See [Influences And Attribution](references/influences.md) for attribution,
+design influences, and duplicate-review provenance.
+
+## Development
+
+From the monorepo root:
+
+```bash
+corepack pnpm install
+corepack pnpm run skills:sync
+corepack pnpm run test:install
+corepack pnpm test
+```
+
+Run agent E2E tests only when an agent runner is configured:
+
+```bash
+corepack pnpm run test:agent
+```

package/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: agent-doc-rules
+description: Maintain repo-level AGENTS.md, README.md, docs placement, factual review, and agent workflow extraction. Use for agent docs, documentation architecture, plain-English repository documentation, overlays, and stale-doc repair; do not use as a general product-doc writer.
+---
+
+# Agent Doc Rules
+
+Use this skill to keep repository instructions and documentation small,
+canonical, plain, and easy for agents and people to use.
+
+## Workflow
+
+1. Inspect the repository before editing. Identify existing `AGENTS.md`,
+   `README.md`, docs, templates, local overrides, and verification commands.
+2. Load only the references needed for the task:
+   - For `AGENTS.md`, read [references/agents-rules.md](references/agents-rules.md).
+   - For `AGENTS.md` reviews, also read
+     [references/agents-rubric.md](references/agents-rubric.md).
+   - For documentation writing, rewriting, or style cleanup, read
+     [references/writing-style.md](references/writing-style.md).
+   - For README work, read
+     [references/readme-rules.md](references/readme-rules.md) and
+     [references/writing-style.md](references/writing-style.md). If the README
+     carries a long runbook or procedure, also read
+     [docs/context-placement.md](docs/context-placement.md) and
+     [references/doc-audit.md](references/doc-audit.md).
+   - For README reviews, also read
+     [references/readme-rubric.md](references/readme-rubric.md).
+   - For documentation placement, canonical homes, or skill/template structure,
+     read [docs/context-placement.md](docs/context-placement.md) and
+     [references/documentation-architecture.md](references/documentation-architecture.md).
+   - For repairing bloated docs, moving inbox notes, or auditing duplicated
+     durable facts, read [references/doc-audit.md](references/doc-audit.md).
+   - For factual accuracy, contradictions, unsupported claims, stale facts, or
+     misleading documentation review, read
+     [references/factual-review.md](references/factual-review.md).
+   - For documentation security review, agent-instruction abuse, secret
+     exfiltration risks, or backdoor-style guidance, read
+     [references/security-review.md](references/security-review.md).
+   - For documentation validation or duplicate checks, read
+     [references/validation.md](references/validation.md).
+3. When starter content is useful, adapt the templates in
+   [assets/templates/](assets/templates/) instead of copying unrelated prose.
+4. Keep each reusable rule in one canonical file. Link to canonical rules from
+   other files instead of duplicating them.
+5. Preserve project-specific facts from the consuming repository, but do not
+   invent or carry forward unsupported workflows, tools, services, hosts, issue
+   processes, or commands. When a manifest such as `package.json` exists, use it
+   to verify documented scripts. Do not infer hidden harness commands such as
+   `test:agent` unless they are visible in the target project manifest and
+   relevant to the user's task.
+6. Before finishing README, `AGENTS.md`, docs, skill, reference, or template
+   changes, run or name the repository's relevant Markdown, link, or
+   documentation checks. Prefer `npm run docs:check` when it exists. If a check
+   cannot run, state why and the residual risk.
+
+For context-placement or notes-triage tasks, make one pass over every source
+fact and assign it to a canonical home:
+
+- `README.md` for project purpose, first useful command, and a compact docs
+  index.
+- `docs/` reference pages for schemas, commands, APIs, and contracts.
+- `docs/` explanation or architecture pages for rationale and trade-offs.
+- `docs/` how-to or troubleshooting pages for fixture failures and repair
+  steps.
+- `AGENTS.md` for short routing, local invariants, verification commands, and
+  the skipped-check residual-risk rule.
+- The original inbox file, such as `notes.md`, should be removed or reduced to a
+  short pointer after durable facts move.
+
+For design influences and attribution, see
+[references/influences.md](references/influences.md).
+
+## Output Rules
+
+- Keep always-loaded agent instructions concise and scannable.
+- If existing docs already satisfy the task, make no file changes. Do not
+  rewrite compliant docs for style-only normalization.
+- Do not rewrite supported local skipped-check wording only to match this
+  skill's preferred phrasing.
+- Write repository docs in plain, concrete English unless the consuming
+  repository sets a different language rule.
+- When creating or repairing `AGENTS.md`, put
+  `.agents/skills/agent-doc-rules/references/agents-rules.md` in a dedicated
+  top-level `Shared Rules` or `Skill Reference` section. Do not copy the
+  referenced rule text, and do not bury the shared-rule link under
+  `Source Of Truth`.
+- Root `AGENTS.md` files should start with a brief project orientation from the
+  local README or manifest, not only generic section headings.
+- When creating a nested `AGENTS.md`, add a short root `AGENTS.md` pointer that
+  names the nested file path and says when agents should read it.
+- Keep troubleshooting, setup, release, and repair procedures in human docs;
+  put only routing links and short invariants in `AGENTS.md`.
+- When simplifying existing docs, do not add generic setup, install, test,
+  deployment, or package-manager steps unless the source docs, user request, or
+  local manifests support them.
+- Move ordinary human runbooks to `docs/` and link to them; do not turn them
+  into task-specific skills unless they are repeated agent workflows.
+- For documentation placement tasks, put rationale and trade-off explanations in
+  durable `docs/` explanation or architecture files, not only in `README.md` and
+  not in schema, importer, command, or API reference pages. Even a one-sentence
+  reason needs a `docs/` owner; `README.md` may summarize and link. Put fixture
+  failure or repair steps in `docs/` how-to or troubleshooting files. Keep
+  `README.md`, reference docs, and `AGENTS.md` to short pointers for those
+  details.
+- During notes triage, treat facts introduced as a reason, rationale, why, or
+  trade-off as explanation content. Create or update a `docs/` explanation or
+  architecture page for that content instead of leaving the README as the only
+  home.
+- When project notes describe a repeated workflow meant for agents, create or
+  update a task-specific `.agents/skills/<name>/SKILL.md` and link to it instead
+  of storing the full workflow in the README or `AGENTS.md`.
+- When adding a project skill, create or update `AGENTS.md` with a short routing
+  pointer to that skill; do not copy the full workflow there.
+- When adding verification guidance, include the command or check and state that
+  skipped checks need a reason and residual-risk note.
+- When a repository exposes `docs:check`, prefer it for README, `AGENTS.md`,
+  docs, skill, reference, and template changes.
+- Put detailed procedures in references, docs, runbooks, or task-specific
+  skills.
+- When moving facts out of an inbox file such as `notes.md`, remove that inbox
+  file or reduce it to a short pointer; do not leave duplicated durable facts
+  behind.
+- Make local overrides explicit, narrow, and easy to find.
+- Keep persisted content in the language required by the consuming repository.
+- Do not include secrets, real customer names, emails, account IDs, private host
+  names, tokens, or environment-specific notes in reusable docs. When source
+  notes contain sensitive examples, keep only a short safety rule that names the
+  sensitive categories to avoid.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent Doc Rules"
+  short_description: "Repo docs, AGENTS.md, factual review, and context placement rules"
+  default_prompt: "Use $agent-doc-rules to review or repair concise, factual repository documentation."

package/assets/templates/AGENTS.overlay.md

@@ -0,0 +1,35 @@
+# Local Agent Rules Overlay
+
+Use this template when a project consumes `agent-doc-rules` but needs local
+rules that are not reusable across repositories.
+
+## Shared Core
+
+This project installs `agent-doc-rules` at:
+
+```text
+.agents/skills/agent-doc-rules/
+```
+
+`skills-lock.json` records the source. Shared rules apply unless this file
+states a narrower local override.
+
+## Shared Rules
+
+- AGENTS.md rules: `.agents/skills/agent-doc-rules/references/agents-rules.md`
+- README rules: `.agents/skills/agent-doc-rules/references/readme-rules.md`
+- Documentation architecture: `.agents/skills/agent-doc-rules/references/documentation-architecture.md`
+
+## Local Overrides
+
+- Add language, security, workflow, or phase constraints specific to this
+  project.
+- Keep overrides explicit and avoid copying shared rules.
+
+## Project Sources Of Truth
+
+- Add canonical docs, specifications, decision logs, or issue templates.
+
+## Project Verification
+
+- Add project-specific test, lint, validation, or manual review steps.

package/assets/templates/AGENTS.project.md

@@ -0,0 +1,31 @@
+# Project Name - AI Agent Instructions
+
+Briefly describe what this repository contains and what agents should keep in
+mind before making changes.
+
+## Shared Rules
+
+- AGENTS.md rules: `.agents/skills/agent-doc-rules/references/agents-rules.md`
+- README rules: `.agents/skills/agent-doc-rules/references/readme-rules.md`
+- Documentation architecture: `.agents/skills/agent-doc-rules/references/documentation-architecture.md`
+
+## Local Overrides
+
+- Add project-specific rules that override the shared core.
+- Keep each override narrow and explicit.
+
+## Source Of Truth
+
+- Link to the canonical project specification, architecture docs, decision log,
+  or README.
+- State which document wins when local docs conflict.
+
+## Project Constraints
+
+- Add safety, security, phase, or workflow constraints that are specific to this
+  repository.
+
+## Verification
+
+- List project-specific checks that should be run before finishing changes.
+- Add the local reporting rule for checks that cannot run.

package/bin/install.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { cp, mkdir, readFile, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const defaultTarget = join(process.cwd(), '.agents', 'skills', 'agent-doc-rules');
+const skillEntries = [
+  'SKILL.md',
+  'README.md',
+  'agents',
+  'assets',
+  'docs',
+  'references',
+];
+
+await main().catch((error) => {
+  console.error(`agent-doc-rules-skill: ${error.message}`);
+  process.exit(1);
+});
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    console.log(usage());
+    return;
+  }
+
+  const target = resolve(process.cwd(), options.target ?? defaultTarget);
+  assertSafeTarget(target);
+
+  const packageJson = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+  const existingTarget = await stat(target).catch((error) => {
+    if (error?.code === 'ENOENT') {
+      return undefined;
+    }
+
+    throw error;
+  });
+
+  if (existingTarget && !existingTarget.isDirectory()) {
+    throw new Error(`Target exists but is not a directory: ${target}`);
+  }
+
+  if (existingTarget && !options.force) {
+    throw new Error(`Target already exists: ${target}\nRe-run with --force to replace it.`);
+  }
+
+  if (options.dryRun) {
+    console.log(`Would install ${packageJson.name}@${packageJson.version} to ${target}`);
+    console.log(`Entries: ${skillEntries.join(', ')}`);
+    return;
+  }
+
+  if (existingTarget) {
+    await rm(target, { recursive: true, force: true });
+  }
+
+  await mkdir(target, { recursive: true });
+
+  for (const entry of skillEntries) {
+    await cp(join(packageRoot, entry), join(target, entry), { recursive: true });
+  }
+
+  console.log(`Installed ${packageJson.name}@${packageJson.version} to ${target}`);
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const options = {
+    dryRun: false,
+    force: false,
+    help: false,
+    target: undefined,
+  };
+
+  if (args[0] === 'install') {
+    args.shift();
+  }
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--force' || arg === '-f') {
+      options.force = true;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--target' || arg === '-t') {
+      const value = args[index + 1];
+
+      if (!value) {
+        throw new Error(`${arg} requires a path value`);
+      }
+
+      options.target = value;
+      index += 1;
+    } else if (arg.startsWith('--target=')) {
+      options.target = arg.slice('--target='.length);
+    } else {
+      throw new Error(`Unknown argument: ${arg}\n\n${usage()}`);
+    }
+  }
+
+  return options;
+}
+
+function assertSafeTarget(target) {
+  if (basename(target) !== 'agent-doc-rules') {
+    throw new Error('Target directory must be named agent-doc-rules.');
+  }
+}
+
+function usage() {
+  return [
+    'Usage: agent-doc-rules-skill [install] [options]',
+    '',
+    'Installs the agent-doc-rules skill into the current project.',
+    '',
+    'Options:',
+    '  -t, --target <path>  Target skill directory. Defaults to .agents/skills/agent-doc-rules',
+    '  -f, --force          Replace an existing target directory',
+    '      --dry-run        Show what would be installed without writing files',
+    '  -h, --help           Show this help',
+  ].join('\n');
+}