feat: add bmad dev auto skill
This commit is contained in:
Alex Verkhovsky
parent
6ac4c26b69
commit
10b7f67941
|
|
@ -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.
|
||||
|
|
@ -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-<N>-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}
|
||||
|
||||
<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
|
||||
|
||||
## 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.
|
||||
|
|
@ -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 = ""
|
||||
|
|
@ -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
|
||||
---
|
||||
|
||||
<!-- Aim for 900–1600 tokens. If larger, add `oversized` to frontmatter `warnings` and continue.
|
||||
Never over-specify "how" — use boundaries + examples instead.
|
||||
Cohesive cross-layer stories (DB+BE+UI) stay in ONE file.
|
||||
IMPORTANT: Remove all HTML comments when filling this template. -->
|
||||
|
||||
<frozen-after-approval reason="invocation-owned intent — do not modify unless a later invocation replaces it">
|
||||
|
||||
## Intent
|
||||
|
||||
<!-- What is broken or missing, and why it matters. Then the high-level approach — the "what", not the "how". -->
|
||||
|
||||
**Problem:** ONE_TO_TWO_SENTENCES
|
||||
|
||||
**Approach:** ONE_TO_TWO_SENTENCES
|
||||
|
||||
## Boundaries & Constraints
|
||||
|
||||
<!-- Three tiers: Always = invariant rules. Block If = decisions that cannot be made unattended. Never = out of scope + forbidden approaches. -->
|
||||
|
||||
**Always:** INVARIANT_RULES
|
||||
|
||||
**Block If:** DECISIONS_REQUIRING_HUMAN_INPUT
|
||||
<!-- Agent: if any of these trigger during execution, write the blocked condition to the result artifact and terminate cleanly. -->
|
||||
|
||||
**Never:** NON_GOALS_AND_FORBIDDEN_APPROACHES
|
||||
|
||||
## I/O & Edge-Case Matrix
|
||||
|
||||
<!-- If no meaningful I/O scenarios exist, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
|
||||
|
||||
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
||||
|----------|--------------|---------------------------|----------------|
|
||||
| HAPPY_PATH | INPUT | OUTCOME | N/A |
|
||||
| ERROR_CASE | INPUT | OUTCOME | ERROR_HANDLING |
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## Code Map
|
||||
|
||||
<!-- Agent-populated during planning. Annotated paths prevent blind codebase searching. -->
|
||||
|
||||
- `FILE` -- ROLE_OR_RELEVANCE
|
||||
- `FILE` -- ROLE_OR_RELEVANCE
|
||||
|
||||
## Tasks & Acceptance
|
||||
|
||||
<!-- Tasks: backtick-quoted file path -- action -- rationale. Prefer one task per file; group tightly-coupled changes when splitting would be artificial. -->
|
||||
<!-- If an I/O Matrix is present, include a task to unit-test its edge cases. -->
|
||||
<!-- AC covers system-level behaviors not captured by the I/O Matrix. Do not duplicate I/O scenarios here. -->
|
||||
|
||||
**Execution:**
|
||||
- [ ] `FILE` -- ACTION -- RATIONALE
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Given PRECONDITION, when ACTION, then EXPECTED_RESULT
|
||||
|
||||
## Spec Change Log
|
||||
|
||||
<!-- Append-only. Populated by step-04 during review loops. Do not modify or delete existing entries.
|
||||
Each entry records: what finding triggered the change, what was amended, what known-bad state
|
||||
the amendment avoids, and any KEEP instructions (what worked well and must survive re-derivation).
|
||||
Empty until the first bad_spec loopback. -->
|
||||
|
||||
## Design Notes
|
||||
|
||||
<!-- If the approach is straightforward, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
|
||||
<!-- Design rationale and golden examples only when non-obvious. Keep examples to 5–10 lines. -->
|
||||
|
||||
DESIGN_RATIONALE_AND_EXAMPLES
|
||||
|
||||
## Verification
|
||||
|
||||
<!-- If no build, test, or lint commands apply, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
|
||||
<!-- How the agent confirms its own work. Prefer CLI commands. When no CLI check applies, state what to inspect manually. -->
|
||||
|
||||
**Commands:**
|
||||
- `COMMAND` -- expected: SUCCESS_CRITERIA
|
||||
|
||||
**Manual checks (if no CLI):**
|
||||
- WHAT_TO_INSPECT_AND_EXPECTED_STATE
|
||||
|
|
@ -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-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> 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-<N>-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-<N>-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 <N> 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`
|
||||
|
|
@ -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 `<frozen-after-approval>...</frozen-after-approval>` 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 `<frozen-after-approval>` 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`
|
||||
|
|
@ -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 `<frozen-after-approval>` 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`
|
||||
|
|
@ -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 `<frozen-after-approval>`. 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 `<frozen-after-approval>`. 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`
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue