diff --git a/src/bmm-skills/plan/bmad-project-context/SKILL.md b/src/bmm-skills/plan/bmad-project-context/SKILL.md index cbf17d03b..fe7259c6f 100644 --- a/src/bmm-skills/plan/bmad-project-context/SKILL.md +++ b/src/bmm-skills/plan/bmad-project-context/SKILL.md @@ -5,11 +5,11 @@ description: 'Write and maintain a project''s agent guide (AGENTS.md): verified # Overview -The product is a good `AGENTS.md` — the short guide an agent loads before every task in this project. The evidence is blunt: generated documentation volume makes agents worse, while a short prescriptive guide of verified, non-derivable facts makes them better. We already know what such a guide contains — the section plan in `references/guide-contract.md` is fixed, and the job is to fill those sections with verified evidence, not to explore the repository for interesting facts. The repository is where claims get *verified*; it is not where the knowledge comes from. The irreplaceable content lives in executable configuration, targeted history, observed agent mistakes, and human heads — in that order of increasing irreplaceability. +The product is a good agent guide — a short `AGENTS.md` every session loads, plus an `AGENTS-dev.md` that coding sessions read. Generated documentation makes agents worse; what helps is a short guide where every line passed its section's admission rule and its facts are verified. The section plan in `references/guide-contract.md` is fixed: the job is to fill it with verified evidence, not to explore the repository for interesting facts. The repository is where claims get verified; the knowledge itself comes from configuration, history, observed agent mistakes, and the people who maintain the project. -Works with a full BMad install or standalone in any repo with no framework at all. +Works with a full BMad install or standalone in any repo. -**Args:** intent (`bootstrap` | `refresh` | `record` | `audit`); `--auto` for headless; a scope path to bound the run; extra source paths or URLs. Supplied values are used directly and skip their questions. +**Args:** intent (`bootstrap` | `refresh` | `record` | `audit`); `--auto` for headless; a scope path to limit the run; extra source paths or URLs. Supplied values are used directly and skip their questions. ## Resolution rules @@ -20,31 +20,31 @@ Works with a full BMad install or standalone in any repo with no framework at al 1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. Execute `{workflow.activation_steps_prepend}`; treat `{workflow.persistent_facts}` entries as standing context (`file:` = paths/globs to load, others verbatim). 2. Config: if `{project-root}/_bmad` exists, `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` and read `{user_name}`, `{communication_language}` (use it every turn), `{output_folder}`. Standalone: skip, and default `{output_folder}` to `_bmad-output`. -3. Read the active steering set: root and nested `AGENTS.md`, `CLAUDE.md` and other agent files, and the ledger at `{output_folder}/project-context-ledger.md` if present. These are the current instructions agents actually receive; every run starts from them. -4. Detect intent and greet `{user_name}`: **bootstrap** (no useful guide yet, or the user wants a rewrite — the default), **refresh** (guide and ledger exist; reconcile with reality), **record** (the user reports an observed agent mistake, lesson, or new rule), **audit** (re-verify and prune). For interactive bootstrap/refresh, ask one opening question: any sources outside the repo (org handbooks, wiki exports, planning docs, MCP knowledgebases) and any area to focus on — note paths for the evidence sweep, don't read them now. Fold `{workflow.external_sources}` into the same list. Execute `{workflow.activation_steps_append}`. +3. Read the existing agent instruction files — root and nested `AGENTS.md`, `CLAUDE.md` and similar — and the ledger at `{output_folder}/project-context-ledger.md` if present. +4. Detect intent and greet `{user_name}`: **bootstrap** (no ledger — this skill's first run here, whether the repo has no guide, a poor one, or a good handwritten one to build on — the default), **refresh** (ledger exists; update the guide to match the repo), **record** (the user reports an observed agent mistake, lesson, or new rule), **audit** (re-verify and prune). For interactive bootstrap/refresh, ask one opening question: any sources outside the repo (org handbooks, wikis, planning docs, MCP knowledgebases) and any area to focus on — note paths for later, don't read them yet. Add `{workflow.external_sources}` entries to the same list. Execute `{workflow.activation_steps_append}`. ## Bootstrap and Refresh -Discovery is progressive — each step narrows the next; broad scanning before the guide is planned is the failure mode this skill replaces. Load `references/guide-contract.md` and `references/evidence.md` before step 1. +Load `references/guide-contract.md` and `references/evidence.md` before step 1. The order matters: plan before scanning, select before writing. -1. **Plan the guide.** Instantiate the contract's section plan for this repo, and list per section the evidence it needs. In a repo with a handwritten `AGENTS.md`, that file is the baseline being improved, never raw material to discard: map its content into the plan first. -2. **Gather evidence.** Fan out parallel subagents, one per evidence lane in `references/evidence.md` — lanes are editorial jobs, not file categories. Each returns ledger-shaped candidates: claim, evidence paths, target section, what behavior it changes, verification status. Corpus rules in the reference bind every scanner. -3. **Verify mechanically.** Run the commands the guide will state (read-only commands freely; anything mutating needs the user's go-ahead) and path-check every claim that names a file. A claim verified by execution or path-check is *verified* — never ask the user to confirm it. -4. **Interview.** Only what no scan can reach: org requirements, frozen areas, domain concepts, intent, priorities — and always "what do agents keep getting wrong here?". Rules and caps in `references/evidence.md`. Log every answer and rejection to the ledger as it lands. -5. **Compose.** Selection and grouping happen before writing: decide what each section says from the accepted candidates, then write the guide as one coherent document under the contract. Copy-editing is the last step, never the curation mechanism. Where an instruction outside the guide contradicts it (a stale `CLAUDE.md` line, a retired command still recommended), propose the concrete fix to that file — surfacing the conflict and leaving both instructions live is a defect. -6. **Coverage check and close.** Walk the ledger: every accepted candidate traces to a guide line, a scoped guide, or a rejection with a reason — an untraceable candidate means the check failed. Confirm the guide meets the contract's budget. Tell the user what was written, what was rejected and why, and — whenever `AGENTS.md` carries the guide — say plainly: if your harness doesn't auto-load `AGENTS.md`, make the file it does load pull this one in (e.g. a `CLAUDE.md` containing `@AGENTS.md`). +1. **Plan the guide.** Instantiate the contract's section plan for this repo and list, per section, the evidence it needs. A handwritten `AGENTS.md` is the baseline being improved, never raw material to discard: map its content into the plan first. +2. **Gather evidence.** Launch parallel subagents, one per evidence source in `references/evidence.md` (sources 1–5; the maintainer, source 6, is step 4). Each returns candidates for the ledger: claim, evidence paths, target section, what behavior it changes, verification status. The scan-scope rules in that file bind every scanner. +3. **Verify.** Run the commands the guide will state and path-check every claim that names a file. Read-only commands run freely; a mutating command (a build, a test suite) waits for its go-ahead, asked as the interview's first question. A claim verified by execution or path-check is verified — never ask the user to confirm it. +4. **Interview.** Only what no scan can reach: org requirements, frozen areas, domain concepts, intent — and always "what do agents keep getting wrong here?". Rules in `references/evidence.md`. Write every answer and rejection to the ledger as it arrives. +5. **Compose.** Decide what each section says from the accepted candidates, then write the guide as one coherent document under the contract. Copy-editing comes last; it is not how selection happens. Where an instruction outside the guide contradicts it (a stale `CLAUDE.md` line, a retired command still recommended), propose the concrete fix to that file — leaving two live contradictory instructions is a defect. +6. **Coverage check and close.** Go through the ledger: every accepted candidate must trace to a guide line, a scoped guide, or a rejection with a reason. Check every repo-relative path the guide names against the filesystem; fix dead links before closing. Confirm the guide fits the contract's budget. Tell the user what was written, what was rejected and why, and — whenever `AGENTS.md` carries the guide — that a harness which doesn't auto-load `AGENTS.md` needs its own file to pull it in (e.g. a `CLAUDE.md` containing `@AGENTS.md`). -**Refresh** runs the same steps against the existing guide and ledger: never re-ask what a prior run settled, re-verify the commands and paths the guide states, and update or remove lines whose evidence is gone. The guide grows only when new evidence earns it. +**Refresh:** same steps against the existing guide and ledger. Never re-ask what a prior run settled; re-verify the commands and paths the guide states; update or remove lines whose evidence is gone. The guide grows only when new evidence justifies it. -**Greenfield:** same pipeline seeded from a spec or planning document (or pure interview). Commands that don't exist yet are written from the decided stack and marked for verification on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — deserves the `bmad-architecture` skill rather than a call made here. +**Greenfield:** same process, based on a spec or planning document (or interview alone). Commands that don't exist yet are written from the decided stack and marked for verification on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — deserves the `bmad-architecture` skill rather than a call made here. ## Record -The cheapest and highest-value intent: capture one observed agent mistake or lesson at the moment it happens. Get the task, the mistake, the correction, and the evidence (a session, a review comment, the user's testimony); log it to the ledger. First occurrence makes a candidate; a recurring or costly mistake earns a line in the guide's pitfalls section now — write it, show the diff. If the mistake is mechanically preventable, say so and propose the hook, lint, or CI check instead: enforcement beats prose. +Record one observed agent mistake or lesson at the moment it happens. Get the task, the mistake, the correction, and the evidence (a session, a review comment, the user's testimony); log it to the ledger. A first occurrence is a candidate; a recurring or costly mistake gets a line in the guide's pitfalls section now — write it, show the diff. If the mistake is mechanically preventable, propose the hook, lint, or CI check instead: enforcement beats prose. ## Audit -Re-verify and shrink: run every command the guide states, path-check every named file, apply the contract's pruning test to every line, and check for contradictions between the guide and other active steering files. Lines that fail move to a scoped guide, get fixed, or die — present proposed deletions for confirmation (interactive) before removing. Audit ends with the guide smaller or equal, never larger. +Run every command the guide states, path-check every named file, apply the contract's pruning test to every line, and check for contradictions with other agent instruction files. Lines that fail move to a scoped guide, get fixed, or are deleted — present proposed deletions for confirmation (interactive) before removing. A pitfall or policy line is deleted only when the thing it guards is gone or the user retires it; absence of recent failures is never grounds. Audit ends with the guide smaller or equal, never larger. ## Modes @@ -52,10 +52,10 @@ Interactive is the default. **Auto mode** (headless, or on request) never asks: ```json {"status": "complete", "intent": "bootstrap", "guide": "AGENTS.md", - "scoped_guides": ["src/billing/AGENTS.md"], + "dev_guide": "AGENTS-dev.md", "scoped_guides": ["src/billing/AGENTS.md"], "ledger": "_bmad-output/project-context-ledger.md"} ``` ## Finalize -Confirm the ledger reflects the run — every candidate dispositioned, every interview answer captured — and run `{workflow.on_complete}` if non-empty. +Confirm the ledger reflects the run — every candidate has a disposition, every interview answer is recorded — and run `{workflow.on_complete}` if non-empty. diff --git a/src/bmm-skills/plan/bmad-project-context/references/evidence.md b/src/bmm-skills/plan/bmad-project-context/references/evidence.md index 08fd150c0..054b5e5ec 100644 --- a/src/bmm-skills/plan/bmad-project-context/references/evidence.md +++ b/src/bmm-skills/plan/bmad-project-context/references/evidence.md @@ -1,27 +1,27 @@ # Evidence -Where guide content comes from, how it is verified, and how the run is recorded. True and useful are different properties: verification establishes truth; only a section's editorial job establishes usefulness. A verified fact with no section that needs it is rejected, with the reason in the ledger. +Where guide content comes from, how it is verified, and how the run is recorded. Verification establishes that a claim is true; a claim is useful only if one of the guide's sections needs it. A verified fact no section needs is rejected, with the reason in the ledger. -## Channels +## Sources -In increasing order of irreplaceability — later channels hold what earlier ones cannot: +Sources 1–5 are scanner work; source 6 is the interview. Later sources hold what earlier ones cannot. -1. **Active steering files** — root and nested `AGENTS.md`, `CLAUDE.md`, editor rule files. What agents are told today: the baseline, plus conflicts and staleness to fix. -2. **Executable configuration and CI** — manifests, lockfiles, workflow files, hooks, Makefiles, linter configs. The commands, gates, and enforcement points. The highest-yield scan there is; most of Commands, Verification, and Policy comes from here and gets verified by execution. -3. **Tracked source** — for boundaries (vendored, generated, frozen areas), conventions that differ from defaults, and entry points. This channel answers questions the section plan already asked; it is never mined for "interesting facts", because a fact's novelty says nothing about whether any agent needs it. -4. **Git history** — targeted, never wholesale: a surprising constraint found in the current state → `git blame` its introduction → `git show` the change → `git log -S`/`-G` for prior attempts and reversions → verify the reason still holds against the present tree. Commit messages are evidence of past intent, not current truth. -5. **Agent session logs and review corrections** — when available or pointed at: the only source that can establish *observed* agent mistakes. Extract structure, never transcripts: task, mistake, correction, consequence, whether an instruction could have prevented it, occurrence count, source sessions. One occurrence is a candidate; recurrence makes a pitfall line. Filter incidental noise (tool outages, typos), and route mechanically-preventable mistakes to hooks/lint/CI proposals instead of prose. -6. **The human** — org requirements, domain concepts, frozen areas, intent, priorities, and mistakes they've watched agents make. The only source for these; no scan substitutes. +1. **Existing recorded instructions and lessons** — root and nested `AGENTS.md`, `CLAUDE.md`, editor rule files, and lessons written anywhere nearby (notes files, warnings in READMEs). What agents are told today: the baseline, plus conflicts and stale claims to fix. Recorded lessons are standing maintainer testimony — kept by default, challenged only with evidence that a referent is gone or wrong. +2. **Executable configuration and CI** — manifests, lockfiles, workflow files, hooks, Makefiles, linter configs. Most of Commands, Verification, and Policy comes from here, verified by execution. +3. **Tracked source** — boundaries (vendored, generated, frozen), conventions that differ from defaults, entry points. Scanned to answer the section plan's questions, never for novelty: an interesting fact no agent needs is noise, and a trap-looking fact is at most an interview question, never a pitfall line. +4. **Git history** — targeted, never wholesale: when the current state contains a surprising constraint, find the change that introduced it and any reverted attempts to remove it, then check the reason still holds today. Commit messages are past intent, not current truth. +5. **Agent session logs and review corrections** — when available or pointed at: the only source of *observed* agent mistakes. Extract structure, never transcripts: task, mistake, correction, consequence, occurrence count, source sessions. One occurrence is a candidate; recurrence makes a pitfall line. Ignore one-off noise (tool outages, typos); route mechanically preventable mistakes to a proposed hook, lint, or CI check instead of prose. +6. **The human** — org requirements, domain concepts, frozen areas, intent, priorities, and mistakes they've watched agents make. No scan substitutes. -External sources the user names (org handbooks, wikis, prior architecture docs, MCP knowledgebases) join at rank 3: mined for candidates, untrusted until verified against the repo or confirmed by the user. +Documents the user names from outside the repo (org handbooks, wikis, prior architecture docs, MCP knowledgebases) are treated like source 3: scanned for candidates, untrusted until verified against the repo or confirmed by the user. -## Corpus rules — binding on every scanner +## Scan scope — binding on every scanner -The corpus is tracked files (`git ls-files`); dependency, vendored, generated, build-output, and cache directories are out unless a specific claim requires looking inside one, and then the scanner states why. Scanners return candidates with evidence; they never decide what gets written. +Scanners read tracked files (`git ls-files`). Dependency, vendored, generated, build-output, and cache directories are out unless a specific claim requires looking inside one, and then the scanner states why. Scanners return candidates with evidence; they never decide what gets written. ## The ledger -`{output_folder}/project-context-ledger.md` — one plain markdown file, the skill's memory across runs. One block per candidate: +`{output_folder}/project-context-ledger.md` — one plain markdown file, this skill's memory across runs. One block per candidate: ```markdown ## @@ -32,12 +32,15 @@ The corpus is tracked files (`git ls-files`); dependency, vendored, generated, b - disposition: guide | scoped: | rejected — | pending ``` -Interview answers, rejections (with reasons), conflicts found in other steering files, and auto-mode assumptions all land here the moment they happen — never batched for session end. Refresh and audit read it first and never re-litigate a recorded disposition unless its evidence changed. The ledger is working memory, not context: agents never load it, and nothing in it counts against the guide's budget. +Interview answers, rejections with reasons, conflicts found in other instruction files, and auto-mode assumptions are all written here the moment they happen. Refresh and audit read the ledger first and don't revisit a recorded disposition unless its evidence changed. Agents never load the ledger; nothing in it counts against the guide's budget. ## Interview rules - **Never ask what a scan could answer.** A claim verified by execution or path-check proceeds as verified; asking the user to confirm it is a defect. -- Chunked rounds, eight questions maximum, fewest possible. Open questions over confirmations: "what do agents keep getting wrong here?", "what would a new engineer be told on day one that's written nowhere?", "what must never be touched?". -- An unverifiable claim from docs or an external source is surfaced as "the docs say X — still true?", never stated as fact. -- Before writing, one closing ask: name in a line what will be captured and ask what's missing — a frozen area, an org rule, a recurring mistake. This class of material is unrecoverable by any later scan. -- A round that yields nothing new is the signal to write, not to invent another round. Out-of-scope material the user volunteers is captured in the ledger, never deflected. +- **Ask recall questions, never review lists.** "What do agents keep getting wrong?" works because the maintainer's memory has already selected what mattered. Never hand the human a selection problem a scan created. +- A mistake this session itself made and caught while reading or verifying the repo is an observed agent failure (sample of one) — worth offering as a question. +- Ask in batches of at most eight questions; fewer is better. Prefer open questions ("what do agents keep getting wrong here?") over confirmations. +- An unverifiable claim from docs or an outside document is asked as "the docs say X — still true?", never stated as fact. +- When the repo contradicts the user's own testimony, show the evidence and ask — never write the claim as given, never drop it silently. Either the claim or the reading of the evidence gets corrected, and the outcome is recorded in the ledger. +- Before writing, one closing question: say in a line what the guide will contain and ask what's missing — a frozen area, an org rule, a recurring mistake. This material is unrecoverable by any later scan. +- A batch that yields nothing new means it is time to write, not to ask more. Off-topic information the user offers is recorded in the ledger, never ignored. diff --git a/src/bmm-skills/plan/bmad-project-context/references/guide-contract.md b/src/bmm-skills/plan/bmad-project-context/references/guide-contract.md index 2d1521a1b..05b672294 100644 --- a/src/bmm-skills/plan/bmad-project-context/references/guide-contract.md +++ b/src/bmm-skills/plan/bmad-project-context/references/guide-contract.md @@ -1,40 +1,46 @@ # Guide Contract -The guide is `AGENTS.md` at the repo root — loaded into every agent session, the highest-cost real estate this skill manages. Every line is paid for in every future task. This contract governs every write to it, in any intent or mode. +The guide is the project's agent instructions, written as two files at the repo root: + +- **`AGENTS.md`** — loaded by every session, whatever its kind: Orientation, Policy, and one closing pointer line: "Editing code? Read `AGENTS-dev.md` first." +- **`AGENTS-dev.md`** — read via that pointer by sessions that will touch code: Commands, Verification, Conventions, Where things are, Known pitfalls. Planning and review sessions never pay for it. + +When the whole guide fits in about 20 instructions, write a single `AGENTS.md` instead — the extra hop isn't worth it. Every line in either file has a recurring cost; this contract governs every write. ## Hard rules -- **Instruction budget: ~150–200 instructions across all always-loaded content, a ceiling not a target.** Instruction-following measurably decays past this range. Count instructions, not lines — one line carrying three rules is three instructions, and whatever `CLAUDE.md` or other always-loaded files add counts against the same ceiling. When the budget is threatened, the weakest line moves to a scoped guide or a linked doc, or dies; the budget is never raised. -- **Priority ordering.** Most load-bearing rules first — the rules whose violation costs the most. A reader who stops halfway got the half that matters most. -- **The pruning test.** *Would removing this line change agent behavior?* If no, the line is deleted. Applied to every line at every write. -- **The inclusion test.** A line earns its place only by being **non-derivable** (the agent cannot learn it from the code in reasonable time) and **behavior-changing** (an agent without it does something wrong). Verified is necessary but not sufficient — a perfectly true fact that changes nothing is still noise. +- **Instruction budget: ~150–200 instructions across everything a coding session loads — a ceiling, not a target.** Instruction-following degrades past this range. Count instructions, not lines (one line carrying three rules is three instructions), and count what `CLAUDE.md` or other always-loaded files add. When the budget is exceeded, the weakest lines move behind links or are deleted; the budget is never raised. +- **Priority order.** Rules whose violation costs the most come first, so a reader who stops halfway got the half that matters most. +- **The pruning test.** *Would removing this line change agent behavior?* If no, delete it. Applied to every line at every write. -## Section plan +## Sections and what admits a line -The default plan; rename sections to fit the project, omit sections that would be empty, never pad one to look complete. Each section is an editorial job, and evidence is gathered *for* it — not sorted into it after the fact. +Each section has its own admission rule. There is no global "non-derivable" test: some sections admit derivable content on purpose, and no section admits content merely for being true. -1. **Orientation** — two to four sentences: what this project is, the stack, where planning, tickets, PRs, and deeper docs live. Under 100 tokens; it orients, it does not tour. -2. **Commands** — build, test (including a single test), lint, run: the exact invocation with flags, plus warnings where an operation is expensive ("the full suite is slow — run the single file while iterating") or where the obvious guess fails. -3. **Verification** — what must pass before commit and push, stated as the exact commands CI runs. -4. **Policy and safety** — branch rules, protected and frozen paths, generated files never edited by hand, secrets handling, what must never be done. -5. **Conventions that differ from defaults** — only the divergences an agent following ecosystem norms would get wrong. Each with its enforcement point or source file linked. -6. **Where things are** — subsystem → entry-point pointers, and "working on X? read Y first" pointers into deeper docs. This is the progressive-disclosure layer: depth lives behind links, never inline. -7. **Known pitfalls** — recurring agent mistakes with their mitigations. Only with evidence (observed sessions, review corrections, or maintainer testimony); a pitfall nobody has hit is a guess. +1. **Orientation** (`AGENTS.md`) — three or four sentences: what this project is, the stack, where planning, tickets, PRs, and deeper docs live. No admission test beyond brevity. +2. **Policy and safety** (`AGENTS.md`) — admitted by **authority**: what the org and the maintainers require and the code cannot express — branch rules, protected and frozen paths, generated files, secrets, what must never be done. +3. **Commands** (`AGENTS-dev.md`) — admitted by **universal need, verified by execution**: build, test (including a single test), lint, run — exact invocations with flags, plus warnings where an operation is expensive or the obvious guess fails. Derivability is no objection: rediscovery is paid at the start of every session, and a derived command is a guess — both trials found repos where the obvious guess is wrong. +4. **Verification** (`AGENTS-dev.md`) — same rule: what must pass before commit and push, as the exact commands CI runs. +5. **Conventions that differ from defaults** (`AGENTS-dev.md`) — admitted when **the agent's default assumption is wrong**: an agent writing new code follows ecosystem norms unless told otherwise. Each line links its enforcement point or source file. Not admitted for being unusual, intricate, or interesting — a fact nobody would get wrong by default is not a convention line. +6. **Where things are** (`AGENTS-dev.md`) — admitted by **localization value**: entry points where work actually lands, and "working on X? read Y first" pointers. Earned per pointer, never exhaustive. Details go behind links, never inline. +7. **Known pitfalls** (`AGENTS-dev.md`) — admitted by **observed failure only**: a lesson already recorded in the repo's instruction files or notes, the maintainer's recollection, session-log evidence, or a mistake the writing session itself made and caught while working. A scan cannot nominate a pitfall: the repo yields hundreds of trap-looking facts and no property of the fact separates the few that cause real mistakes — that signal exists only in observed behavior. A surprising fact from scanning becomes, at most, an interview question ("do agents actually trip on this?"). Apparent derivability is irrelevant here in both directions: most working pitfall rules restate something readable, because agents misread it anyway. + +**Retiring pitfall and policy lines:** a line retires only when the thing it guards is gone (removed, or now mechanically enforced) or the human retires it. Absence of recent failures is never grounds — a working rule erases its own evidence, and half the value of the guide is failures that no longer happen. ## What never enters | Excluded | Why | |---|---| -| Repo overviews, directory trees, tech-stack lists | Measured zero benefit at real cost; agents derive structure fresh in seconds and stored maps rot | -| Anything readable from the code | A paraphrase is a second copy that drifts while the original stays true | +| Repo overviews, directory trees, tech-stack lists | No measured benefit; agents derive structure fresh, and stored copies drift | +| Facts included for being interesting or unusual | Interest is not evidence of need — this is the failure mode this skill replaces | | Style rules an agent is meant to self-enforce | That job belongs to a formatter, linter, hook, or CI check — propose one instead | -| Platitudes ("write clean code") | Already the agent's default; changes nothing | -| Fast-changing facts, pasted code, changelog content | Staleness magnets — the guide is not a memory system | -| Aspirational state | What the system *should* become belongs in specs; an agent acting on aspiration ships fiction | +| Platitudes ("write clean code") | Already the agent's default | +| Fast-changing facts, pasted code, changelog content | Go stale quickly; the guide is not a memory system | +| Aspirational state | Belongs in specs; the guide describes what is | ## Shape and style -Terse imperative lines under plain headings — no prose paragraphs beyond Orientation, no introduction, no summary. Present truth only: never the story of an edit ("we removed X because…" is banned; git holds history). Every named decision, doc, file, or system carries a path or URL a fresh session can follow. Links must survive the file's location: the guide links only to repo-relative paths that exist. Target shape: +Terse imperative lines under plain headings — no prose paragraphs beyond Orientation, no introduction, no summary. State present truth only; git holds history. Every named decision, doc, file, or system includes a repo-relative path or URL that exists. Target shape (single-file form): ```markdown # acme-billing @@ -43,14 +49,14 @@ Planning lives in docs/planning/, tickets in Linear (ACME board), PRs on GitHub. ## Commands - Test: `pnpm test` (vitest — do NOT use jest syntax); single file: `pnpm test -- path/to/file` -- Full suite takes ~15 min; run single files while iterating. +- The full suite is slow; run single files while iterating. ## Before pushing - `pnpm lint && pnpm test` must pass — same commands CI runs. ## Policy - Never push to main; PRs only, one approval required. -- `legacy/` is frozen: never modify; it is being strangled out. +- `legacy/` is frozen: never modify; it is being replaced. - `src/generated/` is generated by `pnpm codegen` — never edit by hand. ## Conventions that differ from defaults @@ -68,12 +74,12 @@ Planning lives in docs/planning/, tickets in Linear (ACME board), PRs on GitHub. ## Editing an existing guide -A handwritten `AGENTS.md` is the baseline, not raw material. Keep its phrasing where it works, propose changes as a diff, and never delete human-written content without agreement — stale human content gets flagged with its evidence, then removed only on confirmation. Human-written content may violate this contract's style and survive; the contract binds what this skill writes, not what humans keep. +A handwritten guide is the baseline, not raw material. Keep its phrasing where it works, propose changes as a diff, and never delete human-written content without agreement. Its recorded lessons — wherever they live: the old `AGENTS.md`, `CLAUDE.md`, notes files, warnings in READMEs — are standing maintainer testimony: keep them by default, and challenge one only with evidence that its referent is gone or wrong, never because scans show no recent failures. Restructuring a single old file into the two-file form is fine; losing its content is not. ## Scoped guides -A subsystem earns its own nested `AGENTS.md` when work keeps landing there and its truths don't belong at root — most harnesses auto-load the nearest file. 25–35 lines answering, in order: what is this, who owns it, how do I run it, what's surprising, where do I go next. Every path verified. Coverage is demand-driven, never wall-to-wall. +A subsystem gets its own nested `AGENTS.md` when work keeps landing there and its truths don't belong at root — most harnesses auto-load the nearest file. 25–35 lines answering, in order: what is this, who owns it, how do I run it, what's surprising, where do I go next. Every path verified. Created when a subsystem needs one, never for every subsystem. ## Small guides are success -A small project needs Orientation, Commands, Verification, and little else. When the evidence supports ten lines, ten lines is the deliverable — manufacturing content to look thorough is exactly the failure this skill replaces. +When the evidence supports ten lines, ten lines is the deliverable.