@buresmi7/agent-doc-rules-skill 0.8.1

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@buresmi7/agent-doc-rules-skill",
+  "version": "0.8.1",
+  "private": false,
+  "description": "Agent Skill for concise AGENTS.md, README, and repository documentation rules",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "agent-doc-rules-skill": "bin/install.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "README.md",
+    "SKILL.md",
+    "agents",
+    "assets",
+    "bin",
+    "docs",
+    "references"
+  ],
+  "devDependencies": {
+    "docmd-skills": "1.1.0",
+    "skill-meta-skill": "0.1.0"
+  },
+  "agentDocRules": {
+    "projectSkills": [
+      {
+        "name": "docmd-writer",
+        "source": "docmd-skills"
+      },
+      {
+        "name": "meta-skill",
+        "source": "skill-meta-skill"
+      }
+    ]
+  }
+}

package/references/agents-rubric.md

@@ -0,0 +1,44 @@
+# AGENTS.md Review Rubric
+
+Use this rubric to review a generated or repaired `AGENTS.md`.
+
+## Critical Criteria
+
+- **Purpose:** The opening identifies the repository and what agents must know
+  before changing it.
+- **Routing:** The file points to canonical docs, shared rules, and local skills
+  instead of repeating their details.
+- **Local facts:** Local language, safety, verification, and workflow rules are
+  preserved when supported by repository files.
+- **Concision:** The file stays short enough to scan and avoids full procedures,
+  architecture essays, and command references.
+- **Source of truth:** Canonical files are linked, and conflicts name the file
+  that wins.
+- **Verification:** Required checks are named, and skipped checks require a
+  reason plus remaining-risk note or otherwise make unchecked work explicit.
+- **Truthfulness:** Commands, tools, hosts, issue workflows, and services are not
+  invented or carried forward when unsupported.
+- **Safety:** Secrets, credentials, account IDs, customer data, private hosts,
+  and environment-specific notes are absent.
+- **No shared-rule copies:** Installed shared rules are linked, not pasted into
+  the project file.
+
+## Scoring Guidance
+
+- **Pass:** All critical criteria pass. Minor wording or ordering issues are
+  acceptable.
+- **Review:** One non-critical section is vague, stale, or too long.
+- **Fail:** Any critical criterion fails, or the file invents project facts.
+
+## Reviewer Questions
+
+Ask these questions before accepting the change:
+
+- Could a new agent find the relevant docs and checks in the first scan?
+- Is any rule copied from `.agents/skills/agent-doc-rules/references/`?
+- Does each local rule come from the repository or the user's explicit request?
+- Should any long procedure move to `docs/`, `references/`, or a task-specific
+  skill?
+- Are nested `AGENTS.md` files a better home for directory-specific rules?
+- Is every verification command supported by the repository or clearly labeled
+  as manual or unavailable?

package/references/agents-rules.md

@@ -0,0 +1,89 @@
+# AGENTS.md Rules
+
+Use this rule when creating or maintaining `AGENTS.md` files. For review, also
+use [AGENTS.md review rubric](agents-rubric.md).
+
+## Purpose
+
+`AGENTS.md` is an always-loaded entry point for AI agents. It should provide
+orientation, local invariants, and links to deeper docs.
+
+It is a navigation layer, not full documentation.
+
+## Core Rules
+
+- Keep `AGENTS.md` short enough to scan quickly.
+- Use short sections with bullets and links.
+- Store detailed procedures in `rules/`, `references/`, skills, or component
+  docs.
+- Do not copy shared rules into project `AGENTS.md`; link to the shared rule
+  from a dedicated top-level `Shared Rules` or `Skill Reference` section.
+- Do not put shared-rule links in `Source Of Truth`; that section is for
+  project-owned canonical docs.
+- When repairing a file that already copied shared rules, replace the copied
+  block with a short `Shared Rules` section that links to the installed rule.
+- State local overrides explicitly.
+- Prefer nested `AGENTS.md` files for directory-specific rules.
+- When adding a nested `AGENTS.md`, keep the root file short but point agents to
+  the nested file before they edit that directory. Do not repeat the nested
+  rules in the root file.
+
+## Recommended Root Structure
+
+```markdown
+# Project Name - AI Agent Instructions
+
+Brief project orientation.
+
+## 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 Rules
+
+Project-specific invariants and overrides.
+
+## Source Of Truth
+
+Canonical project docs and decision records.
+
+## Verification
+
+Project-specific validation commands or checks. If a check cannot run, state why
+and document the remaining risk.
+```
+
+## What To Include
+
+- Brief project description.
+- Links to shared rules and project docs.
+- Local language, safety, security, or workflow overrides.
+- Project-specific verification commands.
+- A short rule that makes skipped verification visible. Existing local wording
+  such as "say what remained unchecked" satisfies this; do not rewrite it only
+  to match this reference's preferred wording.
+- Pointers to issue, PR, or proposal conventions.
+
+## What To Avoid
+
+- Long architecture explanations.
+- Full command references.
+- Duplicated text from shared rules.
+- Stale lists that should be generated or linked.
+- Secrets, credentials, host names, or account IDs.
+
+## Local Override Rule
+
+When a project needs to override the shared core, write the override directly
+and narrowly:
+
+```markdown
+## Local Overrides
+
+- Persisted project artifacts are written in Czech.
+- This local language rule overrides the English default in the shared core.
+```
+
+Local overrides should be rare, explicit, and easy to find.

package/references/doc-audit.md

@@ -0,0 +1,58 @@
+# Documentation Audit
+
+Use this reference when repairing existing repository docs, triaging notes, or
+moving facts between README, `AGENTS.md`, `docs/`, and skills.
+
+## Audit Pass
+
+Before editing, make one inventory of durable facts:
+
+| Fact | Source | Canonical home | Action |
+| --- | --- | --- | --- |
+| What the project does | `README.md` | `README.md` | Keep or tighten |
+| Local safety rule | `AGENTS.md` | `AGENTS.md` | Preserve |
+| Long release procedure | `README.md` | `docs/release.md` | Move and link |
+| Repeated agent workflow | `notes.md` | `.agents/skills/<name>/SKILL.md` | Extract |
+
+Use the table as a working note. Do not add it to the repository unless the user
+asked for an audit report.
+
+## Evidence Rules
+
+- Treat manifests, config files, existing docs, and explicit user instructions
+  as evidence.
+- Verify documented commands against manifests such as `package.json` when one
+  exists.
+- When moving procedures into `docs/`, recheck the commands inside the moved
+  text. Unsupported commands must be removed or marked unavailable wherever they
+  land, not only in the README.
+- Do not infer hidden harness commands such as `test:agent`; a script belongs in
+  docs only when the target manifest or user request supports it.
+- Preserve supported project-specific facts even when rewriting the surrounding
+  prose.
+- Remove or label unsupported commands, integrations, hosts, issue workflows, and
+  services.
+- Do not preserve secrets, private host names, customer identifiers, account IDs,
+  tokens, or environment-specific machine notes.
+
+## Placement Decisions
+
+- Keep human orientation and first useful commands in `README.md`.
+- Move long setup, release, repair, and troubleshooting procedures to `docs/`.
+- Keep always-needed agent routing, local invariants, and verification rules in
+  `AGENTS.md`.
+- Move repeated agent workflows with steps, inputs, outputs, or review rules to a
+  task-specific skill.
+- Reduce inbox files such as `notes.md` to a short pointer after durable facts
+  move.
+
+## Final Review
+
+Before finishing, check that:
+
+- compliant files were left unchanged instead of rewritten for style,
+- each moved fact has one canonical home,
+- source files no longer duplicate durable facts,
+- links point from short entry files to the new canonical homes,
+- command guidance is verified or marked as unavailable,
+- skipped checks include a reason and remaining risk.

package/references/documentation-architecture.md

@@ -0,0 +1,63 @@
+# Documentation Architecture
+
+Use this rule when adding or changing project docs, rules, templates, skills,
+or agent instructions. This is the short agent rule set. For the fuller
+placement model and examples, see
+[Context Placement](../docs/context-placement.md).
+
+## Core Rule
+
+Each fact has one canonical home. Other files link to it.
+
+If the same rule needs to appear in more than one place, keep the rule in the
+lowest shared document and link to it from the others.
+
+## Quick Roles
+
+- `README.md`: human entry point and first useful commands.
+- `docs/`: durable human explanations, how-to guides, references, and runbooks.
+- `AGENTS.md`: always-loaded agent routing, invariants, and verification rules.
+- Nested `AGENTS.md`: directory-specific overrides. Root files should link to
+  them, not copy their details.
+- `.agents/skills/<name>/`: repeated task-specific agent workflows.
+- Skill `references/`: detail loaded after a skill triggers.
+- Templates: reusable output material, not policy prose.
+
+## Placement Rules
+
+- Put stable facts near the thing they describe.
+- Put repeated agent workflow behavior in a task-specific skill.
+- Put cross-cutting policy in `rules/`.
+- Put rationale for format or architecture choices in `docs/`, not in the root
+  README. Prefer a dedicated explanation or architecture page such as
+  `docs/architecture.md` or `docs/output-format.md`; do not make a schema,
+  importer, command, or API reference the canonical home for rationale.
+- When triaging notes, any fact framed as a reason, rationale, why, or trade-off
+  should move to that explanation or architecture page. README may link to it,
+  but should not be the only home.
+- Put command reference in `references/`, not in always-loaded docs.
+- Put setup, install, repair, and troubleshooting procedures in the nearest
+  detailed doc or skill reference, not in always-loaded docs or the root README.
+- Put README quality rules in `references/readme-rules.md`; do not copy them into
+  project README files.
+- Put "why this rule exists" near the canonical rule. Use a short decision note
+  when the trade-off matters.
+- Move detail out when an always-loaded section grows past roughly ten lines.
+- Prefer links over copied text.
+
+## Validation
+
+After changing documentation links, run the consuming project's `docs:check` or
+Markdown link check if one exists.
+
+When no automated checker exists, manually verify local relative links in:
+
+- `AGENTS.md`
+- nested `AGENTS.md` files
+- `rules/`
+- `templates/`
+- root documentation
+
+After changing shared rules or agent instructions, review nearby docs for
+semantic duplicates. Remove duplicated prose and leave links to the canonical
+rule.

package/references/factual-review.md

@@ -0,0 +1,108 @@
+# Factual Documentation Review
+
+Use this reference when reviewing repository docs for factual accuracy,
+contradictions, unsupported claims, stale facts, or misleading precision.
+
+## Review Scope
+
+Review claims that a maintainer or reader could act on:
+
+- commands, scripts, package managers, and setup steps,
+- files, paths, modules, generated artifacts, and configuration names,
+- dependencies, integrations, services, hosts, runtimes, and version claims,
+- supported workflows, release steps, deployment steps, and ownership rules,
+- dates, compatibility statements, guarantees, and broad capability claims.
+
+Do not treat style preferences, intent statements, or roadmap language as false
+facts unless the wording presents them as current behavior.
+
+## Evidence Rules
+
+Use the strongest available evidence before making a finding:
+
+1. The user's explicit constraints for this task.
+2. Executable local evidence, such as a command that succeeds or fails.
+3. Repository manifests, source files, config, tests, lockfiles, and generated
+   files.
+4. Canonical documentation inside the repository.
+5. Official external sources for facts that depend on current external
+   behavior.
+6. No evidence found.
+
+Treat absence of local evidence carefully. A missing `package.json` script can
+disprove a documented `npm run <name>` command. A missing dependency does not by
+itself prove that a service is unused unless the claim depends on that
+dependency.
+
+When a fact may have changed outside the repository, verify it with official
+sources or mark it as `stale-risk`. Do not present a guess as a confirmed
+finding.
+
+## Detection Pass
+
+Make one pass over the relevant docs and collect claims. Then compare each claim
+against evidence:
+
+- Compare documented commands with manifests before preserving them.
+- Check that named files, folders, scripts, config keys, and generated outputs
+  exist or are clearly examples.
+- Compare repeated claims across README files, `AGENTS.md`, docs, templates, and
+  skill references.
+- Flag broad claims such as "all", "always", "fully supported", and
+  "production-ready" when the repository only supports a narrower statement.
+- Flag precise version, date, support, or compatibility claims when the evidence
+  is missing or likely stale.
+- Check whether technically true wording could still lead a reader to the wrong
+  action.
+
+## Finding Types
+
+Use these labels consistently:
+
+- `false`: Evidence contradicts the claim.
+- `contradiction`: Two repository docs cannot both be true.
+- `unsupported`: The claim might be true, but the repository does not support
+  it.
+- `misleading`: The claim is technically defensible but likely to send the
+  reader toward the wrong action.
+- `stale-risk`: The claim depends on changing external facts and has not been
+  verified.
+- `overclaim`: The wording is broader or more certain than the evidence allows.
+
+## Severity
+
+- `fail`: A reader would run the wrong command, edit the wrong file, rely on a
+  nonexistent workflow, or accept a direct contradiction.
+- `warn`: The claim is unsupported, stale-prone, or too broad, but the safe
+  correction needs maintainer judgment.
+- `note`: The wording can be clearer or less precise, but the risk is low.
+
+## Report Format
+
+Lead with findings, ordered by severity. Use this structure for each finding:
+
+```text
+- [fail|warn|note] path/to/file.md:line - Short issue
+  Type: false|contradiction|unsupported|misleading|stale-risk|overclaim
+  Claim: The documented claim under review.
+  Evidence: The repo or external evidence used.
+  Impact: What a reader would get wrong.
+  Fix: Remove, narrow, verify, or replace the claim.
+  Confidence: confirmed|likely|needs maintainer confirmation
+```
+
+If there are no findings, say that directly and list the checks performed. If a
+check could not run, state the reason and the remaining risk.
+
+## Repair Rules
+
+When editing instead of only reviewing:
+
+- Do not apply a requested documentation change when local evidence contradicts
+  it. Return a finding instead.
+- Preserve verified project-specific facts.
+- Remove false claims instead of replacing them with invented details.
+- Narrow overclaims to match the evidence.
+- Mark examples as examples when they are not supported project commands.
+- Link to the canonical source instead of copying conflicting text.
+- Keep uncertain claims out of durable docs unless the user confirms them.

package/references/influences.md

@@ -0,0 +1,63 @@
+# Influences And Attribution
+
+This skill uses original wording and repository-specific rules, but its design
+draws on established documentation and agent-skill practices.
+
+## Agent Skill Structure
+
+The skill layout follows the open Agent Skills pattern:
+
+- a short `SKILL.md` entry point,
+- progressive disclosure through `references/`, `assets/`, and optional
+  scripts,
+- task-specific context loaded only when needed.
+
+Influences:
+
+- [Agent Skills specification](https://agentskills.io/specification)
+- [Anthropic Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+
+## Documentation Architecture
+
+The document-type split in `writing-style.md` follows the Diataxis idea that
+documentation should separate tutorials, how-to guides, reference, and
+explanation because those forms answer different reader needs.
+
+Influences:
+
+- [Diataxis](https://diataxis.fr/)
+- [Diataxis in five minutes](https://diataxis.fr/start-here/)
+
+## Plain English
+
+The plain-English rules follow the long-running technical-writing tradition of
+short words, concrete nouns, active voice, and cutting padding. The local rules
+adapt those principles for repository documentation and AI-generated prose.
+
+Influences:
+
+- [George Orwell, "Politics and the English Language"](https://www.orwellfoundation.com/the-orwell-foundation/orwell/essays-and-other-works/politics-and-the-english-language/)
+- [Ernest Gowers, "The Complete Plain Words"](https://plain-words.com/)
+
+## Public Skills Reviewed
+
+The repository also reviewed public skills to understand common patterns for
+documentation writing, plain-English cleanup, skill authoring, and project
+skill management. The final `agent-doc-rules` skill does not vendor those
+skills; it keeps a smaller local rule set tailored to repository documentation
+and agent context architecture.
+
+Useful references included:
+
+- [anthropics/skills](https://github.com/anthropics/skills)
+- [docmd-io/docmd-skills](https://github.com/docmd-io/docmd-skills)
+- [github/awesome-copilot](https://github.com/github/awesome-copilot)
+- [b1rdmania/claude-plain-english-skill](https://github.com/b1rdmania/claude-plain-english-skill)
+
+## Local Meta-Work Workflow
+
+The documentation duplicate-check model comes from the earlier `meta-work`
+maintenance workflow: run deterministic Markdown and link checks first, then
+review only duplicate candidates with an agent. The published skill keeps that
+separation so routine validation stays cheap and semantic review remains
+explicit.

package/references/readme-rubric.md

@@ -0,0 +1,38 @@
+# README Review Rubric
+
+Use this rubric to review a generated or edited `README.md`.
+
+## Critical Criteria
+
+- **Purpose:** The first section clearly says what the repository is and who
+  should use it.
+- **Truthfulness:** Commands, paths, integrations, and technologies are present
+  only when supported by the repository.
+- **Source of truth:** Canonical docs are linked instead of copied.
+- **Proportionality:** The README is no larger than the project needs.
+- **Actionability:** A new contributor can find the first useful action.
+- **Verification:** The README names relevant checks or states that no check is
+  known.
+- **Plain English:** The README uses direct, concrete language and avoids
+  generic AI or marketing phrasing.
+- **Safety:** Secrets, credentials, account IDs, private hosts, and sensitive
+  environment values are absent.
+- **No placeholders:** Empty template sections and fake badges are removed.
+
+## Scoring Guidance
+
+- **Pass:** All critical criteria pass. Minor wording issues are acceptable.
+- **Review:** One non-critical section is vague, stale, or too long.
+- **Fail:** Any critical criterion fails, or the README invents project facts.
+
+## Reviewer Questions
+
+Ask these questions before accepting the change:
+
+- Does the opening paragraph match the actual repository?
+- Are quick-start commands executable in the documented environment?
+- Is any detail duplicated from `AGENTS.md`, `rules/`, skills, or deeper docs?
+- Would a project-specific detail be better placed in a nearby README, runbook,
+  or reference file?
+- Does the README link to deeper docs before it becomes a long manual?
+- Could any sentence be shorter without losing meaning?

package/references/readme-rules.md

@@ -0,0 +1,124 @@
+# README Rules
+
+Use this rule when creating or maintaining a project `README.md`.
+Also apply [Documentation writing style](writing-style.md) for prose,
+structure, and plain-English review.
+
+## Purpose
+
+`README.md` is the human entry point for the repository. It should answer:
+
+- what this project is,
+- who it is for,
+- where the source of truth lives,
+- how to do the first useful action,
+- how to verify changes.
+
+It is not a full architecture document, runbook, changelog, or agent rule file.
+
+## Core Rules
+
+- Start with a concrete project title and a one-paragraph description.
+- State the repository's role before listing commands or internals.
+- Keep setup, usage, verification, and operational notes in separate sections.
+- Put long procedures in the nearest detailed doc and link to them.
+- When an existing README carries a full human runbook, move the procedure into
+  `docs/` and leave a short pointer in the README. Do not convert ordinary
+  human runbooks into agent skills.
+- Prefer tables for indexes, supported targets, commands, and canonical docs.
+- Include commands only when they are known to work.
+- Mark project status, limitations, and safety boundaries explicitly.
+- Keep secrets, account IDs, host-specific values, and private environment notes
+  out of the README.
+- Remove placeholder sections instead of leaving empty boilerplate.
+- Keep the README proportional to the project size.
+
+## Recommended Shape
+
+Use the smallest shape that fits the project:
+
+```markdown
+# Project Name
+
+One short paragraph explaining what this repository is and why it exists.
+
+## Source Of Truth
+
+Links to canonical docs, specs, decisions, or external systems.
+
+## Quick Start
+
+The shortest verified path to a useful result.
+
+## Usage
+
+Common commands, workflows, or examples.
+
+## Verification
+
+Checks to run before publishing changes.
+
+## Project Notes
+
+Constraints, safety boundaries, status, or operational notes.
+```
+
+Do not include a section just because it appears in this shape.
+
+## Source Of Truth
+
+When the repository has multiple docs, add a compact index:
+
+```markdown
+## Canonical Docs
+
+| Document | Content |
+|---|---|
+| `AGENTS.md` | Project-specific agent rules |
+| `README.md` | Project overview and doc index |
+| `docs/development.md` | Local setup and commands |
+| `docs/architecture.md` | Architecture decisions and boundaries |
+```
+
+State which document wins when docs conflict. If another document is canonical
+for a detail, link to it instead of copying its content.
+
+## Commands
+
+Command sections should be evidence-oriented:
+
+- Use fenced code blocks for commands.
+- Group commands by workflow.
+- Say where commands run when that matters.
+- Avoid commands that depend on private local state unless the README explains
+  the prerequisite.
+- If a command is intentionally illustrative, label it as an example.
+- Do not add generic install or setup steps just because a README has a test
+  command. A setup step needs evidence from the existing docs, the user request,
+  or a local manifest.
+- When a manifest such as `package.json` exists, treat its scripts as the
+  command source of truth. Do not preserve stale README commands that are absent
+  from the manifest unless the documentation clearly labels them as unverified
+  or external.
+- When moving a README runbook into `docs/`, recheck every moved command against
+  the manifest. Do not leave unsupported commands as actionable setup, release,
+  troubleshooting, or repair steps in the new doc.
+- Do not infer hidden test harness or agent-runner scripts such as `test:agent`.
+  Document them only when they are visible in the target manifest and relevant
+  to the README's audience.
+
+## What To Avoid
+
+- Marketing copy that does not help a contributor operate the project.
+- Install or test commands that have not been verified.
+- Generic package-manager instructions that are not supported by local
+  evidence.
+- Full architecture explanations that belong in `docs/`.
+- Duplicated rules from `AGENTS.md`, skills, or shared rule files.
+- Long troubleshooting sections that belong in `references/` or runbooks.
+- Placeholder badges, empty sections, and future-tense promises.
+
+## Review
+
+Use [README review rubric](readme-rubric.md) when reviewing a README generated
+or edited by an agent.