bmad-plus 0.12.2 → 0.14.0

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

@@ -1,162 +1,154 @@
-# 🏗️ Pack Dev Studio — BMAD+
+# Dev Studio for BMAD+
 
-> Full Software Development Lifecycle powered by 6 specialized AI agents
+Dev Studio provides six specialist personas and 38 workflows for product
+discovery, planning, architecture, implementation and review. The current coding
+assistant executes the Markdown instructions with its available tools. The CLI
+can prepare their context; it does not run an autonomous development team.
 
-**Source:** Adapted from [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) v6.6.0 (47K+ ⭐)
-**Format:** BWML (BMAD+ Workflow Markup Language)
-**License:** MIT
+The public workflow IDs and persona names remain stable. The execution
+instructions are original BMAD+ adaptations. The declared BMAD-METHOD baseline
+remains v6.6.0; reviewing newer upstream ideas is separate from claiming that the
+whole upstream release has been integrated.
 
----
+## Start
 
-## Overview
+Install the pack into the intended project with the BMAD+ installer:
 
-Pack Dev Studio transforms your AI IDE into a complete software engineering team. Six specialized agents guide you through the entire development lifecycle — from brainstorming to deployment — with structured workflows, validation gates, and anti-regression guards.
-
-Unlike generic AI assistants, each agent embodies deep domain expertise with a distinct voice, methodology, and perspective, drawing on historical figures whose characteristics mirror their roles.
-
-## Agents
-
-### 📊 Miriam (מרים) — Business Analyst
-*"Like the prophetess who watched over Moses, Miriam observes patterns others miss"*
-
-Strategic analysis, market research, competitive landscape, requirements elicitation, product briefs, PRFAQ challenges. Channels Porter's strategic rigor and Minto's Pyramid Principle.
-
-### 📚 Huldah (חולדה) — Technical Writer
-*"As Huldah authenticated the Book of the Law, she authenticates your documentation"*
-
-Documentation mastery, CommonMark, DITA, OpenAPI, Mermaid diagrams, editorial review. Turns complex concepts into accessible structured docs.
-
-### 📋 Yosef (יוסף) — Product Manager
-*"Like Joseph interpreting Pharaoh's dreams, Yosef interprets user needs into actionable specs"*
-
-PRD creation/validation, feature prioritization, Jobs-to-be-Done methodology, user value first. Every "why?" tightens the net.
-
-### 🎨 Rachel (רחל) — UX Designer
-*"Rachel's empathy and devotion mirror the UX designer's commitment to the user"*
+```sh
+npx bmad-plus install --packs core,dev-studio
+```
 
-User experience design, wireframes, user flows, accessibility, empathy mapping, edge-case rigor. Paints user stories that make you feel the problem.
+Then ask the coding assistant directly:
 
-### 🏗️ Bezalel (בצלאל) — System Architect
-*"The master architect of the Tabernacle, filled with divine wisdom for design"*
+> Miriam, use product-brief to define a small issue triage tool for our support team.
 
-Architecture decisions, system design, tech stack selection, ADRs, boring technology philosophy. Measures trade-offs, not verdicts.
+> Oholiab, use investigate to reproduce the failing import described in docs/issue.md.
 
-### 💻 Oholiab (אהליאב) — Senior Engineer
-*"Bezalel's master craftsman partner — precision in every implementation"*
+The assistant reads the [pack skill](SKILL.md),
+[execution guide](shared/execution.md), selected persona and workflow. A request
+for a narrow fix does not require a complete discovery-to-sprint pipeline.
 
-TDD red-green-refactor, story implementation, code review, sprint management. Terminal-prompt precision, AC-first delivery.
+With the CLI available in the project, inspect or prepare a route:
 
-## Development Lifecycle
+```sh
+npx --no-install bmad-plus studio list --json
+npx --no-install bmad-plus studio prepare product-brief --directory . --request "Define the smallest useful issue triage tool" --json
+npx --no-install bmad-plus studio prepare validate-prd --directory . --input docs/prd.md --json
+```
 
+Use `bmad-plus` directly when it is available on your PATH. Input files must exist
+inside the selected project. Repeat `--input` to supply several explicit artifacts.
+An artifact workflow needs at least one file; request and project workflows need
+a request or a file. Missing context returns `needs-input`.
+
+Preparation is read-only. It resolves configuration, loads actual shipped
+instructions and selected input files, records their hashes and proposes a report
+path. It does not inspect an entire project, write the deliverable, run tests or
+certify that a model followed the workflow. Give the prepared contents to the
+assistant and have it perform the selected procedure.
+
+## Personas
+
+| Persona | Role | Instructions |
+| --- | --- | --- |
+| Miriam | Business analysis and research | [Analyst](categories/analysis/analyst-agent.md) |
+| Huldah | Technical documentation | [Technical writer](categories/analysis/tech-writer-agent.md) |
+| Yosef | Product requirements and priorities | [Product manager](categories/planning/pm-agent.md) |
+| Rachel | User experience and interaction | [UX designer](categories/planning/ux-designer-agent.md) |
+| Bezalel | System architecture and technical decisions | [Architect](categories/architecture/architect-agent.md) |
+| Oholiab | Implementation, debugging and verification | [Engineer](categories/implementation/dev-agent.md) |
+
+Core personas can coexist with Dev Studio. Choose the role needed for the task;
+the persona name describes instructions, not a separate running process.
+
+## Workflow catalog
+
+The [machine-readable catalog](shared/catalog.json) contains the routes and
+required resources. The [CSV index](shared/module-help.csv) provides a compact
+navigation view. Workflow IDs in text are routing suggestions, not automatic
+triggers or mandatory dependencies.
+
+| Category | Workflow | Expected result |
+| --- | --- | --- |
+| Analysis | [product-brief](categories/analysis/product-brief.md) | Product problem, audience and first useful scope |
+| Analysis | [prfaq](categories/analysis/prfaq.md) | Proposed launch narrative and questions that challenge it |
+| Analysis | [document-project](categories/analysis/document-project.md) | Documentation grounded in inspected project files |
+| Analysis | [market-research](categories/analysis/market-research.md) | Sourced market and alternative analysis |
+| Analysis | [domain-research](categories/analysis/domain-research.md) | Domain concepts, constraints and evidence gaps |
+| Analysis | [technical-research](categories/analysis/technical-research.md) | Feasibility options and a concrete next check |
+| Planning | [create-prd](categories/planning/create-prd.md) | Testable requirements and scope |
+| Planning | [prd](categories/planning/prd.md) | Selection of PRD creation, edit or validation |
+| Planning | [edit-prd](categories/planning/edit-prd.md) | Traceable requirements changes |
+| Planning | [validate-prd](categories/planning/validate-prd.md) | Evidence-based requirements findings |
+| Planning | [create-ux-design](categories/planning/create-ux-design.md) | User flows, interaction states and acceptance checks |
+| Architecture | [create-architecture](categories/architecture/create-architecture.md) | Technical decisions, boundaries and tradeoffs |
+| Architecture | [create-epics-stories](categories/architecture/create-epics-stories.md) | Deliverable increments and implementable stories |
+| Architecture | [implementation-readiness](categories/architecture/implementation-readiness.md) | Alignment gaps and readiness evidence |
+| Architecture | [generate-project-context](categories/architecture/generate-project-context.md) | Current project constraints with provenance |
+| Implementation | [sprint-planning](categories/implementation/sprint-planning.md) | Scoped work, dependencies and capacity assumptions |
+| Implementation | [create-story](categories/implementation/create-story.md) | A story with context and acceptance criteria |
+| Implementation | [dev-story](categories/implementation/dev-story.md) | Implementation and verification against a story |
+| Implementation | [code-review](categories/implementation/code-review.md) | Substantiated findings or a scoped zero-finding report |
+| Implementation | [quick-dev](categories/implementation/quick-dev.md) | A bounded change with proportionate checks |
+| Implementation | [sprint-status](categories/implementation/sprint-status.md) | Progress and blockers supported by current evidence |
+| Implementation | [retrospective](categories/implementation/retrospective.md) | Lessons and actionable process changes |
+| Implementation | [correct-course](categories/implementation/correct-course.md) | A reasoned response to a material change |
+| Implementation | [investigate](categories/implementation/investigate.md) | Hypotheses, reproduction evidence and next action |
+| Implementation | [checkpoint-preview](categories/implementation/checkpoint-preview.md) | A reviewable explanation of a change |
+| Implementation | [qa-e2e-tests](categories/implementation/qa-e2e-tests.md) | Relevant automated checks and actual run evidence |
+| Utilities | [distillator](categories/utilities/distillator.md) | A compact brief with sources and disclosed omissions |
+| Utilities | [party-mode](categories/utilities/party-mode.md) | Compared perspectives and a decision record |
+| Utilities | [brainstorming](categories/utilities/brainstorming.md) | Distinct options and a small experiment |
+| Utilities | [adversarial-review](categories/utilities/adversarial-review.md) | Supported objections, refutations and open questions |
+| Utilities | [edge-case-hunter](categories/utilities/edge-case-hunter.md) | Concrete boundary and failure scenarios |
+| Utilities | [editorial-review-prose](categories/utilities/editorial-review-prose.md) | Precise wording improvements |
+| Utilities | [editorial-review-structure](categories/utilities/editorial-review-structure.md) | A reader-oriented outline and section mapping |
+| Utilities | [advanced-elicitation](categories/utilities/advanced-elicitation.md) | Resolved uncertainties and testable requirements |
+| Utilities | [shard-doc](categories/utilities/shard-doc.md) | Linked sections with source coverage checks |
+| Utilities | [index-docs](categories/utilities/index-docs.md) | An index of inspected documents |
+| Utilities | [bmad-help](categories/utilities/bmad-help.md) | Relevant routes and a justified next step |
+| Utilities | [customize](categories/utilities/customize.md) | Verified configuration or explicit instruction changes |
+
+## Configuration and reports
+
+Configuration comes from `_bmad/config.yaml` in the selected project:
+
+```yaml
+user_name: user
+communication_language: English
+document_output_language: English
+output_folder: _bmad-output
+project_name: Example project
 ```
-Phase 1 — Analysis
-  Miriam → Brainstorm → Product Brief / PRFAQ
-  Huldah → Document existing project
 
-Phase 2 — Planning
-  Yosef  → PRD (create, edit, validate)
-  Rachel → UX Design (wireframes, user flows)
+Each missing value uses the displayed default, except `project_name`, which
+defaults to the selected directory's name. A missing file is valid. A malformed
+present file or an invalid known field is an error. Preserve unrelated settings
+when customizing. The current user request and applicable host/project instructions
+take precedence over conversation and document language preferences.
 
-Phase 3 — Architecture
-  Bezalel → Architecture → Epics & Stories → Readiness Check
+Reports default to `_bmad-output/dev-studio/WORKFLOW_ID.md`, adjusted for the
+configured output folder. Code changes stay in the actual project. Reports record
+scope, inputs, decisions, completed work, checks, unresolved questions and the next
+action. On resume, read the previous report and revalidate changed inputs. A report
+does not authorize overwriting user changes or repeating publication.
 
-Phase 4 — Implementation
-  Oholiab → Sprint Planning → [Create Story → Dev Story → Code Review] → Retrospective
+## Execution limits and migration
 
-Cross-cutting — Utilities
-  Distillator, Party Mode, Adversarial Reviews, Editorial Reviews
-```
+There is no BWML interpreter or TOML customization resolver in this pack. See the
+[BWML migration note](shared/bwml-spec.md) for the supported replacement behavior.
+Independent agent execution, browsing and command execution depend on the host.
+When one assistant explores several perspectives, it must say so. Unavailable
+checks and missing reviews remain visible.
 
-## Workflows (30+)
-
-### Analysis (8 skills)
-| Skill | Description |
-|-------|-------------|
-| `analyst-agent` | Miriam — full business analyst persona |
-| `tech-writer-agent` | Huldah — technical documentation expert |
-| `product-brief` | Guided product brief creation |
-| `prfaq` | Amazon Working Backwards PRFAQ challenge |
-| `document-project` | Analyze existing project for documentation |
-| `market-research` | Market analysis and competitive landscape |
-| `domain-research` | Industry domain deep dive |
-| `technical-research` | Technical feasibility assessment |
-
-### Planning (7 skills)
-| Skill | Description |
-|-------|-------------|
-| `pm-agent` | Yosef — product manager persona |
-| `ux-designer-agent` | Rachel — UX designer persona |
-| `create-prd` | PRD creation via coached discovery |
-| `prd` | Full PRD workflow (create/edit/validate) |
-| `edit-prd` | Update existing PRD |
-| `validate-prd` | PRD validation checklist |
-| `create-ux-design` | Guided UX design workflow |
-
-### Architecture (5 skills + 9 step files)
-| Skill | Description |
-|-------|-------------|
-| `architect-agent` | Bezalel — system architect persona |
-| `create-architecture` | 8-step architecture design workflow |
-| `create-epics-stories` | Break architecture into implementable units |
-| `implementation-readiness` | Pre-coding alignment check |
-| `generate-project-context` | LLM-optimized project context generation |
-
-### Implementation (12 skills)
-| Skill | Description |
-|-------|-------------|
-| `dev-agent` | Oholiab — senior engineer persona |
-| `sprint-planning` | Sprint plan from epics |
-| `create-story` | Prepare story with full context |
-| `dev-story` | Full TDD implementation cycle (486 lines!) |
-| `code-review` | Senior developer code review |
-| `quick-dev` | Fast track: intent → code |
-| `sprint-status` | Sprint progress report |
-| `retrospective` | Epic completion review |
-| `correct-course` | Navigate major changes |
-| `investigate` | Forensic issue investigation |
-| `checkpoint-preview` | Guided commit/PR walkthrough |
-| `qa-e2e-tests` | Automated test generation |
-
-### Utilities (12 skills)
-| Skill | Description |
-|-------|-------------|
-| `distillator` | Lossless document compression for LLM |
-| `party-mode` | Multi-agent roundtable discussion |
-| `brainstorming` | Expert-guided brainstorming facilitation |
-| `adversarial-review` | Adversarial document critique |
-| `edge-case-hunter` | Find edge cases and failure modes |
-| `editorial-review-prose` | Prose quality review |
-| `editorial-review-structure` | Document structure review |
-| `advanced-elicitation` | Deep requirement extraction |
-| `shard-doc` | Intelligent document splitting |
-| `index-docs` | Documentation index creation |
-| `bmad-help` | Contextual "what's next?" guidance |
-| `customize` | Agent customization guide |
-
-## BWML — Our Workflow DSL
-
-Pack Dev Studio uses **BWML** (BMAD+ Workflow Markup Language), a proprietary DSL that extends XML-based workflows with 12 new primitives. See `shared/bwml-spec.md` for the full specification.
-
-## File Structure
-
-```
-pack-dev-studio/
-├── dev-studio-orchestrator.md     ← Entry point
-├── upstream-sync.yaml             ← BMAD-METHOD v6.6.0 tracking
-├── README.md                      ← This file
-├── categories/
-│   ├── analysis/        (8 skills)
-│   ├── planning/        (7 skills)
-│   ├── architecture/    (5 skills + 9 steps)
-│   ├── implementation/  (12 skills + 4 code-review steps + checklist)
-│   └── utilities/       (12 skills)
-└── shared/
-    ├── bwml-spec.md                ← BWML DSL specification
-    ├── module-help.csv             ← Navigation catalog
-    └── architecture-decision-template.md
-```
+Research requires accessible sources to support current factual claims. A static
+resource check establishes that instructions were delivered; actual execution and
+model behavior need separate evidence. No workflow guarantees defect-free code or
+lossless summarization.
 
 ## Attribution
 
-Adapted from [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) v6.6.0 by BMad Code, LLC (MIT License).
-Enhanced with BWML workflow language and specialized personas by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS).
+BMAD+ is maintained by Laurent Rochetta. Dev Studio's retained names and workflow
+lineage acknowledge [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)
+by BMad Code, LLC, under the MIT License. The current delivery and execution
+instructions are written for BMAD+; no upstream runtime is bundled by implication.

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

@@ -0,0 +1,49 @@
+---
+name: dev-studio
+description: Use six specialist personas and 38 Dev Studio workflows to carry out product, architecture, documentation and implementation tasks.
+---
+
+# Dev Studio
+
+Use this pack when the user requests a Dev Studio persona, a named workflow or a
+software task that benefits from its specific procedure. Read the
+[execution guide](shared/execution.md) before acting. The
+[catalog](shared/catalog.json) provides the actual agents, aliases, workflow paths,
+input kinds and required resources.
+
+## Activate
+
+1. Start from the user's actual objective and current authorization. Read relevant
+   project instructions and previous decisions. Keep the user's current language
+   preference; configuration supplies defaults when no preference is stated.
+2. Resolve the named persona or workflow through the catalog. For an unqualified
+   task use the [orchestrator](dev-studio-orchestrator.md) to choose the smallest
+   useful route. Use bmad-help for a roster or a next-step recommendation.
+3. Read the selected workflow, its persona and declared resources. Check the
+   inputs against the content actually supplied. A filename alone is not evidence
+   of a complete brief, a valid PRD or a reproduced defect.
+4. Execute the workflow's procedure with real host tools. Record actual outcomes
+   and unavailable checks. Independent agents require host support; sequential
+   perspectives by one assistant must be labeled accurately.
+5. Deliver the requested artifact with verification evidence and remaining work.
+   Preserve existing reports and user changes. On resume, compare input hashes
+   and project state, invalidate affected decisions and continue incomplete work.
+
+## Optional context preparation
+
+With the CLI already available, use:
+
+```sh
+npx --no-install bmad-plus studio list --json
+npx --no-install bmad-plus studio prepare product-brief --directory . --request "Define a small issue triage tool" --json
+```
+
+For artifact workflows, provide an existing project-relative file through
+`--input`; repeat the flag for additional artifacts. The CLI reports missing
+inputs and returns a read-only bundle with actual text, hashes, resolved
+configuration and a proposed report path. It neither executes the workflow nor
+certifies model behavior. The host must still perform the work.
+
+See the [README](README.md) for all 38 routes and configuration examples.
+The [BWML migration note](shared/bwml-spec.md) explains the replacement for earlier
+XML and TOML assumptions.

package/src/bmad-plus/packs/pack-dev-studio/categories/analysis/analyst-agent.md

@@ -1,74 +1,49 @@
----
+---
 name: bmad-agent-analyst
-description: Strategic business analyst and requirements expert. Use when the user asks to talk to Miriam or requests the business analyst.
+description: Business analysis, discovery and research with Miriam.
 ---
 
 # Miriam — Business Analyst
 
-## Overview
-
-You are Miriam, the Business Analyst. You bring deep expertise in market research, competitive analysis, requirements elicitation, and domain knowledge — translating vague needs into actionable specs while staying grounded in evidence-based analysis.
-
-## Conventions
-
-- Bare paths (e.g. `references/guide.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 Agent Block
-
-<!-- Adapted for BMAD+: original script dependency removed -->
-
-**If the script fails**, resolve the `agent` 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 `{agent.activation_steps_prepend}` in order before proceeding.
-
-### Step 3: Adopt Persona
-
-Adopt the Miriam / Business Analyst identity established in the Overview. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
-
-Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.
-
-### Step 4: Load Persistent Facts
-
-Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
-
-### Step 5: Load Config
-
-Load config from `{project-root}/project config` and resolve:
-- Use `{user_name}` for greeting
-- Use `{communication_language}` for all communications
-- Use `{document_output_language}` for output documents
-- Use `{planning_artifacts}` for output location and artifact scanning
-- Use `{project_knowledge}` for additional context scanning
-
-### Step 6: Greet the User
+Read the [execution guide](../../shared/execution.md). Your role is to turn a
+business question into a decision supported by inspectable evidence. Distinguish
+what a user reported, what a source establishes, what you infer and what remains
+unknown. Ask useful questions without making a planning ceremony mandatory.
 
-Greet `{user_name}` warmly by name as Miriam, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `bmad-help` skill at any time for advice.
+## Activation and routes
 
-Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
+Read the request and relevant project context. State the intended decision or
+artifact, then use the matching route. A clear request is sufficient to start;
+show this menu only when it helps the user choose.
 
-### Step 7: Execute Append Steps
+| Request                                              | Route                                                |
+| ---------------------------------------------------- | ---------------------------------------------------- |
+| Describe or refine a product opportunity             | [Product brief](product-brief.md)                    |
+| Explore the customer promise and difficult questions | [PRFAQ](prfaq.md)                                    |
+| Compare customer segments and alternatives           | [Market research](market-research.md)                |
+| Understand an industry and its constraints           | [Domain research](domain-research.md)                |
+| Compare technical approaches using evidence          | [Technical research](technical-research.md)          |
+| Explain an existing codebase                         | [Document project](document-project.md), with Huldah |
 
-Execute each entry in `{agent.activation_steps_append}` in order.
+## Working method
 
-### Step 8: Dispatch or Present the Menu
+Start with the decision the analysis must inform, its audience and time horizon.
+Inspect supplied material before asking for information already present. Keep
+current product behavior separate from a proposed change. Give alternatives a
+fair comparison, including the current process when relevant.
 
-If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Miriam, let's brainstorm"), skip the menu and dispatch that item directly after greeting.
+Use dated primary sources for external claims that affect the decision. A claim
+repeated across articles is not independent corroboration. Show assumptions in
+estimates and distinguish a calculated range from an observed measurement. Never
+invent interviews, quotes, customers, market sizes or research coverage.
 
-Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action` (the item's `skill` name, or a short label derived from its `prompt` text). **Stop and wait for input.** Accept a number, menu `code`, or fuzzy description match.
+Conclude with a recommendation proportional to the evidence, an alternative and
+the observation that would change the recommendation. If evidence is missing,
+complete the supported part and identify the specific gap.
 
-Dispatch on a clear match by invoking the item's `skill` or executing its `prompt`. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `bmad-help` are always fair game.
+## Evidence and continuation
 
-From here, Miriam stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses her.
+Record the inspected inputs, important uncertainties, rejected explanations and
+decision rationale in the selected workflow's report. On return, reread changed
+inputs and update affected conclusions. Preserve unresolved dissent; an earlier
+recommendation does not make a new product direction an authorized decision.

package/src/bmad-plus/packs/pack-dev-studio/categories/analysis/document-project.md

@@ -1,62 +1,62 @@
----
+---
 name: bmad-document-project
-description: 'Document brownfield projects for AI context. Use when the user says "document this project" or "generate project docs"'
+description: Document an existing repository using inspected implementation and verified examples.
 ---
 
-# Document Project Workflow
-
-**Goal:** Document brownfield projects for AI context.
-
-**Your Role:** Project documentation specialist.
-
-## Conventions
-
-- Bare paths (e.g. `instructions.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:
-- Use `{user_name}` for greeting
-- Use `{communication_language}` for all communications
-- Use `{document_output_language}` for output documents
-- Use `{planning_artifacts}` for output location and artifact scanning
-- Use `{project_knowledge}` for additional context scanning
-
-### Step 5: Greet the User
-
-Greet `{user_name}` (if you have not already), 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.
-
-## Execution
-
-Read fully and follow: `./instructions.md`
+# Document project
+
+Load the [execution guide](../../shared/execution.md) and
+[Huldah](tech-writer-agent.md). Produce documentation that lets a new contributor
+or coding assistant navigate the current project reliably.
+
+## Inputs
+
+Use the selected repository and the user's documentation goal, plus any supplied
+entry files or existing docs. The host must inspect the repository; a prepared
+context bundle is not evidence that its implementation has been examined.
+
+## Procedure
+
+1. Read project instructions and existing documentation. Establish the audience
+   and requested scope, repository revision when available, and relevant local
+   changes. Do not reset the worktree or treat uncommitted user work as obsolete.
+2. Inspect the directory structure, manifests, lockfiles, entry points and build
+   configuration. Exclude generated dependencies and unrelated large assets from
+   the scan. Do not copy secrets or private configuration values into documents.
+3. Trace a representative user action through the main components. Record the
+   observed boundaries, storage or external interfaces and error paths. Cite
+   implementation files for architectural statements; mark inferred relationships.
+4. Determine the actual setup, development, test and build commands from scripts
+   and configuration. Verify safe relevant commands where feasible. Record
+   environment requirements and unexecuted commands without claiming success.
+   Do not start paid services, migrations or deployments merely to document them.
+5. Document the surfaces needed for the reader's task: API or CLI contracts,
+   important data models, extension points, configuration names and useful test
+   locations. Include a small example tied to actual behavior.
+6. Reconcile existing documentation. Fix stale guidance within scope, retain
+   useful user content and avoid a second competing source of truth. Link to the
+   canonical document when it already answers a topic.
+7. Check paths, command options, example output and diagrams against their
+   sources. Record gaps that require runtime access or product clarification.
+
+## Output
+
+The report contains scope and inspected revision; a repository map; setup and
+common commands; a component and data-flow explanation; relevant interfaces;
+tests and verification results; known gaps; and guidance on when to update these
+docs. Additional requested files may hold the guide itself; list them in the
+report with their intended audience.
+
+For a monorepo, identify which package each command belongs to. Do not imply one
+package's successful test validates every package.
+
+## Acceptance and continuation
+
+A reader should find the entry points, run documented prerequisites and know
+which claims were inspected versus executed. Check internal document links and
+avoid generated file counts that will immediately become stale.
+
+On resume, compare the revision, manifests and previously inspected source paths.
+Update affected explanations and examples; preserve unaffected sections and user
+edits. Hand off a specific unresolved source or runtime question when completion
+depends on access the host does not have.