basic BMAD setup

2026-10-15 08:57:23 +02:00
parent 44029127dc
commit 5e747654b9
438 changed files with 41818 additions and 0 deletions
@@ -0,0 +1,14 @@
+---
+name: bmad-walkthrough
+description: 'Guide a human review of a commit, PR, file, or directory. Use when invoked by name'
+---
+
+Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory:
+
+```bash
+uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}"
+```
+
+- On success, the command prints `read and follow` and an absolute path to a rendered `workflow.md`. Read that file and follow it.
+- If the script is not found, BMad is not set up here. Offer to run the `bmad` skill's setup, installing `bmad` first if you do not have it (`npx skills add bmad-code-org/BMAD-METHOD --skill bmad`), then run the command above once more.
+- On any other failure (including `uv` being unavailable), report the command output and HALT. Do not run any workflow source directly.
@@ -0,0 +1,3 @@
+[skill]
+bmod = "bmod-method"
+source = "github:bmad-code-org/BMAD-METHOD/skills"
@@ -0,0 +1,30 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-walkthrough.
+# Mirrors the agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   strings: override wins • arrays (persistent_facts): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Executed when the workflow starts.
+on_activation = ""
+
+# Executed when a block is first presented.
+on_block_activation = ""
+
+# Facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Each entry is either:
+#   - a literal sentence, e.g. "All stories must include testable acceptance criteria."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+persistent_facts = []
+
+# Executed when the user says a block is done.
+on_block_complete = ""
+
+# Executed when the user wraps up.
+on_complete = ""
@@ -0,0 +1,16 @@
+# Step 1: Orientation
+
+Understand what the target is and what it is for. Use the target's
+plan or spec, PR description, and commit messages when they exist.
+Ask the user questions until you know both.
+
+## CHECKPOINT
+
+If subagents are available: is the background subagent for writing
+the log and narrative files running? If not, spawn it now. Doing
+that work in the main session distracts the user. Do not load the
+next step until that subagent is running.
+
+## NEXT
+
+Read fully and follow: `{{ rendered("step-02-narrative.md") }}`
@@ -0,0 +1,25 @@
+# Step 2: Create review narrative
+
+Write the review narrative and the review log in a new folder
+`walkthrough-<slug>/` under
+`{{ initiative_folder }}/`: the narrative as
+`walkthrough-<slug>.md`, the log as `walkthrough-<slug>-log.md`.
+`<slug>` is a short review slug; check that the folder name is
+unused before creating it.
+
+- **Review narrative:** Write blocks in the Block shapes. Use
+  unchecked boxes for unvisited, in-progress, or reopened blocks,
+  labeling their state; check a block when the user indicates they
+  are satisfied with it. Note whether it changed during review and
+  identify the current block. Work performed on a block does not
+  itself mean it is accepted.
+- **Review log:** Read and use `{{ rendered("templates/log-template.md") }}`.
+  Keep findings, decisions, edits, and test results out of the review
+  narrative.
+
+If you are running in a sidebar of VS Code, Cursor, or another
+editor, open the narrative file in the editor.
+
+## NEXT
+
+Read fully and follow: `{{ rendered("step-03-walkthrough.md") }}`
@@ -0,0 +1,61 @@
+# Step 3: Walkthrough
+
+Give the block's link into the narrative, its content in that block's
+shape.
+{% if workflow.on_block_activation %}
+
+{{ workflow.on_block_activation }}
+{% endif %}
+
+Suggest 1-3 moves that fit. Then stop. The named moves are not
+exhaustive; if something else is more obvious, suggest that instead.
+The user may choose something you did not suggest. Do what the user
+says. Stay with the current block until the user explicitly says it
+is done.
+
+Do not add status chatter ("still current", "waiting on you") on
+later turns unless the reviewer asks where they are.
+
+If they reject a block's shape, rewrite that block in the shape they
+describe, in both the session and the narrative, and record the
+constraint in the log so it applies to every later block. Do not
+present the same block a third time in a different shape without
+being asked.
+
+When they say the block is done:
+{{ workflow.on_block_complete | default("
+- present the next block first so they can keep going.
+- then record that the previous block is done: check it
+  in the narrative silently, and revise the remaining narrative if it
+  needs to change.
+- If the tree is dirty, ask the user whether to commit.
+  A dirty tree is generally undesirable; the user can still move on.", true) }}
+
+When every block has been gone through, suggest wrap-up.
+
+# Moves
+
+A repertoire the user may select from. Do not start a move unless the user
+picks it. Record the outcome in the review log and keep their place in
+the review narrative.
+
+- **Thoughts:** In this session, look at the requested area and say
+  what you think. Report concrete findings with clickable
+  references. Do not use any formal review skills.
+- **Second opinion:** The same question, in a fresh subagent that
+  does not have this review's conversation. Do not use any formal review
+  skills.
+- **Formal review:** Use the most appropriate formal review skill
+  available. If it's code and `bmad-code-review` skill is installed, prefer
+  that unless the user says otherwise.
+- **Test:** Help test the part under discussion. Identify useful checks
+  and expected behavior, run what you can, and guide the user through
+  observations that need them. Record what was actually tested, the
+  results, and anything still unverified.
+- **Drive:** Start the app and tell the user which buttons to push to
+  see the target do its thing.
+- **Wrap-up:** The review is finished. Guess the follow-through
+  this work was for (e.g. merge the PR, write the review, commit
+  and push if they edited) and ask the user if that is what they
+  want. Do not do it until they say so. Do not end with only a
+  summary in chat. {% if workflow.on_complete %}{{ workflow.on_complete }}{% endif %}
@@ -0,0 +1,38 @@
+{% raw %}# Review log: {{review_identifier}}
+
+Target: {{target_reference}}
+
+<!--
+Append-only record of outcomes/decisions.
+Main purpose: persisted context for resuming or analyzing
+the review process. You're writing this log for consumption
+by another LLM session.
+
+Record decisions and their reasons, user constraints, unresolved
+findings, and references needed to recover evidence. Link to large
+results rather than copying them here.
+This is NOT a transcript or internal deliberation.
+The review narrative (the human-facing file) owns review blocks
+and their statuses.
+
+Log entry:
+Use format below. Omit empty fields. In Result, give each finding's
+disposition: fixed, accepted as-is, deferred, or open. When a
+disposition changes, append a new entry; do not edit earlier ones.
+Record the actual session ID supplied by the environment and an ISO
+8601 timestamp with local timezone for each entry. If the session ID
+is unavailable, write "unavailable" rather than inventing one.
+
+Token budget: up to 150 tokens per entry.
+The smaller the better, but do not sacrifice precision.
+-->
+
+## {{entry_number}} — {{block_or_area}} — {{activity}}
+
+Session: {{session_id}} · Timestamp: {{timestamp}}
+
+- Action: {{what_was_examined_changed_or_tested}}
+- Result: {{findings_outcome_or_decision_and_reason}}
+- Evidence: {{file_references_commands_or_result_links}}
+- Open: {{unresolved_work_or_question}}
+{% endraw %}
@@ -0,0 +1,99 @@
+Guide a human review of a target, one block at a time. They may
+stop to inspect, edit, or test. Keep track of which blocks the
+user has called done. A block or the review as a whole is done
+only when the user says it is.
+
+# Terms
+
+- **Target:** The commit, PR, file, or directory being reviewed.
+- **Review:** The session. Done when the user says it is.
+- **Block:** One slice of the walkthrough. Accepted only when the user
+  says so.
+- **Review narrative:** The human-facing writeup. Organized in blocks.
+  Owns block review status.
+- **Review log:** Append-only record of review activities and outcomes.
+- **Finding:** A concrete issue from inspection.
+- **Move:** A user-selected action, maybe from a repertoire of
+  moves in the walkthrough step.
+
+# Human attention is scarce
+
+Show only what a human needs to see. Do not distract them. Write
+the log, edit the narrative, look things up, reason — but do not
+put it in the session.
+
+When subagents are available, spawn a cheap background one for
+writing log and narrative files. Doing that work in the main
+session distracts the user.
+
+# Write for a human
+
+The session output and the review narrative file are for a human.
+Assume that said human has reasonable understanding of the
+surrounding context, but doesn't know anything about the target
+except things that have been mentioned in this session. Leave the
+brief log style to the log.
+
+# Clickable file refs
+
+Never write a file or `file:line` reference in human-facing output
+as plain text.
+
+In the review narrative file, every file and `file:line` must be a
+markdown link relative to that file (`[label](../src/foo.ts)`).
+
+In the session, never write a markdown link. Use a form the host
+can click: a Cursor code citation (`startLine:endLine:path` on the
+opening fence); a VS Code `#file:path`; or a CWD-relative
+`path:line` with no leading `/`. If unsure, use `path:line`.
+
+# Block shapes
+
+**Intent** (block 1). What the change is for and why it exists now.
+If you found a target plan file with an intent section, paste it
+verbatim. Otherwise generate from what you know about the target, no
+more than 300 tokens. Include a short note on where you got it from.
+
+**Broad strokes** (block 2). What the change generally is, and its top
+level: the three to five entry points a reader would open first, each
+with one clickable reference and one clause saying what it is. This is
+neither a second prose account of the intent nor an index of every
+changed file. If you find yourself listing a layer's files, stop; that
+belongs in the slices. Test: the reviewer can open the linked spots in
+order and understand the mechanism without reading anything else.
+
+**Slices** (middle blocks). One concern per block, not one file. Lead
+with the mechanism in two or three sentences, then the specific places
+with references.
+
+For a simple change applied to a large number of files, group the
+files by how they were changed (one or several groups). Treat each
+group as a slice: one or two worked examples, plus a clickable list
+of the rest that got the same treatment.
+
+**Periphery** (last block). Docs, build registration, small enablers.
+References only, one clause each.
+
+{% if workflow.on_activation %}
+# On Activation
+
+{{ workflow.on_activation }}
+{% endif %}
+{% if workflow.persistent_facts %}
+# Persistent facts
+
+Do not compact these away. Load `file:` paths. Expand globs and read
+every match. Other entries are facts.
+
+{{ workflow.persistent_facts }}
+
+{% endif %}
+# Workflow
+
+Follow the step files in order. Read one step fully, execute it, then
+load the next step only when directed. Do not skip, reorder, or
+pre-load steps.
+
+# FIRST STEP
+
+Read fully and follow: `{{ rendered("step-01-orientation.md") }}` to begin.