docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,6 @@
|
||||
---
|
||||
name: bmad-quick-dev-new-preview
|
||||
description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
|
||||
---
|
||||
|
||||
Follow the instructions in ./workflow.md.
|
||||
@@ -0,0 +1 @@
|
||||
type: skill
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
|
||||
deferred_work_file: '{implementation_artifacts}/deferred-work.md'
|
||||
spec_file: '' # set at runtime before leaving this step
|
||||
---
|
||||
|
||||
# Step 1: Clarify and Route
|
||||
|
||||
## RULES
|
||||
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
- The prompt that triggered this workflow IS the intent — not a hint.
|
||||
- Do NOT assume you start from zero.
|
||||
- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
|
||||
- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them.
|
||||
|
||||
## ARTIFACT SCAN
|
||||
|
||||
- `{wipFile}` exists? → Offer resume or archive.
|
||||
- Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
|
||||
- If `ready-for-dev` or `in-progress` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 3.
|
||||
- If `in-review` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 4.
|
||||
- Unformatted spec or intent file lacking `status` frontmatter in `{implementation_artifacts}`? → Suggest to the user to treat its contents as the starting intent for this workflow. DO NOT attempt to infer a state and resume it.
|
||||
|
||||
## INSTRUCTIONS
|
||||
|
||||
1. Load context.
|
||||
- List files in `{planning_artifacts}` and `{implementation_artifacts}`.
|
||||
- If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
|
||||
2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
|
||||
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, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
|
||||
4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
|
||||
- Present detected distinct goals as a bullet list.
|
||||
- Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
|
||||
- HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
|
||||
- On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
|
||||
- On **K**: Proceed as-is.
|
||||
5. Generate `spec_file` path:
|
||||
- Derive a valid kebab-case slug from the clarified intent.
|
||||
- If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc.
|
||||
- Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`.
|
||||
6. Route:
|
||||
- **One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. `execution_mode = "one-shot"`. → Step 3.
|
||||
- **Plan-code-review** — everything else. `execution_mode = "plan-code-review"`. → Step 2.
|
||||
- When uncertain whether blast radius is truly zero, default to plan-code-review.
|
||||
|
||||
|
||||
## NEXT
|
||||
|
||||
- One-shot / ready-for-dev: Read fully and follow `./step-03-implement.md`
|
||||
- Plan-code-review: Read fully and follow `./step-02-plan.md`
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
|
||||
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.
|
||||
|
||||
## INSTRUCTIONS
|
||||
|
||||
1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
|
||||
2. Read `../tech-spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`.
|
||||
3. Self-review against READY FOR DEVELOPMENT standard.
|
||||
4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
|
||||
5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
|
||||
- Show user the token count.
|
||||
- HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
|
||||
- On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
|
||||
- On **K**: Continue to checkpoint with full spec.
|
||||
|
||||
### CHECKPOINT 1
|
||||
|
||||
Present summary. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. HALT and ask human: `[A] Approve` | `[E] Edit`
|
||||
|
||||
- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
|
||||
- **E**: Apply changes, then return to CHECKPOINT 1.
|
||||
|
||||
|
||||
## NEXT
|
||||
|
||||
Read fully and follow `./step-03-implement.md`
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
---
|
||||
|
||||
# Step 3: Implement
|
||||
|
||||
## RULES
|
||||
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
- No push. No remote ops.
|
||||
- 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, HALT and ask the human to provide the spec file path before proceeding.
|
||||
|
||||
## INSTRUCTIONS
|
||||
|
||||
### Baseline (plan-code-review only)
|
||||
|
||||
Capture `baseline_commit` (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.
|
||||
|
||||
`execution_mode = "one-shot"` or no sub-agents/tasks available: implement the intent.
|
||||
|
||||
Otherwise (`execution_mode = "plan-code-review"`): hand `{spec_file}` to a sub-agent/task and let it implement.
|
||||
|
||||
## 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.
|
||||
|
||||
## INSTRUCTIONS
|
||||
|
||||
Change `{spec_file}` status to `in-review` in the frontmatter before continuing.
|
||||
|
||||
### Construct Diff (plan-code-review only)
|
||||
|
||||
Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`.
|
||||
|
||||
Do NOT `git add` anything — this is read-only inspection.
|
||||
|
||||
### Review
|
||||
|
||||
**One-shot:** Skip diff construction. Still invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files — inline review invites anchoring bias.
|
||||
|
||||
**Plan-code-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 — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
|
||||
|
||||
- **Blind hunter** — receives `{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, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review.
|
||||
- **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
|
||||
- **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,17 @@
|
||||
---
|
||||
---
|
||||
|
||||
# Step 5: Present
|
||||
|
||||
## RULES
|
||||
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
- NEVER auto-push.
|
||||
|
||||
## INSTRUCTIONS
|
||||
|
||||
1. Change `{spec_file}` status to `done` in the frontmatter.
|
||||
2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
|
||||
3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request.
|
||||
|
||||
Workflow complete.
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: '{title}'
|
||||
type: 'feature' # feature | bugfix | refactor | chore
|
||||
created: '{date}'
|
||||
status: 'draft' # draft | ready-for-dev | in-progress | in-review | done
|
||||
context: [] # optional: max 3 project-wide standards/docs. NO source code files.
|
||||
---
|
||||
|
||||
<!-- Target: 900–1300 tokens. Above 1600 = high risk of context rot.
|
||||
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. -->
|
||||
|
||||
# {title}
|
||||
|
||||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||||
|
||||
## 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. Ask First = human-gated decisions. Never = out of scope + forbidden approaches. -->
|
||||
|
||||
**Always:** INVARIANT_RULES
|
||||
|
||||
**Ask First:** DECISIONS_REQUIRING_HUMAN_APPROVAL
|
||||
<!-- Agent: if any of these trigger during execution, HALT and ask the user before proceeding. -->
|
||||
|
||||
**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,79 @@
|
||||
---
|
||||
main_config: '{project-root}/_bmad/bmm/config.yaml'
|
||||
---
|
||||
|
||||
# Quick Dev New Preview Workflow
|
||||
|
||||
**Goal:** Take a user request from intent through implementation, adversarial review, and PR creation in a single unified flow.
|
||||
|
||||
**Your Role:** You are an elite developer. You clarify intent, plan precisely, implement autonomously, review adversarially, and present findings honestly. Minimum ceremony, maximum signal.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
## SCOPE STANDARD
|
||||
|
||||
A specification should target a **single user-facing goal** within **900–1600 tokens**:
|
||||
|
||||
- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
|
||||
- Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
|
||||
- Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
|
||||
- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
|
||||
- **Neither limit is a gate.** Both are proposals with user override.
|
||||
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **step-file architecture** for disciplined execution:
|
||||
|
||||
- **Micro-file Design**: Each step is self-contained and followed exactly
|
||||
- **Just-In-Time Loading**: Only load the current step file
|
||||
- **Sequential Enforcement**: Complete steps in order, no skipping
|
||||
- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
|
||||
- **Append-Only Building**: Build artifacts incrementally
|
||||
|
||||
### Step Processing Rules
|
||||
|
||||
1. **READ COMPLETELY**: Read the entire step file before acting
|
||||
2. **FOLLOW SEQUENCE**: Execute sections in order
|
||||
3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
|
||||
4. **LOAD NEXT**: When directed, read fully and follow the next step file
|
||||
|
||||
### 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** follow the exact instructions in the step file
|
||||
- **ALWAYS** halt at checkpoints and wait for human input
|
||||
|
||||
|
||||
## INITIALIZATION SEQUENCE
|
||||
|
||||
### 1. Configuration Loading
|
||||
|
||||
Load and read full config from `{main_config}` and resolve:
|
||||
|
||||
- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
|
||||
- `communication_language`, `document_output_language`, `user_skill_level`
|
||||
- `date` as system-generated current datetime
|
||||
- `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}`.
|
||||
|
||||
### 2. Paths
|
||||
|
||||
- `wipFile` = `{implementation_artifacts}/tech-spec-wip.md`
|
||||
|
||||
### 3. First Step Execution
|
||||
|
||||
Read fully and follow: `./steps/step-01-clarify-and-route.md` to begin the workflow.
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
name: bmad-quick-dev
|
||||
description: 'Implement a Quick Tech Spec for small changes or features. Use when the user provides a quick tech spec and says "implement this quick spec" or "proceed with implementation of [quick tech spec]"'
|
||||
---
|
||||
|
||||
Follow the instructions in ./workflow.md.
|
||||
@@ -0,0 +1 @@
|
||||
type: skill
|
||||
@@ -0,0 +1,169 @@
|
||||
---
|
||||
---
|
||||
|
||||
# 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:** Read fully and follow: `./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)
|
||||
|
||||
Display: "**Select:** [P] Plan first (tech-spec) [E] Execute directly"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF P: Direct user to invoke the `bmad-quick-spec` skill. **EXIT Quick Dev.**
|
||||
- IF E: Ask for any additional guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md`
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed when user makes a selection
|
||||
|
||||
---
|
||||
|
||||
### Escalation Triggered - Level 0-2
|
||||
|
||||
Present: "This looks like a focused feature with multiple components."
|
||||
|
||||
Display:
|
||||
|
||||
**[P] Plan first (tech-spec)** (recommended)
|
||||
**[W] Seems bigger than quick-dev** - Recommend the Full BMad Flow PRD Process
|
||||
**[E] Execute directly**
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF P: Direct user to invoke the `bmad-quick-spec` skill. **EXIT Quick Dev.**
|
||||
- IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.**
|
||||
- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md`
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed when user makes a selection
|
||||
|
||||
---
|
||||
|
||||
### Escalation Triggered - Level 3+
|
||||
|
||||
Present: "This sounds like platform/system work."
|
||||
|
||||
Display:
|
||||
|
||||
**[W] Start BMad Method** (recommended)
|
||||
**[P] Plan first (tech-spec)** (lighter planning)
|
||||
**[E] Execute directly** - feeling lucky
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF P: Direct user to invoke the `bmad-quick-spec` skill. **EXIT Quick Dev.**
|
||||
- IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.**
|
||||
- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md`
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed when user makes a selection
|
||||
|
||||
---
|
||||
|
||||
## NEXT STEP DIRECTIVE
|
||||
|
||||
**CRITICAL:** When this step completes, explicitly state which step to load:
|
||||
|
||||
- Mode A (tech-spec): "**NEXT:** read fully and follow: `./step-03-execute.md`"
|
||||
- Mode B (direct, [E] selected): "**NEXT:** Read fully and follow: `./step-02-context-gathering.md`"
|
||||
- Escalation ([P] 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,114 @@
|
||||
---
|
||||
---
|
||||
|
||||
# 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:** Read fully and follow: `./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,107 @@
|
||||
---
|
||||
---
|
||||
|
||||
# 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), read fully and follow: `./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,107 @@
|
||||
---
|
||||
---
|
||||
|
||||
# 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,94 @@
|
||||
---
|
||||
---
|
||||
|
||||
# Step 5: Adversarial Code Review
|
||||
|
||||
**Goal:** Construct diff of all changes, invoke adversarial review skill, 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 `bmad-review-adversarial-general` skill. If possible, use information asymmetry: invoke the skill in a separate subagent or process with read access to the project, but no context except the `{diff_output}`.
|
||||
|
||||
Pass `{diff_output}` as the content to review. The skill should return a list of findings.
|
||||
|
||||
---
|
||||
|
||||
### 3. Process Findings
|
||||
|
||||
Capture the findings from the skill 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, read fully and follow: `./step-06-resolve-findings.md` for user to choose resolution approach.
|
||||
|
||||
---
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
- Diff constructed from baseline_commit
|
||||
- New files included in diff
|
||||
- Skill 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 skill without providing diff input
|
||||
- Accepting zero findings without questioning
|
||||
- Presenting fewer findings than the review skill returned without explicit instruction to do so
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
---
|
||||
|
||||
# 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: "How would you like to handle these findings?"
|
||||
|
||||
Display:
|
||||
|
||||
**[W] Walk through** - Discuss each finding individually
|
||||
**[F] Fix automatically** - Automatically fix issues classified as "real"
|
||||
**[S] Skip** - Acknowledge and proceed to commit
|
||||
|
||||
### Menu Handling Logic:
|
||||
|
||||
- IF W: Execute WALK THROUGH section below
|
||||
- IF F: Execute FIX AUTOMATICALLY section below
|
||||
- IF S: Execute SKIP section below
|
||||
|
||||
### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed when user makes a selection
|
||||
|
||||
---
|
||||
|
||||
## WALK THROUGH [W]
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## FIX AUTOMATICALLY [F]
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SKIP [S]
|
||||
|
||||
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
|
||||
@@ -0,0 +1,38 @@
|
||||
# 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`
|
||||
- `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
|
||||
|
||||
- `project_context` = `**/project-context.md` (load if exists)
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION
|
||||
|
||||
Read fully and follow: `./steps/step-01-mode-detection.md` to begin the workflow.
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
name: bmad-quick-spec
|
||||
description: 'Very quick process to create implementation-ready quick specs for small changes or features. Use when the user says "create a quick spec" or "generate a quick tech spec"'
|
||||
---
|
||||
|
||||
Follow the instructions in ./workflow.md.
|
||||
@@ -0,0 +1 @@
|
||||
type: skill
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
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]` → Read fully and follow: `./step-02-investigate.md` (Step 2)
|
||||
- `[1, 2]` → Read fully and follow: `./step-03-generate.md` (Step 3)
|
||||
- `[1, 2, 3]` → Read fully and follow: `./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 `{implementation_artifacts}` 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 `../tech-spec-template.md`
|
||||
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:**
|
||||
|
||||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)"
|
||||
|
||||
b) **HALT and wait for user selection.**
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
|
||||
- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `./step-02-investigate.md`
|
||||
- IF Any other comments or queries: respond helpfully then redisplay menu
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After A or P execution, return to this 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,140 @@
|
||||
---
|
||||
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: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)"
|
||||
|
||||
**HALT and wait for user selection.**
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
|
||||
- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `./step-03-generate.md`
|
||||
- IF Any other comments or queries: respond helpfully then redisplay menu
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After A or P execution, return to this 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,123 @@
|
||||
---
|
||||
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) **Read fully and follow: `./step-04-review.md` (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,195 @@
|
||||
---
|
||||
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"
|
||||
|
||||
**Present review menu:**
|
||||
|
||||
Display: "**Select:** [C] Continue [E] Edit [Q] Questions [A] Advanced Elicitation [P] Party Mode"
|
||||
|
||||
**HALT and wait for user selection.**
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF C: Proceed to Section 3 (Finalize the Spec)
|
||||
- IF E: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu
|
||||
- IF Q: Answer questions, then redisplay this menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
|
||||
- IF Any other comments or queries: respond helpfully then redisplay menu
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to finalize when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
|
||||
### 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 Logic:
|
||||
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
|
||||
- IF B: Invoke the `bmad-quick-dev` skill with `{finalFile}` in a fresh context if possible (warn: fresh context is better)
|
||||
- IF D: Exit workflow - display final confirmation and path to spec
|
||||
- IF P: Invoke the `bmad-party-mode` skill with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
|
||||
- IF R: Execute Adversarial Review (see below)
|
||||
- IF Any other comments or queries: respond helpfully then redisplay menu
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- After A, P, or R execution, return to this menu
|
||||
|
||||
#### Adversarial Review [R] Process:
|
||||
|
||||
1. **Invoke Adversarial Review Skill**:
|
||||
> With `{finalFile}` constructed, invoke the `bmad-review-adversarial-general` skill. If possible, use information asymmetry: invoke the skill in a separate subagent or process with read access to the project, but no context except the `{finalFile}`.
|
||||
> Pass `{finalFile}` as the content to review. The skill should return a list of findings.
|
||||
|
||||
2. **Process Findings**:
|
||||
> Capture the findings from the skill 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}
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
main_config: '{project-root}/_bmad/bmm/config.yaml'
|
||||
|
||||
---
|
||||
|
||||
# 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, read fully and follow the next step file
|
||||
|
||||
### 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`, `planning_artifacts`, `implementation_artifacts`, `user_name`
|
||||
- `communication_language`, `document_output_language`, `user_skill_level`
|
||||
- `date` as system-generated current datetime
|
||||
- `project_context` = `**/project-context.md` (load if exists)
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### 2. First Step Execution
|
||||
|
||||
Read fully and follow: `./steps/step-01-understand.md` to begin the workflow.
|
||||
Reference in New Issue
Block a user