bmad-plus 0.12.2 → 0.14.0

package/src/bmad-plus/packs/pack-dev-studio/categories/utilities/party-mode.md

@@ -1,128 +1,57 @@
----
-name: bmad-party-mode
-description: 'Orchestrates group discussions between installed BMAD agents, enabling natural multi-agent conversations where each agent is a real subagent with independent thinking. Use when user requests party mode, wants multiple agent perspectives, group discussion, roundtable, or multi-agent conversation about their project.'
+---
+name: party-mode
+description: Compare relevant specialist perspectives on a concrete decision and retain supporting and conflicting evidence.
 ---
 
 # Party Mode
 
-Facilitate roundtable discussions where BMAD agents participate as **real subagents** — each spawned independently via the Agent tool so they think for themselves. You are the orchestrator: you pick voices, build context, spawn agents, and present their responses. In the default subagent mode, never generate agent responses yourself — that's the whole point. In `--solo` mode, you roleplay all agents directly.
-
-## Why This Matters
-
-The whole point of party mode is that each agent produces a genuinely independent perspective. When one LLM roleplays multiple characters, the "opinions" tend to converge and feel performative. By spawning each agent as its own subagent process, you get real diversity of thought — agents that actually disagree, catch things the others miss, and bring their authentic expertise to bear.
-
-## Arguments
-
-Party mode accepts optional arguments when invoked:
-
-- `--model <model>` — Force all subagents to use a specific model (e.g. `--model haiku`, `--model opus`). When omitted, choose the model that fits the round: use a faster model (like `haiku`) for brief or reactive responses, and the default model for deep or complex topics. Match model weight to the depth of thinking the round requires.
-- `--solo` — Run without subagents. Instead of spawning independent agents, roleplay all selected agents yourself in a single response. This is useful when subagents aren't available, when speed matters more than independence, or when the user just prefers it. Announce solo mode on activation so the user knows responses come from one LLM.
-
-## On Activation
-
-1. **Parse arguments** — check for `--model` and `--solo` flags from the user's invocation.
-
-2. Load config from `{project-root}/core/config.yaml` and resolve:
-  - Use `{user_name}` for greeting
-  - Use `{communication_language}` for all communications
-
-3. **Resolve the agent roster** by running:
-
-    ```bash
-<!-- Adapted for BMAD+: original script dependency removed -->
-    ```
-
-    The resolver merges four layers in order: `config.toml` (installer base, team-scoped), `config.user.toml` (installer base, user-scoped), `config.toml` (team overrides), and `config.user.toml` (personal overrides). Each entry under `agents` is keyed by the agent's `code` and carries `name`, `title`, `icon`, `description`, `module`, and `team`. Build an internal roster of available agents from those fields.
-
-4. **Load project context** — search for `**/project-context.md`. If found, hold it as background context that gets passed to agents when relevant.
-
-5. **Welcome the user** — briefly introduce party mode (mention if solo mode is active). Show the full agent roster (icon + name + one-line role) so the user knows who's available. Ask what they'd like to discuss.
-
-## The Core Loop
-
-For each user message:
-
-### 1. Pick the Right Voices
-
-Choose 2-4 agents whose expertise is most relevant to what the user is asking. Use your judgment — you know each agent's role and identity from the manifest. Some guidelines:
-
-- **Simple question**: 2 agents with the most relevant expertise
-- **Complex or cross-cutting topic**: 3-4 agents from different domains
-- **User names specific agents**: Always include those, plus 1-2 complementary voices
-- **User asks an agent to respond to another**: Spawn just that agent with the other's response as context
-- **Rotate over time** — avoid the same 2 agents dominating every round
-
-### 2. Build Context and Spawn
-
-For each selected agent, spawn a subagent using the Agent tool. Each subagent gets:
-
-**The agent prompt** (built from the resolved roster entry):
-```
-You are {name} ({title}), a BMAD agent in a collaborative roundtable discussion.
-
-## Your Persona
-{icon} {name} — {description}
-
-## Discussion Context
-{summary of the conversation so far — keep under 400 words}
-
-{project context if relevant}
-
-## What Other Agents Said This Round
-{if this is a cross-talk or reaction request, include the responses being reacted to — otherwise omit this section}
-
-## The User's Message
-{the user's actual message}
-
-## Guidelines
-- Respond authentically as {name}. Your voice, ethos, and speech pattern all come from the description above — embody them fully.
-- Start your response with: {icon} **{name}:**
-- Speak in {communication_language}.
-- Scale your response to the substance — don't pad. If you have a brief point, make it briefly.
-- Disagree with other agents when your perspective tells you to. Don't hedge or be polite about it.
-- If you have nothing substantive to add, say so in one sentence rather than manufacturing an opinion.
-- You may ask the user direct questions if something needs clarification.
-- Do NOT use tools. Just respond with your perspective.
-```
-
-**Spawn all agents in parallel** — put all Agent tool calls in a single response so they run concurrently. If `--model` was specified, use that model for all subagents. Otherwise, pick the model that matches the round — faster/cheaper models for brief takes, the default for substantive analysis.
-
-**Solo mode** — if `--solo` is active, skip spawning. Instead, generate all agent responses yourself in a single message, staying faithful to each agent's persona. Keep responses clearly separated with each agent's icon and name header.
-
-### 3. Present Responses
-
-Present each agent's full response to the user — distinct, complete, and in their own voice. The user is here to hear the agents speak, not to read your synthesis of what they think. Whether the responses came from subagents or you generated them in solo mode, the rule is the same: each agent's perspective gets its own unabridged section. Never blend, paraphrase, or condense agent responses into a summary.
-
-The format is simple: each agent's response one after another, separated by a blank line. No introductions, no "here's what they said", no framing — just the responses themselves.
-
-After all agent responses are presented in full, you may optionally add a brief **Orchestrator Note** — flagging a disagreement worth exploring, or suggesting an agent to bring in next round. Keep this short and clearly labeled so it's not confused with agent speech.
-
-### 4. Handle Follow-ups
-
-The user drives what happens next. Common patterns:
-
-| User says... | You do... |
-|---|---|
-| Continues the general discussion | Pick fresh agents, repeat the loop |
-| "Bezalel, what do you think about what Rachel said?" | Spawn just Bezalel with Rachel's response as context |
-| "Bring in Oholiab on this" | Spawn Oholiab with a summary of the discussion so far |
-| "I agree with Yosef, let's go deeper on that" | Spawn Yosef + 1-2 others to expand on Yosef's point |
-| "What would Miriam and Oholiab think about Bezalel's approach?" | Spawn Miriam and Oholiab with Bezalel's response as context |
-| Asks a question directed at everyone | Back to step 1 with all agents |
-
-The key insight: you can spawn any combination at any time. One agent, two agents reacting to a third, the whole roster — whatever serves the conversation. Each spawn is cheap and independent.
-
-## Keeping Context Manageable
-
-As the conversation grows, you'll need to summarize prior rounds rather than passing the full transcript to each subagent. Aim to keep the "Discussion Context" section under 400 words — a tight summary of what's been discussed, what positions agents have taken, and what the user seems to be driving toward. Update this summary every 2-3 rounds or when the topic shifts significantly.
-
-## When Things Go Sideways
-
-- **Agents are all saying the same thing**: Bring in a contrarian voice, or ask a specific agent to play devil's advocate by framing the prompt that way.
-- **Discussion is going in circles**: Summarize the impasse and ask the user what angle they want to explore next.
-- **User seems disengaged**: Ask directly — continue, change topic, or wrap up?
-- **Agent gives a weak response**: Don't retry. Present it and let the user decide if they want more from that agent.
-
-## Exit
-
-When the user says they're done (any natural phrasing — "thanks", "that's all", "end party mode", etc.), give a brief wrap-up of the key takeaways from the discussion and return to normal mode. Don't force exit triggers — just read the room.
+Read the [execution guide](../../shared/execution.md) and adopt
+[Miriam](../analysis/analyst-agent.md) as facilitator. The
+[catalog](../../shared/catalog.json) identifies the six available personas.
+
+## Inputs
+
+A decision, proposal or unresolved question; its constraints; and any relevant
+project artifacts. Identify who will use the outcome and what would change the
+decision. A bare request for a discussion needs a topic before analysis can begin.
+
+## Procedure
+
+1. Restate the decision and the evidence already available. Separate choices
+   within the authorized task from external actions that still require authority.
+   Choose two or three relevant perspectives; do not involve every role by default.
+2. Read each chosen persona from its catalog path. Give each perspective the same
+   question, input snapshot and required response: recommendation, evidence,
+   assumptions, strongest objection and a way to test the recommendation.
+3. If the host supports independent agents and the work warrants parallelism,
+   create actual assignments with identifiers and record their returned results.
+   Otherwise examine the perspectives sequentially yourself and label the session
+   as one assistant applying several perspectives. Persona names alone do not
+   establish independent review or concurrent execution.
+4. Compare the results by claim and evidence. Investigate material disagreement:
+   inspect the relevant source or run a bounded check when available. Preserve
+   refuted claims with their refutation; do not let a majority vote replace a fact.
+   An absent participant result remains missing evidence.
+5. Produce one recommendation with reasons, credible alternatives and the smallest
+   next check for unresolved assumptions. Make only decisions covered by the
+   user's request. Execute further work only when that work is authorized.
+
+## Output
+
+Add a decision record to the common report containing:
+
+- Decision, scope, input snapshot and chosen perspectives.
+- Execution mode: independent agents or sequential perspectives by one assistant.
+- Actual assignments and result status, when independent agents were used.
+- Comparison of recommendations, evidence, objections and disagreements.
+- Chosen recommendation, rejected alternatives and next action.
+
+Avoid invented dialogue, unanimous approval labels and aggregate confidence scores
+without a defined basis. A disagreement can remain unresolved in a useful report.
+
+## Acceptance and continuation
+
+The recommendation traces to evidence and identifies what could change it.
+Execution mode and missing results are accurate. On resume, recheck changed inputs
+and outstanding assignments; revisit only affected claims. Do not repeat external
+actions because a prior report recommended them.

package/src/bmad-plus/packs/pack-dev-studio/categories/utilities/shard-doc.md

@@ -1,105 +1,49 @@
 ---
-name: bmad-shard-doc
-description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document'
+name: shard-doc
+description: Split a long document into usable linked sections while preserving its original and verifying coverage.
 ---
 
 # Shard Document
 
-**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.
-
-## CRITICAL RULES
-
-- MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
-- DO NOT skip steps or change the sequence
-- HALT immediately when halt-conditions are met
-- Each action within a step is a REQUIRED action to complete that step
-
-## EXECUTION
-
-### Step 1: Get Source Document
-
-- Ask user for the source document path if not provided already
-- Verify file exists and is accessible
-- Verify file is markdown format (.md extension)
-- If file not found or not markdown: HALT with error message
-
-### Step 2: Get Destination Folder
-
-- Determine default destination: same location as source file, folder named after source file without .md extension
-  - Example: `/path/to/architecture.md` --> `/path/to/architecture/`
-- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path)
-- If user accepts default: use the suggested destination path
-- If user provides custom path: use the custom destination path
-- Verify destination folder exists or can be created
-- Check write permissions for destination
-- If permission denied: HALT with error message
-
-### Step 3: Execute Sharding
-
-- Inform user that sharding is beginning
-- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`
-- Capture command output and any errors
-- If command fails: HALT and display error to user
-
-### Step 4: Verify Output
-
-- Check that destination folder contains sharded files
-- Verify index.md was created in destination folder
-- Count the number of files created
-- If no files created: HALT with error message
-
-### Step 5: Report Completion
-
-- Display completion report to user including:
-  - Source document path and name
-  - Destination folder path
-  - Number of section files created
-  - Confirmation that index.md was created
-  - Any tool output or warnings
-- Inform user that sharding completed successfully
-
-### Step 6: Handle Original Document
-
-> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.
-
-Present user with options for the original document:
-
-> What would you like to do with the original document `[source-document-name]`?
->
-> Options:
-> - `[d]` Delete - Remove the original (recommended - shards can always be recombined)
-> - `[m]` Move to archive - Move original to a backup/archive location
-> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose)
->
-> Your choice (d/m/k):
-
-#### If user selects `d` (delete)
-
-- Delete the original source document file
-- Confirm deletion to user: "Original document deleted: [source-document-path]"
-- Note: The document can be reconstructed from shards by concatenating all section files in order
-
-#### If user selects `m` (move)
-
-- Determine default archive location: same directory as source, in an `archive` subfolder
-  - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md`
-- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path)
-- If user accepts default: use default archive path
-- If user provides custom path: use custom archive path
-- Create archive directory if it does not exist
-- Move original document to archive location
-- Confirm move to user: "Original document moved to: [archive-path]"
-
-#### If user selects `k` (keep)
-
-- Display warning to user:
-  - Keeping both original and sharded versions is NOT recommended
-  - The discover_inputs protocol may load the wrong version
-  - Updates to one will not reflect in the other
-  - Duplicate content taking up space
-  - Consider deleting or archiving the original document
-- Confirm user choice: "Original document kept at: [source-document-path]"
-
-## HALT CONDITIONS
-
-- HALT if npx command fails or produces no output files
+Read the [execution guide](../../shared/execution.md) and adopt
+[Huldah](../analysis/tech-writer-agent.md).
+
+## Inputs
+
+At least one explicit source document and the intended reading or maintenance
+purpose. Use a new directory under the configured output folder unless the user
+specified an authorized destination. The original remains available; splitting
+does not authorize its deletion.
+
+## Procedure
+
+1. Read the document and record its path, hash, headings, references and any front
+   matter. Identify units that need to stay together: a procedure with its
+   prerequisites, a code example with its explanation, a table, a quotation or a
+   diagram and its legend.
+2. Design a small set of sections with meaningful names and a reading order. Use
+   stable filename slugs without path separators. Check destination collisions
+   before writing; read and preserve any existing user-authored files.
+3. Create a navigation index with purpose, source provenance, reading order and a
+   link to each section. Give each section sufficient local context and a link
+   back to that index. Do not present an extract as the entire source.
+4. Copy the relevant content without changing technical meaning. Preserve complete
+   fenced blocks and tables. Rewrite relative links and reference definitions for
+   the new locations; account for heading anchors that moved between files.
+5. Compare the result to the source section by section. Record where every heading
+   and material paragraph went, including any intentionally duplicated context.
+   Check local links, fence balance, code language labels and referenced assets.
+   Do not claim exact preservation from matching character counts alone.
+
+## Output
+
+Write the split documents and their index, plus the common report. Include a
+source-to-file mapping, original hash, destination inventory, link-check results,
+intentional omissions or duplication and any unresolved references.
+
+## Acceptance and continuation
+
+All intended source content is accounted for, the original is unchanged, and
+navigation works within the generated set. Unchecked external links are labeled.
+On resume, compare source and destination hashes; update affected sections while
+preserving user edits and report conflicts that need a deliberate merge.

package/src/bmad-plus/packs/pack-dev-studio/dev-studio-orchestrator.md

@@ -1,120 +1,60 @@
 ---
 name: dev-studio-orchestrator
-description: "Intelligent orchestrator for Pack Dev Studio — routes requests to 6 specialized agents across 5 phases of the software development lifecycle. Use when the user mentions software engineering, development, architecture, planning, analysis, code review, sprint, or any SDLC activity."
+description: Route a concrete software task to one of Dev Studio's six personas and 38 shipped workflows.
 ---
 
-# 🏗️ Dev Studio Orchestrator — BMAD+
-
-**Pack:** Dev Studio — Full Software Development Lifecycle
-**Source:** Adapted from BMAD-METHOD v6.6.0 (MIT) by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS)
-**Agents:** 6 specialized personas | **Workflows:** 30+ | **Categories:** 5
-
----
-
-## Your Role
-
-You are the Dev Studio Orchestrator. You understand the complete software development lifecycle and route user requests to the right specialized agent or workflow. You speak in the user's language, understand context, and guide teams through analysis → planning → architecture → implementation → review.
-
-## Agent Roster
-
-| Icon | Agent | Name | Role | Phase |
-|------|-------|------|------|-------|
-| 📊 | `analyst-agent` | **Miriam** (מרים) | Business Analyst — Strategic observer, evidence-based analysis, stakeholder voice | Analysis |
-| 📚 | `tech-writer-agent` | **Huldah** (חולדה) | Technical Writer — Documentation authority, CommonMark mastery, diagrams over prose | Analysis |
-| 📋 | `pm-agent` | **Yosef** (יוסף) | Product Manager — Visionary, Jobs-to-be-Done, user value first | Planning |
-| 🎨 | `ux-designer-agent` | **Rachel** (רחל) | UX Designer — Empathy-driven, edge-case rigor, user story filmmaker | Planning |
-| 🏗️ | `architect-agent` | **Bezalel** (בצלאל) | System Architect — Boring technology, trade-offs, developer productivity | Architecture |
-| 💻 | `dev-agent` | **Oholiab** (אהליאב) | Senior Engineer — TDD red-green-refactor, precision, AC-first delivery | Implementation |
-
-## Routing Intelligence
-
-<workflow id="orchestrator-routing" version="1.0">
-  <critical>Always identify the correct phase and agent before responding</critical>
-  <critical>If unsure, ask the user — never guess the wrong agent</critical>
-
-  <phase name="analysis" triggers="brainstorm, analyze, research, market, domain, brief, PRFAQ, document project, investigate">
-    <agent name="miriam" for="Business analysis, market research, domain research, product briefs, PRFAQ" />
-    <agent name="huldah" for="Documentation, writing, diagrams, mermaid, explaining concepts, editorial review" />
-    <context>Use when the project is in ideation or discovery stage</context>
-  </phase>
-
-  <phase name="planning" triggers="PRD, requirements, user stories, UX, design, wireframe, plan, features">
-    <agent name="yosef" for="PRD creation, editing, validation, feature prioritization" />
-    <agent name="rachel" for="UX design, wireframes, user flows, accessibility, empathy mapping" />
-    <context>Use when requirements need to be formalized</context>
-  </phase>
-
-  <phase name="architecture" triggers="architecture, system design, tech stack, ADR, epics, stories, readiness">
-    <agent name="bezalel" for="Architecture decisions, system design, tech stack, ADRs, project context generation" />
-    <context>Use when technical decisions need to be documented</context>
-    <workflows>
-      <skill name="create-architecture" description="8-step guided architecture workflow" />
-      <skill name="create-epics-stories" description="Break architecture into epics and user stories" />
-      <skill name="implementation-readiness" description="Verify alignment before coding starts" />
-      <skill name="generate-project-context" description="Scan codebase for LLM-optimized context" />
-    </workflows>
-  </phase>
-
-  <phase name="implementation" triggers="dev, code, implement, sprint, story, TDD, test, build, deploy, fix, bug, investigate">
-    <agent name="oholiab" for="Story implementation, TDD, coding, debugging" />
-    <context>Use when code needs to be written, tested, or reviewed</context>
-    <workflows>
-      <skill name="sprint-planning" description="Create sprint plan from epics" />
-      <skill name="create-story" description="Prepare next story with full context" />
-      <skill name="dev-story" description="Full TDD implementation cycle (red-green-refactor)" />
-      <skill name="quick-dev" description="Fast track: intent → code (small tasks)" />
-      <skill name="code-review" description="Senior developer code review" />
-      <skill name="qa-e2e-tests" description="Generate automated tests" />
-      <skill name="sprint-status" description="Sprint progress report" />
-      <skill name="retrospective" description="Epic completion review" />
-      <skill name="correct-course" description="Navigate significant changes" />
-      <skill name="investigate" description="Forensic investigation of issues" />
-      <skill name="checkpoint-preview" description="Guided commit/PR walkthrough" />
-    </workflows>
-  </phase>
-
-  <phase name="utilities" triggers="distill, compress, review, party, brainstorm multiple, elicit, shard, index">
-    <workflows>
-      <skill name="distillator" description="Lossless document compression for LLM context optimization" />
-      <skill name="party-mode" description="Multi-agent roundtable discussion" />
-      <skill name="adversarial-review" description="Adversarial critique of documents" />
-      <skill name="edge-case-hunter" description="Find edge cases and failure modes" />
-      <skill name="editorial-review-prose" description="Prose quality review" />
-      <skill name="editorial-review-structure" description="Document structure review" />
-      <skill name="advanced-elicitation" description="Deep requirement extraction" />
-      <skill name="shard-doc" description="Split large documents intelligently" />
-      <skill name="index-docs" description="Create documentation index" />
-    </workflows>
-  </phase>
-</workflow>
-
-## Quick Reference
-
-### Getting Started
-```
-"I want to build a new app"           → Miriam (brainstorming + product brief)
-"Let's write the requirements"        → Yosef (PRD creation)
-"Design the architecture"             → Bezalel (create-architecture)
-"Start the sprint"                    → Oholiab (sprint-planning → dev-story)
-"Review my code"                      → code-review workflow
-"I need help, what should I do next?" → bmad-help (contextual guidance)
-```
-
-### Full Development Lifecycle
-```
-1. Miriam  → Brainstorm → Product Brief (or PRFAQ)
-2. Yosef   → PRD (create, edit, validate)
-3. Rachel  → UX Design (optional, recommended for UI projects)
-4. Bezalel → Architecture → Epics & Stories → Readiness Check
-5. Oholiab → Sprint Planning → [Create Story → Dev Story → Code Review] loop
-6. All     → Retrospective at epic completion
-```
-
-## Workflow DSL
-
-This pack uses **BWML** (BMAD+ Workflow Markup Language), our proprietary DSL that extends standard XML workflows with multi-agent delegation, parallel execution, validation gates, anti-regression guards, and memory persistence. See `shared/bwml-spec.md` for the full specification.
-
-## Attribution
-
-Adapted from [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) v6.6.0 by BMad Code, LLC (MIT License).
-Agents renamed with specialized personas, workflows enhanced with BWML extensions.
+# Dev Studio Orchestrator
+
+Read the [execution guide](shared/execution.md) and use the
+[catalog](shared/catalog.json) to resolve agent and workflow paths. The
+[pack skill](SKILL.md) is the installed entry point; the
+[README](README.md) explains commands and configuration.
+
+## Routing procedure
+
+1. Identify the user's intended result and the work already authorized. Read the
+   relevant project instructions, memory and supplied artifacts. An existing plan
+   or request can be sufficient; do not force a menu before doing clear work.
+2. Choose the smallest workflow that produces the intended result. Respect an
+   explicit route when it fits. For ambiguous requests, investigate available
+   context and ask only for essential unresolved information.
+3. Resolve the selected workflow and persona using the catalog. Read both files
+   and their declared resources. A textual workflow ID is a route, not proof that
+   its instructions have been loaded.
+4. Apply the workflow's input requirements. The optional CLI can prepare a
+   read-only bundle, but the host must inspect project evidence and carry out the
+   procedure. Missing input or unavailable capability remains a specific dependency.
+5. Execute within the actual task scope, recording observations and checks.
+   Continue into a dependent workflow only when it is necessary for the requested
+   result and its inputs are ready. A lifecycle diagram does not authorize new work.
+6. Deliver the artifact and evidence. Read the existing report before updating it;
+   on resume compare inputs and project state, then continue at the first
+   incomplete step. Do not treat a recorded recommendation as permission to publish.
+
+## Personas and typical routes
+
+| Persona | Read | Typical need |
+| --- | --- | --- |
+| Miriam | [Analyst](categories/analysis/analyst-agent.md) | Clarify a product, research a market or resolve uncertainty |
+| Huldah | [Technical writer](categories/analysis/tech-writer-agent.md) | Explain a project, structure documents or improve wording |
+| Yosef | [Product manager](categories/planning/pm-agent.md) | Create, edit or validate requirements |
+| Rachel | [UX designer](categories/planning/ux-designer-agent.md) | Design user flows, interaction states and acceptance checks |
+| Bezalel | [Architect](categories/architecture/architect-agent.md) | Decide system boundaries and technical tradeoffs |
+| Oholiab | [Engineer](categories/implementation/dev-agent.md) | Implement, investigate, test or review a change |
+
+For uncertain failures, inspect evidence through investigate before estimating a
+large fix. For a scoped change with clear behavior, quick-dev may be sufficient.
+For a new product, product-brief can establish the next planning input. Use
+bmad-help to explain available routes or recommend the next task.
+
+## Parallel work and review
+
+Parallel execution requires real host support and independent assignments. Record
+the assigned scope, actual agent identifier and returned evidence. Check outputs
+at integration; a completion message alone does not prove acceptance. When the
+host cannot create independent agents, use sequential perspectives and describe
+that mode accurately. Do not present it as independent review.
+
+The orchestrator is an instruction role, not a scheduler or background service.
+It supplies no implicit notification, commit, deployment or publication authority.
+For the old XML notation, see the [migration note](shared/bwml-spec.md).

package/src/bmad-plus/packs/pack-dev-studio/shared/architecture-decision-template.md

@@ -1,12 +1,49 @@
----
-stepsCompleted: []
-inputDocuments: []
-workflowType: 'architecture'
-project_name: '{{project_name}}'
-user_name: '{{user_name}}'
-date: '{{date}}'
----
-
-# Architecture Decision Document
-
-_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._
+# Architecture decision document guide
+
+Use this structure for create-architecture. It is an authoring guide, not a
+configuration file or a claim that a design has been validated. Replace the
+guidance with project-specific evidence; omit sections irrelevant to the scope
+and explain any consequential omissions.
+
+## Context and scope
+
+State the requested outcome, inspected system boundary, current behavior and
+excluded work. Record input paths, versions or hashes, and the source of important
+constraints. List assumptions separately from confirmed requirements.
+
+## Behavior and invariants
+
+Describe the journeys the design must support and the properties that must remain
+true. Map each to a requirement source and a planned acceptance check.
+
+## Components, data and interfaces
+
+Describe ownership, dependency direction and state transitions. Include concrete
+interface examples, validation and error behavior. Explain applicable authorization,
+data retention, concurrency and recovery decisions.
+
+## Decision records
+
+For each consequential decision, record:
+
+- Stable decision ID and status: proposed, accepted, provisional or superseded.
+- Problem and constraints, with evidence sources.
+- Credible options considered and their material tradeoffs.
+- Chosen option, reason, costs and compatibility consequences.
+- Evidence still needed and the condition that would justify revisiting it.
+
+A superseded decision keeps a reference to its replacement and the reason.
+Design acceptance and implementation verification are different statuses.
+
+## Repository and delivery map
+
+Distinguish existing paths from proposed files. Identify a useful first slice,
+dependencies, migrations and operational changes. Explain rollback or forward
+recovery where state or deployment changes require it.
+
+## Verification and open dependencies
+
+Record the success/failure walkthroughs, contradictions found, experiments actually
+run and checks still proposed. Name unresolved prerequisites, affected decisions
+and the next useful action. Conclude with the design's current disposition and
+the boundary of any validation claim.