Initial commit: Brachnha Insight project setup
- Next.js 14+ with App Router and TypeScript - Tailwind CSS and ShadCN UI styling - Zustand state management - Dexie.js for IndexedDB (local-first data) - Auth.js v5 for authentication - BMAD framework integration Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Max
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: 'step-01-mode-detection'
|
||||
description: 'Determine execution mode (tech-spec vs direct), handle escalation, set state variables'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev'
|
||||
thisStepFile: './step-01-mode-detection.md'
|
||||
nextStepFile_modeA: './step-03-execute.md'
|
||||
nextStepFile_modeB: './step-02-context-gathering.md'
|
||||
---
|
||||
|
||||
# Step 1: Mode Detection
|
||||
|
||||
**Goal:** Determine execution mode, capture baseline, handle escalation if needed.
|
||||
|
||||
---
|
||||
|
||||
## STATE VARIABLES (capture now, persist throughout)
|
||||
|
||||
These variables MUST be set in this step and available to all subsequent steps:
|
||||
|
||||
- `{baseline_commit}` - Git HEAD at workflow start (or "NO_GIT" if not a git repo)
|
||||
- `{execution_mode}` - "tech-spec" or "direct"
|
||||
- `{tech_spec_path}` - Path to tech-spec file (if Mode A)
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION SEQUENCE
|
||||
|
||||
### 1. Capture Baseline
|
||||
|
||||
First, check if the project uses Git version control:
|
||||
|
||||
**If Git repo exists** (`.git` directory present or `git rev-parse --is-inside-work-tree` succeeds):
|
||||
|
||||
- Run `git rev-parse HEAD` and store result as `{baseline_commit}`
|
||||
|
||||
**If NOT a Git repo:**
|
||||
|
||||
- Set `{baseline_commit}` = "NO_GIT"
|
||||
|
||||
### 2. Load Project Context
|
||||
|
||||
Check if `{project_context}` exists (`**/project-context.md`). If found, load it as a foundational reference for ALL implementation decisions.
|
||||
|
||||
### 3. Parse User Input
|
||||
|
||||
Analyze the user's input to determine mode:
|
||||
|
||||
**Mode A: Tech-Spec**
|
||||
|
||||
- User provided a path to a tech-spec file (e.g., `quick-dev tech-spec-auth.md`)
|
||||
- Load the spec, extract tasks/context/AC
|
||||
- Set `{execution_mode}` = "tech-spec"
|
||||
- Set `{tech_spec_path}` = provided path
|
||||
- **NEXT:** Load `step-03-execute.md`
|
||||
|
||||
**Mode B: Direct Instructions**
|
||||
|
||||
- User provided task description directly (e.g., `refactor src/foo.ts...`)
|
||||
- Set `{execution_mode}` = "direct"
|
||||
- **NEXT:** Evaluate escalation threshold, then proceed
|
||||
|
||||
---
|
||||
|
||||
## ESCALATION THRESHOLD (Mode B only)
|
||||
|
||||
Evaluate user input with minimal token usage (no file loading):
|
||||
|
||||
**Triggers escalation (if 2+ signals present):**
|
||||
|
||||
- Multiple components mentioned (dashboard + api + database)
|
||||
- System-level language (platform, integration, architecture)
|
||||
- Uncertainty about approach ("how should I", "best way to")
|
||||
- Multi-layer scope (UI + backend + data together)
|
||||
- Extended timeframe ("this week", "over the next few days")
|
||||
|
||||
**Reduces signal:**
|
||||
|
||||
- Simplicity markers ("just", "quickly", "fix", "bug", "typo", "simple")
|
||||
- Single file/component focus
|
||||
- Confident, specific request
|
||||
|
||||
Use holistic judgment, not mechanical keyword matching.
|
||||
|
||||
---
|
||||
|
||||
## ESCALATION HANDLING
|
||||
|
||||
### No Escalation (simple request)
|
||||
|
||||
Present choice:
|
||||
|
||||
```
|
||||
**[t] Plan first** - Create tech-spec then implement
|
||||
**[e] Execute directly** - Start now
|
||||
```
|
||||
|
||||
- **[t]:** Direct user to `{quick_spec_workflow}`. **EXIT Quick Dev.**
|
||||
- **[e]:** Ask for any additional guidance, then **NEXT:** Load `step-02-context-gathering.md`
|
||||
|
||||
### Escalation Triggered - Level 0-2
|
||||
|
||||
```
|
||||
This looks like a focused feature with multiple components.
|
||||
|
||||
**[t] Create tech-spec first** (recommended)
|
||||
**[w] Seems bigger than quick-dev** - see what BMad Method recommends
|
||||
**[e] Execute directly**
|
||||
```
|
||||
|
||||
- **[t]:** Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
|
||||
- **[w]:** Direct to `{workflow_init}`. **EXIT Quick Dev.**
|
||||
- **[e]:** Ask for guidance, then **NEXT:** Load `step-02-context-gathering.md`
|
||||
|
||||
### Escalation Triggered - Level 3+
|
||||
|
||||
```
|
||||
This sounds like platform/system work.
|
||||
|
||||
**[w] Start BMad Method** (recommended)
|
||||
**[t] Create tech-spec** (lighter planning)
|
||||
**[e] Execute directly** - feeling lucky
|
||||
```
|
||||
|
||||
- **[w]:** Direct to `{workflow_init}`. **EXIT Quick Dev.**
|
||||
- **[t]:** Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
|
||||
- **[e]:** Ask for guidance, then **NEXT:** Load `step-02-context-gathering.md`
|
||||
|
||||
---
|
||||
|
||||
## NEXT STEP DIRECTIVE
|
||||
|
||||
**CRITICAL:** When this step completes, explicitly state which step to load:
|
||||
|
||||
- Mode A (tech-spec): "**NEXT:** Loading `step-03-execute.md`"
|
||||
- Mode B (direct, [e] selected): "**NEXT:** Loading `step-02-context-gathering.md`"
|
||||
- Escalation ([t] or [w]): "**EXITING Quick Dev.** Follow the directed workflow."
|
||||
|
||||
---
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
- `{baseline_commit}` captured and stored
|
||||
- `{execution_mode}` determined ("tech-spec" or "direct")
|
||||
- `{tech_spec_path}` set if Mode A
|
||||
- Project context loaded if exists
|
||||
- Escalation evaluated appropriately (Mode B)
|
||||
- Explicit NEXT directive provided
|
||||
|
||||
## FAILURE MODES
|
||||
|
||||
- Proceeding without capturing baseline commit
|
||||
- Not setting execution_mode variable
|
||||
- Loading step-02 when Mode A (tech-spec provided)
|
||||
- Attempting to "return" after escalation instead of EXIT
|
||||
- No explicit NEXT directive at step completion
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
name: 'step-02-context-gathering'
|
||||
description: 'Quick context gathering for direct mode - identify files, patterns, dependencies'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev'
|
||||
thisStepFile: './step-02-context-gathering.md'
|
||||
nextStepFile: './step-03-execute.md'
|
||||
---
|
||||
|
||||
# Step 2: Context Gathering (Direct Mode)
|
||||
|
||||
**Goal:** Quickly gather context for direct instructions - files, patterns, dependencies.
|
||||
|
||||
**Note:** This step only runs for Mode B (direct instructions). If `{execution_mode}` is "tech-spec", this step was skipped.
|
||||
|
||||
---
|
||||
|
||||
## AVAILABLE STATE
|
||||
|
||||
From step-01:
|
||||
|
||||
- `{baseline_commit}` - Git HEAD at workflow start
|
||||
- `{execution_mode}` - Should be "direct"
|
||||
- `{project_context}` - Loaded if exists
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION SEQUENCE
|
||||
|
||||
### 1. Identify Files to Modify
|
||||
|
||||
Based on user's direct instructions:
|
||||
|
||||
- Search for relevant files using glob/grep
|
||||
- Identify the specific files that need changes
|
||||
- Note file locations and purposes
|
||||
|
||||
### 2. Find Relevant Patterns
|
||||
|
||||
Examine the identified files and their surroundings:
|
||||
|
||||
- Code style and conventions used
|
||||
- Existing patterns for similar functionality
|
||||
- Import/export patterns
|
||||
- Error handling approaches
|
||||
- Test patterns (if tests exist nearby)
|
||||
|
||||
### 3. Note Dependencies
|
||||
|
||||
Identify:
|
||||
|
||||
- External libraries used
|
||||
- Internal module dependencies
|
||||
- Configuration files that may need updates
|
||||
- Related files that might be affected
|
||||
|
||||
### 4. Create Mental Plan
|
||||
|
||||
Synthesize gathered context into:
|
||||
|
||||
- List of tasks to complete
|
||||
- Acceptance criteria (inferred from user request)
|
||||
- Order of operations
|
||||
- Files to touch
|
||||
|
||||
---
|
||||
|
||||
## PRESENT PLAN
|
||||
|
||||
Display to user:
|
||||
|
||||
```
|
||||
**Context Gathered:**
|
||||
|
||||
**Files to modify:**
|
||||
- {list files}
|
||||
|
||||
**Patterns identified:**
|
||||
- {key patterns}
|
||||
|
||||
**Plan:**
|
||||
1. {task 1}
|
||||
2. {task 2}
|
||||
...
|
||||
|
||||
**Inferred AC:**
|
||||
- {acceptance criteria}
|
||||
|
||||
Ready to execute? (y/n/adjust)
|
||||
```
|
||||
|
||||
- **y:** Proceed to execution
|
||||
- **n:** Gather more context or clarify
|
||||
- **adjust:** Modify the plan based on feedback
|
||||
|
||||
---
|
||||
|
||||
## NEXT STEP DIRECTIVE
|
||||
|
||||
**CRITICAL:** When user confirms ready, explicitly state:
|
||||
|
||||
- **y:** "**NEXT:** Loading `step-03-execute.md`"
|
||||
- **n/adjust:** Continue gathering context, then re-present plan
|
||||
|
||||
---
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
- Files to modify identified
|
||||
- Relevant patterns documented
|
||||
- Dependencies noted
|
||||
- Mental plan created with tasks and AC
|
||||
- User confirmed readiness to proceed
|
||||
|
||||
## FAILURE MODES
|
||||
|
||||
- Executing this step when Mode A (tech-spec)
|
||||
- Proceeding without identifying files to modify
|
||||
- Not presenting plan for user confirmation
|
||||
- Missing obvious patterns in existing code
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: 'step-03-execute'
|
||||
description: 'Execute implementation - iterate through tasks, write code, run tests'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev'
|
||||
thisStepFile: './step-03-execute.md'
|
||||
nextStepFile: './step-04-self-check.md'
|
||||
---
|
||||
|
||||
# Step 3: Execute Implementation
|
||||
|
||||
**Goal:** Implement all tasks, write tests, follow patterns, handle errors.
|
||||
|
||||
**Critical:** Continue through ALL tasks without stopping for milestones.
|
||||
|
||||
---
|
||||
|
||||
## AVAILABLE STATE
|
||||
|
||||
From previous steps:
|
||||
|
||||
- `{baseline_commit}` - Git HEAD at workflow start
|
||||
- `{execution_mode}` - "tech-spec" or "direct"
|
||||
- `{tech_spec_path}` - Tech-spec file (if Mode A)
|
||||
- `{project_context}` - Project patterns (if exists)
|
||||
|
||||
From context:
|
||||
|
||||
- Mode A: Tasks and AC extracted from tech-spec
|
||||
- Mode B: Tasks and AC from step-02 mental plan
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION LOOP
|
||||
|
||||
For each task:
|
||||
|
||||
### 1. Load Context
|
||||
|
||||
- Read files relevant to this task
|
||||
- Review patterns from project-context or observed code
|
||||
- Understand dependencies
|
||||
|
||||
### 2. Implement
|
||||
|
||||
- Write code following existing patterns
|
||||
- Handle errors appropriately
|
||||
- Follow conventions observed in codebase
|
||||
- Add appropriate comments where non-obvious
|
||||
|
||||
### 3. Test
|
||||
|
||||
- Write tests if appropriate for the change
|
||||
- Run existing tests to catch regressions
|
||||
- Verify the specific AC for this task
|
||||
|
||||
### 4. Mark Complete
|
||||
|
||||
- Check off task: `- [x] Task N`
|
||||
- Continue to next task immediately
|
||||
|
||||
---
|
||||
|
||||
## HALT CONDITIONS
|
||||
|
||||
**HALT and request guidance if:**
|
||||
|
||||
- 3 consecutive failures on same task
|
||||
- Tests fail and fix is not obvious
|
||||
- Blocking dependency discovered
|
||||
- Ambiguity that requires user decision
|
||||
|
||||
**Do NOT halt for:**
|
||||
|
||||
- Minor issues that can be noted and continued
|
||||
- Warnings that don't block functionality
|
||||
- Style preferences (follow existing patterns)
|
||||
|
||||
---
|
||||
|
||||
## CONTINUOUS EXECUTION
|
||||
|
||||
**Critical:** Do not stop between tasks for approval.
|
||||
|
||||
- Execute all tasks in sequence
|
||||
- Only halt for blocking issues
|
||||
- Tests failing = fix before continuing
|
||||
- Track all completed work for self-check
|
||||
|
||||
---
|
||||
|
||||
## NEXT STEP
|
||||
|
||||
When ALL tasks are complete (or halted on blocker), load `step-04-self-check.md`.
|
||||
|
||||
---
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
- All tasks attempted
|
||||
- Code follows existing patterns
|
||||
- Error handling appropriate
|
||||
- Tests written where appropriate
|
||||
- Tests passing
|
||||
- No unnecessary halts
|
||||
|
||||
## FAILURE MODES
|
||||
|
||||
- Stopping for approval between tasks
|
||||
- Ignoring existing patterns
|
||||
- Not running tests after changes
|
||||
- Giving up after first failure
|
||||
- Not following project-context rules (if exists)
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: 'step-04-self-check'
|
||||
description: 'Self-audit implementation against tasks, tests, AC, and patterns'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev'
|
||||
thisStepFile: './step-04-self-check.md'
|
||||
nextStepFile: './step-05-adversarial-review.md'
|
||||
---
|
||||
|
||||
# Step 4: Self-Check
|
||||
|
||||
**Goal:** Audit completed work against tasks, tests, AC, and patterns before external review.
|
||||
|
||||
---
|
||||
|
||||
## AVAILABLE STATE
|
||||
|
||||
From previous steps:
|
||||
|
||||
- `{baseline_commit}` - Git HEAD at workflow start
|
||||
- `{execution_mode}` - "tech-spec" or "direct"
|
||||
- `{tech_spec_path}` - Tech-spec file (if Mode A)
|
||||
- `{project_context}` - Project patterns (if exists)
|
||||
|
||||
---
|
||||
|
||||
## SELF-CHECK AUDIT
|
||||
|
||||
### 1. Tasks Complete
|
||||
|
||||
Verify all tasks are marked complete:
|
||||
|
||||
- [ ] All tasks from tech-spec or mental plan marked `[x]`
|
||||
- [ ] No tasks skipped without documented reason
|
||||
- [ ] Any blocked tasks have clear explanation
|
||||
|
||||
### 2. Tests Passing
|
||||
|
||||
Verify test status:
|
||||
|
||||
- [ ] All existing tests still pass
|
||||
- [ ] New tests written for new functionality
|
||||
- [ ] No test warnings or skipped tests without reason
|
||||
|
||||
### 3. Acceptance Criteria Satisfied
|
||||
|
||||
For each AC:
|
||||
|
||||
- [ ] AC is demonstrably met
|
||||
- [ ] Can explain how implementation satisfies AC
|
||||
- [ ] Edge cases considered
|
||||
|
||||
### 4. Patterns Followed
|
||||
|
||||
Verify code quality:
|
||||
|
||||
- [ ] Follows existing code patterns in codebase
|
||||
- [ ] Follows project-context rules (if exists)
|
||||
- [ ] Error handling consistent with codebase
|
||||
- [ ] No obvious code smells introduced
|
||||
|
||||
---
|
||||
|
||||
## UPDATE TECH-SPEC (Mode A only)
|
||||
|
||||
If `{execution_mode}` is "tech-spec":
|
||||
|
||||
1. Load `{tech_spec_path}`
|
||||
2. Mark all tasks as `[x]` complete
|
||||
3. Update status to "Implementation Complete"
|
||||
4. Save changes
|
||||
|
||||
---
|
||||
|
||||
## IMPLEMENTATION SUMMARY
|
||||
|
||||
Present summary to transition to review:
|
||||
|
||||
```
|
||||
**Implementation Complete!**
|
||||
|
||||
**Summary:** {what was implemented}
|
||||
**Files Modified:** {list of files}
|
||||
**Tests:** {test summary - passed/added/etc}
|
||||
**AC Status:** {all satisfied / issues noted}
|
||||
|
||||
Proceeding to adversarial code review...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## NEXT STEP
|
||||
|
||||
Proceed immediately to `step-05-adversarial-review.md`.
|
||||
|
||||
---
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
- All tasks verified complete
|
||||
- All tests passing
|
||||
- All AC satisfied
|
||||
- Patterns followed
|
||||
- Tech-spec updated (if Mode A)
|
||||
- Summary presented
|
||||
|
||||
## FAILURE MODES
|
||||
|
||||
- Claiming tasks complete when they're not
|
||||
- Not running tests before proceeding
|
||||
- Missing AC verification
|
||||
- Ignoring pattern violations
|
||||
- Not updating tech-spec status (Mode A)
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
name: 'step-05-adversarial-review'
|
||||
description: 'Construct diff and invoke adversarial review task'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev'
|
||||
thisStepFile: './step-05-adversarial-review.md'
|
||||
nextStepFile: './step-06-resolve-findings.md'
|
||||
---
|
||||
|
||||
# Step 5: Adversarial Code Review
|
||||
|
||||
**Goal:** Construct diff of all changes, invoke adversarial review task, present findings.
|
||||
|
||||
---
|
||||
|
||||
## AVAILABLE STATE
|
||||
|
||||
From previous steps:
|
||||
|
||||
- `{baseline_commit}` - Git HEAD at workflow start (CRITICAL for diff)
|
||||
- `{execution_mode}` - "tech-spec" or "direct"
|
||||
- `{tech_spec_path}` - Tech-spec file (if Mode A)
|
||||
|
||||
---
|
||||
|
||||
### 1. Construct Diff
|
||||
|
||||
Build complete diff of all changes since workflow started.
|
||||
|
||||
### If `{baseline_commit}` is a Git commit hash:
|
||||
|
||||
**Tracked File Changes:**
|
||||
|
||||
```bash
|
||||
git diff {baseline_commit}
|
||||
```
|
||||
|
||||
**New Untracked Files:**
|
||||
Only include untracked files that YOU created during this workflow (steps 2-4).
|
||||
Do not include pre-existing untracked files.
|
||||
For each new file created, include its full content as a "new file" addition.
|
||||
|
||||
### If `{baseline_commit}` is "NO_GIT":
|
||||
|
||||
Use best-effort diff construction:
|
||||
|
||||
- List all files you modified during steps 2-4
|
||||
- For each file, show the changes you made (before/after if you recall, or just current state)
|
||||
- Include any new files you created with their full content
|
||||
- Note: This is less precise than Git diff but still enables meaningful review
|
||||
|
||||
### Capture as {diff_output}
|
||||
|
||||
Merge all changes into `{diff_output}`.
|
||||
|
||||
**Note:** Do NOT `git add` anything - this is read-only inspection.
|
||||
|
||||
---
|
||||
|
||||
### 2. Invoke Adversarial Review
|
||||
|
||||
With `{diff_output}` constructed, invoke the review task. If possible, use information asymmetry: run this step, and only it, in a separate subagent or process with read access to the project, but no context except the `{diff_output}`.
|
||||
|
||||
```xml
|
||||
<invoke-task>Review {diff_output} using {project-root}/_bmad/core/tasks/review-adversarial-general.xml</invoke-task>
|
||||
```
|
||||
|
||||
**Platform fallback:** If task invocation not available, load the task file and execute its instructions inline, passing `{diff_output}` as the content.
|
||||
|
||||
The task should: review `{diff_output}` and return a list of findings.
|
||||
|
||||
---
|
||||
|
||||
### 3. Process Findings
|
||||
|
||||
Capture the findings from the task output.
|
||||
**If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance.
|
||||
Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided).
|
||||
DO NOT exclude findings based on severity or validity unless explicitly asked to do so.
|
||||
Order findings by severity.
|
||||
Number the ordered findings (F1, F2, F3, etc.).
|
||||
If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description
|
||||
|
||||
---
|
||||
|
||||
## NEXT STEP
|
||||
|
||||
With findings in hand, load `step-06-resolve-findings.md` for user to choose resolution approach.
|
||||
|
||||
---
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
- Diff constructed from baseline_commit
|
||||
- New files included in diff
|
||||
- Task invoked with diff as input
|
||||
- Findings received
|
||||
- Findings processed into TODOs or table and presented to user
|
||||
|
||||
## FAILURE MODES
|
||||
|
||||
- Missing baseline_commit (can't construct accurate diff)
|
||||
- Not including new untracked files in diff
|
||||
- Invoking task without providing diff input
|
||||
- Accepting zero findings without questioning
|
||||
- Presenting fewer findings than the review task returned without explicit instruction to do so
|
||||
@@ -0,0 +1,140 @@
|
||||
---
|
||||
name: 'step-06-resolve-findings'
|
||||
description: 'Handle review findings interactively, apply fixes, update tech-spec with final status'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev'
|
||||
thisStepFile: './step-06-resolve-findings.md'
|
||||
---
|
||||
|
||||
# Step 6: Resolve Findings
|
||||
|
||||
**Goal:** Handle adversarial review findings interactively, apply fixes, finalize tech-spec.
|
||||
|
||||
---
|
||||
|
||||
## AVAILABLE STATE
|
||||
|
||||
From previous steps:
|
||||
|
||||
- `{baseline_commit}` - Git HEAD at workflow start
|
||||
- `{execution_mode}` - "tech-spec" or "direct"
|
||||
- `{tech_spec_path}` - Tech-spec file (if Mode A)
|
||||
- Findings table from step-05
|
||||
|
||||
---
|
||||
|
||||
## RESOLUTION OPTIONS
|
||||
|
||||
Present choice to user:
|
||||
|
||||
```
|
||||
How would you like to handle these findings?
|
||||
|
||||
**[1] Walk through** - Discuss each finding individually
|
||||
**[2] Auto-fix** - Automatically fix issues classified as "real"
|
||||
**[3] Skip** - Acknowledge and proceed to commit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OPTION 1: WALK THROUGH
|
||||
|
||||
For each finding in order:
|
||||
|
||||
1. Present the finding with context
|
||||
2. Ask: **fix now / skip / discuss**
|
||||
3. If fix: Apply the fix immediately
|
||||
4. If skip: Note as acknowledged, continue
|
||||
5. If discuss: Provide more context, re-ask
|
||||
6. Move to next finding
|
||||
|
||||
After all findings processed, summarize what was fixed/skipped.
|
||||
|
||||
---
|
||||
|
||||
## OPTION 2: AUTO-FIX
|
||||
|
||||
1. Filter findings to only those classified as "real"
|
||||
2. Apply fixes for each real finding
|
||||
3. Report what was fixed:
|
||||
|
||||
```
|
||||
**Auto-fix Applied:**
|
||||
- F1: {description of fix}
|
||||
- F3: {description of fix}
|
||||
...
|
||||
|
||||
Skipped (noise/uncertain): F2, F4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OPTION 3: SKIP
|
||||
|
||||
1. Acknowledge all findings were reviewed
|
||||
2. Note that user chose to proceed without fixes
|
||||
3. Continue to completion
|
||||
|
||||
---
|
||||
|
||||
## UPDATE TECH-SPEC (Mode A only)
|
||||
|
||||
If `{execution_mode}` is "tech-spec":
|
||||
|
||||
1. Load `{tech_spec_path}`
|
||||
2. Update status to "Completed"
|
||||
3. Add review notes:
|
||||
```
|
||||
## Review Notes
|
||||
- Adversarial review completed
|
||||
- Findings: {count} total, {fixed} fixed, {skipped} skipped
|
||||
- Resolution approach: {walk-through/auto-fix/skip}
|
||||
```
|
||||
4. Save changes
|
||||
|
||||
---
|
||||
|
||||
## COMPLETION OUTPUT
|
||||
|
||||
```
|
||||
**Review complete. Ready to commit.**
|
||||
|
||||
**Implementation Summary:**
|
||||
- {what was implemented}
|
||||
- Files modified: {count}
|
||||
- Tests: {status}
|
||||
- Review findings: {X} addressed, {Y} skipped
|
||||
|
||||
{Explain what was implemented based on user_skill_level}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW COMPLETE
|
||||
|
||||
This is the final step. The Quick Dev workflow is now complete.
|
||||
|
||||
User can:
|
||||
|
||||
- Commit changes
|
||||
- Run additional tests
|
||||
- Start new Quick Dev session
|
||||
|
||||
---
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
- User presented with resolution options
|
||||
- Chosen approach executed correctly
|
||||
- Fixes applied cleanly (if applicable)
|
||||
- Tech-spec updated with final status (Mode A)
|
||||
- Completion summary provided
|
||||
- User understands what was implemented
|
||||
|
||||
## FAILURE MODES
|
||||
|
||||
- Not presenting resolution options
|
||||
- Auto-fixing "noise" or "uncertain" findings
|
||||
- Not updating tech-spec after resolution (Mode A)
|
||||
- No completion summary
|
||||
- Leaving user unclear on next steps
|
||||
52
_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md
Normal file
52
_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: quick-dev
|
||||
description: 'Flexible development - execute tech-specs OR direct instructions with optional planning.'
|
||||
---
|
||||
|
||||
# Quick Dev Workflow
|
||||
|
||||
**Goal:** Execute implementation tasks efficiently, either from a tech-spec or direct user instructions.
|
||||
|
||||
**Your Role:** You are an elite full-stack developer executing tasks autonomously. Follow patterns, ship code, run tests. Every response moves the project forward.
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **step-file architecture** for focused execution:
|
||||
|
||||
- Each step loads fresh to combat "lost in the middle"
|
||||
- State persists via variables: `{baseline_commit}`, `{execution_mode}`, `{tech_spec_path}`
|
||||
- Sequential progression through implementation phases
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION
|
||||
|
||||
### Configuration Loading
|
||||
|
||||
Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
|
||||
|
||||
- `user_name`, `communication_language`, `user_skill_level`
|
||||
- `output_folder`, `planning_artifacts`, `implementation_artifacts`
|
||||
- `date` as system-generated current datetime
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Paths
|
||||
|
||||
- `installed_path` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev`
|
||||
- `project_context` = `**/project-context.md` (load if exists)
|
||||
- `project_levels` = `{project-root}/_bmad/bmm/workflows/workflow-status/project-levels.yaml`
|
||||
|
||||
### Related Workflows
|
||||
|
||||
- `quick_spec_workflow` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md`
|
||||
- `workflow_init` = `{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.yaml`
|
||||
- `party_mode_exec` = `{project-root}/_bmad/core/workflows/party-mode/workflow.md`
|
||||
- `advanced_elicitation` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml`
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION
|
||||
|
||||
Load and execute `steps/step-01-mode-detection.md` to begin the workflow.
|
||||
@@ -0,0 +1,189 @@
|
||||
---
|
||||
name: 'step-01-understand'
|
||||
description: 'Analyze the requirement delta between current state and what user wants to build'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec'
|
||||
nextStepFile: './step-02-investigate.md'
|
||||
skipToStepFile: './step-03-generate.md'
|
||||
templateFile: '{workflow_path}/tech-spec-template.md'
|
||||
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
|
||||
---
|
||||
|
||||
# Step 1: Analyze Requirement Delta
|
||||
|
||||
**Progress: Step 1 of 4** - Next: Deep Investigation
|
||||
|
||||
## RULES:
|
||||
|
||||
- MUST NOT skip steps.
|
||||
- MUST NOT optimize sequence.
|
||||
- MUST follow exact instructions.
|
||||
- MUST NOT look ahead to future steps.
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## CONTEXT:
|
||||
|
||||
- Variables from `workflow.md` are available in memory.
|
||||
- Focus: Define the technical requirement delta and scope.
|
||||
- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2.
|
||||
- Objective: Establish a verifiable delta between current state and target state.
|
||||
|
||||
## SEQUENCE OF INSTRUCTIONS
|
||||
|
||||
### 0. Check for Work in Progress
|
||||
|
||||
a) **Before anything else, check if `{wipFile}` exists:**
|
||||
|
||||
b) **IF WIP FILE EXISTS:**
|
||||
|
||||
1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted`
|
||||
2. Calculate progress: `lastStep = max(stepsCompleted)`
|
||||
3. Present to user:
|
||||
|
||||
```
|
||||
Hey {user_name}! Found a tech-spec in progress:
|
||||
|
||||
**{title}** - Step {lastStep} of 4 complete
|
||||
|
||||
Is this what you're here to continue?
|
||||
|
||||
[y] Yes, pick up where I left off
|
||||
[n] No, archive it and start something new
|
||||
```
|
||||
|
||||
4. **HALT and wait for user selection.**
|
||||
|
||||
a) **Menu Handling:**
|
||||
|
||||
- **[y] Continue existing:**
|
||||
- Jump directly to the appropriate step based on `stepsCompleted`:
|
||||
- `[1]` → Load `{nextStepFile}` (Step 2)
|
||||
- `[1, 2]` → Load `{skipToStepFile}` (Step 3)
|
||||
- `[1, 2, 3]` → Load `./step-04-review.md` (Step 4)
|
||||
- **[n] Archive and start fresh:**
|
||||
- Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md`
|
||||
|
||||
### 1. Greet and Ask for Initial Request
|
||||
|
||||
a) **Greet the user briefly:**
|
||||
|
||||
"Hey {user_name}! What are we building today?"
|
||||
|
||||
b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look.
|
||||
|
||||
### 2. Quick Orient Scan
|
||||
|
||||
a) **Before asking detailed questions, do a rapid scan to understand the landscape:**
|
||||
|
||||
b) **Check for existing context docs:**
|
||||
|
||||
- Check `{output_folder}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
|
||||
- Check for `**/project-context.md` - if it exists, skim for patterns and conventions
|
||||
- Check for any existing stories or specs related to user's request
|
||||
|
||||
c) **If user mentioned specific code/features, do a quick scan:**
|
||||
|
||||
- Search for relevant files/classes/functions they mentioned
|
||||
- Skim the structure (don't deep-dive yet - that's Step 2)
|
||||
- Note: tech stack, obvious patterns, file locations
|
||||
|
||||
d) **Build mental model:**
|
||||
|
||||
- What's the likely landscape for this feature?
|
||||
- What's the likely scope based on what you found?
|
||||
- What questions do you NOW have, informed by the code?
|
||||
|
||||
**This scan should take < 30 seconds. Just enough to ask smart questions.**
|
||||
|
||||
### 3. Ask Informed Questions
|
||||
|
||||
a) **Now ask clarifying questions - but make them INFORMED by what you found:**
|
||||
|
||||
Instead of generic questions like "What's the scope?", ask specific ones like:
|
||||
- "`AuthService` handles validation in the controller — should the new field follow that pattern or move it to a dedicated validator?"
|
||||
- "`NavigationSidebar` component uses local state for the 'collapsed' toggle — should we stick with that or move it to the global store?"
|
||||
- "The epics doc mentions X - is this related?"
|
||||
|
||||
**Adapt to {user_skill_level}.** Technical users want technical questions. Non-technical users need translation.
|
||||
|
||||
b) **If no existing code is found:**
|
||||
|
||||
- Ask about intended architecture, patterns, constraints
|
||||
- Ask what similar systems they'd like to emulate
|
||||
|
||||
### 4. Capture Core Understanding
|
||||
|
||||
a) **From the conversation, extract and confirm:**
|
||||
|
||||
- **Title**: A clear, concise name for this work
|
||||
- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces)
|
||||
- **Problem Statement**: What problem are we solving?
|
||||
- **Solution**: High-level approach (1-2 sentences)
|
||||
- **In Scope**: What's included
|
||||
- **Out of Scope**: What's explicitly NOT included
|
||||
|
||||
b) **Ask the user to confirm the captured understanding before proceeding.**
|
||||
|
||||
### 5. Initialize WIP File
|
||||
|
||||
a) **Create the tech-spec WIP file:**
|
||||
|
||||
1. Copy template from `{templateFile}`
|
||||
2. Write to `{wipFile}`
|
||||
3. Update frontmatter with captured values:
|
||||
```yaml
|
||||
---
|
||||
title: '{title}'
|
||||
slug: '{slug}'
|
||||
created: '{date}'
|
||||
status: 'in-progress'
|
||||
stepsCompleted: [1]
|
||||
tech_stack: []
|
||||
files_to_modify: []
|
||||
code_patterns: []
|
||||
test_patterns: []
|
||||
---
|
||||
```
|
||||
4. Fill in Overview section with Problem Statement, Solution, and Scope
|
||||
5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery.
|
||||
6. Write the file
|
||||
|
||||
b) **Report to user:**
|
||||
|
||||
"Created: `{wipFile}`
|
||||
|
||||
**Captured:**
|
||||
|
||||
- Title: {title}
|
||||
- Problem: {problem_statement_summary}
|
||||
- Scope: {scope_summary}"
|
||||
|
||||
### 6. Present Checkpoint Menu
|
||||
|
||||
a) **Display menu:**
|
||||
|
||||
```
|
||||
[a] Advanced Elicitation - dig deeper into requirements
|
||||
[c] Continue - proceed to next step
|
||||
[p] Party Mode - bring in other experts
|
||||
```
|
||||
|
||||
b) **HALT and wait for user selection.**
|
||||
|
||||
#### Menu Handling:
|
||||
|
||||
- **[a]**: Load and execute `{advanced_elicitation}`, then return here and redisplay menu
|
||||
- **[c]**: Load and execute `{nextStepFile}` (Map Technical Constraints)
|
||||
- **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu
|
||||
|
||||
---
|
||||
|
||||
## REQUIRED OUTPUTS:
|
||||
|
||||
- MUST initialize WIP file with captured metadata.
|
||||
|
||||
## VERIFICATION CHECKLIST:
|
||||
|
||||
- [ ] WIP check performed FIRST before any greeting.
|
||||
- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
|
||||
- [ ] User selected [c] to continue.
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
name: 'step-02-investigate'
|
||||
description: 'Map technical constraints and anchor points within the codebase'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec'
|
||||
nextStepFile: './step-03-generate.md'
|
||||
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
|
||||
---
|
||||
|
||||
# Step 2: Map Technical Constraints & Anchor Points
|
||||
|
||||
**Progress: Step 2 of 4** - Next: Generate Plan
|
||||
|
||||
## RULES:
|
||||
|
||||
- MUST NOT skip steps.
|
||||
- MUST NOT optimize sequence.
|
||||
- MUST follow exact instructions.
|
||||
- MUST NOT generate the full spec yet (that's Step 3).
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## CONTEXT:
|
||||
|
||||
- Requires `{wipFile}` from Step 1 with the "Problem Statement" defined.
|
||||
- Focus: Map the problem statement to specific anchor points in the codebase.
|
||||
- Output: Exact files to touch, classes/patterns to extend, and technical constraints identified.
|
||||
- Objective: Provide the implementation-ready ground truth for the plan.
|
||||
|
||||
## SEQUENCE OF INSTRUCTIONS
|
||||
|
||||
### 1. Load Current State
|
||||
|
||||
**Read `{wipFile}` and extract:**
|
||||
|
||||
- Problem statement and scope from Overview section
|
||||
- Any context gathered in Step 1
|
||||
|
||||
### 2. Execute Investigation Path
|
||||
|
||||
**Universal Code Investigation:**
|
||||
|
||||
_Isolate deep exploration in sub-agents/tasks where available. Return distilled summaries only to prevent context snowballing._
|
||||
|
||||
a) **Build on Step 1's Quick Scan**
|
||||
|
||||
Review what was found in Step 1's orient scan. Then ask:
|
||||
|
||||
"Based on my quick look, I see [files/patterns found]. Are there other files or directories I should investigate deeply?"
|
||||
|
||||
b) **Read and Analyze Code**
|
||||
|
||||
For each file/directory provided:
|
||||
|
||||
- Read the complete file(s)
|
||||
- Identify patterns, conventions, coding style
|
||||
- Note dependencies and imports
|
||||
- Find related test files
|
||||
|
||||
**If NO relevant code is found (Clean Slate):**
|
||||
|
||||
- Identify the target directory where the feature should live.
|
||||
- Scan parent directories for architectural context.
|
||||
- Identify standard project utilities or boilerplate that SHOULD be used.
|
||||
- Document this as "Confirmed Clean Slate" - establishing that no legacy constraints exist.
|
||||
|
||||
|
||||
c) **Document Technical Context**
|
||||
|
||||
Capture and confirm with user:
|
||||
|
||||
- **Tech Stack**: Languages, frameworks, libraries
|
||||
- **Code Patterns**: Architecture patterns, naming conventions, file structure
|
||||
- **Files to Modify/Create**: Specific files that will need changes or new files to be created
|
||||
- **Test Patterns**: How tests are structured, test frameworks used
|
||||
|
||||
d) **Look for project-context.md**
|
||||
|
||||
If `**/project-context.md` exists and wasn't loaded in Step 1:
|
||||
|
||||
- Load it now
|
||||
- Extract patterns and conventions
|
||||
- Note any rules that must be followed
|
||||
|
||||
### 3. Update WIP File
|
||||
|
||||
**Update `{wipFile}` frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
# ... existing frontmatter ...
|
||||
stepsCompleted: [1, 2]
|
||||
tech_stack: ['{captured_tech_stack}']
|
||||
files_to_modify: ['{captured_files}']
|
||||
code_patterns: ['{captured_patterns}']
|
||||
test_patterns: ['{captured_test_patterns}']
|
||||
---
|
||||
```
|
||||
|
||||
**Update the Context for Development section:**
|
||||
|
||||
Fill in:
|
||||
|
||||
- Codebase Patterns (from investigation)
|
||||
- Files to Reference table (files reviewed)
|
||||
- Technical Decisions (any decisions made during investigation)
|
||||
|
||||
**Report to user:**
|
||||
|
||||
"**Context Gathered:**
|
||||
|
||||
- Tech Stack: {tech_stack_summary}
|
||||
- Files to Modify: {files_count} files identified
|
||||
- Patterns: {patterns_summary}
|
||||
- Tests: {test_patterns_summary}"
|
||||
|
||||
### 4. Present Checkpoint Menu
|
||||
|
||||
**Display menu:**
|
||||
|
||||
```
|
||||
[a] Advanced Elicitation - explore more context
|
||||
[c] Continue - proceed to Generate Spec
|
||||
[p] Party Mode - bring in other experts
|
||||
```
|
||||
|
||||
**HALT and wait for user selection.**
|
||||
|
||||
#### Menu Handling:
|
||||
|
||||
- **[a]**: Load and execute `{advanced_elicitation}`, then return here and redisplay menu
|
||||
- **[c]**: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then load and execute `{nextStepFile}`
|
||||
- **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu
|
||||
|
||||
---
|
||||
|
||||
## REQUIRED OUTPUTS:
|
||||
|
||||
- MUST document technical context (stack, patterns, files identified).
|
||||
- MUST update `{wipFile}` with functional context.
|
||||
|
||||
## VERIFICATION CHECKLIST:
|
||||
|
||||
- [ ] Technical mapping performed and documented.
|
||||
- [ ] `stepsCompleted: [1, 2]` set in frontmatter.
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
name: 'step-03-generate'
|
||||
description: 'Build the implementation plan based on the technical mapping of constraints'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec'
|
||||
nextStepFile: './step-04-review.md'
|
||||
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
|
||||
---
|
||||
|
||||
# Step 3: Generate Implementation Plan
|
||||
|
||||
**Progress: Step 3 of 4** - Next: Review & Finalize
|
||||
|
||||
## RULES:
|
||||
|
||||
- MUST NOT skip steps.
|
||||
- MUST NOT optimize sequence.
|
||||
- MUST follow exact instructions.
|
||||
- MUST NOT implement anything - just document.
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## CONTEXT:
|
||||
|
||||
- Requires `{wipFile}` with defined "Overview" and "Context for Development" sections.
|
||||
- Focus: Create the implementation sequence that addresses the requirement delta using the captured technical context.
|
||||
- Output: Implementation-ready tasks with specific files and instructions.
|
||||
- Target: Meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`.
|
||||
|
||||
## SEQUENCE OF INSTRUCTIONS
|
||||
|
||||
### 1. Load Current State
|
||||
|
||||
**Read `{wipFile}` completely and extract:**
|
||||
|
||||
- All frontmatter values
|
||||
- Overview section (Problem, Solution, Scope)
|
||||
- Context for Development section (Patterns, Files, Decisions)
|
||||
|
||||
### 2. Generate Implementation Plan
|
||||
|
||||
Generate specific implementation tasks:
|
||||
|
||||
a) **Task Breakdown**
|
||||
|
||||
- Each task should be a discrete, completable unit of work
|
||||
- Tasks should be ordered logically (dependencies first)
|
||||
- Include the specific files to modify in each task
|
||||
- Be explicit about what changes to make
|
||||
|
||||
b) **Task Format**
|
||||
|
||||
```markdown
|
||||
- [ ] Task N: Clear action description
|
||||
- File: `path/to/file.ext`
|
||||
- Action: Specific change to make
|
||||
- Notes: Any implementation details
|
||||
```
|
||||
|
||||
### 3. Generate Acceptance Criteria
|
||||
|
||||
**Create testable acceptance criteria:**
|
||||
|
||||
Each AC should follow Given/When/Then format:
|
||||
|
||||
```markdown
|
||||
- [ ] AC N: Given [precondition], when [action], then [expected result]
|
||||
```
|
||||
|
||||
**Ensure ACs cover:**
|
||||
|
||||
- Happy path functionality
|
||||
- Error handling
|
||||
- Edge cases (if relevant)
|
||||
- Integration points (if relevant)
|
||||
|
||||
### 4. Complete Additional Context
|
||||
|
||||
**Fill in remaining sections:**
|
||||
|
||||
a) **Dependencies**
|
||||
|
||||
- External libraries or services needed
|
||||
- Other tasks or features this depends on
|
||||
- API or data dependencies
|
||||
|
||||
b) **Testing Strategy**
|
||||
|
||||
- Unit tests needed
|
||||
- Integration tests needed
|
||||
- Manual testing steps
|
||||
|
||||
c) **Notes**
|
||||
|
||||
- High-risk items from pre-mortem analysis
|
||||
- Known limitations
|
||||
- Future considerations (out of scope but worth noting)
|
||||
|
||||
### 5. Write Complete Spec
|
||||
|
||||
a) **Update `{wipFile}` with all generated content:**
|
||||
|
||||
- Ensure all template sections are filled in
|
||||
- No placeholder text remaining
|
||||
- All frontmatter values current
|
||||
- Update status to 'review' (NOT 'ready-for-dev' - that happens after user review in Step 4)
|
||||
|
||||
b) **Update frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
# ... existing values ...
|
||||
status: 'review'
|
||||
stepsCompleted: [1, 2, 3]
|
||||
---
|
||||
```
|
||||
|
||||
c) **Load and execute `{nextStepFile}` (Step 4)**
|
||||
|
||||
## REQUIRED OUTPUTS:
|
||||
|
||||
- Tasks MUST be specific, actionable, ordered logically, with files to modify.
|
||||
- ACs MUST be testable, using Given/When/Then format.
|
||||
- Status MUST be updated to 'review'.
|
||||
|
||||
## VERIFICATION CHECKLIST:
|
||||
|
||||
- [ ] `stepsCompleted: [1, 2, 3]` set in frontmatter.
|
||||
- [ ] Spec meets the **READY FOR DEVELOPMENT** standard.
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
name: 'step-04-review'
|
||||
description: 'Review and finalize the tech-spec'
|
||||
|
||||
workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec'
|
||||
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
|
||||
---
|
||||
|
||||
# Step 4: Review & Finalize
|
||||
|
||||
**Progress: Step 4 of 4** - Final Step
|
||||
|
||||
## RULES:
|
||||
|
||||
- MUST NOT skip steps.
|
||||
- MUST NOT optimize sequence.
|
||||
- MUST follow exact instructions.
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## CONTEXT:
|
||||
|
||||
- Requires `{wipFile}` from Step 3.
|
||||
- MUST present COMPLETE spec content. Iterate until user is satisfied.
|
||||
- **Criteria**: The spec MUST meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`.
|
||||
|
||||
## SEQUENCE OF INSTRUCTIONS
|
||||
|
||||
### 1. Load and Present Complete Spec
|
||||
|
||||
**Read `{wipFile}` completely and extract `slug` from frontmatter for later use.**
|
||||
|
||||
**Present to user:**
|
||||
|
||||
"Here's your complete tech-spec. Please review:"
|
||||
|
||||
[Display the complete spec content - all sections]
|
||||
|
||||
"**Quick Summary:**
|
||||
|
||||
- {task_count} tasks to implement
|
||||
- {ac_count} acceptance criteria to verify
|
||||
- {files_count} files to modify
|
||||
|
||||
Does this capture your intent? Any changes needed?"
|
||||
|
||||
### 2. Handle Review Feedback
|
||||
|
||||
a) **If user requests changes:**
|
||||
|
||||
- Make the requested edits to `{wipFile}`
|
||||
- Re-present the affected sections
|
||||
- Ask if there are more changes
|
||||
- Loop until user is satisfied
|
||||
|
||||
b) **If the spec does NOT meet the "Ready for Development" standard:**
|
||||
|
||||
- Point out the missing/weak sections (e.g., non-actionable tasks, missing ACs).
|
||||
- Propose specific improvements to reach the standard.
|
||||
- Make the edits once the user agrees.
|
||||
|
||||
c) **If user has questions:**
|
||||
|
||||
- Answer questions about the spec
|
||||
- Clarify any confusing sections
|
||||
- Make clarifying edits if needed
|
||||
|
||||
### 3. Finalize the Spec
|
||||
|
||||
**When user confirms the spec is good AND it meets the "Ready for Development" standard:**
|
||||
|
||||
a) Update `{wipFile}` frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
# ... existing values ...
|
||||
status: 'ready-for-dev'
|
||||
stepsCompleted: [1, 2, 3, 4]
|
||||
---
|
||||
```
|
||||
|
||||
b) **Rename WIP file to final filename:**
|
||||
- Using the `slug` extracted in Section 1
|
||||
- Rename `{wipFile}` → `{implementation_artifacts}/tech-spec-{slug}.md`
|
||||
- Store this as `finalFile` for use in menus below
|
||||
|
||||
### 4. Present Final Menu
|
||||
|
||||
a) **Display completion message and menu:**
|
||||
|
||||
```
|
||||
**Tech-Spec Complete!**
|
||||
|
||||
Saved to: {finalFile}
|
||||
|
||||
---
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
[a] Advanced Elicitation - refine further
|
||||
[r] Adversarial Review - critique of the spec (highly recommended)
|
||||
[b] Begin Development - start implementing now (not recommended)
|
||||
[d] Done - exit workflow
|
||||
[p] Party Mode - get expert feedback before dev
|
||||
|
||||
---
|
||||
|
||||
Once you are fully satisfied with the spec (ideally after **Adversarial Review** and maybe a few rounds of **Advanced Elicitation**), it is recommended to run implementation in a FRESH CONTEXT for best results.
|
||||
|
||||
Copy this prompt to start dev:
|
||||
|
||||
\`\`\`
|
||||
quick-dev {finalFile}
|
||||
\`\`\`
|
||||
|
||||
This ensures the dev agent has clean context focused solely on implementation.
|
||||
```
|
||||
|
||||
b) **HALT and wait for user selection.**
|
||||
|
||||
#### Menu Handling:
|
||||
|
||||
- **[a]**: Load and execute `{advanced_elicitation}`, then return here and redisplay menu
|
||||
- **[b]**: Load and execute `{quick_dev_workflow}` with the final spec file (warn: fresh context is better)
|
||||
- **[d]**: Exit workflow - display final confirmation and path to spec
|
||||
- **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu
|
||||
- **[r]**: Execute Adversarial Review:
|
||||
1. **Invoke Adversarial Review Task**:
|
||||
> With `{finalFile}` constructed, invoke the review task. If possible, use information asymmetry: run this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`.
|
||||
<invoke-task>Review {finalFile} using {project-root}/_bmad/core/tasks/review-adversarial-general.xml</invoke-task>
|
||||
> **Platform fallback:** If task invocation not available, load the task file and execute its instructions inline, passing `{finalFile}` as the content.
|
||||
> The task should: review `{finalFile}` and return a list of findings.
|
||||
|
||||
2. **Process Findings**:
|
||||
> Capture the findings from the task output.
|
||||
> **If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance.
|
||||
> Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided).
|
||||
> DO NOT exclude findings based on severity or validity unless explicitly asked to do so.
|
||||
> Order findings by severity.
|
||||
> Number the ordered findings (F1, F2, F3, etc.).
|
||||
> If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description
|
||||
|
||||
3. Return here and redisplay menu.
|
||||
|
||||
### 5. Exit Workflow
|
||||
|
||||
**When user selects [d]:**
|
||||
|
||||
"**All done!** Your tech-spec is ready at:
|
||||
|
||||
`{finalFile}`
|
||||
|
||||
When you're ready to implement, run:
|
||||
|
||||
```
|
||||
quick-dev {finalFile}
|
||||
```
|
||||
|
||||
Ship it!"
|
||||
|
||||
---
|
||||
|
||||
## REQUIRED OUTPUTS:
|
||||
|
||||
- MUST update status to 'ready-for-dev'.
|
||||
- MUST rename file to `tech-spec-{slug}.md`.
|
||||
- MUST provide clear next-step guidance and recommend fresh context for dev.
|
||||
|
||||
## VERIFICATION CHECKLIST:
|
||||
|
||||
- [ ] Complete spec presented for review.
|
||||
- [ ] Requested changes implemented.
|
||||
- [ ] Spec verified against **READY FOR DEVELOPMENT** standard.
|
||||
- [ ] `stepsCompleted: [1, 2, 3, 4]` set and file renamed.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: '{title}'
|
||||
slug: '{slug}'
|
||||
created: '{date}'
|
||||
status: 'in-progress'
|
||||
stepsCompleted: []
|
||||
tech_stack: []
|
||||
files_to_modify: []
|
||||
code_patterns: []
|
||||
test_patterns: []
|
||||
---
|
||||
|
||||
# Tech-Spec: {title}
|
||||
|
||||
**Created:** {date}
|
||||
|
||||
## Overview
|
||||
|
||||
### Problem Statement
|
||||
|
||||
{problem_statement}
|
||||
|
||||
### Solution
|
||||
|
||||
{solution}
|
||||
|
||||
### Scope
|
||||
|
||||
**In Scope:**
|
||||
{in_scope}
|
||||
|
||||
**Out of Scope:**
|
||||
{out_of_scope}
|
||||
|
||||
## Context for Development
|
||||
|
||||
### Codebase Patterns
|
||||
|
||||
{codebase_patterns}
|
||||
|
||||
### Files to Reference
|
||||
|
||||
| File | Purpose |
|
||||
| ---- | ------- |
|
||||
|
||||
{files_table}
|
||||
|
||||
### Technical Decisions
|
||||
|
||||
{technical_decisions}
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Tasks
|
||||
|
||||
{tasks}
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
{acceptance_criteria}
|
||||
|
||||
## Additional Context
|
||||
|
||||
### Dependencies
|
||||
|
||||
{dependencies}
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
{testing_strategy}
|
||||
|
||||
### Notes
|
||||
|
||||
{notes}
|
||||
79
_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
Normal file
79
_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: quick-spec
|
||||
description: Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec.
|
||||
main_config: '{project-root}/_bmad/bmm/config.yaml'
|
||||
web_bundle: true
|
||||
|
||||
# Checkpoint handler paths
|
||||
advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
quick_dev_workflow: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md'
|
||||
---
|
||||
|
||||
# Quick-Spec Workflow
|
||||
|
||||
**Goal:** Create implementation-ready technical specifications through conversational discovery, code investigation, and structured documentation.
|
||||
|
||||
**READY FOR DEVELOPMENT STANDARD:**
|
||||
|
||||
A specification is considered "Ready for Development" ONLY if it meets the following:
|
||||
|
||||
- **Actionable**: Every task has a clear file path and specific action.
|
||||
- **Logical**: Tasks are ordered by dependency (lowest level first).
|
||||
- **Testable**: All ACs follow Given/When/Then and cover happy path and edge cases.
|
||||
- **Complete**: All investigation results from Step 2 are inlined; no placeholders or "TBD".
|
||||
- **Self-Contained**: A fresh agent can implement the feature without reading the workflow history.
|
||||
|
||||
---
|
||||
|
||||
**Your Role:** You are an elite developer and spec engineer. You ask sharp questions, investigate existing code thoroughly, and produce specs that contain ALL context a fresh dev agent needs to implement the feature. No handoffs, no missing context - just complete, actionable specs.
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **step-file architecture** for disciplined execution:
|
||||
|
||||
### Core Principles
|
||||
|
||||
- **Micro-file Design**: Each step is a self-contained instruction file that must be followed exactly
|
||||
- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until directed
|
||||
- **Sequential Enforcement**: Sequence within step files must be completed in order, no skipping or optimization
|
||||
- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array
|
||||
- **Append-Only Building**: Build the tech-spec by updating content as directed
|
||||
|
||||
### Step Processing Rules
|
||||
|
||||
1. **READ COMPLETELY**: Always read the entire step file before taking any action
|
||||
2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
|
||||
3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
|
||||
4. **CHECK CONTINUATION**: Only proceed to next step when user selects [c] (Continue)
|
||||
5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
|
||||
6. **LOAD NEXT**: When directed, load and read entire next step file, then execute
|
||||
|
||||
### Critical Rules (NO EXCEPTIONS)
|
||||
|
||||
- **NEVER** load multiple step files simultaneously
|
||||
- **ALWAYS** read entire step file before execution
|
||||
- **NEVER** skip steps or optimize the sequence
|
||||
- **ALWAYS** update frontmatter of output file when completing a step
|
||||
- **ALWAYS** follow the exact instructions in the step file
|
||||
- **ALWAYS** halt at menus and wait for user input
|
||||
- **NEVER** create mental todo lists from future steps
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION SEQUENCE
|
||||
|
||||
### 1. Configuration Loading
|
||||
|
||||
Load and read full config from `{main_config}` and resolve:
|
||||
|
||||
- `project_name`, `output_folder`, `planning_artifacts`, `implementation_artifacts`, `user_name`
|
||||
- `communication_language`, `document_output_language`, `user_skill_level`
|
||||
- `date` as system-generated current datetime
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### 2. First Step Execution
|
||||
|
||||
Load, read the full file, and then execute `steps/step-01-understand.md` to begin the workflow.
|
||||
Reference in New Issue
Block a user