bmad-plus 0.5.0 → 0.6.0

package/src/bmad-plus/packs/pack-dev-studio/categories/implementation/investigate.md

@@ -0,0 +1,194 @@
+---
+name: bmad-investigate
+description: Forensic case investigation with evidence-graded findings, calibrated to the input. Use when the user asks to investigate a bug, trace what caused an incident, walk through unfamiliar code, or build a mental model of a code area before working on it.
+---
+
+# Investigate
+
+## Overview
+
+Reconstruct what's happening, or what an unfamiliar area does, from the available evidence. Produce a structured case
+file another engineer can pick up cold. Calibrate continuously between defect-chasing (symptom-driven) and
+area-exploration (no symptom); the same discipline applies on both ends.
+
+**Args:** A ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or a path
+to an existing case file. The last form resumes a prior investigation; everything else opens a new case.
+
+**Output:** `{implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}`. Reference inputs
+are recorded; raw content is not read into the parent context until an outcome calls for it.
+
+`{slug}` is the ticket ID when one is provided, otherwise a short descriptive name agreed with the user, sanitized to
+lowercase alphanumeric with hyphens. On collision with an existing case file at the resolved path, ask whether to
+rename to `slug-YYYY-MM-DD.md` or resume the existing file (resuming routes to Outcome 0).
+
+After every outcome, present what was learned and pause for the user before continuing.
+
+## Principles
+
+- **Evidence grading.**
+  - **Confirmed.** Directly observed; cite `path:line`, log timestamp, or commit hash.
+  - **Deduced.** Logically follows from Confirmed evidence; show the chain.
+  - **Hypothesized.** Plausible but unconfirmed; state what would confirm or refute it.
+- **Stronghold first.** Anchor in one Confirmed piece of evidence and expand outward. Never start from a theory and
+  hunt for support. When evidence is sparse, switch to evidence-light mode (Outcome 1 branch).
+- **Challenge the premise.** The user's description is a hypothesis, not a fact. Verify independently; if evidence
+  contradicts, say so.
+- **Follow the evidence, not the narrative.** When evidence contradicts the working theory, update the theory — never
+  the other way around. Resist confirmation bias even when the user is convinced.
+- **Hypotheses are never deleted.** Update Status (Open / Confirmed / Refuted) and add a Resolution. Wrong turns are
+  part of the deliverable.
+- **Missing evidence is itself a finding.** Document the gap, what it would resolve, and how to obtain it.
+- **Write it down early.** Initialize the case file as soon as the slug is agreed; it is the persistent state across
+  interruptions.
+- **Path:line citations** use CWD-relative format, no leading `/`, so they're clickable in IDE-embedded terminals.
+- **Delegation discipline.** When a step requires reading 5+ files or any file >10K tokens, delegate to a subagent
+  that returns structured JSON only. Cite `path:line` from the result; don't re-read in the parent.
+- **Issue independent operations in parallel** (multi-grep, multi-read, parallel inventories) — one message, multiple
+  tool calls.
+- **Communication.** Evidence-first language ("the evidence shows", "unconfirmed, requires X to verify"). No hedging,
+  no narrative.
+
+## On Activation
+
+### Step 1: Resolve the workflow block
+
+<!-- Adapted for BMAD+: original script dependency removed -->
+
+If the script fails, stop and surface the error.
+
+### Step 2: Execute prepend steps
+
+Run each entry in `{workflow.activation_steps_prepend}` in order.
+
+### Step 3: Load persistent facts
+
+Treat each entry in `{workflow.persistent_facts}` as foundational context. `file:` prefixes are paths or globs under
+`{project-root}` (load contents); other entries are facts verbatim.
+
+### Step 4: Load config
+
+Load `{project-root}/project config` and resolve `{user_name}`, `{communication_language}`,
+`{document_output_language}`, `{implementation_artifacts}`, `{project_knowledge}`. If `{implementation_artifacts}` is
+unresolved, fall back to `./investigations/` and surface the fallback before initializing.
+
+### Step 5: Greet
+
+Greet `{user_name}` in `{communication_language}`.
+
+### Step 6: Execute append steps
+
+Run each entry in `{workflow.activation_steps_append}` in order.
+
+### Step 7: Acknowledge and route
+
+Acknowledge the input as a reference (record paths and IDs; don't read raw content). Path to an existing case file →
+Outcome 0. Otherwise → Outcome 1.
+
+## Procedure
+
+### Outcome 0: Existing case is loaded and surfaced
+
+Read the case file. Surface, in order: open hypotheses (Status = Open) with their confirm/refute criteria; open
+backlog (Status ≠ Done); missing-evidence rows; last Conclusion with confidence. Ask which thread to pull. New
+evidence opens a new `## Follow-up: {YYYY-MM-DD}` block (append `#2`, `#3` on same-day reentry). Pause for user with the recap above; wait for direction.
+
+### Outcome 1: Scope and stronghold are established
+
+Acknowledge each input shape — record location, scope, time window only; bulk reads happen in Outcome 2.
+
+- **Issue tracker ticket.** Fetch full details via available MCP tools.
+- **Diagnostic archive.** Record path, file count, time window.
+- **Log file or stack trace.** Record path and time window; only the stack frame already in the user's message is in
+  scope here.
+- **Free-text description.** Capture verbatim; treat as hypothesis.
+- **Code area name** (no symptom). Record entry point.
+- **Recent commit area.** Record commit range.
+
+If the user arrived with a hypothesis, register it as Hypothesis #1. Find the stronghold *independently*; the user's
+hypothesis is one of the things the stronghold validates or refutes.
+
+Find a stronghold: a Confirmed piece of evidence (error message, function name, HTTP route, config parameter, test
+case). Anchor here.
+
+**Initialize `{case_file}` before branching.** The path is
+`{implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}` with `{slug}` substituted (slug
+and collision rules in Overview). Create the file from `{workflow.case_file_template}` and fill Hand-off Brief
+(rough), Case Info, Problem Statement, initial Evidence Inventory.
+
+**Evidence-light branch.** When no Confirmed evidence is reachable: mark the case evidence-light in the Hand-off
+Brief; populate the Investigation Backlog with prioritized data-collection items; record "to make progress, I need one
+of: …"; pause for the user to provide evidence or authorize Outcome 2 to scan more broadly.
+
+Otherwise present scope, stronghold, file path, proposed approach. Pause for user with the recap above; wait for direction.
+
+### Outcome 2: Evidence perimeter is mapped
+
+Survey the scene: inventory available evidence in parallel across these independent categories: diagnostic archives;
+issue tracker; version control; test results; static analysis; source code. For any category exceeding ~10K tokens,
+delegate to a subagent that returns a JSON manifest (paths, sizes, time windows, key fragments cited as `path:line`).
+
+Classify each Available, Partial, or Missing — Missing is itself a finding. Update Evidence Inventory and Investigation
+Backlog. Pause for user with the recap above; wait for direction.
+
+### Outcome 3: Cause is reasoned about with discipline
+
+- **Trace causality.** Symptom-driven: trace backward from the symptom to producing conditions and the state that
+  emerged. Exploration: trace backward from outputs (returns, side effects, messages sent) to producing conditions.
+  Same technique, different anchor.
+- **Reconstruct the timeline** by cross-referencing logs, system events, version control, user observations.
+- **Form and test hypotheses.** State, identify confirming/refuting evidence, search, grade
+  (Confirmed / Refuted / Open). Update Status. Never delete.
+- **Refutation pass.** Each time a hypothesis transitions toward Confirmed, actively look for refuting evidence first.
+  Record the attempt in Resolution.
+- **Verify the user's premise.** If evidence contradicts, say so explicitly.
+- **Add discovered paths to the backlog.** Stay focused on the current thread.
+
+Update Confirmed Findings, Deduced Conclusions, Hypothesized Paths, Backlog, Timeline. Highlight contradictions to the
+original premise. Pause for user with the recap above; wait for direction.
+
+### Outcome 4: Source has been traced where it matters
+
+Issue these first-pass scans as parallel tool calls in one message: grep for exact error strings; glob the affected
+directory for parallel implementations; `git log` for recent changes.
+
+Then sequentially: read the surrounding code; follow the caller chain; watch for language and process boundary
+crossings (compiled→scripts, IPC, host→device, configuration flow).
+
+Lean by case type:
+
+- **Exploration:** I/O mapping (triggers, outputs, dependencies); frequent-terms scan; control-flow filtering
+  (branches, loops, error handling, state-machine transitions).
+- **Symptom-driven:** depth assessment — is the root cause reachable from local context, or is a broader area model
+  required? Surface escalations; never silently expand scope. Trivial-fix assessment — off-by-one, missing null check,
+  swapped argument → one-line code suggestion or draft diff in the report; non-trivial → stop at the root cause area.
+
+Investigation stops at the diagnosis; implementation is out of scope. Update Source Code Trace (Error origin, Trigger,
+Condition, Related files; area model when broader). Pause for user with the recap above; wait for direction.
+
+### Outcome 5: Report is finalized and the hand-off is clean
+
+Update `{case_file}`:
+
+- **Hand-off Brief** rewritten to final form (3 sentences, 15-second read).
+- **Final Conclusion** with confidence: **High** (Confirmed root cause, deterministic repro), **Medium** (Deduced;
+  minor uncertainty), **Low** (Hypothesized; clear data gap).
+- **Fix direction** when applicable (categorize by mechanism if multiple combine).
+- **Diagnostic steps** if uncertainty remains.
+- **Reproduction Plan** when applicable, or a verification plan for exploration cases.
+- **Status:** Active / Concluded / Blocked on evidence.
+
+Present the conclusion, then a concrete next-steps menu: trivial fix → `bmad-quick-dev`; scope/plan adjustment →
+`bmad-correct-course`; tracked story → `bmad-create-story`; fresh review → `bmad-code-review`. Recommend the
+highest-value action. Mitigations and workarounds are generated only on explicit request — investigation stops at the
+diagnosis. Execute `{workflow.on_complete}` if non-empty. Pause for user with the recap above; wait for direction.
+
+## Follow-up Iterations
+
+Continue work by appending to `{case_file}` under a new `## Follow-up: {YYYY-MM-DD}` block (`#2`, `#3` on same-day
+reentry). The investigation is complete when:
+
+- Root cause is Confirmed.
+- Root cause is Hypothesized with a clear data gap.
+- The mental model is sufficient for the user's stated goal (exploration cases).
+- The backlog contains only items requiring unavailable evidence.
+- The user explicitly concludes.

package/src/bmad-plus/packs/pack-dev-studio/categories/implementation/qa-e2e-tests.md

@@ -0,0 +1,176 @@
+---
+name: bmad-qa-generate-e2e-tests
+description: 'Generate end to end automated tests for existing features. Use when the user says "create qa automated tests for [feature]"'
+---
+
+# QA Generate E2E Tests Workflow
+
+**Goal:** Generate automated API and E2E tests for implemented code.
+
+**Your Role:** You are a QA automation engineer. You generate tests ONLY — no code review or story validation (use the `bmad-code-review` skill for that).
+
+## Conventions
+
+- Bare paths (e.g. `checklist.md`) resolve from the skill root.
+- `this skill directory` resolves to this skill's installed directory (where `agent configuration` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+<!-- Adapted for BMAD+: original script dependency removed -->
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `this skill file` — defaults
+2. `{project-root}/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/project config` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `implementation_artifacts`
+- `date` as system-generated current datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. Begin the workflow below.
+
+## Paths
+
+- `test_dir` = `{project-root}/tests`
+- `source_dir` = `{project-root}`
+- `default_output_file` = `{implementation_artifacts}/tests/test-summary.md`
+
+## Execution
+
+### Step 0: Detect Test Framework
+
+Check project for existing test framework:
+
+- Look for `package.json` dependencies (playwright, jest, vitest, cypress, etc.)
+- Check for existing test files to understand patterns
+- Use whatever test framework the project already has
+- If no framework exists:
+  - Analyze source code to determine project type (React, Vue, Node API, etc.)
+  - Search online for current recommended test framework for that stack
+  - Suggest the meta framework and use it (or ask user to confirm)
+
+### Step 1: Identify Features
+
+Ask user what to test:
+
+- Specific feature/component name
+- Directory to scan (e.g., `src/components/`)
+- Or auto-discover features in the codebase
+
+### Step 2: Generate API Tests (if applicable)
+
+For API endpoints/services, generate tests that:
+
+- Test status codes (200, 400, 404, 500)
+- Validate response structure
+- Cover happy path + 1-2 error cases
+- Use project's existing test framework patterns
+
+### Step 3: Generate E2E Tests (if UI exists)
+
+For UI features, generate tests that:
+
+- Test user workflows end-to-end
+- Use semantic locators (roles, labels, text)
+- Focus on user interactions (clicks, form fills, navigation)
+- Assert visible outcomes
+- Keep tests linear and simple
+- Follow project's existing test patterns
+
+### Step 4: Run Tests
+
+Execute tests to verify they pass (use project's test command).
+
+If failures occur, fix them immediately.
+
+### Step 5: Create Summary
+
+Output markdown summary:
+
+```markdown
+# Test Automation Summary
+
+## Generated Tests
+
+### API Tests
+- [x] tests/api/endpoint.spec.ts - Endpoint validation
+
+### E2E Tests
+- [x] tests/e2e/feature.spec.ts - User workflow
+
+## Coverage
+- API endpoints: 5/10 covered
+- UI features: 3/8 covered
+
+## Next Steps
+- Run tests in CI
+- Add more edge cases as needed
+```
+
+## Keep It Simple
+
+**Do:**
+
+- Use standard test framework APIs
+- Focus on happy path + critical errors
+- Write readable, maintainable tests
+- Run tests to verify they pass
+
+**Avoid:**
+
+- Complex fixture composition
+- Over-engineering
+- Unnecessary abstractions
+
+**For Advanced Features:**
+
+If the project needs:
+
+- Risk-based test strategy
+- Test design planning
+- Quality gates and NFR assessment
+- Comprehensive coverage analysis
+- Advanced testing patterns and utilities
+
+> **Install Test Architect (TEA) module**: <https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/>
+
+## Output
+
+Save summary to: `{default_output_file}`
+
+**Done!** Tests generated and verified. Validate against `./checklist.md`.
+
+## On Complete
+
+<!-- Adapted for BMAD+: original script dependency removed -->
+
+If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/bmad-plus/packs/pack-dev-studio/categories/implementation/quick-dev.md

@@ -0,0 +1,111 @@
+---
+name: bmad-quick-dev
+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.'
+---
+
+# Quick Dev New Preview Workflow
+
+**Goal:** Turn user intent into a hardened, reviewable artifact.
+
+**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
+
+## 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.
+
+## Conventions
+
+- Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root.
+- `this skill directory` resolves to this skill's installed directory (where `agent configuration` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+<!-- Adapted for BMAD+: original script dependency removed -->
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `this skill file` — defaults
+2. `{project-root}/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/project 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
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `project_context` = `**/project-context.md` (load if exists)
+- CLAUDE.md / memory files (load if exist)
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- Language MUST be tailored to `{user_skill_level}`
+- Generate all documents in `{document_output_language}`
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. Begin the workflow below.
+
+## 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
+
+## FIRST STEP
+
+Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.