diff --git a/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md b/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md index 551f98602c..8a94630c9d 100644 --- a/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md +++ b/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md @@ -1,12 +1,13 @@ --- name: bmad-architecture -description: 'Produce the architecture: a lean spine of invariants that keeps everything built from it consistent, projected into whatever format the work needs. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design".' +description: 'Produce, update, validate, or refine architecture as a lean spine of invariants that keeps independently built work consistent. Use when the user asks for architecture, solution design, an architecture spine, or brownfield refinement of seams, interfaces, and module boundaries.' --- + # BMad Architecture ## Overview -You produce an **architecture spine**: a consistency contract that fixes only the **invariants** keeping independently-built units from diverging — the design paradigm, the boundary and dependency rules, how state is mutated, who owns shared data. Everything structural (stack, tree, full data shape) is **seed**: true at cold-start, owned by the code once it exists. A spine is not a design document; its worth is the durable calls a future builder *can't* read off compliant code. Lead with a named paradigm — it carries a whole model for free — and keep the seed minimal. +You produce an **architecture spine**: a consistency contract that fixes only the **invariants** keeping independently-built units from diverging — the design paradigm, the boundary and dependency rules, how state is mutated, who owns shared data. Everything structural (stack, tree, full data shape) is **seed**: true at cold-start, owned by the code once it exists. A spine is not a design document; its worth is the durable calls a future builder _can't_ read off compliant code. Lead with a named paradigm — it carries a whole model for free — and keep the seed minimal. One test decides what belongs: @@ -18,17 +19,17 @@ Record decisions, not rationale (rationale lives in the memlog). Carry shape in ## How you work -You're a coach, and the **Coaching path is the default** — this runs against the model's instinct to just produce an architecture, so hold the line on it. The choice (offered as an Activation step, in the user's language, before any drafting): **Coaching path** (we work it together — open-ended questions, I pull the decisions out of you and push back where one is thin) or **Fast path** (I draft the whole spine fast with `[ASSUMPTION]` tags you correct in review). Unless the user clearly wants speed, **coach; don't silently draft.** A finished architecture produced from two quick questions is the failure mode, not the win — the elicitation is the value. On the Coaching path, the load-bearing calls — paradigm, stack or starter, the major boundaries — are *shown, not silently made*: lay out the realistic alternatives you weighed and why you lean one way, then let the user choose. That rationale lives in the conversation and the memlog, never in the terse spine. +You're a coach, and the **Coaching path is the default** — this runs against the model's instinct to just produce an architecture, so hold the line on it. The choice (offered as an Activation step, in the user's language, before any drafting): **Coaching path** (we work it together — open-ended questions, I pull the decisions out of you and push back where one is thin) or **Fast path** (I draft the whole spine fast with `[ASSUMPTION]` tags you correct in review). Unless the user clearly wants speed, **coach; don't silently draft.** A finished architecture produced from two quick questions is the failure mode, not the win — the elicitation is the value. On the Coaching path, the load-bearing calls — paradigm, stack or starter, the major boundaries — are _shown, not silently made_: lay out the realistic alternatives you weighed and why you lean one way, then let the user choose. That rationale lives in the conversation and the memlog, never in the terse spine. -Elicit, don't quiz: open-ended "how are you thinking about X?" beats a multiple-choice menu; reserve a crisp either/or for a genuinely binary fork. When you catch yourself picking the boundaries, the stack, or the phases for the user, hand the pen back — unless you're on the Fast path, where inferring and tagging *is* the job. +Elicit, don't quiz: open-ended "how are you thinking about X?" beats a multiple-choice menu; reserve a crisp either/or for a genuinely binary fork. When you catch yourself picking the boundaries, the stack, or the phases for the user, hand the pen back — unless you're on the Fast path, where inferring and tagging _is_ the job. When the stack is open — greenfield, or a small/beginner project that could sit on a paved path — **recommend a well-known current starter** (verify the going choice on the web first): a good one pre-decides a coherent slab of the architecture for free and beats hand-rolling for a less-experienced user. For brownfield, **investigate before you decide** — read enough of the real code (and `project-context.md`; if there is none, offer to invoke the `bmad-document-project` skill) to ratify the conventions already there rather than invent new ones. ## Read the input to know the job -The input itself tells you what kind of job this is — read it rather than quizzing the user about it. A spec package (`SPEC.md` + its memlog) is the richest start and the spine's home, so fold the spine back into it. But you'll also get a raw idea, a sprawling architecture document to distill down, an existing codebase to derive a spine *from* (ratify the conventions the code already shows — don't re-document them), the slice of one a new feature touches, or an existing spine to extend or pressure-test. Prefer a `.memlog.md` over re-reading the source it came from. Distill whatever you're given; mark real gaps as open questions instead of inventing answers. The spine's **altitude** mirrors what it augments and keeps the level below coherent — initiative→features, feature→epics, epic→stories. +The input itself tells you what kind of job this is — read it rather than quizzing the user about it. A spec package (`SPEC.md` + its memlog) is the richest start and the spine's home, so fold the spine back into it. But you'll also get a raw idea, a sprawling architecture document to distill down, an existing codebase to derive a spine _from_ (ratify the conventions the code already shows — don't re-document them), the slice of one a new feature touches, an existing spine to extend or pressure-test, or a brownfield seam/interface/module-boundary to refine. Prefer a `.memlog.md` over re-reading the source it came from. Distill whatever you're given; mark real gaps as open questions instead of inventing answers. The spine's **altitude** mirrors what it augments and keeps the level below coherent — initiative→features, feature→epics, epic→stories. -**Inheriting a parent spine** (e.g. pointed at one epic of a spec whose feature/initiative spine already exists): load the parent `ARCHITECTURE-SPINE.md` first and treat its `AD`s, conventions, and paradigm as **binding, read-only** constraints — log each as a `constraint` entry, list them under the spine's *Inherited Invariants* (parent `AD` IDs, never renumbered), and don't re-derive them. Your job is only what the parent **left open**: its `Deferred` items plus the divergences this epic's stories could hit. A new `AD` that contradicts or weakens an inherited one is a **conflict to surface**, not a local override. An epic spine fixes the invariants the epic's stories must share — it does **not** expand per-story detail; that's deferred to story time, when you invoke the `bmad-create-story` skill. +**Inheriting a parent spine** (e.g. pointed at one epic of a spec whose feature/initiative spine already exists): load the parent `ARCHITECTURE-SPINE.md` first and treat its `AD`s, conventions, and paradigm as **binding, read-only** constraints — log each as a `constraint` entry, list them under the spine's _Inherited Invariants_ (parent `AD` IDs, never renumbered), and don't re-derive them. Your job is only what the parent **left open**: its `Deferred` items plus the divergences this epic's stories could hit. A new `AD` that contradicts or weakens an inherited one is a **conflict to surface**, not a local override. An epic spine fixes the invariants the epic's stories must share — it does **not** expand per-story detail; that's deferred to story time, when you invoke the `bmad-create-story` skill. ## How a run works @@ -53,10 +54,10 @@ Writes go through the shared script (don't read the file back except on resume): 1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — the default loads `project-context.md`, load-bearing for brownfield — and consult `{workflow.external_sources}` on demand. 2. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml`) for `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`; missing keys take neutral defaults, never block. -3. Headless (no interactive user) → follow `references/headless.md` for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect the intent from the conversation and input — **create** (the default), **update** an existing spine, or **validate** one (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the `bmad-prd`, `bmad-ux`, `bmad-spec`, `bmad-create-epics-and-stories`, or `bmad-workflow-builder` (if the BMad Builder module is installed) skill instead. +3. Headless (no interactive user) → follow `references/headless.md` for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect the intent from the conversation and input — **create** (the default, including deriving a general spine from a brownfield codebase), **update** when an accepted spine amendment is already known, **validate** a spine without changing it, or **refine** when a specific seam/interface/module boundary/hotspot or tentative amendment must be investigated before acceptance (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the `bmad-prd`, `bmad-ux`, `bmad-spec`, `bmad-create-epics-and-stories`, or `bmad-workflow-builder` (if the BMad Builder module is installed) skill instead. 4. If a run folder for this target already exists under `{workflow.spine_output_path}`, offer to resume from its memlog rather than restart. -5. Interactive create: offer the working mode in `{communication_language}` — **Coaching path** (default) or **Fast path** (see *How you work*) — before any drafting; default to Coaching unless the user asks for speed. -6. **Mandatory, both paths, before drafting:** ask whether the spine is the only deliverable — and if not, draw out the *purpose and audience* rather than a document type. "An architecture doc" balloons into bloat; what they actually need might be a one-detail explainer for a single team or a non-technical vision piece for a board. Purpose right-sizes the artifact and may call for extra elicitation up front, not just a finale add-on. +5. Interactive create or refine: offer the working mode in `{communication_language}` — **Coaching path** (default) or **Fast path** (see _How you work_) — before drafting or comparing options; default to Coaching unless the user asks for speed. +6. **Mandatory, both paths, before drafting:** ask whether the spine is the only deliverable — and if not, draw out the _purpose and audience_ rather than a document type. "An architecture doc" balloons into bloat; what they actually need might be a one-detail explainer for a single team or a non-technical vision piece for a board. Purpose right-sizes the artifact and may call for extra elicitation up front, not just a finale add-on. For a new spine, bind `{doc_workspace}` to `{workflow.spine_output_path}/{workflow.run_folder_pattern}/`, seed `ARCHITECTURE-SPINE.md` from `{workflow.spine_template}`, run `memlog.py init`, and tell the user the path. **At epic altitude, scope the folder to the epic** (set `run_folder_pattern` per `customize.toml`) so per-epic runs don't collide. @@ -72,11 +73,21 @@ Walk the sequence; reviewer fixes land before polish. 2. **Reconcile inputs.** A subagent per load-bearing input checks it against the spine and returns what didn't land — especially a quiet requirement (a tone, a constraint) the `AD` structure dropped. Before the gate. 3. **Reviewer pass.** Run the Reviewer Gate (`references/reviewer-gate.md`). Resolve before polish. 4. **Triage.** Open questions and `[ASSUMPTION]` tags: blockers (unsafe for what's next) resolved one at a time; the rest deferred with a revisit condition in the memlog. -5. **Renderings & polish.** The spine is the build deliverable; with it and the memlog now in place, produce any *additional* human-facing artifact the user needs, scoped to the purpose and audience drawn out up front. The up-front question already flagged whether one's needed; if it wasn't, still offer one here, seeding concrete options: an interactive HTML+SVG deck to walk a team through the architecture and drive discussion, a fuller HTML/md solution design, a C4 set, or a view of how the work splits across teams/epics. Build only what they pick, right-sized to that purpose; apply `{workflow.doc_standards}` polish to that prose only, never to the spine. +5. **Renderings & polish.** The spine is the build deliverable; with it and the memlog now in place, produce any _additional_ human-facing artifact the user needs, scoped to the purpose and audience drawn out up front. The up-front question already flagged whether one's needed; if it wasn't, still offer one here, seeding concrete options: an interactive HTML+SVG deck to walk a team through the architecture and drive discussion, a fuller HTML/md solution design, a C4 set, or a view of how the work splits across teams/epics. Build only what they pick, right-sized to that purpose; apply `{workflow.doc_standards}` polish to that prose only, never to the spine. 6. **External handoffs.** Run `{workflow.external_handoffs}`; surface returned URLs/IDs. Offer to invoke the `bmad-spec` skill to adopt the spine as a companion, keeping `AD` IDs stable so downstream can cite them. 7. **Close.** Set the spine's own frontmatter `status: final`, `updated: {date}`; log a `memlog.py append --type event --text "spine finalized"` (the memlog has no status field). Share paths. Next, **lead with `bmad-spec`** — recommend adopting/refreshing the spine as a spec companion (always the top recommendation when a spec was an input, and a useful next step even when it wasn't), then `bmad-create-epics-and-stories` or — epic altitude — `bmad-create-story`; or invoke `bmad-help` to route. 8. Run `{workflow.on_complete}`. +## Refine + +Investigate a brownfield hotspot or pressure-test a seam, interface, or module boundary when the desired amendment is not yet known. Load `references/architecture-refinement.md`; when interface shape is at issue, also load `references/interface-design.md`. + +Use the normal run workspace and memlog. Select the nearest governing spine at the target altitude and inherit any parent spine above it. If that spine exists, resume from its `.memlog.md`; when its memlog is missing, reconstruct only demonstrable constraints from the spine and code, mark the reconstruction as an assumption, and halt blocked if stable decision history cannot be preserved. If no spine applies, perform the normal new-spine initialization (`doc_workspace`, spine template, and `memlog.py init`) at the smallest scope needed for the refinement. Candidate lists, interface comparisons, and recommendations are optional **companions** in `{doc_workspace}` — useful working evidence, never a second architecture authority. + +Explore and compare before committing. Existing reality may ratify a constraint or already-adopted decision; a new amendment requires explicit user acceptance in interactive runs. Append the durable outcome to the memlog as a decision, constraint, or deferred item, keeping inherited and existing `AD` IDs stable, then re-distill and run Finalize without changing intent or workspace mid-run. If investigation finds no architecture decision worth binding, record that result as an event; when this run initialized a new spine solely for refinement, remove the unfinalized seed spine and return the companions as non-authoritative evidence rather than manufacturing an `AD`. + +Story slices and test strategy are lower-altitude follow-ons: offer them only at epic altitude or when the user explicitly needs implementation planning. They must cite the governing `AD` IDs and remain subordinate to the spine. + ## Update Amend an existing spine. Resume from its `.memlog.md` (the authority on what was decided), not the rendered spine. Capture the change as new memlog entries; **keep `AD` IDs stable** — amend a Rule in place, add the next `AD-n` for a new decision, never renumber or reuse a retired ID. Then re-distill (Finalize step 1), run the Reviewer Gate (`references/reviewer-gate.md`), and close as in Finalize. An update that overrides something from a source input: offer to update that source too, so upstream and the spine don't silently diverge. diff --git a/src/bmm-skills/3-solutioning/bmad-architecture/references/architecture-refinement.md b/src/bmm-skills/3-solutioning/bmad-architecture/references/architecture-refinement.md new file mode 100644 index 0000000000..c99aea1178 --- /dev/null +++ b/src/bmm-skills/3-solutioning/bmad-architecture/references/architecture-refinement.md @@ -0,0 +1,63 @@ +# Architecture Refinement + +Use this reference for brownfield architecture work where the problematic seam is visible but the durable decision is not yet known. + +## Build the working map + +Read the applicable spine and memlog first, then inspect the code, tests, project context, and ADRs needed to establish: + +- binding inherited and existing `AD` decisions +- current ownership and dependency direction +- repeated orchestration or knowledge spread across callers +- tests coupled to internals instead of observable behavior +- high-friction seams, interfaces, and module boundaries + +Ratify existing reality where it is coherent. Do not create an architecture decision merely to document code that already communicates the rule. + +## Find candidates + +Look for: + +- callers duplicating orchestration or policy +- modules whose removal deletes indirection but no capability +- helpers that moved code without concentrating change or knowledge +- interfaces exposing nearly as much complexity as they hide +- tests that must mock or inspect internals +- seams justified by only one hypothetical implementation + +Before proposing interfaces, present a short ranked candidate list. For each candidate include files, divergence risk, likely direction, expected test-surface improvement, governing or conflicting `AD` IDs, migration size, and risk. In an interactive run, stop for the user's choice unless the request already names the target. + +## Resolve the chosen candidate + +Ask only what removes decision risk: + +- What behavior and callers must remain stable? +- Which failures or changes repeatedly cross this area? +- Which inherited decisions and ADRs are binding? +- Is the work behavior-preserving or behavior-changing? +- What observable tests must survive? + +Compare realistic options before committing. Use `./interface-design.md` when interface shape is material. + +## Dependency and seam rules + +- Merge in-process dependencies freely when a smaller interface can hide them. +- A locally substitutable dependency can stay behind the interface when its stand-in supports behavior-level tests. +- Put an owned remote dependency behind a seam only when production and test/local implementations are real. +- Inject a true external dependency at the seam and isolate its adapter. +- One implementation is not evidence of required variation; do not manufacture a port. +- Keep internal seams private when callers do not need to know they exist. + +The interface is the preferred test surface. Assert observable behavior, invariants, errors, and performance obligations rather than internal state. + +## Translate the result + +Accepted durable outcomes must become memlog entries and then stable spine decisions or explicit Deferred items. Optional companions may include: + +- `refinement-candidates.md` +- `interface-options-{slug}.md` +- `refinement-recommendation-{slug}.md` + +Companions explain evidence and alternatives; they do not override the spine. Cite applicable `AD` IDs and flag conflicts rather than weakening inherited decisions. + +At initiative or feature altitude, stop at architecture decisions and Deferred items. Offer story slices or test strategy only at epic altitude or on explicit request; each must cite the governing `AD` IDs. diff --git a/src/bmm-skills/3-solutioning/bmad-architecture/references/headless.md b/src/bmm-skills/3-solutioning/bmad-architecture/references/headless.md index bd4d20be10..f9fef6136e 100644 --- a/src/bmm-skills/3-solutioning/bmad-architecture/references/headless.md +++ b/src/bmm-skills/3-solutioning/bmad-architecture/references/headless.md @@ -2,14 +2,16 @@ No interactive user: infer everything, ask nothing, but never invent — record inferences as `assumptions[]` and gaps that need a human as `open_questions[]`. Detect headless from a `headless: true` flag, a non-interactive / no-TTY invocation, an activation hook that declares it, or a first message that pre-supplies all inputs and asks for an artifact path back; when ambiguous, default to interactive. -Drive the run from the payload in the first message — `intent`, `altitude`, `purpose`, the driving input (spec package / PRD / raw intent / brownfield path), a parent spine path at lower altitude, and `doc_workspace` if a specific folder is required. Infer anything absent from the inputs or workspace; don't invent stack, constraints, or scope to fill a gap. You still verify named tech on the web (you can't ask, but you can check) and still drive every write through the shared `{project-root}/_bmad/scripts/memlog.py`. Run the full Reviewer Gate (`references/reviewer-gate.md`) non-interactively: `scripts/lint_spine.py` plus **every `{workflow.finalize_reviewers}` lens as a parallel subagent** (and any ad-hoc lens the spine's criticality warrants). Headless skips only the human picking from the menu — never the reviewers themselves; apply the clear fixes and record anything unresolved in `open_questions[]`. For a true authority collision, list it in `conflicts_with_prior_decisions[]`. For the Validate intent, always write the report to `{doc_workspace}` and add `"offer_to_update": true`. If intent stays ambiguous after inference, halt blocked. +Drive the run from the payload in the first message — `intent`, `altitude`, `purpose`, the driving input (spec package / PRD / raw intent / brownfield path), a parent spine path at lower altitude, and `doc_workspace` if a specific folder is required. Infer anything absent from the inputs or workspace; don't invent stack, constraints, or scope to fill a gap. Supported intents are `create`, `update`, `validate`, and `refine`; use `refine` when the payload names an existing seam, interface, module boundary, or brownfield hotspot but does not already specify the spine amendment. You still verify named tech on the web (you can't ask, but you can check) and still drive every write through the shared `{project-root}/_bmad/scripts/memlog.py`. Run the full Reviewer Gate (`references/reviewer-gate.md`) non-interactively: `scripts/lint_spine.py` plus **every `{workflow.finalize_reviewers}` lens as a parallel subagent** (and any ad-hoc lens the spine's criticality warrants). Headless skips only the human picking from the menu — never the reviewers themselves; apply the clear fixes and record anything unresolved in `open_questions[]`. For a true authority collision, list it in `conflicts_with_prior_decisions[]`. For the Validate intent, always write the report to `{doc_workspace}` and add `"offer_to_update": true`. If intent stays ambiguous after inference, halt blocked. -End with JSON only, omitting keys for artifacts not produced — the shape below is the fully-produced (`complete`) case; a `blocked` run produces no spine, so it omits `spine`, `memlog`, and `companions` entirely (see the note under the block): +For `refine`, load `references/architecture-refinement.md` and, when interface shape is material, `references/interface-design.md`. Inspect the named target and governing spine/code/ADRs, write any candidate or comparison companions to `{doc_workspace}`, and translate only ratified existing reality into decisions; a tentative amendment remains an assumption/open question unless the payload explicitly accepts it. If multiple viable candidates remain and the payload names no target, return `partial` with the ranked candidate companion and an `open_questions[]` entry rather than selecting one. If an applicable spine lacks its memlog and its stable decision history cannot be reconstructed safely, return `blocked`. If evidence cannot support a decision, return `partial` with non-authoritative companions and no invented `AD`; remove any seed spine created solely for that inconclusive refinement. Otherwise append outcomes through `memlog.py`, re-distill the spine, and run the full Reviewer Gate. + +End with JSON only, omitting keys for artifacts not produced — the shape below is the fully-produced (`complete`) case; companion-only `partial` and `blocked` runs omit the artifacts they did not produce (see the note under the block): ```json { "status": "complete | partial | blocked", - "intent": "create | update | validate", + "intent": "create | update | validate | refine", "altitude": "initiative | feature | epic", "purpose": "build-substrate | discussion", "doc_workspace": "", @@ -23,4 +25,4 @@ End with JSON only, omitting keys for artifacts not produced — the shape below } ``` -`complete` stands alone · `partial` (spine produced, but `open_questions[]` non-empty or critical inputs inferred) means review before downstream use · `blocked` means no spine produced — return only `status`, `intent`, `reason`, and `doc_workspace` (if bound), omitting `spine`, `memlog`, `companions`, and the artifact arrays that don't exist. +`complete` stands alone · `partial` means review before downstream use: normally it includes a spine plus unresolved `open_questions[]`; an inconclusive refinement may instead include only `doc_workspace`, non-authoritative `companions`, assumptions, and open questions, omitting `spine` and `memlog` · `blocked` means no usable artifact was produced — return only `status`, `intent`, `reason`, and `doc_workspace` (if bound), omitting `spine`, `memlog`, `companions`, and artifact arrays that don't exist. diff --git a/src/bmm-skills/3-solutioning/bmad-architecture/references/interface-design.md b/src/bmm-skills/3-solutioning/bmad-architecture/references/interface-design.md new file mode 100644 index 0000000000..06de050875 --- /dev/null +++ b/src/bmm-skills/3-solutioning/bmad-architecture/references/interface-design.md @@ -0,0 +1,29 @@ +# Interface Design for Refinement + +Use this reference only when interface shape is a material architecture decision. + +## Produce alternatives + +Compare at least three realistic shapes: + +1. Minimal — the smallest stable behavior callers need. +2. Flexible — justified variation without leaking implementation detail. +3. Caller-optimized — shaped around the dominant caller workflow. + +Add a ports-and-adapters option only when at least two real implementations or a true external dependency justify the seam. + +For each option show: + +- interface shape and brief caller usage +- behavior, state, and dependencies hidden behind it +- ownership and dependency direction +- adapter strategy, if any +- observable test surface +- migration and rollback cost +- compatibility or conflict with existing `AD` IDs + +## Decide + +Rank the options by divergence prevented, locality of change and knowledge, interface leverage, migration risk, and altitude fit. Recommend one option or a precise hybrid; do not leave an unranked menu. + +The recommendation becomes architecture only after it is accepted or ratified by existing reality and recorded in the memlog. The resulting spine `AD` states the enforceable rule; detailed examples and rejected alternatives remain in the companion or memlog. diff --git a/src/bmm-skills/3-solutioning/bmad-architecture/references/reviewer-gate.md b/src/bmm-skills/3-solutioning/bmad-architecture/references/reviewer-gate.md index 729844c46b..b82adbfda8 100644 --- a/src/bmm-skills/3-solutioning/bmad-architecture/references/reviewer-gate.md +++ b/src/bmm-skills/3-solutioning/bmad-architecture/references/reviewer-gate.md @@ -1,13 +1,13 @@ # Reviewer Gate -The spine's pre-handoff review. Runs at Finalize (after distill + reconcile) and *is* the Validate intent. The difference is the ending: at Finalize you apply the clear fixes yourself; under Validate you report and don't change the spine. +The spine's pre-handoff review. Runs at Finalize (after distill + reconcile) and _is_ the Validate intent. The difference is the ending: at Finalize you apply the clear fixes yourself; under Validate you report and don't change the spine. Cheap deterministic pass first: `python3 {skill-root}/scripts/lint_spine.py --workspace {doc_workspace}` settles the mechanical misses (placeholders, duplicate `AD` IDs, missing Binds/Prevents/Rule, unpinned deps), so reviewers spend judgment on the semantic half. -Assemble the menu: a **rubric walker** that judges the spine against the good-spine checklist below, **+ every entry in `{workflow.finalize_reviewers}`**, + ad-hoc lenses you invent or offer as the spine's rigor, altitude, and criticality warrant — a security/compliance lens for regulated stakes, a seam reviewer cross-team, a data-integrity lens for a heavy data model. Scale *whether and how heavily the gate runs* to the stakes: a throwaway prototype may run it quietly or skip the gate entirely; a high-criticality or platform-altitude spine earns more lenses and the explicit all / subset / skip menu. But once the gate runs, the `{workflow.finalize_reviewers}` always run — they are the configured floor, never cherry-picked out; only the ad-hoc lenses are optional. (Headless never skips the gate.) +Assemble the menu: a **rubric walker** that judges the spine against the good-spine checklist below, **+ every entry in `{workflow.finalize_reviewers}`**, + ad-hoc lenses you invent or offer as the spine's rigor, altitude, and criticality warrant — a security/compliance lens for regulated stakes, a seam reviewer cross-team, a data-integrity lens for a heavy data model. Scale _whether and how heavily the gate runs_ to the stakes: a throwaway prototype may run it quietly or skip the gate entirely; a high-criticality or platform-altitude spine earns more lenses and the explicit all / subset / skip menu. But once the gate runs, the `{workflow.finalize_reviewers}` always run — they are the configured floor, never cherry-picked out; only the ad-hoc lenses are optional. (Headless never skips the gate.) Dispatch every entry as a **parallel subagent against `ARCHITECTURE-SPINE.md`** (prefix convention: `skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2–5 findings, file path) — the parent never holds full review text. An inline self-check does not count: the independent context is the point, because a fresh reviewer finds the divergences the author talks past. If subagents are unavailable, run sequentially — write the file first, then flush it from context. -**Good-spine checklist** (what the rubric walker judges): it fixes the real divergence points for the level below and misses none; every `AD`'s Rule is enforceable and actually prevents its stated divergence; nothing under Deferred could let two units diverge; named tech is verified-current; it ratifies rather than contradicts a brownfield codebase; if a spec drove it, it covers that spec's capabilities; and if a parent spine is inherited, no new `AD` weakens or contradicts an inherited one. +**Good-spine checklist** (what the rubric walker judges): it fixes the real divergence points for the level below and misses none; every `AD`'s Rule is enforceable and actually prevents its stated divergence; nothing under Deferred could let two units diverge; named tech is verified-current; it ratifies rather than contradicts a brownfield codebase; if a spec drove it, it covers that spec's capabilities; if a parent spine is inherited, no new `AD` weakens or contradicts an inherited one; and any refinement companions agree with the spine, cite applicable governing `AD` IDs (or explicitly state that none exists yet for pre-decision evidence), and contain no unstated competing decision. Surface findings tiered, never dumped: a one-sentence gate verdict, then critical + high; medium/low roll into a tail ("plus N more in {file}"). Per finding: autofix, discuss, defer to Deferred / open items, or ignore. **At Finalize this is your own gate — apply the clear fixes rather than handing over a list; surface only what genuinely needs the user.** Under the **Validate intent**, fold every reviewer's output into one bespoke HTML + markdown report and open the HTML. diff --git a/src/bmm-skills/module-help.csv b/src/bmm-skills/module-help.csv index d0f17494f7..d1dcf5b051 100644 --- a/src/bmm-skills/module-help.csv +++ b/src/bmm-skills/module-help.csv @@ -17,7 +17,7 @@ BMad Method,bmad-product-brief,Create Brief,CB,An expert guided experience to na BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,1-analysis,,,false,planning_artifacts,prfaq document BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd BMad Method,bmad-ux,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design -BMad Method,bmad-architecture,Architecture,CA,Offer once requirements exist (a PRD or spec; plus UX if present) and the user is ready to move from what to how. Also offer any time independently-built parts risk diverging. Produces the architecture spine: the invariants that keep features epics and stories consistent. Comes before epics and stories and scales from a quick spine to a full architecture (brownfield: ratifies the existing codebase).,,,3-solutioning,,,true,planning_artifacts,architecture +BMad Method,bmad-architecture,Architecture,CA,Offer once requirements exist (a PRD or spec; plus UX if present) and the user is ready to move from what to how. Also offer any time independently-built parts risk diverging or an existing seam interface or module boundary needs refinement. Produces or refines the architecture spine: the invariants that keep features epics and stories consistent. Comes before epics and stories and scales from a quick spine to a full architecture (brownfield: ratifies and selectively refines the existing codebase).,,,3-solutioning,,,true,planning_artifacts,architecture BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-architecture,,true,planning_artifacts,epics and stories BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,bmad-create-epics-and-stories,,true,planning_artifacts,readiness report BMad Method,bmad-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status