Ia Md Docs

Markdown Documentation

Manage project documentation by verifying against actual codebase state. Emphasize verification over blind generation -- analyze structure, files, and patterns before writing.

Portability

AGENTS.md is the universal context file (works with Claude Code, Codex, Kilocode). If the project uses CLAUDE.md, treat it as a symlink to AGENTS.md or migrate content into AGENTS.md and create the symlink:

# If CLAUDE.md exists and AGENTS.md doesn't
mv CLAUDE.md AGENTS.md && ln -sf AGENTS.md CLAUDE.md

When this skill references "context files", it means AGENTS.md (and CLAUDE.md if present as symlink).

Workflows

Update Context Files

Verify and fix AGENTS.md against the actual codebase. See update-agents.md for the full verification workflow.

1. Read existing AGENTS.md, extract verifiable claims (paths, commands, structure, tooling) 2. Verify each claim against codebase (ls, cat package.json, cat pyproject.toml, etc.) 3. Fix discrepancies: outdated paths, wrong commands, missing sections, stale structure 4. Discover undocumented patterns (scripts, build tools, test frameworks not yet documented) 5. Report changes

Update README

Generate or refresh README.md from project metadata and structure. See update-readme.md for section templates and language-specific patterns.

1. Detect language/stack from config files (package.json, pyproject.toml, composer.json) 2. Extract metadata: name, version, description, license, scripts 3. If README exists and --preserve: keep custom sections (About, Features), regenerate standard sections (Install, Usage) 4. Generate sections appropriate to project type (library vs application) 5. Report changes

Update CONTRIBUTING

Update existing CONTRIBUTING.md only -- never auto-create. See update-contributing.md.

When updating, detect project conventions automatically:

• Package manager from lock files (package-lock.json → npm, yarn.lock → yarn, pnpm-lock.yaml → pnpm, bun.lockb → bun)
• Branch conventions from git history (feature/, fix/, chore/ prefixes)
• Test commands from package.json scripts or pyproject.toml

Merge advisory. When CONTRIBUTING.md sits next to an AGENTS.md (repo root or any package root), surface a one-line recommendation: merge the contribution workflow section into the sibling AGENTS.md so the context file owns dev workflow, branch conventions, and review process as a single source of truth. Then suggest the user delete CONTRIBUTING.md after the merge. Never auto-merge and never auto-delete -- the user performs both. Continue the requested workflow regardless; the CONTRIBUTING file is advisory only.

Update DOCS

If DOCS.md exists, treat it as API-level documentation (endpoints, function signatures, type definitions). Verify against actual code the same way as AGENTS.md. Never auto-create DOCS.md -- only update existing.

Initialize Context

Create AGENTS.md from scratch for projects without documentation. See init-agents.md.

1. Analyze project: language, framework, structure, build/test tools 2. Generate terse, expert-to-expert context sections 3. Write AGENTS.md, create CLAUDE.md symlink

What Belongs in Context Files

Keep AGENTS.md / CLAUDE.md to durable signal. Do NOT enumerate:

• Installed skills, plugins, or extensions -- these change with the user's environment, not the project. The list rots within weeks and turns into a confusing catalog of names that may not be installed for the next reader.
• Tool versions outside the project's source of truth -- package.json engines, .nvmrc, pyproject.toml Python constraint, composer.json PHP version. List the source-of-truth file path; do not duplicate the version inline.
• Linter / formatter rule restatements -- if .eslintrc, ruff.toml, phpcs.xml already enforce it, the file is the spec. List the command to run; do not paraphrase rules.
• README content -- if information is already in README.md (install, badges, intro), reference it; do not re-paste.

The test: if a fact will be wrong in two months without anyone touching this file, it does not belong here. The file is for project-specific rules that survive tool churn.

Context File Hierarchy

Structure CLAUDE.md (and AGENTS.md) content by priority so the most critical information loads first when context is compacted:

1. Rules -- project constraints, forbidden patterns, required conventions. Override everything else. 2. Tech stack -- languages, frameworks, package managers. For exact versions, point at the project's source-of-truth file (package.json engines, .nvmrc, pyproject.toml, composer.json); do not duplicate the version inline. 3. Commands -- how to build, test, lint, deploy. Exact commands, not descriptions. 4. Conventions -- naming patterns, file organization, architectural decisions. 5. Boundaries -- what's off-limits, what requires approval, scope constraints.

Rules that prevent mistakes outweigh background information. Place them at the top so they survive aggressive context compaction.

Monorepo Discovery (Authoring)

Before invoking any update-* or init-* workflow on a multi-package repo, enumerate every package root that should own an AGENTS.md / README.md. Authoring is recursive by default; pass --root-only to collapse back to the repo root.

Resolve the repository root once:

git rev-parse --show-toplevel

*Find existing context files to refresh (`update-` discovery):**

git ls-files --cached --others --exclude-standard \
  -- '**/README.md' 'README.md' '**/AGENTS.md' 'AGENTS.md'

*Find package roots that should get a new file (`init-` discovery):** package roots are directories holding a language/tooling manifest -- the repo root plus the unique directories of these files:

git ls-files --cached --others --exclude-standard \
  -- '**/package.json' 'package.json' '**/Cargo.toml' 'Cargo.toml' \
     '**/pyproject.toml' 'pyproject.toml' '**/setup.py' 'setup.py' \
     '**/go.mod' 'go.mod' '**/composer.json' 'composer.json'

If the repo uses workspace globs (pnpm-workspace.yaml, package.json workspaces:, Cargo.toml [workspace], go.work), prefer those as ground truth over file enumeration — they declare the canonical package set and avoid false positives from nested vendored manifests.

Always exclude during discovery: .git, node_modules, vendor, .venv, target, dist, build, out, .next, coverage, anything ignored by git, and hidden dot-directories that lack a manifest.

Per-file scoping. Treat each target independently:

• The metadata source is the nearest enclosing manifest (the one in its own directory; otherwise walk up to the repo root).
• A nested README.md links to its sibling AGENTS.md, not the root one.
• Each AGENTS.md gets a sibling CLAUDE.md symlink in the same directory (ln -sf AGENTS.md CLAUDE.md, run from that directory).
• CONTRIBUTING.md is checked per directory; apply the merge advisory from the Update CONTRIBUTING section.

Process deepest-first or root-first consistently, and report results grouped by path. When a sweep would create or rewrite more than a handful of files, list the planned targets and get confirmation before writing.

Monorepo Context Loading

Claude Code's context-file loading in monorepos follows three rules -- understanding them determines where content belongs:

• Ancestors load immediately: walking UP from the current working directory, every AGENTS.md / CLAUDE.md encountered is loaded at startup. Put shared conventions at the repo root.
• Descendants load lazily: an AGENTS.md deeper in the tree loads only when Claude reads or edits a file inside that subtree. Put package-specific conventions at each package's root (packages/api/AGENTS.md, apps/web/AGENTS.md).
• Siblings never load: packages/a/AGENTS.md will NOT auto-load when working in packages/b/. Do not rely on sibling-package context leaking across.

Implication for monorepo layouts: duplicate any rule that must apply across sibling packages into each package's AGENTS.md (or hoist it to the repo root). The loader will not discover it laterally. Conversely, avoid putting package-specific rules at the root -- they'll load into every session regardless of relevance and burn context.

Arguments

All workflows support:

• --dry-run: preview changes without writing
• --preserve: keep existing structure, fix inaccuracies only
• --minimal: quick pass, high-level structure only
• --thorough: deep analysis of all files

Backup Handling

Before overwriting, back up existing files:

cp AGENTS.md AGENTS.md.backup
cp README.md README.md.backup

Never delete backups automatically.

Writing Style

• Lead with the answer. First sentence of each section states the conclusion; reasoning follows. No "In this section, we'll..." preamble.
• Imperative form for instructions: "Build the project" not "The project is built" — verify no passive voice in any directive sentence.
• Expert-to-expert: cut explanations of concepts the target reader already knows. For CLAUDE.md/AGENTS.md, assume familiarity with git, package managers, test runners, and the project's main language.
• Scannable: headings every ~20 lines, bullet lists for ≥3 parallel items, fenced code blocks for every command.
• Verify every command and path against the codebase. Run each command before committing; grep for each referenced path. Stale paths and untested commands are the most common doc defect.
• Sentence case headings, no emoji decoration (exception: changelog entries may use emoji per project convention).
• Actionable headings: "Set SAML before adding users" — not "SAML configuration timing". Reader should know what to do from the heading alone.
• Collapse depth with <details> blocks instead of deleting content (blank line required after <summary> for GitHub rendering).

README Anti-Patterns

Flag during Update README workflows:

• Framework-first lead (explaining the tech stack before the problem it solves)
• Jargon before definition (using project-specific terms without introduction)
• Theory before try (architecture explanation before a working example)
• Claims without evidence ("blazingly fast" with no benchmarks)

Report Format

After every operation, display a summary:

[OK] Updated AGENTS.md
  - Fixed build command
  - Added new directory to structure

[OK] Updated README.md
  - Added installation section
  - Updated badges

[--] CONTRIBUTING.md not found (skipped)

Verify

• Every factual claim in updated docs verified against current codebase
• No stale file paths or component names
• Formatting renders correctly in markdown preview

Initialize Context Workflow

Create AGENTS.md from scratch for projects without documentation.

Check Existing

test -f AGENTS.md && echo "exists" || echo "missing"
test -f CLAUDE.md && echo "claude exists" || echo "no claude"

If AGENTS.md exists: warn user, suggest update workflow instead. Allow override with --force.

If CLAUDE.md exists but AGENTS.md doesn't: migrate -- rename to AGENTS.md, create CLAUDE.md symlink.

Modes

Automatic (no arguments): derive everything from project analysis.

Guided (arguments provided): user describes the project focus, e.g. "PHP Laravel API with queue workers" or "Python data pipeline with scheduled jobs".

Gather Context

Read available config files (skip missing):

• package.json -- stack, scripts, dependencies
• pyproject.toml -- Python project config
• composer.json -- PHP project config
• README.md -- project overview
• .gitignore -- exclusion patterns
• Directory listing (2 levels deep)

Determine:

• Primary language/framework
• Project type: library, application, CLI tool, script collection
• Build/test/lint tools
• Architecture patterns

Language Templates

PHP / Laravel

## Stack
- PHP 8.4+ with Laravel
- Composer for dependencies
- PHPUnit / Pest for testing

## Commands
- `composer install` -- install dependencies
- `php artisan serve` -- local dev server
- `php artisan test` -- run tests
- `php artisan migrate` -- run migrations

Python

## Stack
- Python 3.11+
- uv for dependency management

## Commands
- `uv sync` -- install dependencies
- `uv run pytest` -- run tests
- `uv run ruff check .` -- lint

JavaScript / TypeScript

## Stack
- TypeScript with strict mode
- {detected package manager}

## Commands
- `{pm} install` -- install dependencies
- `{pm} run build` -- build
- `{pm} test` -- run tests

PineScript

## Stack
- Pine Script v6 (TradingView)

## Development
- Edit in TradingView Pine Editor
- Test with bar replay and strategy tester
- No external build tools

Bash / Shell

## Stack
- Bash scripts for automation
- ShellCheck for linting

## Commands
- `shellcheck *.sh` -- lint all scripts
- `chmod +x script.sh && ./script.sh` -- run

Generate Content

Sections to include (only if relevant):

• Stack -- languages, frameworks, tools
• Structure -- key directories and files
• Commands -- build, test, lint, deploy
• Code style -- naming, formatting, patterns
• Constraints -- security, performance, environment

Style: terse, imperative, expert-to-expert. No fluff.

Quality rules (SkillsBench arXiv:2602.12670):

• Procedural over declarative -- "Run npm test" beats "Tests should pass"
• Tables over prose -- agents parse structured data more reliably
• 2K-8K chars is optimal (+18.8pp). Beyond 15K, effectiveness degrades. Split or link out.
• Context-first ordering -- overview before commands, commands before architecture

Write

1. Write AGENTS.md with generated content 2. Create CLAUDE.md symlink: ln -sf AGENTS.md CLAUDE.md 3. Report: show file path, preview first 10 lines

✓ Created AGENTS.md
✓ Created CLAUDE.md → AGENTS.md symlink
  - Detected: Python project (pyproject.toml)
  - Sections: Stack, Structure, Commands, Code Style

Update Context Files Workflow

Verify and fix AGENTS.md (and CLAUDE.md symlink) against actual codebase state.

Step 1: Extract Verifiable Claims

Read AGENTS.md and extract every factual claim:

• File paths and directory structures
• Build, test, lint commands
• Dependency and tooling references
• Code conventions and patterns described
• Environment variables or configuration

Step 2: Verify Claims

Check each claim against the codebase:

Paths and structure:

• ls, tree (2 levels) to verify directories exist
• If path changed: update. If deleted: remove section.

Commands:

• Check package.json scripts, composer.json scripts, pyproject.toml scripts, Makefile, justfile
• If command syntax changed: update. If removed: mark for removal.

Code patterns:

• Read actual files to verify described patterns still hold
• Update outdated patterns to match current code

Step 3: Discover Undocumented Patterns

Scan for patterns not yet in AGENTS.md:

• Task runner recipes (justfile, Makefile, package.json scripts) not documented
• Lint/format configuration that exists but has no corresponding section
• Build/test/deploy commands with no documentation
• New directories or modules not mentioned in structure

Step 4: Apply Updates

If `--dry-run`: show planned changes as diff without writing.

If `--preserve`: fix inaccuracies only, keep existing structure and phrasing.

Otherwise: reorganize for clarity, add missing sections, remove stale content.

Step 5: Report

✓ Updated AGENTS.md
  - Fixed: build command npm → pnpm
  - Removed: stale reference to /old-dir
  - Added: new /api directory to structure

Suggested additions:
  - Consider documenting: jest test configuration

If no changes needed: ✓ AGENTS.md is up to date

Update CONTRIBUTING Workflow

Update existing CONTRIBUTING.md only. Never auto-create -- contribution guidelines represent intentional maintainer decisions.

Prerequisite

test -f CONTRIBUTING.md && echo "exists" || echo "missing"

If missing: report to user and stop. Do not create unless explicitly requested.

Scope of Updates

Fix (technical accuracy):

• Outdated CLI commands (npm → pnpm, yarn → bun)
• Incorrect file paths or directory references
• Broken links to issues, templates, or docs
• Stale branch references (master → main)
• Wrong tooling references (Jest → Vitest, ESLint → Biome)

Preserve (policy decisions):

• Contribution policies (CLA, DCO, licensing)
• Review processes and expectations
• Code of conduct references
• Governance and maintainer decisions
• Communication channel preferences

Workflow

1. Read existing CONTRIBUTING.md, parse structure and code blocks 2. Detect current tooling: package manager (from lock files), available scripts, branch conventions, linter/formatter config 3. Compare documented commands, paths, links against actual codebase 4. Fix technical inaccuracies while preserving structure and policies 5. Use Edit tool for targeted replacements, not full rewrites

Adding Acknowledgements

If requested, add or update an Acknowledgements/Credits section. Place at the end, before License if present. Keep it factual -- list contributors, tools, or inspirations without embellishment.

Report

✓ Updated CONTRIBUTING.md
  - Fixed package manager: npm → pnpm
  - Corrected branch reference: master → main
  - Updated test command

⊘ Policy sections preserved (CLA, review process)

Update README Workflow

Generate or refresh README.md based on codebase analysis.

Guiding Principles

• Balanced, not bloated: 200-400 lines for most projects
• Show, don't tell: code examples over prose
• Every section must add value -- skip empty or trivial sections
• Readers should find what they need in under 30 seconds

Target length: --minimal 100-200 lines, default 200-400, --thorough 400-600.

Language/Stack Detection

Extract from config files: name, version, description, license, dependencies, scripts, repo URL.

Detect package manager from lock files:

• package-lock.json → npm
• pnpm-lock.yaml → pnpm
• yarn.lock → yarn
• bun.lockb → bun
• composer.lock → composer
• uv.lock → uv
• poetry.lock → poetry

Section Order

Libraries (exports modules, no main entry):

1. Title + badges 2. Description 3. Features (if --preserve or --thorough) 4. Installation 5. Usage with code examples 6. API Reference (--thorough only) 7. License

Applications (has entry point, runnable):

1. Title + badges 2. Description 3. Features 4. Installation / Getting Started 5. Usage 6. Configuration (if config files found) 7. Scripts / Commands 8. Project Structure (--thorough only) 9. License

PineScript indicators/strategies:

1. Title 2. Description (what it measures/trades) 3. Inputs and parameters 4. Usage (how to add to TradingView chart) 5. Logic overview 6. Alerts (if applicable)

Section Guidelines

Title + Badges: Project name from config or repo name. Add badges for CI (if .github/workflows/ exists), license, version. Skip badges for private repos.

Description: 1-3 sentences. Answer "what does this do?" Extract from config file description field when available.

Features: 3-8 bullet points for --thorough. Skip if obvious from description. --minimal omits this.

Installation: Show install command for detected package manager. Include git clone if no registry. For PHP: composer require or composer install.

Usage: Minimal working example (5-15 lines). Extract from tests or examples/ directory if they exist. Use proper language tags on code blocks.

Scripts/Commands: List from package.json scripts, composer scripts, Makefile targets. Format as table if 5+ items.

Project Structure: Only for --thorough. Show 5-10 key directories, 2 levels deep max. Skip if structure is obvious.

Configuration: Document if .env.example, config files exist. Show key options. Otherwise omit.

Preserve Mode

When --preserve is set and README.md exists:

Keep (user-written): About, Features, Why X, Background, custom sections.

Regenerate (likely outdated): Install, Usage, Scripts, Structure, Badges, Configuration.

Merge preserved sections with regenerated ones in standard order.

Formatting

• Sentence case headings, no emoji headers
• ## for main sections, ### for subsections
• Code blocks with language tags
• Tables for commands if 5+ items
• Admonitions for important notes: > [!NOTE] and > [!WARNING]
• No git operations -- user reviews and commits manually

ia-md-docs Specification

Intent

ia-md-docs is a workflow-class skill (a multi-step process producing concrete artifacts). Manages project documentation: CLAUDE.md, AGENTS.md, README.md, CONTRIBUTING.md. Use when asked to update, create, or init these context files. Not for general markdown editing.

Scope

In scope:

• Behaviors described in SKILL.md and routed via the should_trigger phrasings in distillery/tests/fixtures/triggers/ia-md-docs.jsonl.
• Updates to runtime behavior, structure, trigger precision, references, and validation.

Out of scope:

• Acting as the runtime instructions themselves (those live in SKILL.md).
• Trigger phrasings already covered by adjacent ia-* skills (validate-plugin flags >70% description overlap as DUPLICATE_TRIGGER).
• <!-- to fill in: domain-specific exclusions when the skill drifts -->

Trigger Context

• Class: workflow
• Hook regex: plugins/whetstone/hooks/skill-patterns.sh -> SKILL_PATTERNS[ia-md-docs]
• Common requests (from fixture should_trigger):
• "update the readme with the new API endpoints"
• "create the agents.md file for this project"
• "structure the CLAUDE.md with the most important rules first"
• Should not trigger for (from fixture should_not_trigger):
• "fix the flaky integration test for payments"
• "add Redis caching to the product listing"
• "rewrite this skill's SKILL.md body"

Source And Evidence Model

Authoritative sources:

• SKILL.md -- runtime instructions and reference routing.
• references/*.md -- bundled supplementary content (4 file(s)).
• distillery/tests/fixtures/triggers/ia-md-docs.jsonl -- positive and negative trigger phrasings under regression test.
• plugins/whetstone/hooks/skill-patterns.sh -- regex pattern that fires this skill.
• distillery/.eval-data/ia-md-docs/ -- harvested session examples (when present).

Data that must not be stored in this skill or its references:

• Secrets, credentials, tokens.
• Machine-specific filesystem paths (/home/..., /Users/..., ~/ai/...). The validator (MACHINE_PATH_LEAK) flags these as HIGH.
• Private URLs, customer data, or unredacted personal information.

Coverage matrix

Evaluation

Lightweight (run on every change):

python3 distillery/scripts/distiller.py validate-plugin --component ia-md-docs
python3 distillery/scripts/distiller.py test-triggers --skill ia-md-docs

Deeper (when behavior risk warrants):

python3 distillery/scripts/distiller.py dspy-eval ia-md-docs
python3 distillery/scripts/distiller.py diagnose-negatives ia-md-docs

Acceptance gates:

• validate-plugin --component ia-md-docs returns 0 HIGH findings.
• test-triggers --skill ia-md-docs returns F1 = 1.0 with floors of 5 should_trigger and 5 should_not_trigger.
• For dspy-eval, the composite score does not regress against the most recent saved baseline (see distillery/.eval-data/ia-md-docs/history.json).

Known Limitations

<!-- to fill in over time as drift surfaces. Default rule: any time diagnose-negatives surfaces a recurring failure pattern, document it here so future maintainers understand the trade-off the current implementation accepts. -->

Maintenance Notes

• Update SKILL.md when the runtime workflow, branch conditions, or output contract changes.
• Update this SPEC.md when intent, scope, evidence model, evaluation gates, or maintenance expectations change.
• Update the trigger fixture when adding new positive phrasings, removing stale ones, or expanding scope (the 5/5 floor is a hard validator gate).
• Update the hook regex in skill-patterns.sh whenever fixture positives expose a missed phrasing; verify F1 = 1.0 with eval-triggers before committing.
• Run the full release pipeline via /release -- never bump versions or update CHANGELOG.md from a per-skill edit.