bmad-method 6.10.1-next.50 → 6.10.1-next.52

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.10.1-next.50",
+  "version": "6.10.1-next.52",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/src/bmm-skills/agents/bmad-agent-analyst/customize.toml

@@ -101,5 +101,5 @@ skill = "bmad-prfaq"
 
 [[agent.menu]]
 code = "PC"
-description = "Curate the verified project context AI agents load — kernel + knowledge bundle (ingest, query, audit)"
+description = "Set up or refresh this repo's agent instructions — verified commands, policy, conventions, pitfalls (setup, refresh, record, audit)"
 skill = "bmad-project-context"

package/src/bmm-skills/module-help.csv

@@ -1,6 +1,6 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
-BMad Method,bmad-project-context,Project Context,PC,"Curate the verified project context AI agents load: a small always-loaded kernel plus a knowledge bundle. Ingest (brownfield or greenfield), query, and audit — replaces document-project and generate-project-context.",,,anytime,,,false,project_knowledge,kernel.md + context bundle
+BMad Method,bmad-project-context,Project Context,PC,"Set up or refresh a repo's agent instructions so AI agents work well in it: verified commands, policy, conventions that differ from defaults, and known pitfalls. Setup, refresh, record, and audit — replaces document-project and generate-project-context.",,,anytime,,,false,repo root,AGENTS.md managed block
 BMad Method,bmad-build,Build,BD,Official Phase 4 implementation loop: clarify intent plan implement review and present.,,,ship,bmad-sprint-planning,bmad-code-review,true,implementation_artifacts,spec and project implementation
 BMad Method,bmad-spec,Spec,SPC,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
 BMad Method,bmad-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal

package/src/bmm-skills/plan/bmad-document-project/SKILL.md

@@ -5,6 +5,10 @@ description: 'Deprecated — forwards to bmad-project-context. Use when the user
 
 # DEPRECATED — forwards to bmad-project-context
 
-Tell the user: this skill is deprecated — `bmad-project-context` now owns this job, and instead of generating documentation volume it curates a small verified context system (an always-loaded kernel plus a knowledge bundle). Invoke `bmad-project-context` next time.
+Tell the user two things.
 
-Then invoke `bmad-project-context` with **ingest** intent, forwarding the user's original request and any paths or documents they supplied, verbatim. It takes the workflow from here.
+First: this skill is deprecated. Generating documentation volume about a codebase made agents worse, not better — agents read code more accurately than prose describing code, and the generated set was stale on arrival. `bmad-project-context` owns what remains useful: a small verified block in the repo's `AGENTS.md` carrying what the code cannot say — required policy, conventions that differ from defaults, what running the project takes that no config file states, and known pitfalls.
+
+Second, so they are not surprised by what they get: the deeper "explain this system, its rationale and its history" material is a different altitude and is not part of that block. It is coming as its own capability. If that is what they were after, say so plainly rather than producing a thin substitute.
+
+Then invoke `bmad-project-context` with **setup** intent, forwarding the user's original request and any paths or documents they supplied, verbatim. It takes the workflow from here.

package/src/bmm-skills/plan/bmad-generate-project-context/SKILL.md

@@ -5,6 +5,6 @@ description: 'Deprecated — forwards to bmad-project-context. Use when the user
 
 # DEPRECATED — forwards to bmad-project-context
 
-Tell the user: this skill is deprecated — `bmad-project-context` now owns this job. Instead of one generated `project-context.md`, it curates a small verified context system (an always-loaded kernel plus a knowledge bundle); any existing `project-context.md` keeps loading and becomes a mining source. Invoke `bmad-project-context` next time.
+Tell the user: this skill is deprecated — `bmad-project-context` now owns this job. Instead of one generated `project-context.md`, it writes a small verified block inside the repo's `AGENTS.md`, and any existing `project-context.md` is offered up for absorption rather than left orphaned. Invoke `bmad-project-context` next time.
 
-Then invoke `bmad-project-context` with **ingest** intent, forwarding the user's original request and any inputs they supplied (architecture doc, spec, preferences), verbatim. It takes the workflow from here.
+Then invoke `bmad-project-context` with **setup** intent, forwarding the user's original request and any inputs they supplied (architecture doc, spec, standards, preferences), verbatim. It takes the workflow from here.

package/src/bmm-skills/plan/bmad-project-context/SKILL.md

@@ -1,74 +1,109 @@
 ---
 name: bmad-project-context
-description: 'Curate and maintain verified project context for AI agents. Use when the user says "project context", "document project", "generate project context", "refresh context", or "audit context"'
+description: 'Set up or refresh agent instructions so AI agents work well in it. Use when the user says "project context", "set up AGENTS.md", "document this project", "refresh context", "audit context", wants to apply coding standards or governance to a repo, or wants to record a mistake agents keep making'
 ---
 
 # Overview
 
-You are the curator of everything the code can't say. This skill builds and maintains a project's context system: a tiny always-loaded **kernel** and a **bundle** of small verified knowledge entries — architecture rationale, unobvious conventions, landmines, org requirements. The governing thesis, backed by measurement: generated documentation makes agents worse; a curated minimum of verified, non-derivable truths makes them better. So you curate the minimum non-derivable set and never describe what the code already says.
+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.
 
-Works with a full BMad install or standalone in any repo with no framework at all.
+Conversational always; the user approves every write.
 
-**Args:** intent (`ingest` | `query` | `audit`); `--auto` for headless; a scope path to bound the run; placement (`bmad` | `agent-files` | `both`); a bundle-root override; extra source paths or URLs to mine. Supplied values are used directly and skip their questions. Script interface: `uv run {skill-root}/scripts/context.py --help`.
+**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/kernel-contract.md`) resolve from this skill's installed directory.
+- 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. Mechanics: every mechanical fact comes from the script, never from guessing. If `{project-root}/_bmad/scripts/context.py` is missing (standalone repo), run `uv run {skill-root}/scripts/context.py bootstrap` once — it installs itself there. All later calls: `uv run {project-root}/_bmad/scripts/context.py <command>` (`--json` on any command for machine reads; `--help` for the full interface).
-3. Config comes from one resolution, never hand-merged: `uv run {project-root}/_bmad/scripts/context.py config --json`. It delegates to the installed BMad resolver (`resolve_config.py`) when present and otherwise falls back through the legacy and standalone config files itself, so the script and this session can never disagree about paths. Read `{user_name}`, `{communication_language}` (use it every turn), `{document_output_language}`, `{project_knowledge}`, `{output_folder}` (standalone default `_bmad-output`), and `context_placement` from its output.
-4. **First run** (no kernel at `{project_knowledge}/kernel.md`), interactive only: load `references/placement.md` and settle the bundle location and placement there. In auto mode: detect (BMad install → bmad, else agent-files), record `context_placement`, don't ask.
-5. Init or resume the memlog at `{project_knowledge}/.memlog.md` (`uv run {project-root}/_bmad/scripts/memlog.py init --path ...` if absent; if present, read it once — it is the record of every prior run, and refresh diffs against it instead of starting over). If `memlog.py` itself is missing (standalone repo), append one-line typed entries to the same file directly — append-only, never rewritten.
-6. Detect intent — **ingest** (build or refresh; the default), **query** (answer from the bundle), **audit** (shrink and re-verify) — and greet `{user_name}`. For interactive ingest, ask what they bring before anything scans: sources outside the repo (org handbooks, wiki or Notion exports, prior architecture docs, MCP knowledgebases) and any area to focus on — note the paths for subagent scanning, don't read them now; when a named source is huge, ask one bounding question rather than scanning it whole. Fold `{workflow.external_sources}` entries into the same source list. Auto mode skips the ask, scans what's discoverable, and logs that as an assumption. Execute `{workflow.activation_steps_append}`.
+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}`.
 
-## Engine disciplines — every intent, every mode
+## Setup and Refresh Steps
 
-- Every user decision, confirmed claim, rejected claim, and idea lands in the memlog the moment it happens — never batched for session end.
-- **Orchestrate the scanning.** Discovery is yours to plan with whatever tools fit, but make good use of parallel subagents: they scan, returning claims with evidence paths and an inferred|needs-confirmation mark; you interrogate and decide, and never grind a large tree through your own context.
+No writes until step 5!
 
-## Writing rules — every kernel line, entry, and compass
+### 1. Assess and report
 
-- **Succinct to the point of discomfort.** Every sentence costs context in every future session. If a line can be shorter, it isn't done.
-- **Present truth only.** State what *is*, never the story of the edit — "we removed X because..." is banned prose. Git and the memlog hold history; supersession is a dated frontmatter field.
-- **No reference without a link.** Every mentioned decision, doc, file, or system carries a path, `[[project:entry]]` link, or URL a fresh context can follow. "As previously discussed" is banned.
+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`.
 
-## Ingest
+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.
 
-The outcome: a kernel within its instruction budget and bundle entries for what earned depth — every claim verified (user-confirmed or path-checked, interactive only; auto mode writes the same content marked `generated`) before it's written as truth. Contracts govern the artifacts: load `references/kernel-contract.md` and `references/bundle-contract.md` before writing either.
+### 2. Ask what they bring
 
-**Brownfield:** discover the repo however you judge best, then fan out the source scan (trust ladder: code and configs are ground truth; planning docs next — an ARCHITECTURE-SPINE is the premier source; existing docs folders, org docs, and MCP knowledgebases are untrusted until verified against code). Then interrogate in chunked rounds per `references/interrogation-guide.md` — confirmations first, then only the genuinely unknowable. Never ask what a scan could answer. A bloated docs folder is a source to strip-mine, then recommend archiving.
+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:** same pipeline seeded from a bmad-spec artifact or planning doc (or pure interview). If a genuinely contested decision surfaces — real tradeoffs, multiple viable shapes — say it deserves `bmad-architecture` rather than making the call: decisions are born there; they *live* here.
+Greenfield: this is the whole content. Brownfield: it is the half no scan reaches.
 
-**Refresh:** ingest with existing artifacts — read the memlog, run `sweep`, diff instead of restarting, never re-ask what a prior run settled. Sweep findings resolve against code, not prose: when a path a claim names is gone, the claim is updated to the new reality or removed/marked superseded — re-pointing its `sources` at documents that merely mention it is laundering, not verification. Total size must hold or shrink.
+### 3. Discover and verify
 
-**Scope:** whole repo or a component; in a monorepo, global truths go in the root kernel, component truths in that component's compass. After writing: `index`, then `validate` — its stats block is the measured budget check; an over-budget finding means cut, never raise. Under agent-files/both placement, `sync --dry-run` first and show which files it will touch (confirm on the session's first sync; auto mode skips the ask and logs the written list to the memlog), then `sync`. Close with a fresh-eyes polish pass: a subagent holding only the written artifacts and the two contract files — none of this conversation — returns proposed cuts and rewrites (line, which test it fails, replacement or delete); apply or override, logging overrides to the memlog. The writer who just heard every line justified cannot honestly run the pruning test on it. If subagents are unavailable, run the pass yourself against the contracts. Log the run's summary to the memlog and offer a face artifact.
+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.
 
-## Query
+`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.
 
-Answer a question from the bundle without loading all of it: resolve through `index.md`, and return only the relevant entries with their trust metadata (`verified`/`generated`, sources, staleness — staleness read from `sweep --json`, never recomputed; field semantics in `references/bundle-contract.md`). Anything outside this repo — a `[[project:entry]]` link, a question about another project — goes through `resolve <name>` only, which returns a local path, SHA, and freshness; never crawl the filesystem or workspace for another project's context, because the same query must work when that project isn't checked out. Never dump the bundle. If the bundle can't answer, say so — don't improvise an answer the context doesn't hold.
+Each child agreed in step 1 is scanned as its own scope, against its own manifests.
 
-## Audit
+### 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.
+- 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.
 
-Keep the set small and true: run `validate` and `sweep` — sweep's `missing` list is the path-check for every claim naming a file, and validate's stats block measures the kernel budget — and apply the pruning test to every kernel line — *would removing this line change agent behavior?* If no, it goes. Entries that paraphrase readable code are deleted; unconfirmed `generated` entries are queued for confirmation. Load `references/bundle-contract.md` before mutating any entry — the frontmatter it acts on is defined there. Where an obeya is configured, propose batched promotion of `org-candidate` entries. Audit ends with the context smaller or equal, never larger — present proposed deletions for confirmation (interactive) before removing; in auto mode deletions proceed and every removal lands in the memlog as a typed entry.
+### Refresh
 
-## Modes
+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 — write it, show the diff. If it is mechanically preventable, propose the hook, lint rule, or CI check instead.
+
+## Audit
 
-Interactive is the default: the user is the oracle, in chunked rounds. **Auto mode** (headless, or on request) accepts inferences without confirmation — everything it writes, including path-checked claims, is marked `generated`, never `verified` (`verified` asserts a human was in the loop), and every assumption lands in the memlog. A headless invocation may supply intent (`ingest`|`query`|`audit`), a scope path, a placement, and a bundle root — supplied values are used directly; only genuinely absent ones are inferred, each inference logged as an `assumption`. When invoked headless: never ask; if intent is neither supplied nor inferable, halt with a `blocked` JSON status and `reason`. End with JSON:
+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.
 
-```json
-{"status": "complete", "intent": "ingest", "kernel": "docs/kernel.md",
- "bundle": "docs/", "memlog": "docs/.memlog.md", "placement": "agent-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.
 
-## Face artifacts
+## Children
 
-On request after any intent, generate a human-readable face of the context — always asking its purpose first so it fits (a slide deck for one subsystem, a website of everything, a service explainer). Faces are written outside the bundle (default `{output_folder}`), never indexed, never cited as a source, and regenerated rather than maintained: the organized, indexed markdown is the only source of truth.
+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.
 
-## Finalize
+A chosen child that ends with nothing its parent does not already say gets no file. Say so and move on.
 
-Distill the memlog — every meaningful entry captured in an artifact or set aside as noise — confirm `validate` exits clean, tell the user what exists where (and what was *not* created, if kernel-only). When `AGENTS.md` carries the kernel, say plainly: if your harness doesn't auto-load `AGENTS.md`, make the context file it does load pull this one in (e.g. a `CLAUDE.md` containing `@AGENTS.md`). Then run `{workflow.on_complete}` if non-empty.
+List every child in the parent's **Where things are** with one line and its path. Discovery never depends on the harness finding it.

package/src/bmm-skills/plan/bmad-project-context/customize.toml

@@ -11,15 +11,14 @@
 # --- Universal defaults ---
 activation_steps_prepend = []
 activation_steps_append = []
-# Deliberately empty: the file this skill wants standing (the kernel) is only
-# knowable after config resolves, and the usual **/project-context.md glob is
-# this skill's own superseded output. Users append their own facts.
+# 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 fed into every ingest fan-out at their
-# trust-ladder rank (untrusted until verified against code). Append-only.
-# Entries: "file:{project-root}/..." or "file:/abs/path" for docs,
-# "skill:name" to consult a skill, plain text for a standing fact,
+# 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 = []

package/src/bmm-skills/plan/bmad-project-context/references/best-practices.md

@@ -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.
+- **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.

package/src/bmm-skills/plan/bmad-project-context/references/template.md

@@ -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.

package/src/bmm-skills/ship/bmad-correct-course/SKILL.md

@@ -77,7 +77,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
 | Architecture | `{planning_artifacts}/*architecture*.md` (whole) or `{planning_artifacts}/*architecture*/*.md` (sharded) | FULL_LOAD |
 | UX Design | `{planning_artifacts}/*ux*.md` (whole) or `{planning_artifacts}/*ux*/*.md` (sharded) | FULL_LOAD |
 | Spec | `{planning_artifacts}/*spec-*.md` (whole) | FULL_LOAD |
-| Document Project | `{project_knowledge}/index.md` (sharded) | INDEX_GUIDED |
+| Project Context | `AGENTS.md` in the affected repo (the `bmad:context` block) | FULL_LOAD |
 
 ## Execution
 
@@ -95,12 +95,11 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
    - Process the combined content as a single document
 4. **Priority**: If both whole and sharded versions exist, use the whole document
 
-**Discovery Process for INDEX_GUIDED documents (Document Project):**
+**Discovery Process for Project Context:**
 
-1. **Search for index file** - Look for `{project_knowledge}/index.md`
-2. **If found**: Read the index to understand available documentation sections
-3. **Selectively load sections** based on relevance to the change being analyzed — do NOT load everything, only sections that relate to the impacted areas
-4. **This document is optional** — skip if `{project_knowledge}` does not exist (greenfield projects)
+1. **Read `AGENTS.md`** in the repo the change affects — the block between the `bmad:context` markers carries the policy, frozen paths, and conventions a course correction must respect.
+2. **Follow only the pointers that relate to the impacted areas** — nested component files or linked rule files listed under "Where things are". Do not load them all.
+3. **This document is optional** — skip if the repo has no `AGENTS.md` (greenfield projects).
 
 **Fuzzy matching**: Be flexible with document names — users may use variations like `prd.md`, `bmm-prd.md`, `product-requirements.md`, etc.
 

package/src/core-skills/bmad-forge-idea/scripts/resolve_personas.py

@@ -48,7 +48,9 @@ PARTY_SKILL = "bmad-party-mode"
 def _run_json(cmd):
     """Run a resolver script and parse its JSON stdout. None on any failure."""
     try:
-        out = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+        out = subprocess.run(
+            cmd, capture_output=True, text=True, encoding="utf-8", timeout=60
+        )
     except (OSError, subprocess.SubprocessError):
         return None
     if out.returncode != 0 or not out.stdout.strip():