bmad 6.11
This commit is contained in:
@@ -0,0 +1,110 @@
|
||||
---
|
||||
name: bmad-project-context
|
||||
description: 'Set up, refresh, or audit a repository''s agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfall lines. Must be invoked by name.'
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
A conversation that produces a repository's agent instructions: a small verified block inside `AGENTS.md`. The user brings rules they want followed — governance, security, standards — and the repository supplies the rest, verified.
|
||||
|
||||
Conversational always; the user approves every write.
|
||||
|
||||
**Args:** intent (`setup` | `refresh` | `record` | `audit`); a target repo or path; extra source paths or URLs. Supplied values skip their questions.
|
||||
|
||||
## Resolution rules
|
||||
|
||||
- Bare paths and `{skill-root}` (e.g. `references/best-practices.md`) resolve from this skill's installed directory.
|
||||
- `{project-root}` → the project working directory.
|
||||
- **Target** → the repository being described, defaulting to `{project-root}`. If it resolves to more than one working tree, or to one the user cannot commit in, ask before writing.
|
||||
|
||||
## On Activation
|
||||
|
||||
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.
|
||||
3. **Load `references/best-practices.md` and `references/template.md` before anything else.** Every decision below is made against them.
|
||||
4. Detect intent and greet `{user_name}`: **setup** (no block in the target — the default), **refresh** (a block exists), **record** (the user reports a mistake agents made), **audit** (re-verify and prune). Fold `{workflow.external_sources}` into the source list. Execute `{workflow.activation_steps_append}`.
|
||||
|
||||
## Setup and Refresh Steps
|
||||
|
||||
No writes until step 5!
|
||||
|
||||
### 1. Assess and report
|
||||
|
||||
Read `AGENTS.md`, harness or agent specific rule files, docs folders, and any notes carrying lessons. Report what exists and how it measures up, per `best-practices.md`.
|
||||
|
||||
If the target contains separable units — a workspace manifest listing members, or directories carrying their own build manifest — name them and ask whether this run covers the root only, all of them, or which. Absent that evidence, do not ask. Sibling repositories are not children; each is its own target, offered in turn.
|
||||
|
||||
### 2. Ask what they bring
|
||||
|
||||
Rules to follow regardless of what the repo does: governance, security and compliance, coding standards, style guides, frozen areas. Ask for outside documents too — handbooks, wikis, architecture docs, MCP knowledgebases. Note the paths; do not read them yet.
|
||||
|
||||
Greenfield: this is the whole content. Brownfield: it is the half no scan reaches.
|
||||
|
||||
### 3. Discover and verify
|
||||
|
||||
Fan out with parallel subagents against what the sections need — executable config and CI for policy and for what they already state, tracked source for conventions and boundaries, targeted history for constraints whose reason must still hold.
|
||||
|
||||
`package.json`, a `Makefile`, `pyproject.toml`, and CI config are read to know what the block must not repeat. Their caveats come from the human in step 4. Path-check every claim naming a file.
|
||||
|
||||
Each child agreed in step 1 is scanned as its own scope, against its own manifests.
|
||||
|
||||
### 4. Interview the gaps
|
||||
|
||||
Only what no scan reaches: what agents keep getting wrong here, what is off limits, what a domain term means, why a constraint exists.
|
||||
|
||||
- Never ask what a scan could answer. Asking the user to confirm a path-checked claim, or one a config file already states, is a defect.
|
||||
- Ask recall questions, not review lists. Never hand the user a selection problem a scan created.
|
||||
- A mistake this session made and caught is observed evidence — offer it.
|
||||
- A repeatable command spotted in anything read this session — a log, a doc, its own runs — whose correct form is not the obvious guess is a candidate line: offer it. E.g. `uv run pytest` where plain `pytest` looks right but runs outside the project environment.
|
||||
- Batches of at most eight; fewer is better. A batch yielding nothing new means write.
|
||||
- When the repo contradicts the user, show the evidence and ask. Never write the claim as given, never drop it silently.
|
||||
|
||||
### 5. Show the block, then write it
|
||||
|
||||
Compose against `template.md`. For each candidate, ask first whether a hook, lint rule, or CI check enforces it better than prose; if so propose the check, and the line becomes the fallback if they decline.
|
||||
|
||||
**Show the complete block before writing it**, and every child block alongside it — one approval covers the set. On approval, splice between the markers, leaving everything outside them byte-identical. Fill each provenance line with today's date and the verified SHA.
|
||||
|
||||
Where an instruction elsewhere contradicts the block in a way that changes behavior — a stale `CLAUDE.md` line, a retired command — propose the fix to that file. Two live contradictory instructions is a defect.
|
||||
|
||||
Never commit.
|
||||
|
||||
### 6. Close
|
||||
|
||||
- What went in, and what was left out and why.
|
||||
- Why, in the user's terms, from `best-practices.md` — why it is small, why what the repo already states stays out, why a pitfall line stays until its cause is gone.
|
||||
- How it loads, and that other harness files can point at it.
|
||||
- Maintenance: re-run after significant change, `record` the moment an agent gets something wrong, prefer a check over a new line.
|
||||
- Rules repeating across their projects, or personal rather than the team's, belong in their global agent config.
|
||||
|
||||
### Refresh
|
||||
|
||||
Same steps, step 1 as a diff. Read the provenance line, re-verify every path and every caveat, and run `git log --diff-filter=DR --name-only` since the recorded SHA against every line — update or remove lines whose evidence is gone. Never re-ask what a prior run settled; the interview shrinks to what changed about how the team works. The block grows only on new evidence.
|
||||
|
||||
### Greenfield
|
||||
|
||||
Seeded from a spec or planning document, or interview alone. Commands that do not exist yet are written as explicit TODOs naming the decided stack, never a guessed invocation stated as fact, and verified on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — goes to `bmad-architecture`.
|
||||
|
||||
### Migration
|
||||
|
||||
If the target has a `project-context.md` from the retired skills, commonly under `{output_folder}`, read it in step 1 and offer to absorb its content. Do not delete it without agreement, and do not silently orphan it.
|
||||
|
||||
## Record
|
||||
|
||||
Capture one observed agent mistake as it happens — the only admissible source for a pitfall line.
|
||||
|
||||
Take the task, the mistake, the correction, and its evidence. Check the block for a line already covering it. One occurrence is noted; a recurring or costly mistake earns a line now — an exact invocation under **Running and verifying** when it is a command error, otherwise a pitfall. Write it and show the diff. If it is mechanically preventable, propose the hook, lint rule, or CI check instead.
|
||||
|
||||
## Audit
|
||||
|
||||
Re-check every caveat, path-check every file, follow every pointer, and ask of every line whether removing it would change agent behavior. Check for contradictions with other instruction files.
|
||||
|
||||
Failing lines move behind an observable trigger, get fixed, or are deleted — confirm deletions first. **A policy or pitfall line goes only when the thing it guards is gone or the user retires it; nothing failing lately is not grounds.** Audit ends smaller or equal.
|
||||
|
||||
## Children
|
||||
|
||||
A component, nested repository, or extracted rules file gets its own file under the same shape when work keeps landing there and its truths do not belong at the parent level. Rules bounded to a directory go in a nested `AGENTS.md` there, attached by location. Use a linked file only when the trigger is not a path.
|
||||
|
||||
A chosen child that ends with nothing its parent does not already say gets no file. Say so and move on.
|
||||
|
||||
List every child in the parent's **Where things are** with one line and its path. Discovery never depends on the harness finding it.
|
||||
@@ -0,0 +1,24 @@
|
||||
# DO NOT EDIT -- overwritten on every update.
|
||||
#
|
||||
# Workflow customization surface for bmad-project-context.
|
||||
# Team overrides: {project-root}/_bmad/custom/bmad-project-context.toml
|
||||
# Personal overrides: {project-root}/_bmad/custom/bmad-project-context.user.toml
|
||||
#
|
||||
# Merge rules: scalars override (last layer wins); arrays append.
|
||||
|
||||
[workflow]
|
||||
|
||||
# --- Universal defaults ---
|
||||
activation_steps_prepend = []
|
||||
activation_steps_append = []
|
||||
# Deliberately empty: this skill's own output (AGENTS.md) is loaded by the
|
||||
# harness, not through this array. Users append their own standing facts.
|
||||
persistent_facts = []
|
||||
on_complete = ""
|
||||
|
||||
# Standing outside-the-repo sources offered at every setup/refresh run
|
||||
# (untrusted until verified against the repo or user-confirmed).
|
||||
# Append-only. Entries: "file:{project-root}/..." or "file:/abs/path" for
|
||||
# docs, "skill:name" to consult a skill, plain text for a standing fact,
|
||||
# "tool:name" for an MCP knowledgebase.
|
||||
external_sources = []
|
||||
@@ -0,0 +1,65 @@
|
||||
# What belongs in a repo's agent instructions
|
||||
|
||||
Rules for deciding what goes in the block, for judging what a repo already has, and for explaining both to the user.
|
||||
|
||||
## The test
|
||||
|
||||
Can an agent derive this by reading the repository? If yes, leave it out — a stored copy is a stale duplicate of something the agent reads more accurately first-hand, and it is charged on every session. Write down what the code cannot say.
|
||||
|
||||
## Admit
|
||||
|
||||
- **Policy the code cannot express** — branch rules, frozen and protected paths, generated files, secrets, security and compliance. Stated by a human or read off an enforcing config, never inferred.
|
||||
- **What a config file cannot say about running the project** — the root test script does nothing in this workspace, integration tests need a service up first, the suite takes eleven minutes so iterate on single files, the `Makefile` is the real entry point and `package.json` is vestigial, CI runs a typecheck the test script does not. The invocation itself is already stated in `package.json`, `Makefile`, `pyproject.toml`, or CI config and does not earn a line — the correction or the caveat does.
|
||||
- **Conventions that differ from ecosystem defaults.** An agent follows the norm unless told otherwise, so only the divergences earn a line. Command invocations count: when the obvious command is wrong here — a bare-repo prefix, a required wrapper — the exact working invocation earns a line, and no observed mistake is needed to admit it.
|
||||
- **Pitfalls with observed evidence** — a recorded lesson, the maintainer's recollection, the same mistake fixed repeatedly in history, or one this session made and caught. A repo yields hundreds of trap-looking facts and none of them predict real mistakes; only observed behavior does. A surprising scan finding is a question to ask, not a line to write.
|
||||
- **Runtime behavior invisible from the repo** — replaying webhooks, lying health endpoints, environment quirks — once a human confirms it.
|
||||
- **Entry points and pointers** to where work lands.
|
||||
|
||||
Prefer prohibitions to advice, and name the permitted alternative in the same line.
|
||||
|
||||
## Exclude
|
||||
|
||||
| | Why |
|
||||
|---|---|
|
||||
| Repo overviews, directory trees, stack lists | Derived fresh, more accurately; stored copies rot |
|
||||
| Anything included for being interesting | Interest is not need |
|
||||
| Style rules an agent self-enforces | Belongs in a formatter, linter, hook, or CI check — propose the check instead |
|
||||
| Platitudes | Already the default |
|
||||
| Commands already stated in `package.json`, a `Makefile`, or CI config | Read from the source of truth; a copy drifts the moment a script is renamed |
|
||||
| Pasted code, changelog content, fast-changing facts | Stale immediately |
|
||||
| Aspirational state | Describe what is; intent belongs in specs |
|
||||
| History and edit narration | Git holds it; state present truth |
|
||||
|
||||
## Retire
|
||||
|
||||
A policy or pitfall line goes only when the thing it guards is gone, or the user retires it. Nothing failing lately is not evidence — a working rule erases its own evidence.
|
||||
|
||||
Every other line faces one question at each write: would removing it change agent behavior? If no, cut it.
|
||||
|
||||
## Size
|
||||
|
||||
Every line is paid in every session, and instruction-following degrades as the loaded set grows. Count what other always-loaded files add. Over budget means cut the weakest lines or move them behind a trigger — never raise the budget. Ten lines of evidence means ten lines.
|
||||
|
||||
## Retrieval
|
||||
|
||||
An index the agent must choose to fetch gets skipped; one already in context does not. Keep everything load-bearing in the block. A pointer out of it names a trigger the agent can observe — a path, a file type, a named task — never one it must judge ("when the task is complex") or track about itself ("before your first edit").
|
||||
|
||||
Rules bounded to a directory go in a nested `AGENTS.md` there, attached by location rather than by pointer. Use a linked file only when the trigger is not a path.
|
||||
|
||||
## Maintain
|
||||
|
||||
- Re-check that caveats still hold — a slow suite that got fast, a workaround for a bug that was fixed.
|
||||
- Diff deletions and renames since the verified SHA against every line.
|
||||
- Record provenance in the block so the next run knows what it is diffing from.
|
||||
- Capture mistakes when they happen, not at review time. One occurrence is a note; recurrence earns a line.
|
||||
- Route anything mechanically preventable to a hook, lint rule, or CI check. A check that lands deletes its line.
|
||||
|
||||
## Repo or home directory
|
||||
|
||||
This block belongs committed: shared by the team, consistent across machines, versioned with the code it constrains.
|
||||
|
||||
Two things belong in the user's global agent config instead — rules repeating across all their projects, and personal preferences that are theirs rather than the team's.
|
||||
|
||||
## Judging an existing file
|
||||
|
||||
Report, in this order: what is derivable filler, what is unverifiable or stale, what is missing against the sections above, and what is already good. Keep recorded lessons by default — they are maintainer testimony, and are challenged only with evidence that the thing they name is gone or wrong.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Block shape
|
||||
|
||||
Sections in this order. Omit any section with nothing that passes its rule — never write an empty one. Admission rules: `best-practices.md`.
|
||||
|
||||
1. **Orientation** — three or four sentences: what this is, the stack, where planning and deeper docs live.
|
||||
2. **Policy** — what the org requires.
|
||||
3. **Where things are** — entry points, and pointers to children and linked files.
|
||||
4. **Running and verifying** — only what `package.json`, a `Makefile`, or CI config does not already say.
|
||||
5. **Conventions that differ from defaults**
|
||||
6. **Known pitfalls**
|
||||
|
||||
Terse imperative lines under plain headings. No prose beyond Orientation, no introduction, no summary. A bare fact appears only as the justification clause of an instruction — "Exclude `vendor/` from searches, it is 60% of tracked files", never "`vendor/` is 60% of tracked files". A prohibition names the alternative. At most two emphasis markers in the whole block.
|
||||
|
||||
## Worked example
|
||||
|
||||
````markdown
|
||||
<!-- bmad:context -->
|
||||
<!-- Verified 2026-08-08 against a1b2c3d. Managed by bmad-project-context; edits inside this block are replaced on refresh. Keep anything you want preserved outside the markers. -->
|
||||
|
||||
## acme-billing
|
||||
|
||||
Payment processing for Acme storefronts. TypeScript/Node, pnpm, Postgres. Planning lives in `docs/planning/`, tickets in Linear (ACME board).
|
||||
|
||||
## Policy
|
||||
|
||||
- Never push to main; PRs only, one approval.
|
||||
- Never modify `legacy/` — frozen, being replaced. New work goes in `src/`.
|
||||
- Never hand-edit `src/generated/` — run `pnpm codegen`.
|
||||
|
||||
## Where things are
|
||||
|
||||
- Webhook handling: `src/routes/webhooks.ts`; conventions in `docs/webhooks.md`
|
||||
- Writing a migration? Read `docs/db-rules.md` first — ordering, transaction boundaries, pool limits.
|
||||
- Billing service has its own guide: `services/billing/AGENTS.md`
|
||||
|
||||
## Running and verifying
|
||||
|
||||
- Run single test files while iterating; the full suite takes ~11 minutes.
|
||||
- Integration tests need `docker compose up -d` first, and fail confusingly without it.
|
||||
- CI also runs `pnpm typecheck`, which `pnpm test` does not cover.
|
||||
|
||||
## Conventions that differ from defaults
|
||||
|
||||
- Money is integer cents (`amountCents`), never floats — `src/lib/money.ts`
|
||||
- All DB access goes through repositories in `src/repos/`; never call the client directly.
|
||||
|
||||
## Known pitfalls
|
||||
|
||||
- Stripe webhooks replay in staging every 6h — handlers must be idempotent.
|
||||
- Use vitest matchers, not jest — agents repeatedly add jest syntax here.
|
||||
|
||||
<!-- /bmad:context -->
|
||||
````
|
||||
|
||||
Fill the provenance line with the real date and the commit SHA verified against. Refresh diffs from that SHA.
|
||||
Reference in New Issue
Block a user