basic BMAD setup

.agents/skills/bmad-walkthrough/workflow.md

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