Alex Verkhovsky
c4ec1837b8
* feat(project-context): adopt handwritten instructions via a ledger A non-empty instruction file without a managed block now routes to a new adopt intent — the migration form of refresh — never to setup. Every existing instruction enters a retention ledger (retain, rewrite, relocate, automate, delete) presented in full before anything is written; a deletion needs one of four grounds, and one without hard grounds is held for line-item approval that block approval never grants. Best practices replace the derivability test with a retrieval-cost test, admit compact architecture and toolchain pins, and gate nested AGENTS.md files on loading verified for every harness in use, falling back to path-qualified root lines. The explanation and how-to docs follow the same reframing. * fix(project-context): scope splice preservation to the block itself Step 5's byte-identical clause read as forbidding any change outside the markers, which contradicted the ledger's approved rewrites, relocations, and deletions of handwritten instructions there. The splice still touches nothing outside the markers; outside text changes only through a settled ledger entry or a proposed fix the user has seen. Also from review: the how-to routing sentence now distinguishes adopt from refresh, template section 4 includes pyproject.toml, and the theory doc qualifies the source-recovery claim to implementation behavior. * docs(project-context): plain-language pass on how-to and explanation The reader-facing pages had absorbed the skill's internal vocabulary — the disposition taxonomy, approval tiers, harness loading mechanics — and metaphors that mean nothing to a casual reader. Replace them with the user-level promise: you see what happens to every existing instruction before anything is written, and nothing is deleted without your sign-off. The theory page keeps its technical depth by design. * docs(project-context): drop behavior sentence from skill description The description is a routing trigger; the adopt verb already carries the cue, and the preservation behavior is documented where it runs. * refactor(project-context): move intent-conflict rule from Args to detection The Args line declares the interface; the guard against silently obeying a supplied intent that contradicts the detected state belongs in step 4, where detection happens. * docs(project-context): trim Args platitude, mark conflict case as example * docs(project-context): replace canonical/toolchain-pin jargon with plain terms Right commands to use, required tool versions, cross-component rules - same meaning, readable by anyone. * docs(project-context): plain-language the cross-component admission rule * docs(project-context): rewrite the adopted-content budget paragraph readably
5.1 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Project Context | How bmad-project-context writes a repository's agent instructions — a small verified block in AGENTS.md |
|
bmad-project-context sets up a repository so AI agents work well in it. The output is a small verified block inside the repo's AGENTS.md: what the org requires, the commands that were actually run, the conventions where the obvious guess is wrong, and the mistakes agents keep making here.
It is a conversation, not a generator. You bring the rules you want followed — governance, security, coding standards — and it discovers and verifies the rest. The human is in the loop for every write; there is no unattended mode.
For the full reasoning, including what is deliberately not captured and why, see The Theory of Project Context.
What goes in, and what doesn't
The governing line is what a fact costs to retrieve at the moment it is needed. Agents read code more accurately than they read prose describing code, and a stored description of what they find cheaply is a stale duplicate charged on every call — so repo overviews, directory trees and tech-stack lists never enter. What stays is what an agent rediscovers expensively, or only after the mistake.
What earns a line is what the code cannot say:
- Policy the org requires — frozen paths, generated files, branch rules, security and compliance.
- What a config file cannot say about running the project — the catch, and which command is the right one to use, not a copy of every script.
pnpm testis already inpackage.json; that the suite takes eleven minutes, or needs a service running first, is not. - Conventions that differ from ecosystem defaults, because an agent follows the norm unless told otherwise.
- Known pitfalls, admitted only from observed failure — a lesson already recorded, the maintainer's recollection, a mistake fixed repeatedly in git history, or one the writing session made and caught. A trap-looking fact from a scan becomes a question, never a line.
- Cross-component rules and required versions — the few rules that must hold across parts of the system an agent cannot see from the file it is editing, and the tool versions the project actually builds with.
- Pointers to where work lands, and to nested or linked files worth reading first.
Every rule the skill applies is written out in references/best-practices.md, with the evidence behind it. The skill uses it to assess what your repo already has, and explains its reasoning back to you at the end.
The intents
| Intent | What it does |
|---|---|
| Setup | For a repo with no instructions worth preserving. Ask what you bring, discover and verify the rest, show you the block, then write it. |
| Adopt | For instructions you already wrote. You see where every one of them went before anything is written; nothing is deleted without your sign-off. |
| Refresh | The same run against an existing block: re-run its commands, diff deletions and renames since the recorded commit, update what moved. |
| Record | Capture one observed agent mistake at the moment it happens. A recurring or costly one earns a line. |
| Audit | Re-verify and prune. The block ends smaller or equal, never larger. |
How agents load it
AGENTS.md at the repo root, which every major coding harness reads. BMad owns only the region between <!-- bmad:context --> and <!-- /bmad:context -->; everything you write outside those markers is preserved byte for byte, and a refresh never touches it.
Monorepo components and nested repositories get their own file under the same rules, listed as pointers in the parent. A large rule set that only applies to one directory can move into an AGENTS.md file in that directory — but only after checking that the tools you use actually read it there. If they don't, the rules stay in the root file, each naming the directory it applies to.
Repo or home directory
What this skill writes belongs committed to the repository — shared by the team, consistent across machines, versioned with the code it constrains. If you find the same rules repeating across every project, or they are your personal preferences rather than the team's, they belong in your agent's global configuration in your home directory instead.
Interaction with architecture
Decisions are born in bmad-architecture. If a genuinely contested design decision surfaces here — real tradeoffs, multiple viable shapes — the skill says it deserves bmad-architecture rather than quietly making the call.
Replaces two earlier skills
:::note[Deprecated: bmad-document-project and bmad-generate-project-context]
Both earlier skills are deprecated and now forward here. bmad-generate-project-context produced a single project-context.md — if you have one, setup offers to absorb its content rather than orphaning it. bmad-document-project scanned a brownfield repo into generated documentation, which is the approach the evidence went against; the deeper "explain this system and its rationale" material is a different altitude and is coming as its own capability.
:::