From 10b7f679417e7a22238e95aca38ee557c353b31b Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Mon, 22 Jun 2026 15:12:48 -0700 Subject: [PATCH] feat: add bmad dev auto skill --- .../4-implementation/bmad-dev-auto/SKILL.md | 82 +++++++++++++++++ .../bmad-dev-auto/compile-epic-context.md | 62 +++++++++++++ .../bmad-dev-auto/customize.toml | 41 +++++++++ .../bmad-dev-auto/spec-template.md | 89 +++++++++++++++++++ .../step-01-clarify-and-route.md | 82 +++++++++++++++++ .../bmad-dev-auto/step-02-plan.md | 33 +++++++ .../bmad-dev-auto/step-03-implement.md | 40 +++++++++ .../bmad-dev-auto/step-04-review.md | 50 +++++++++++ .../bmad-dev-auto/step-05-present.md | 78 ++++++++++++++++ .../bmad-dev-auto/step-oneshot.md | 63 +++++++++++++ .../bmad-dev-auto/sync-sprint-status.md | 19 ++++ 11 files changed, 639 insertions(+) create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/compile-epic-context.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/step-05-present.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/step-oneshot.md create mode 100644 src/bmm-skills/4-implementation/bmad-dev-auto/sync-sprint-status.md diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md b/src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md new file mode 100644 index 000000000..2491c21d9 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md @@ -0,0 +1,82 @@ +--- +name: bmad-dev-auto +description: 'One iteration of an unattended development loop. Use when invoked by name.' +--- + +# Dev Auto Workflow + +**Goal:** Turn intent into a hardened, reviewable artifact, without human interaction. + +**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions. + +Using subagents when instructed is mandatory. If you cannot, record `no subagents` in the result artifact and end the run. + +## Result Artifact + +The result artifact is `{spec_file}` once it is known. If `{spec_file}` is unknown, create `{implementation_artifacts}/bmad-dev-auto-result-{slug-or-timestamp}.md`. + +## READY FOR DEVELOPMENT STANDARD + +A specification is "Ready for Development" when: + +- **Actionable**: Every task has a file path and specific action. +- **Logical**: Tasks ordered by dependency. +- **Testable**: All ACs use Given/When/Then. +- **Complete**: No placeholders or TBDs. + +## Conventions + +- Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root. +- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives). +- `{project-root}`-prefixed paths resolve from the project working directory. +- `{skill-name}` resolves to the skill directory's basename. + +## On Activation + +### Step 1: Resolve the Workflow Block + +Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` + +**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver: + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. + +### Step 2: Execute Prepend Steps + +Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding. + +### Step 3: Load Persistent Facts + +Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim. + +### Step 4: Load Config + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name` +- `communication_language`, `document_output_language`, `user_skill_level` +- `date` as system-generated current datetime +- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` +- `project_context` = `**/project-context.md` (load if exists) +- CLAUDE.md / memory files (load if exist) +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Language MUST be tailored to `{user_skill_level}` +- Generate all documents in `{document_output_language}` + +### Step 5: Execute Append Steps + +Execute each entry in `{workflow.activation_steps_append}` in order. + +Activation is complete after all activation steps have run. + +## WORKFLOW EXECUTION + +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 WORKFLOW STEP + +Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow. diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/compile-epic-context.md b/src/bmm-skills/4-implementation/bmad-dev-auto/compile-epic-context.md new file mode 100644 index 000000000..eb21c98ac --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/compile-epic-context.md @@ -0,0 +1,62 @@ +# Compile Epic Context + +**Task** +Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic--context.md`). + +**Steps** + +1. Read the epics file and extract the target epic's title, goal, and list of stories. +2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief). +3. Pull only the information relevant to this epic. +4. Write the compiled context to the exact output path using the format below. + +## Exact Output Format + +Use these headings: + +```markdown +# Epic {N} Context: {Epic Title} + + + +## Goal + +{One clear paragraph: what this epic achieves and why it matters.} + +## Stories + +- Story X.Y: Brief title only +- ... + +## Requirements & Constraints + +{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).} + +## Technical Decisions + +{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.} + +## UX & Interaction Patterns + +{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).} + +## Cross-Story Dependencies + +{Dependencies between stories in this epic or with other epics/systems (omit if none).} +``` + +## Rules + +- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc. +- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't. +- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill. +- **No story-level details.** The story list is for orientation only. Individual story specs handle the details. +- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code. +- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into bmad-dev-auto's context alongside other material. +- **Never hallucinate content.** If source material doesn't say something, don't invent it. +- **Omit empty sections entirely**, except Goal and Stories, which are always required. + +## Error handling + +- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file. +- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections. diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml b/src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml new file mode 100644 index 000000000..26dafc4e8 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml @@ -0,0 +1,41 @@ +# DO NOT EDIT -- overwritten on every update. +# +# Workflow customization surface for bmad-dev-auto. Mirrors the +# agent customization shape under the [workflow] namespace. + +[workflow] + +# --- Configurable below. Overrides merge per BMad structural rules: --- +# scalars: override wins • arrays (persistent_facts, activation_steps_*): append +# arrays-of-tables with `code`/`id`: replace matching items, append new ones. + +# Steps to run before the standard activation (config load). +# Overrides append. Use for pre-flight loads, compliance checks, etc. + +activation_steps_prepend = [] + +# Steps to run after activation but before the workflow begins. +# Overrides append. Use for context-heavy setup that should happen +# once the user has been acknowledged. + +activation_steps_append = [] + +# Persistent facts the workflow keeps in mind for the whole run +# (standards, compliance constraints, stylistic guardrails). +# Distinct from the runtime memory sidecar — these are static context +# loaded on activation. Overrides append. +# +# 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 = [ + "file:{project-root}/**/project-context.md", +] + +# Scalar: executed when the workflow reaches its final step, +# after implementation is complete and explanations are provided. Override wins. +# Leave empty for no custom post-completion behavior. + +on_complete = "" diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md b/src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md new file mode 100644 index 000000000..138170864 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md @@ -0,0 +1,89 @@ +--- +title: '{title}' +type: 'feature' # feature | bugfix | refactor | chore +created: '{date}' +status: 'draft' # draft | ready-for-dev | in-progress | in-review | done | blocked +context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body. +warnings: [] # optional: machine-readable warnings for orchestration, e.g. oversized, multiple-goals +--- + + + + + +## Intent + + + +**Problem:** ONE_TO_TWO_SENTENCES + +**Approach:** ONE_TO_TWO_SENTENCES + +## Boundaries & Constraints + + + +**Always:** INVARIANT_RULES + +**Block If:** DECISIONS_REQUIRING_HUMAN_INPUT + + +**Never:** NON_GOALS_AND_FORBIDDEN_APPROACHES + +## I/O & Edge-Case Matrix + + + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| HAPPY_PATH | INPUT | OUTCOME | N/A | +| ERROR_CASE | INPUT | OUTCOME | ERROR_HANDLING | + + + +## Code Map + + + +- `FILE` -- ROLE_OR_RELEVANCE +- `FILE` -- ROLE_OR_RELEVANCE + +## Tasks & Acceptance + + + + + +**Execution:** +- [ ] `FILE` -- ACTION -- RATIONALE + +**Acceptance Criteria:** +- Given PRECONDITION, when ACTION, then EXPECTED_RESULT + +## Spec Change Log + + + +## Design Notes + + + + +DESIGN_RATIONALE_AND_EXAMPLES + +## Verification + + + + +**Commands:** +- `COMMAND` -- expected: SUCCESS_CRITERIA + +**Manual checks (if no CLI):** +- WHAT_TO_INSPECT_AND_EXPECTED_STATE diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md new file mode 100644 index 000000000..58ebc6c14 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md @@ -0,0 +1,82 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +spec_file: '' # set at runtime for both routes before leaving this step +story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds +--- + +# Step 1: Clarify and Route + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Treat the invocation intent as workflow input, not as a substitute for step-02 investigation and spec generation. +- **EARLY EXIT** means: stop this step immediately, then read and follow the target file. Return here only if a later step explicitly says to loop back. +- **BLOCKED EXIT** means: write the blocked reason to the result artifact and end the run. + +## Intent check (do this first) + +Use the invocation prompt as the intent. + +If the invocation prompt explicitly points to an existing spec file with recognized `status` frontmatter, set `spec_file`. Before exiting, run **Story-key resolution** (below). Then **EARLY EXIT** to the appropriate step: +- `draft` → `./step-02-plan.md` +- `ready-for-dev` or `in-progress` → `./step-03-implement.md` +- `in-review` → `./step-04-review.md` +- `done` → ingest as context and proceed to INSTRUCTIONS — do not resume. + +Otherwise, treat the invocation prompt as starting intent. This may be a story ID, ticket ID, file path, short description, or longer free-form intent. Do not infer workflow state from non-spec files. +If the invocation prompt does not contain enough intent to identify what to implement, write `unclear intent` to the result artifact and **BLOCKED EXIT**. + +### Story-key resolution + +This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `{epic_num}` and `{story_num}`. If the spec is not an epic story, skip silently and leave `{story_key}` unset. + +If the spec is an epic story and `{sprint_status}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `{story_key}` to that full key. Zero or multiple matches → leave `{story_key}` unset (warn on multiple). + +## INSTRUCTIONS + +1. Load context. + - List files in `{planning_artifacts}` and `{implementation_artifacts}`. + - If the invocation prompt points to an unformatted spec or intent file, ingest that file. Do not scan for unrelated intent files. + - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together. + + **A) Epic story path** — if the intent is clearly an epic story: + + 1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B. + + 2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic--context.md` (where `` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer. + - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). + - **If missing, empty, or invalid:** compile it in the next bullet. + + 3. **Compile epic context if needed.** If no valid cached epic context was loaded, produce `{implementation_artifacts}/epic--context.md` by spawning a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic--context.md`. If sub-agents are unavailable, write `no subagents` to the result artifact and **BLOCKED EXIT**. + + 4. **Verify if compiled.** If epic context was compiled, verify the output file exists, is non-empty, and starts with `# Epic Context:`. If valid, load it. If verification fails, write the failed context-compilation condition to the result artifact and **BLOCKED EXIT**. + + 5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, write the missing continuity decision to the result artifact and **BLOCKED EXIT**. + + 6. **Resolve `{story_key}`.** If not already set by an earlier early-exit path, run **Story-key resolution** (above) now. + + **B) Freeform path** — if the intent is not an epic story: + - Planning artifacts are the output of BMAD phases 1-3. Typical files include: + - **PRD** (`*prd*`) — product requirements and success criteria + - **Architecture** (`*architecture*`) — technical design decisions and constraints + - **UX/Design** (`*ux*`) — user experience and interaction design + - **Epics** (`*epic*`) — feature breakdown into implementable stories + - **Product Brief** (`*brief*`) — project vision and scope + - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone. +2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, write them as a blocked condition in the result artifact and **BLOCKED EXIT**. +3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, write the condition to the result artifact and **BLOCKED EXIT**. If version control is unavailable, skip this check. +4. Multi-goal warning. If the intent appears to contain multiple independently shippable goals, carry `multiple-goals` forward so step-02 can add it to `{spec_file}` frontmatter `warnings`. Do not split or block. +5. Route: + + Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`. + + **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. + + **EARLY EXIT** → `./step-oneshot.md` + + **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path. + + +## NEXT + +Read fully and follow `./step-02-plan.md` diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md new file mode 100644 index 000000000..85c3baee8 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md @@ -0,0 +1,33 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step 2: Plan + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No intermediate approvals. +- Never ask questions or wait for approval. + +## INSTRUCTIONS + +1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `...` block as `preserved_intent`. Otherwise `preserved_intent` is empty. +2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ +3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `` block in your filled spec before writing. Write the result to `{spec_file}`. +4. Self-review against READY FOR DEVELOPMENT standard. +5. If intent gaps exist, do not fantasize and do not leave open questions. Set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, the unanswered questions, and evidence gathered, then terminate cleanly. +6. Warning check. If step-01 carried `multiple-goals`, add it to `{spec_file}` frontmatter `warnings`. If `{spec_file}` exceeds 1600 tokens, add `oversized` to frontmatter `warnings`. Continue either way. + +### APPROVAL BLOCK + +Do not present a conversational checkpoint. + +Re-read `{spec_file}` from disk. +- **If the file is missing:** write a best-effort result artifact in `{implementation_artifacts}` with `Status: blocked`, `Blocking condition: planned spec file disappeared before implementation`, and terminate cleanly. +- **If the file exists:** compare the content to what you wrote. If it has changed since you wrote it, note the external edits in `## Auto Run Result`. Set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, `Blocking condition: missing spec approval/edit decision`, and terminate cleanly. + + +## NEXT + +Read fully and follow `./step-03-implement.md` diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md new file mode 100644 index 000000000..d5e1afff8 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md @@ -0,0 +1,40 @@ +--- +--- + +# Step 3: Implement + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Sequential execution only. +- Content inside `` in `{spec_file}` is read-only. Do not modify. + +## PRECONDITION + +Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, write a best-effort result artifact in `{implementation_artifacts}` with `Status: blocked`, `Blocking condition: missing spec_file before implementation`, and terminate cleanly. + +## INSTRUCTIONS + +### Baseline + +Capture `baseline_revision` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes. + +### Implement + +Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation. + +Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`. + +If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context. + +Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, `Blocking condition: implementation subagent unavailable`, and terminate cleanly. + +**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case. + +### Self-Check + +Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding. + +## NEXT + +Read fully and follow `./step-04-review.md` diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md new file mode 100644 index 000000000..3ae5020ec --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md @@ -0,0 +1,50 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +specLoopIteration: 1 +--- + +# Step 4: Review + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Review subagents get NO conversation context. +- All review subagents must run at the same model capability as the current session. + +## INSTRUCTIONS + +Change `{spec_file}` status to `in-review` in the frontmatter before continuing. + +### Construct Diff + +Read `{baseline_revision}` from `{spec_file}` frontmatter. If `{baseline_revision}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_revision}`. + +Do NOT `git add` anything — this is read-only inspection. + +### Review + +Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, `Blocking condition: review subagents unavailable`, and the prompt file paths, then terminate cleanly. + +- **Blind hunter** — receives inline `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill. +- **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill. +- **Acceptance auditor** — receives `{diff_output}`, `{spec_file}`, and read access to the project. Must also read the docs listed in `{spec_file}` frontmatter `context`. Checks for violations of acceptance criteria, rules, and principles from the spec and context docs. + +### Classify + +1. Deduplicate all review findings. +2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**. + - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading. + - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code. + - **patch** — caused by the change; trivially fixable without human input. Just part of the diff. + - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention. + - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real. +3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, `Blocking condition: review repair loop exceeded 5 iterations`, and terminate cleanly. + - **intent_gap** — Root cause is inside ``. Revert code changes. Set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, the intent-gap findings, and the missing human intent decision, then terminate cleanly. + - **bad_spec** — Root cause is outside ``. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again. + - **patch** — Auto-fix. These are the only findings that survive loopbacks. + - **defer** — Append to `{deferred_work_file}`. + - **reject** — Drop silently. + +## NEXT + +Read fully and follow `./step-05-present.md` diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-05-present.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-05-present.md new file mode 100644 index 000000000..73558db4d --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-05-present.md @@ -0,0 +1,78 @@ +--- +--- + +# Step 5: Present + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Do not present options or offers. + +## INSTRUCTIONS + +### Generate Suggested Review Order + +Read `{baseline_revision}` from `{spec_file}` frontmatter and construct the diff of all changes since that revision. + +Append the review order as a `## Suggested Review Order` section to `{spec_file}` **after the last existing section**. Do not modify the Code Map. + +Build the trail as an ordered sequence of **stops** — clickable `path:line` references with brief framing — optimized for a human reviewer reading top-down to understand the change: + +1. **Order by concern, not by file.** Group stops by the conceptual concern they address (e.g., "validation logic", "schema change", "UI binding"). A single file may appear under multiple concerns. +2. **Lead with the entry point** — the single highest-leverage file:line a reviewer should look at first to grasp the design intent. +3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops. +4. **End with peripherals** — tests, config, types, and other supporting changes come last. +5. **Every code reference is a clickable spec-file-relative link.** Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format each stop as a markdown link: `[short-name:line](../../path/to/file.ts#L42)`. Use a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. The relative path must be dynamically derived — never hardcode the depth. +6. **Each stop gets one ultra-concise line of framing** (≤15 words) — why this approach was chosen here and what it achieves in the context of the change. No paragraphs. + +Format each stop as framing first, link on the next indented line: + +```markdown +## Suggested Review Order + +**{Concern name}** + +- {one-line framing} + [`file.ts:42`](../../src/path/to/file.ts#L42) + +- {one-line framing} + [`other.ts:17`](../../src/path/to/other.ts#L17) + +**{Next concern}** + +- {one-line framing} + [`file.ts:88`](../../src/path/to/file.ts#L88) +``` + +> The `../../` prefix above is illustrative — compute the actual relative path from `{spec_file}`'s directory to each target file. + +When there is only one concern, omit the bold label — just list the stops directly. + +### Mark Spec Done + +Change `{spec_file}` status to `done` in the frontmatter. + +Follow `./sync-sprint-status.md` with `{target_status}` = `review`. + +### Append Result Report + +Append `## Auto Run Result` to `{spec_file}` **after** `## Suggested Review Order`. Include: + +- `Status: done` +- Summary of implemented change +- Files changed with one-line descriptions +- Review findings breakdown: patches applied, items deferred, items rejected +- Verification performed, including command outcomes or manual inspection notes +- Any residual risks + +### Display Summary + +Display summary of your work to the user. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Mention that `{spec_file}` now contains a Suggested Review Order and Auto Run Result. + +Workflow complete. + +## On Complete + +Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` + +If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting. diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-oneshot.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-oneshot.md new file mode 100644 index 000000000..6adb1c01a --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-oneshot.md @@ -0,0 +1,63 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step One-Shot: Implement, Review, Present + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Do not present options or offers. + +## INSTRUCTIONS + +### Implement + +Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`. + +Implement the clarified intent directly. + +### Review + +Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}`, write `{spec_file}` with `Status: blocked` and the review prompt path, then terminate cleanly. + +### Classify + +Deduplicate all review findings. Three categories only: + +- **patch** — trivially fixable. Auto-fix immediately. +- **defer** — pre-existing issue not caused by this change. Append to `{deferred_work_file}`. +- **reject** — noise. Drop silently. + +If a finding is caused by this change but too significant for a trivial patch, write `{spec_file}` with `Status: blocked`, the finding, and the missing repair decision, then terminate cleanly. + +### Generate Spec Trace + +Set `{title}` = a concise title derived from the clarified intent. + +Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others: + +1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`. +2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal. +3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing). + +Follow `./sync-sprint-status.md` with `{target_status}` = `review`. + +### Present + +Append `## Auto Run Result` to `{spec_file}` with: + +- `Status: done` +- List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths. +- Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so. +- Verification performed and residual risks. + +Display a summary in conversation output. Mention that `{spec_file}` now contains a Suggested Review Order and Auto Run Result. + +Workflow complete. + +## On Complete + +Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` + +If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting. diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/sync-sprint-status.md b/src/bmm-skills/4-implementation/bmad-dev-auto/sync-sprint-status.md new file mode 100644 index 000000000..13708b95f --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/sync-sprint-status.md @@ -0,0 +1,19 @@ +# Sync Sprint Status + +Shared sub-step for updating `sprint-status.yaml` during bmad-dev-auto. Called from any route (plan-code-review, one-shot, future routes) with a `{target_status}` parameter. + +## Preconditions + +Skip this entire file (return to caller) if ANY of: +- `{story_key}` is unset +- `{sprint_status}` does not exist on disk + +## Instructions + +1. Load the FULL `{sprint_status}` file. +2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller. +3. **Idempotency check.** If `development_status[{story_key}]` is already at `{target_status}` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status. +4. Set `development_status[{story_key}]` to `{target_status}`. +5. **Epic lift (only when `{target_status}` = `in-progress`).** Derive the parent epic key as `epic-{N}` from the leading numeric segment of `{story_key}` (e.g., `3-2-digest-delivery` → `epic-3`). If that entry exists and is `backlog`, set it to `in-progress`. Leave it alone otherwise. Skip this sub-step entirely when `{target_status}` is not `in-progress`. +6. Refresh `last_updated` to the current date. +7. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS and WORKFLOW NOTES.