# Context content and writing

## 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.
- **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.

What earns the space is the inverse: document what the agent cannot discover by reading the repo -- the unwritten convention, the reason behind a choice, the gotcha no config file confesses. The environment is a source of truth too, so a section restating it is a cache, and a cache earns its load only when the lookup is expensive. Naming the one test command among forty `package.json` scripts is an expensive lookup and belongs here (see Commands below); a raw `ls -R` dump or a paraphrase of `--help` is a cheap one the agent can re-derive on demand. A curated structure note -- what a new top-level directory is *for* -- is not the same thing, and still belongs here.

Treat fewer words as an optimization signal, not an acceptance criterion. Before condensing or merging rules in a context file, capture a baseline and predeclare the decisions the file exists to control: request authority, external actions, when to ask, proof standards, failure attribution. Compare baseline and candidate on the same cases; any safety, authority, or honesty regression rejects the candidate however much smaller it is. Prefer merging duplicated rules and deleting procedural restatement; preserve exact wording where it is what changes behavior. Change one rule group at a time, and add a case when a new failure mode appears rather than growing the file pre-emptively.

A fact any flow might need belongs in the always-loaded context file, not in the one sub-document whose flow needs it today; a cross-cutting convention recorded only as a comment at one call site is invisible at the next. Put the shared fact in the file every session loads, and enforce a cross-site rule at the shared initialization point rather than restating it per site.


## 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 (versions: see above).
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.


## 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.
- **One directive per sentence.** A rule that bundles two actions gets half-applied: the reader acts on the first clause and the last, and drops the middle. Move any sequence of 3+ steps into a numbered list rather than burying it in prose.
- **`must`/`never` for requirements, `should`/`may` for latitude.** A requirement phrased as "should" reads as optional and gets skipped.
- **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.
- **Verify every external identifier, not just internal paths.** A cited upstream PR, issue, RFC, or release tag is a claim about someone else's repository: open it and confirm the title matches what the sentence says it is. Shorthand that merely *looks* canonical (`PR-120`, `issue 99`) is the usual failure — it gets treated as the real ID by everything downstream and fans out into every artifact built from that file. Write the canonical form (`owner/repo#N`), and re-verify state claims ("merged", "fixed in") before publishing, since those rot fastest. One lookup per cited ID is cheaper than correcting the same wrong link in N places after it ships.
- **Sentence case headings**, no emoji decoration in CLAUDE.md/AGENTS.md/CONTRIBUTING/DOCS; README headers may carry at most one conventional emoji per header (see ia-writing's README rules); 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).
- **Treat every published snippet as a test.** Code in a README or docs page is never exercised by the suite, so it drifts to a missing method or a wrong output. Extract every snippet and every stated output into one script and run it against the built artifact before publishing; keep runnable copies next to the code. Audit the reverse direction separately -- features that shipped and were never documented.


## 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)
- Changelog-speak, in both directions -- forward-looking hype ("now supports", "new in 3.2", "coming soon") and backward-looking narration of a diff ("this replaced the previous approach", "X was refactored to use Y"). A README describes the tool's present tense; a reader without the commit history gets archaeology instead of a description. Version-migration notes belong in CHANGELOG or `docs/`, and CHANGELOG, release notes, migration guides, and decision records are exempt -- being version-scoped is their purpose

# Documentation workflows

## Workflows

### Update Context Files

Verify and fix AGENTS.md against the actual codebase. See [update-agents.md](./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](./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](./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.

When a doc prescribes a machine-consumed shape (a JSON artifact, config file, or request body) that code then validates, the two drift silently and each drift costs one caller a rejected write. A test that greps the doc for key names is a second copy of the doc: it goes green when both copies are wrong together, which is the only failure that matters. Have the tool report its validators' key sets as a versioned subcommand, sourced from the **same constants the validators read** — a constant only the report reads is decoration — then compare the doc against that report in both directions: a documented key no validator accepts, and a required key no example shows. Guard the guard: an example nothing can classify is a failure rather than a skip, and a validated artifact with no example is a failure.

- Assert nested rows separately -- a walk over top-level examples cannot reach a row inside an array.
- Assert field order when the doc's order is how a reader learns the shape.
- Run the comparison against the installed binary as well as the build tree.

### Initialize Context

Create AGENTS.md from scratch for projects without documentation. See [init-agents.md](./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

# Initialize Context Workflow

Create AGENTS.md from scratch for projects without documentation.

## Check Existing

```bash
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

```markdown
## 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

```markdown
## 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

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

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

### PineScript

```markdown
## Stack
- Pine Script v6 (TradingView)

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

### Bash / Shell

```markdown
## 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
```

# Monorepo Handling

## 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:**

```bash
git rev-parse --show-toplevel
```

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

```bash
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:

```bash
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 of SKILL.md.

Process deepest-first or root-first consistently, and report results grouped by path.

## Context loading rules

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.

# 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

```bash
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

| Signal | Stack |
|--------|-------|
| `package.json` | Node.js / TypeScript / JavaScript |
| `pyproject.toml`, `setup.py` | Python |
| `composer.json` | PHP |
| `*.pine` files | PineScript |
| `*.sh`, `Makefile` | Bash / Shell |

**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. Every badge must resolve dynamically -- `shields.io/npm/v/PKG`, `github/v/release/OWNER/REPO`, `github/license/OWNER/REPO`, `github/actions/workflow/status/...?branch=<default>` -- using the repo's actual workflow filename and default branch. Never hardcode a version into an `img.shields.io/badge/...` URL; a badge that can go stale is a bug. Static `badge/...` is acceptable only for facts that change with a commit (supported platforms, language version, minimum OS). Confirm each badge renders rather than returning the shields "invalid" card.

**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; at most one conventional emoji per header is allowed (see ia-writing's README rules) -- never inline in prose
- `##` 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