yeaight7 avatar

documentation-systems

Documentation architecture, API reference authoring, ADR writing, readme hardening, and doc quality.

version
0.6.3
GitHub stars
9

Install

/plugin install documentation-systems@agent-powerups

Run it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.

Contents

Discovered from source

Skills 9

Human-AI Document Standard (HADS)


AI READING INSTRUCTION

This skill teaches the agent how to read, generate, and validate HADS documents. Read all [SPEC] blocks before responding to any HADS-related request. Read [NOTE] blocks if you need context on intent or edge cases.


1. WHAT IS HADS

[SPEC]

  • HADS = Human-AI Document Standard
  • Convention for Markdown technical documentation
  • Four block types: **[SPEC]**, **[NOTE]**, **[BUG]**, **[?]**
  • Every HADS document requires: H1 title, version declaration, AI manifest
  • AI manifest appears before first content section, tells AI what to read/skip
  • File extension: .md — standard Markdown, no tooling required

2. BLOCK TYPES

[SPEC]

**[SPEC]**   Authoritative fact. Terse. Bullet lists, tables, code. AI reads always.
**[NOTE]**   Human context, history, examples. AI may skip.
**[BUG]**    Verified failure + fix. Required fields: symptom, cause, fix. Always read.
**[?]**      Unverified / inferred. Lower confidence. Always flagged.

Block tag rules:

  • Bold, on its own line: **[SPEC]**
  • Content follows immediately (no blank line between tag and content)
  • Multiple blocks of different types allowed per section
  • Titled BUG blocks allowed: **[BUG] Short description**
  • No nesting of blocks inside blocks

3. REQUIRED DOCUMENT STRUCTURE

[SPEC]

# Document Title
**Version X.Y.Z** · Author · Date · [metadata]

---

## AI READING INSTRUCTION

Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified — treat with lower confidence.

---

## 1. First Section

**[SPEC]**
...

Required elements in order:

  1. H1 title
  2. Version block in header
  3. AI manifest section before first content section
  4. Content sections (H2), subsections (H3)

4. HOW AI READS HADS

[SPEC] When encountering a HADS document:

  1. Find and read the AI manifest first
  2. Read all [SPEC] blocks — these are ground truth
  3. Read all [BUG] blocks — always, before generating any code or config
  4. Read [NOTE] blocks only if [SPEC] is insufficient to answer the query
  5. Treat [?] content as hypothesis — note uncertainty in response

Token optimization: for large documents, scan section headings first, then read only [SPEC] and [BUG] blocks in relevant sections.


5. HOW TO GENERATE HADS

[SPEC] When asked to write documentation in HADS format:

  1. Start with header block (title, version, metadata)
  2. Add AI manifest — always include, never skip
  3. Organize content into numbered H2 sections
  4. For each fact: write as [SPEC] — terse, bullet or table or code
  5. For each "why" or context: write as [NOTE]
  6. For each known failure mode with confirmed fix: write as [BUG]
  7. For each unverified claim: write as [?]
  8. End with changelog section

Content rules for [SPEC]:

  • Prefer bullet lists over prose
  • Prefer tables for multi-field facts
  • Prefer code blocks for syntax, formats, examples
  • Maximum 2 sentences of prose — if more needed, move to [NOTE]

Content rules for [BUG]:

  • Always include: symptom, cause, fix
  • Optional: affected versions, workaround
  • Title on same line: **[BUG] Short description**

[NOTE] When converting existing documentation to HADS: extract facts into [SPEC], move narrative and history to [NOTE], surface all known issues as [BUG]. Do not duplicate content between block types.


6. VALIDATION RULES

[SPEC] A valid HADS document must have:

  • H1 title
  • Version in header
  • AI manifest before first content section
  • All block tags bold
  • [BUG] blocks contain at minimum symptom + fix

7. DESIGN INTENT

[NOTE] HADS exists because AI models increasingly read documentation before humans do. The format optimizes for this reality without sacrificing human readability.

Key insight: the AI manifest is the core innovation. It lets the model know what to read and what to skip — without requiring it to reason about document structure. Explicit is better than implicit for model consumption.

Purpose

Outdated API documentation causes integration failures. The code is the source of truth, and the docs must match. Review the docs against the actual route handlers and fix mismatches immediately — do not defer.

When to Use

  • A PR adds or modifies routes, request/response types, or error handling
  • Consumers report behavior that contradicts the documented API
  • Before publishing or versioning an OpenAPI/Swagger spec

Inputs

  • The API documentation (OpenAPI/Swagger spec, or inline route docs)
  • The route handler source, types/validation schemas, and API tests

Workflow

  1. Inventory both sides. List documented endpoints and implemented routes, then diff the two lists:

    rg -n "^  /" openapi.yaml                                   # documented paths
    rg -n "router\.(get|post|put|patch|delete)\(" src/          # implemented routes
    git diff --name-only origin/main...HEAD -- "src/routes/"    # what changed recently
    
  2. Verify each endpoint (e.g., POST /users) against its route definition: path, method, and auth requirements — route middleware vs the documented security scheme.

  3. Verify parameters. All required request parameters (body, query, params) must be documented with correct types. Compare against the handler's validation schema or type definitions, not against the old doc.

  4. Verify responses. All possible response status codes (200, 400, 404, 500) and their payloads must match the actual error handlers and return statements:

    rg -n "res\.status\(|throw new .*Error" src/routes/   # codes actually produced
    
  5. Cross-check examples against tests. Documented request/response examples should match what the API tests actually send and assert.

  6. Fix immediately. If there is a mismatch, update the OpenAPI spec or inline documentation now. Do not defer it.

Output

  • Per-endpoint verdict: documented vs actual (path, method, auth, params, status codes, examples)
  • Spec/doc fixes applied, or a mismatch list with file:line where fixing needs owner input

Verification

  • Every changed route compared against its documented endpoint
  • Parameter names, types, and required flags match the handler's validation
  • Documented status codes match the codes actually returned or thrown
  • Auth requirements per endpoint match the route middleware
  • No mismatch deferred — fixed or explicitly escalated

Failure Modes

  • Doc-first trust — assuming the spec is right; the code is the source of truth.
  • Happy-path-only review — checking 200 responses while error codes drift unchecked.
  • Silent auth drift — an endpoint gains an auth requirement the docs never mention.
  • Deferred fixes — "will update the spec later" is how the drift started.

Purpose

Code tells you how a system works. ADRs tell you why it works that way, preventing future maintainers (and AI agents) from suggesting "improvements" that were already tried and discarded.

When to Use

  • Finalizing a major design decision (e.g., "Choosing Postgres over MongoDB", "Using custom event bus over Redis")
  • Reversing or superseding a previous decision
  • A reviewer or agent proposes a change that contradicts an existing constraint

Inputs

  • The decision, the alternatives considered, and the constraints that drove it
  • The ADR directory (conventionally docs/adr/)

Workflow

  1. Check for an existing ADR first — the decision may already be recorded or superseded:

    ls docs/adr/                          # existing records
    rg -ln "<topic keyword>" docs/adr/    # is this decision already covered?
    
  2. Create the record at docs/adr/YYYY-MM-DD-<short-title>.md — date-prefixed for ordering, kebab-case title.

  3. Fill the structure — keep it under 300 words; focus on constraints, not theory:

    # <Decision title>
    
    ## Status
    Accepted | Superseded by <newer ADR filename>
    
    ## Context
    What is the problem? What constraints apply?
    
    ## Decision
    What are we doing?
    
    ## Consequences
    What trade-offs are we accepting? What becomes harder?
    
  4. Handle supersession explicitly. When reversing a decision, do NOT edit history: write a new ADR, mark the old one "Superseded by" with a link to the new file, and state what changed.

  5. Link from where the decision bites — a one-line pointer near the affected module or in the architecture doc, so the why is discoverable from the how.

Output

  • A dated ADR file with Status / Context / Decision / Consequences
  • Superseded ADRs updated with forward links — never deleted or rewritten

Verification

  • File saved under docs/adr/ with a date-prefixed kebab-case name
  • Status, Context, Decision, and Consequences sections all present; body under ~300 words
  • Consequences state real trade-offs, not just benefits
  • Superseded decisions marked and forward-linked, not edited or removed
  • Decision discoverable from the affected code or architecture doc

Failure Modes

  • Retroactive rewriting — editing an old ADR to match a new decision destroys the historical why; supersede instead.
  • Theory essays — pages of architecture philosophy nobody reads; constraints fit in 300 words.
  • Consequence-free records — a Decision without trade-offs is advocacy, not a record.
  • Orphaned ADRs — records nobody can find from the code they govern.

Purpose

Large centralized documentation files consume too much context window. Decentralized, module-specific context docs provide targeted information exactly when an agent needs it.

When to Use

  • A module's boundaries or invariants keep being rediscovered the hard way
  • Onboarding or agent sessions repeatedly ask the same questions about a subsystem
  • After a refactor changed how a module communicates with the rest of the app

Inputs

  • The subsystem directory and its public interface
  • Existing docs, to avoid duplicating the central README or architecture docs

Workflow

  1. Decide where the context belongs. Module-specific knowledge goes in a context file inside the subsystem directory (e.g., src/auth/CONTEXT.md); repo-wide knowledge belongs in the central README or architecture docs — one home per fact, never both:

    find src -iname "CONTEXT.md" -o -iname "README.md"   # existing context docs
    rg -ln "<module name>" docs/                         # already documented centrally?
    
  2. Document only the boundaries. How does this module communicate with the rest of the app? What are its critical invariants? Not implementation detail the code already states.

  3. Keep it terse. Bullet points and exact file paths. No transient notes — session state, TODO lists, and progress logs belong in handoff documents, not context docs.

  4. Validate every path the doc references:

    rg -no "src/[A-Za-z0-9_./-]+" src/auth/CONTEXT.md | sort -u   # referenced paths
    test -f src/auth/session.ts && echo OK                        # confirm each exists
    
  5. Update these files inline when refactoring the module. A context doc that lags the refactor is worse than none.

Output

  • A short, boundary-focused context file inside the subsystem directory
  • Stale or central-doc-duplicating content removed or relocated

Verification

  • Doc lives inside the subsystem it describes
  • Content is boundaries and invariants, not implementation detail or transient notes
  • Every referenced file path verified to exist
  • No duplication of central docs — one home per fact
  • Doc updated in the same change set as the refactor that affected it

Failure Modes

  • Context dumping — pasting session notes or progress logs into a context doc; that is a handoff, not context.
  • Central duplication — the same fact in the central README and the module doc, guaranteed to diverge.
  • Path rot — referenced files moved since the doc was written; validate paths on every touch.
  • Novel-length context — if it doesn't fit on a screen, agents won't load it when they need it.

Context Retrieval Loop (Documentation)

Gather documentation context before writing or updating docs. Prevents duplicating existing content or violating project conventions.

When to Use

  • About to write a new doc, README section, or ADR
  • Updating existing documentation and unsure of scope
  • Spawning a documentation subagent that needs file context

The 3-Cycle Loop

Cycle 1 — Broad Search

# Find existing docs
find . -name "*.md" -not -path "*/node_modules/*" | head -30
rg "<topic>" docs/ *.md -l 2>/dev/null

Stop here if you find the existing doc that covers this topic.

Cycle 2 — Source and Existing Docs

Read the source files the docs will describe. Find existing docs for the same area:

rg "<module-name>" docs/ -l
cat README.md | head -60

Stop here if you understand the scope of what needs to be written or updated.

Cycle 3 — Conventions and Setup

ls docs/ .github/ 2>/dev/null
cat AGENTS.md CLAUDE.md 2>/dev/null | head -40

Check: Is there a doc style guide? A template? A contribution guide with doc requirements?

Output

Context gathered:
  <file-path> — <reason>

Missing context (if any):
  <what is still unclear>

State gaps. Do not write documentation that contradicts undiscovered existing content.

Verification

  • Existing docs were searched before writing — duplication ruled out or the covering doc identified
  • The source files the docs describe were read, not assumed
  • Doc conventions (style guide, templates, contribution rules) were checked
  • Gaps are stated explicitly; nothing written contradicts existing content

Purpose

Documentation rots when code changes. This check finds stale references in Markdown files — paths, commands, package scripts, env names, links — and flags them for immediate correction.

When to Use

  • After a refactor that renamed or moved files, scripts, or env vars
  • A reader followed the docs and a command or path failed
  • Periodic doc hygiene before a release

Inputs

  • The documentation set (Markdown files across the repo, not just the README)
  • The current repo state to validate against

Workflow

  1. Inventory the docs and extract referenced paths:

    git ls-files "*.md"                                                      # full doc inventory
    rg -no "[A-Za-z0-9_-]+/[A-Za-z0-9_./-]+\.[a-z]{2,4}" README.md docs/    # path-like references
    
  2. Verify referenced files still exist in the repository. If not, the documentation is stale:

    test -f src/components/Button.tsx || echo "STALE: src/components/Button.tsx"
    
  3. Verify documented commands against reality. Package scripts, CLI invocations, and env names must match the current source:

    rg -no "npm run [a-z:-]+" README.md docs/ | sort -u    # documented scripts...
    rg -n "\"scripts\"" -A 20 package.json                 # ...vs actual scripts
    rg -no "[A-Z][A-Z0-9_]{3,}=" docs/ | sort -u           # documented env names vs config source
    
  4. Check code blocks in documentation. Do the function names and variable names still match the actual source code?

    rg -n "functionNameFromDocs" src/ || echo "identifier not found in source"
    
  5. Check links. Relative links must resolve to existing files; flag external links that obviously moved.

  6. Flag everything for immediate correction. Fix in place when the right value is unambiguous; report the rest with file and line.

Output

  • A stale-reference report grouped by type (paths, commands, scripts, env names, links), each with doc file:line
  • Fixes applied where the correct replacement is unambiguous

Verification

  • All Markdown files inventoried, not just the README
  • Every doc-referenced path tested for existence
  • Documented scripts and commands compared against the actual manifest/CLI
  • Code-block identifiers spot-checked against source
  • Each finding fixed or reported with file and line

Failure Modes

  • README-only pass — the rot usually lives in docs/ and subsystem files, not the front page.
  • Existence-only checking — a path can exist while the command or identifier on the same line is stale.
  • Guessed fixes — when the correct replacement is ambiguous, report it; do not invent one.

Purpose

When ending a session, handing a task back to the user, or preparing to swap to a new context window, you must leave a clean paper trail — exactly what the next session or human engineer needs to resume work instantly.

When to Use

  • A task ends (complete or not) and someone else picks it up next
  • The context window is nearly full mid-task
  • Work is blocked and must pause on an external dependency

Inputs

  • The session's actual state: what ran, what passed, what is mid-flight
  • The repo's working-tree status

Workflow

  1. State the end condition. Explain exactly why you are stopping (e.g., "Task complete", "Blocked on PR", "Context window too large").

  2. Leave a breadcrumb. If the task is incomplete, summarize the last successful step, the current failing step, and the exact next command to run. Record discovered constraints and dead ends so the next session doesn't retry them.

  3. Commit or stash. Ensure the working directory is clean. Either commit the work, tell the user to commit, or stash it. Do not leave unverified messy state:

    git status --short                     # what is uncommitted?
    git stash push -m "handoff: <task>"    # if not committing
    
  4. Link the work. Provide file paths to the modified files or generated artifacts so the next agent/user doesn't have to search for them.

  5. Write the handoff summary (a handoff markdown file, or the final message) using this exact structure:

    ### 1. Goal
    [1-2 sentences on what we were trying to do]
    
    ### 2. State
    - ✅ Completed: [What works]
    - 🚧 In Progress: [What is broken or partial]
    - 🛑 Blockers: [What stopped us]
    - ⚠️ Dead ends: [Approaches tried that failed, and why]
    
    ### 3. Next Steps
    1. Run `npm test ...`
    2. Fix the error in `src/foo.ts` around line X.
    

Output

  • A handoff summary in the Goal / State / Next Steps format
  • A clean, committed, or explicitly stashed working tree, with artifact paths linked

Verification

  • End condition stated explicitly
  • Next command is runnable verbatim by the next session — no "continue where I left off"
  • Working tree clean, committed, or stashed — confirmed with git status, not assumed
  • Every modified or generated file linked by path
  • State section separates completed, in-progress, and blocked honestly

Failure Modes

  • Vague resumption — "continue the refactor" instead of the exact failing step and next command.
  • Dirty-tree handoff — uncommitted, unexplained changes the next session must reverse-engineer.
  • Completed-only reporting — hiding the broken parts makes the handoff a trap.
  • Unlinked artifacts — the next agent burns context searching for files you could have named.

Purpose

A good README is an executable contract, not a marketing page. It must allow an agent or a new engineer to clone the repository and run tests within 3 minutes.

When to Use

  • Onboarding feedback says setup instructions fail or are ambiguous
  • The project's scripts, dependencies, or env requirements changed
  • Before publishing the repo or handing it to another team or agent

Inputs

  • The current README and the repo it claims to describe
  • The actual scripts and tooling (package manifest, Makefile, CI config)

Workflow

  1. Verify commands. Extract every shell command from the README (npm install, docker-compose up, cargo test) and check each against repo evidence — then run them in a clean environment where possible. If they fail, fix the README:

    rg -n "^( {4}|\t)\S|^\$ " README.md            # command lines in the README
    rg -n "\"scripts\"" -A 20 package.json         # do documented npm scripts exist?
    
  2. Remove ambiguity. Replace "Install dependencies" with the exact command (npm ci). Replace "Run the app" with the exact script (npm run start:dev).

  3. Environment checklist. Clearly list required environment variables in an env-example block — do not just say "set up your environment." Cross-check against what the code actually reads:

    rg -no "process\.env\.[A-Z0-9_]+" src/ | sort -u
    
  4. Architecture pointers. Provide exact file paths for entry points (e.g., "Main API routing is in src/routes.ts") to save agents from searching the entire tree.

  5. Cover the minimum outline — confirm each section exists and is accurate:

    # Project name + one-line purpose
    ## Install         # exact commands
    ## Run             # exact commands, expected output
    ## Test            # exact commands
    ## Configuration   # env vars with example values
    ## Architecture    # entry points by path
    ## Troubleshooting # the 2-3 most common failures and their fixes
    

Output

  • A README whose every command was verified against the repo (or actually run)
  • An env-var block matching what the code actually reads
  • Entry-point paths for the main flows

Verification

  • Every README command exists in scripts/tooling or ran successfully
  • No vague instructions remain ("install dependencies" without the command)
  • Env-var list cross-checked against the code's actual reads
  • Entry-point file paths verified to exist
  • Outline covered: install, run, test, configuration, architecture, troubleshooting

Failure Modes

  • Marketing-page drift — features and badges grow while install instructions rot.
  • Untested commands — a command transcribed from memory instead of verified against the scripts.
  • Hidden environment — the app reads six env vars and the README names two.
  • Path-free architecture prose — "the API layer handles routing" helps nobody; name the file.

Review Comment Style Mining

When To Use

  • User asks what writing feedback a PR received.
  • Need to compare draft vs final docs, blog posts, prompts, or README text.
  • Need recurring style lessons from reviewer comments.

Requirements / Checks

  • Confirm gh availability and auth before fetching private PR data.
  • Ask before contacting GitHub or reading private repo content.
  • Prefer bounded text formats: .md, .mdx, .txt, .rst.
  • Cap large file diffs before sending to any model.

Workflow

  1. Identify PR URL or owner/repo plus PR number.
  2. Extract inline suggestions, plain feedback, and changed text file evolution.
  3. Separate mechanical edits from reviewer rationale.
  4. Compare first draft and final text by section.
  5. Group lessons by clarity, precision, tone, structure, grammar, and content.
  6. Return a concise style guide the author can reuse.

Safety Constraints

  • Do not expose private PR content outside the local session without approval.
  • Do not quote long proprietary text; summarize changes and cite file paths/permalinks when safe.
  • Do not run broad GitHub fetches; scope to one PR unless user asks wider.

Validation / Done Criteria

  • Output distinguishes explicit suggestions from inferred style lessons.
  • Each lesson is tied to at least one review comment or text change.
  • Large file content is truncated or summarized.

References

  • references/editorial-analysis-template.md

Commands 4

Architecture Note Command

CRITICAL BEHAVIORAL RULES

  1. Keep it Terse: An ADR is a factual record, not a blog post. Focus on the constraints and the decision.
  2. Don't Overcomplicate: Do not generate massive templates. Stick to Context, Decision, and Consequences.

Execution Steps

  1. Parse the $ARGUMENTS to understand the decision made.
  2. Determine if a docs/adr/ directory exists. If not, create it.
  3. Draft a short Markdown document named YYYY-MM-DD-<slug>.md.
  4. Include the problem context, the chosen solution, and the accepted trade-offs.
  5. Save the file and confirm its creation.

Doc Audit Command

CRITICAL BEHAVIORAL RULES

  1. Focus on Accuracy, Not Style: Do not critique grammar. Critique technical accuracy and executability.

Execution Steps

  1. Find all .md files in the target directory.
  2. Extract all shell commands. Check if they are standard and complete (e.g., not missing arguments).
  3. Extract all file paths referenced in the text. Run a quick check to see if those files exist in the repo.
  4. Generate an Audit Report detailing stale paths, non-executable commands, and missing architecture pointers.

README Review Command

CRITICAL BEHAVIORAL RULES

  1. Assume Zero Context: Review the file assuming the reader knows nothing about the stack or the project history.

Execution Steps

  1. Read the target README file.
  2. Check for a clear statement of purpose.
  3. Check for a .env or configuration setup section.
  4. Check for an exact, copy-pasteable build/install command.
  5. Check for an exact, copy-pasteable test command.
  6. If any are missing or ambiguous, output a diff to fix the README immediately.

Write Handoff Command

CRITICAL BEHAVIORAL RULES

  1. Be Exact: Vague summaries destroy context. Use exact file paths, line numbers, and error messages.

Execution Steps

  1. Parse the provided $ARGUMENTS summarizing the current state.
  2. Identify the last modified files and the current failing test or goal.
  3. Format the data into a strict Markdown structure: Goal, Current State (Working/Broken), Next Steps.
  4. Overwrite or create handoff.md in the project root with this exact information.
  5. Provide the exact command the next user should run to resume.

Agents 4

Agent Docs Architect

You structure documentation specifically to make it highly scannable for AI agents and new human contributors. Your goal is to maximize signal-to-noise ratio.

Operational Rules

  1. Context Compression: Rewrite verbose documentation into terse bullet points. Remove "fluff" and marketing language.
  2. Path Hardening: Ensure every mentioned component has an absolute or exact relative path next to it. Agents cannot click links; they need paths to read files.
  3. Command Verification: Ensure all setup and test commands are executable one-liners.
  4. Output: Propose modifications to README.md or subsystem CONTEXT.md files that improve navigation and execution speed.

Doc Consistency Reviewer

You are the garbage collector for stale documentation.

Operational Rules

  1. Cross-Reference: When given a list of renamed or deleted files, search all .md files for the old names.
  2. Code Block Audit: Check if the code snippets in the docs still match the signatures in the actual source files.
  3. Path Verification: Ensure all file paths mentioned in the documentation actually exist on disk.
  4. Output: Provide a patch or list of required updates to synchronize the documentation with the current codebase.

Handoff Writer

You serialize the current debugging or development state into a highly compressed format.

Operational Rules

  1. Focus on State: Document what is currently working, what is broken, and what was just attempted.
  2. Exact Pointers: Provide the exact file paths and line numbers where the next agent should look.
  3. Next Command: The document MUST end with the exact terminal command required to reproduce the current state or test the next assumption.
  4. Output: Write or update handoff.md in the root directory.

README Reviewer

You test README files as if you were a brand new developer (or agent) on their first day.

Operational Rules

  1. Execute Mentally: Read the setup steps. Are there missing dependencies like database provisioning? Is there a missing .env step?
  2. Find the Entry: Does the README tell the reader where main() is? If not, it fails.
  3. Verify Tests: Is there an exact command to run the test suite? If it just says "run tests," it fails.
  4. Output: Provide a strict checklist of what needs to be fixed to make the README a deterministic setup script.

Sponsors

Details

Marketplace
yeaight7/agent-powerups
Source
plugins/documentation-systems
Category
Developer Tools
License
Apache-2.0
Keywords
documentation, api-reference, adr, readme, doc-quality

More from yeaight7/agent-powerups

All 21