@skyf0xx/hedgehog 0.1.13 → 0.1.16

package/README.md

@@ -8,7 +8,13 @@ AI writes code faster than humans ever could, but **speed without discipline cre
 
 **Build faster**, **save context**, stay aligned, and **ship** software you can still understand six months later.
 
-![Hedgehog — build software the right way, one step at a time](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/hero.png)
+Hedgehog pairs **BMAD's planning** with **disciplined execution**, in one workflow.
+
+- Plan: BMAD workflow
+- Build: Hedgehog execution discipline
+- Ship: Quality gates and incremental loops
+
+![Hedgehog - build software the right way, one step at a time](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/hero.png)
 
 ## Hedgehog gives AI
 
@@ -23,7 +29,7 @@ AI writes code faster than humans ever could, but **speed without discipline cre
 - **Self-documenting architecture:** the codebase carries the context, not the AI
 - **Traceable evolution:** decisions are preserved through conventional commits
 
-![Just describe what you want](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/curve.png)
+![Just describe what you want](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/handoff.jpg)
 
 ## Why Hedgehog Exists
 
@@ -52,16 +58,16 @@ The build order is not something you negotiate with the AI. It is encoded into t
 ## The Hedgehog Loop
 
 ``` text
-Planning intake — [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)'s brief/PRD/UX spec, mined into scope
+Planning intake - BMAD-METHOD's brief/PRD/UX spec, mined into scope
 boundary + domain vocabulary (planner agent)
   ↓
 Bootstrap (once per project)
   ↓
-Phase A, per module — schema → contract → repository → service → controller
+Phase A, per module - schema → contract → repository → service → controller
   ↓
 Phase A closes for the module (gated: typecheck, lint, test)
   ↓
-Phase B, per module — hook → UX rationale → screen
+Phase B, per module - hook → UX rationale → screen
   ↓
 Repeat for the next module or the next step
 ```
@@ -78,13 +84,13 @@ npx @skyf0xx/hedgehog init
 ```
 
 Then open Claude Code and describe what you want to build. The
-`planner` agent runs planning intake first — BMAD-METHOD's brainstorming,
-brief, PRD, and UX spec — then mines that into what's in scope and which
+`planner` agent runs planning intake first - BMAD-METHOD's brainstorming,
+brief, PRD, and UX spec - then mines that into what's in scope and which
 add-ons (Auth, Queue, Mobile) you need; once you confirm, it scaffolds
 the project itself.
 
-The core workspace — Nx, `packages/config`, `packages/db`, `apps/api`,
-`apps/web`, and every enforcement file — lands instantly from a
+The core workspace - Nx, `packages/config`, `packages/db`, `apps/api`,
+`apps/web`, and every enforcement file - lands instantly from a
 pre-verified template rather than being generated live; bootstrap then
 only runs whichever add-ons planning intake determined your project needs.
 
@@ -106,7 +112,7 @@ Under the hood, it applies the practices experienced engineers rely on:
 - continuous verification
 - conventional commits
 
-AI becomes the builder operating inside those constraints — turning ideas into software without requiring you to manage every implementation detail.
+AI becomes the builder operating inside those constraints - turning ideas into software without requiring you to manage every implementation detail.
 
 ## Architecture
 
@@ -136,28 +142,25 @@ Hedgehog is a package of agents and skills, built on an opinionated stack so the
 
 ## How Hedgehog Compares
 
-Superpowers and BMAD both improve on raw prompting: one gives the AI good habits, the other gives it a planning process. In both, the order of work is a convention the AI can still break.
+Superpowers and BMAD both improve on raw prompting: one gives the AI good habits, the other a planning process. Alone, either can still be broken by convention.
 
-Hedgehog enforces its build order with tooling instead: Nx module boundaries, commit hooks, phase gates. The order holds because the tooling holds it, not because the AI followed the discipline.
+Hedgehog runs BMAD for planning, then enforces the build that follows with tooling, not convention: Nx boundaries, commit hooks, phase gates.
 
-| | Superpowers | BMAD | Hedgehog |
+| | Superpowers | BMAD | Hedgehog + BMAD |
 | --- | --- | --- | --- |
-| **What it is** | A skills library for Claude Code: brainstorm, plan, TDD, debug, review | A multi-agent planning framework: PM, Architect, Dev, QA personas | A build discipline: fixed stack, enforced module order |
-| **Order comes from** | Skill instructions the agent is told to follow | Sequenced documents (brief → PRD → architecture → stories) | Tooling (Nx boundaries, lefthook, phase gate) |
-| **Enforcement mechanism** | None. Prompted convention | None. One optional agent-run checklist between phases | Mechanically enforced by Nx boundaries, commit hooks, and the phase gate |
+| **What it is** | A skills library: brainstorm, plan, TDD, debug, review | A multi-agent planning framework: PM, Architect, Dev, QA personas | BMAD planning (brief → PRD → architecture) feeding a fixed-stack, enforced-order build |
+| **Order comes from** | Skill instructions the agent is told to follow | Sequenced documents (brief → PRD → architecture → stories) | Tooling (Nx, lefthook, phase gate) |
+| **Enforcement mechanism** | None. Prompted convention | None. One optional checklist between phases | Execution mechanically enforced |
 | **Unit of work** | A task, planned in worktree-isolated steps | A story, derived from PRD and architecture docs | A module layer (schema → contract → repo → service → controller → UI) |
 | **Stack** | Whatever the project already uses | No stack opinion | One locked stack (Nx, NestJS, Drizzle, ts-rest, Next.js) |
-| **Context per step** | As much as the task pulls in | A full brief, PRD, and architecture doc per story | One module layer at a time (e.g. just the repository, just the controller) |
+| **Context per step** | As much as the task pulls in | A full brief, PRD, and architecture doc per story | One module layer at a time - BMAD's docs are mined once, up front |
 | **Finding a bug** | Search wherever the task touched | Search wherever the story touched | Search one layer, in one module, in a fixed order |
-| **Real cost** | No safety net if the model shortcuts its own process | Documentation overhead most solo projects don't need | Less flexibility: the stack and order aren't negotiable |
+| **Real cost** | No safety net if the model shortcuts its own process | Documentation overhead most solo projects don't need | Stack and order aren't negotiable |
 
 ## Credits
 
 Planning intake runs on [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)
-(`bmad-code-org/BMAD-METHOD`), MIT-licensed — vendored in full at
-`skills/BMAD/` in every Hedgehog install. BMAD elicits the brief, PRD,
-and UX spec; Hedgehog's own `planner` agent takes over from there with
-the build discipline above.
+(`bmad-code-org/BMAD-METHOD`) MIT-licensed.
 
 ## Support Hedgehog
 

package/bin/cli.mjs

@@ -36,6 +36,10 @@ const DOTFILE_RENAMES = { 'gitignore.template': '.gitignore' };
 const PLAN = [
   { type: 'dir', from: 'src/agents', to: '.claude/agents' },
   { type: 'dir', from: 'src/skills', to: '.claude/skills' },
+  // The vendored BMAD-METHOD planning shelf that hedgehog-planning-intake
+  // runs — referenced by repo-root-relative path (skills/BMAD/...), so it
+  // lands there rather than under .claude/.
+  { type: 'dir', from: 'skills/BMAD', to: 'skills/BMAD' },
   { type: 'file', from: 'src/templates/CLAUDE.md', to: 'CLAUDE.md' },
   { type: 'file', from: 'src/templates/TODO.md', to: 'TODO.md' },
   // The pre-built, pre-verified core Nx workspace — packages/config,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {
@@ -21,7 +21,8 @@
     "src/agents",
     "src/skills",
     "src/templates",
-    "src/golden-core"
+    "src/golden-core",
+    "skills/BMAD"
   ],
   "engines": {
     "node": ">=18"

package/skills/BMAD/ATTRIBUTION.md

@@ -0,0 +1,52 @@
+# Attribution
+
+This directory vendors a subset of [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)
+(`bmad-code-org/BMAD-METHOD`), MIT-licensed. See `LICENSE` in this directory
+for the full license text.
+
+- **Source repo:** https://github.com/bmad-code-org/BMAD-METHOD
+- **Vendored from:** `main` branch, commit `bb45db4aa4496c69239f9c0629c290fd1b072fc9`
+- **Vendored on:** 2026-07-23
+- **Module:** `bmm` (BMAD Method Module)
+
+## What's vendored
+
+Seven skills from BMAD-METHOD's planning shelf, plus the two shared scripts
+they depend on:
+
+- `core-skills/bmad-brainstorming`
+- `core-skills/bmad-advanced-elicitation`
+- `core-skills/bmad-deep-recon`
+- `bmm-skills/1-analysis/bmad-product-brief`
+- `bmm-skills/1-analysis/bmad-prfaq`
+- `bmm-skills/2-plan-workflows/bmad-prd`
+- `bmm-skills/2-plan-workflows/bmad-ux`
+- `scripts/memlog.py`, `scripts/resolve_customization.py` (shared utilities
+  every vendored skill calls, originally at `src/scripts/` in the source
+  repo)
+
+Each skill directory carries its own templates, reference files, and
+scripts as vendored, unmodified except where noted below.
+
+## What's stripped
+
+BMAD-METHOD's own orchestration layer is not vendored and is removed from
+every skill file that referenced it:
+
+- Central config resolution (`_bmad/scripts/resolve_config.py`,
+  `_bmad/config.toml`, `_bmad/bmm/config.yaml`) — replaced with trivial
+  defaults inline in each skill.
+- `bmad-party-mode` (multi-agent roster) mentions and invocations.
+- Chain-forward "common next skill" suggestions and `bmad-help` routing.
+- Misroute-detection logic pointing at non-vendored BMAD skills.
+
+`{bmad-root}` is introduced as a convention across the vendored files,
+meaning this directory (`skills/BMAD/`) — used to address the shared
+scripts (`{bmad-root}/scripts/memlog.py`, etc.) without reaching outside
+this vendored tree.
+
+## Re-vendoring
+
+Pinned deliberately. Re-vendoring against a newer BMAD-METHOD commit is a
+manual act: repeat the fetch against the new ref, re-apply the strip step
+above, and update this file's pinned commit and date.

package/skills/BMAD/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2025 BMad Code, LLC
+
+This project incorporates contributions from the open source community.
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor attribution.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TRADEMARK NOTICE:
+BMad™, BMad Method™, and BMad Core™ are trademarks of BMad Code, LLC, covering all
+casings and variations (including BMAD, bmad, BMadMethod, BMAD-METHOD, etc.). The use of
+these trademarks in this software does not grant any rights to use the trademarks
+for any other purpose. See [TRADEMARK.md](TRADEMARK.md) for detailed guidelines.

package/skills/BMAD/bmm-skills/1-analysis/bmad-prfaq/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: bmad-prfaq
+description: Working Backwards PRFAQ challenge that stress-tests a product concept customer-first. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
+---
+
+# Working Backwards: The PRFAQ Challenge
+
+## Overview
+
+This skill forges product concepts through Amazon's Working Backwards methodology — the PRFAQ (Press Release / Frequently Asked Questions). Act as a relentless but constructive product coach who stress-tests every claim, challenges vague thinking, and refuses to let weak ideas pass unchallenged. The user walks in with an idea. They walk out with a battle-hardened concept — or the honest realization they need to go deeper. Both are wins.
+
+The PRFAQ forces customer-first clarity: write the press release announcing the finished product before building it. If you can't write a compelling press release, the product isn't ready. The customer FAQ validates the value proposition from the outside in. The internal FAQ addresses feasibility, risks, and hard trade-offs.
+
+**This is hardcore mode.** The coaching is direct, the questions are hard, and vague answers get challenged. But when users are stuck, offer concrete suggestions, reframings, and alternatives — tough love, not tough silence. The goal is to strengthen the concept, not to gatekeep it.
+
+**Args:** Accepts `--headless` / `-H` for autonomous first-draft generation from provided context.
+
+**Output:** A complete PRFAQ document + PRD distillate for downstream pipeline consumption.
+
+**Research-grounded.** All competitive, market, and feasibility claims in the output must be verified against current real-world data. Proactively research to fill knowledge gaps — the user deserves a PRFAQ informed by today's landscape, not yesterday's assumptions.
+
+## Conventions
+
+- Bare paths (e.g. `references/press-release.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+- `{bmad-root}` is the vendored `skills/BMAD/` root.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+**If the script fails**, read `{skill-root}/customize.toml` directly and use its defaults.
+
+### 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: Resolve Context
+
+Resolve, using sensible defaults:
+- `{user_name}` for greeting — ask the user or omit
+- `{communication_language}` for all communications — English
+- `{document_output_language}` for output documents — English
+- `{planning_artifacts}` for output location and artifact scanning
+- `{project_knowledge}` for additional context scanning
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`. Be warm but efficient — dream builder energy.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Pre-workflow Setup
+
+1. **Resume detection:** Check if `{planning_artifacts}/prfaq-{project_name}.md` already exists. If it does, read only the first 20 lines to extract the frontmatter `stage` field and offer to resume from the next stage. Do not read the full document. If the user confirms, route directly to that stage's reference file.
+
+2. **Mode detection:**
+- `--headless` / `-H`: Produce complete first-draft PRFAQ from provided inputs without interaction. Validate the input schema only (customer, problem, stakes, solution concept present and non-vague) — do not read any referenced files or documents yourself. If required fields are missing or too vague, return an error with specific guidance on what's needed. Fan out artifact analyzer and web researcher subagents in parallel (see Contextual Gathering below) to process all referenced materials, then create the output document at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md` and route to `./references/press-release.md`.
+- Default: Full interactive coaching — the gauntlet.
+
+**Headless input schema:**
+- **Required:** customer (specific persona), problem (concrete), stakes (why it matters), solution (concept)
+- **Optional:** competitive context, technical constraints, team/org context, target market, existing research
+
+**Set the tone immediately.** This isn't a warm, exploratory greeting. Frame it as a challenge — the user is about to stress-test their thinking by writing the press release for a finished product before building anything. Convey that surviving this process means the concept is ready, and failing here saves wasted effort. Be direct and energizing.
+
+Then briefly ground the user on what a PRFAQ actually is — Amazon's Working Backwards method where you write the finished-product press release first, then answer the hardest customer and stakeholder questions. The point is forcing clarity before committing resources.
+
+Then proceed to Stage 1 below.
+
+## Stage 1: Ignition
+
+**Goal:** Get the raw concept on the table and immediately establish customer-first thinking. This stage ends when you have enough clarity on the customer, their problem, and the proposed solution to draft a press release headline.
+
+**Customer-first enforcement:**
+
+- If the user leads with a solution ("I want to build X"): redirect to the customer's problem. Don't let them skip the pain.
+- If the user leads with a technology ("I want to use AI/blockchain/etc"): challenge harder. Technology is a "how", not a "why" — push them to articulate the human problem. Strip away the buzzword and ask whether anyone still cares.
+- If the user leads with a customer problem: dig deeper into specifics — how they cope today, what they've tried, why it hasn't been solved.
+
+When the user gets stuck, offer concrete suggestions based on what they've shared so far. Draft a hypothesis for them to react to rather than repeating the question harder.
+
+**Concept type detection:** Early in the conversation, identify whether this is a commercial product, internal tool, open-source project, or community/nonprofit initiative. Store this as `{concept_type}` — it calibrates FAQ question generation in Stages 3 and 4. Non-commercial concepts don't have "unit economics" or "first 100 customers" — adapt the framing to stakeholder value, adoption paths, and sustainability instead.
+
+**Essentials to capture before progressing:**
+- Who is the customer/user? (specific persona, not "everyone")
+- What is their problem? (concrete and felt, not abstract)
+- Why does this matter to them? (stakes and consequences)
+- What's the initial concept for a solution? (even rough)
+
+**Fast-track:** If the user provides all four essentials in their opening message (or via structured input), acknowledge and confirm understanding, then move directly to document creation and Stage 2 without extended discovery.
+
+**Graceful redirect:** If after 2-3 exchanges the user can't articulate a customer or problem, don't force it. Point them upstream: `bmad-brainstorming` if they need to generate options, or `bmad-forge-idea` if they hold an idea that hasn't been pressure-tested into something sound yet.
+
+**Contextual Gathering:** Once you understand the concept, gather external context before drafting begins.
+
+1. **Ask about inputs:** Ask the user whether they have existing documents, research, brainstorming, or other materials to inform the PRFAQ. Collect paths for subagent scanning — do not read user-provided files yourself; that's the Artifact Analyzer's job.
+2. **Fan out subagents in parallel:**
+   - **Artifact Analyzer** (`./agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents, plus any user-provided paths. Receives the product intent summary so it knows what's relevant.
+   - **Web Researcher** (`./agents/web-researcher.md`) — Searches for competitive landscape, market context, and current industry data relevant to the concept. Receives the product intent summary.
+3. **Graceful degradation:** If subagents are unavailable, scan the most relevant 1-2 documents inline and do targeted web searches directly. Never block the workflow.
+4. **Merge findings** with what the user shared. Surface anything surprising that enriches or challenges their assumptions before proceeding.
+
+**Create the output document** at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md`. Write the frontmatter (populate `inputs` with any source documents used) and any initial content captured during Ignition. This document is the working artifact — update it progressively through all stages.
+
+**Coaching Notes Capture:** Before moving on, append a `<!-- coaching-notes-stage-1 -->` block to the output document: concept type and rationale, initial assumptions challenged, why this direction over alternatives discussed, key subagent findings that shaped the concept framing, and any user context captured that doesn't fit the PRFAQ itself.
+
+**When you have enough to draft a press release headline**, route to `./references/press-release.md`.
+
+## Stages
+
+| # | Stage | Purpose | Location |
+|---|-------|---------|----------|
+| 1 | Ignition | Raw concept, enforce customer-first thinking | SKILL.md (above) |
+| 2 | The Press Release | Iterative drafting with hard coaching | `./references/press-release.md` |
+| 3 | Customer FAQ | Devil's advocate customer questions | `./references/customer-faq.md` |
+| 4 | Internal FAQ | Skeptical stakeholder questions | `./references/internal-faq.md` |
+| 5 | The Verdict | Synthesis, strength assessment, final output | `./references/verdict.md` |

package/skills/BMAD/bmm-skills/1-analysis/bmad-prfaq/agents/artifact-analyzer.md

@@ -0,0 +1,60 @@
+# Artifact Analyzer
+
+You are a research analyst. Your job is to scan project documents and extract information relevant to a product concept being stress-tested through the PRFAQ process.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of the concept — customer, problem, solution direction
+- **Scan paths:** Directories to search for relevant documents (e.g., planning artifacts, project knowledge folders)
+- **User-provided paths:** Any specific files the user pointed to
+
+## Process
+
+1. **Scan the provided directories** for documents that could be relevant:
+   - Brainstorming reports (`*brainstorm*`, `*ideation*`)
+   - Research documents (`*research*`, `*analysis*`, `*findings*`)
+   - Project context (`*context*`, `*overview*`, `*background*`)
+   - Existing briefs or summaries (`*brief*`, `*summary*`)
+   - Any markdown, text, or structured documents that look relevant
+
+2. **For sharded documents** (a folder with `index.md` and multiple files), read the index first to understand what's there, then read only the relevant parts.
+
+3. **For very large documents** (estimated >50 pages), read the table of contents, executive summary, and section headings first. Read only sections directly relevant to the stated product intent. Note which sections were skimmed vs read fully.
+
+4. **Read all relevant documents in parallel** — issue all Read calls in a single message rather than one at a time. Extract:
+   - Key insights that relate to the product intent
+   - Market or competitive information
+   - User research or persona information
+   - Technical context or constraints
+   - Ideas, both accepted and rejected (rejected ideas are valuable — they prevent re-proposing)
+   - Any metrics, data points, or evidence
+
+5. **Ignore documents that aren't relevant** to the stated product intent. Don't waste tokens on unrelated content.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,500 tokens. Maximum 5 bullets per section — prioritize the most impactful findings.
+
+```json
+{
+  "documents_found": [
+    {"path": "file path", "relevance": "one-line summary"}
+  ],
+  "key_insights": [
+    "bullet — grouped by theme, each self-contained"
+  ],
+  "user_market_context": [
+    "bullet — users, market, competition found in docs"
+  ],
+  "technical_context": [
+    "bullet — platforms, constraints, integrations"
+  ],
+  "ideas_and_decisions": [
+    {"idea": "description", "status": "accepted|rejected|open", "rationale": "brief why"}
+  ],
+  "raw_detail_worth_preserving": [
+    "bullet — specific details, data points, quotes for the distillate"
+  ]
+}
+```

package/skills/BMAD/bmm-skills/1-analysis/bmad-prfaq/agents/web-researcher.md

@@ -0,0 +1,49 @@
+# Web Researcher
+
+You are a market research analyst. Your job is to find current, relevant competitive, market, and industry context for a product concept being stress-tested through the PRFAQ process.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of the concept — customer, problem, solution direction, and the domain it operates in
+
+## Process
+
+1. **Identify search angles** based on the product intent:
+   - Direct competitors (products solving the same problem)
+   - Adjacent solutions (different approaches to the same pain point)
+   - Market size and trends for the domain
+   - Industry news or developments that create opportunity or risk
+   - User sentiment about existing solutions (what's frustrating people)
+
+2. **Execute 3-5 targeted web searches** — quality over quantity. Search for:
+   - "[problem domain] solutions comparison"
+   - "[competitor names] alternatives" (if competitors are known)
+   - "[industry] market trends [current year]"
+   - "[target user type] pain points [domain]"
+
+3. **Synthesize findings** — don't just list links. Extract the signal.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,000 tokens. Maximum 5 bullets per section.
+
+```json
+{
+  "competitive_landscape": [
+    {"name": "competitor", "approach": "one-line description", "gaps": "where they fall short"}
+  ],
+  "market_context": [
+    "bullet — market size, growth trends, relevant data points"
+  ],
+  "user_sentiment": [
+    "bullet — what users say about existing solutions"
+  ],
+  "timing_and_opportunity": [
+    "bullet — why now, enabling shifts"
+  ],
+  "risks_and_considerations": [
+    "bullet — market risks, competitive threats, regulatory concerns"
+  ]
+}
+```

package/skills/BMAD/bmm-skills/1-analysis/bmad-prfaq/assets/prfaq-template.md

@@ -0,0 +1,62 @@
+---
+title: "PRFAQ: {project_name}"
+status: "{status}"
+created: "{timestamp}"
+updated: "{timestamp}"
+stage: "{current_stage}"
+inputs: []
+---
+
+# {Headline}
+
+## {Subheadline — one sentence: who benefits and what changes for them}
+
+**{City, Date}** — {Opening paragraph: announce the product/initiative, state the user's problem, and the key benefit.}
+
+{Problem paragraph: the user's pain today. Specific, concrete, felt. No mention of the solution yet.}
+
+{Solution paragraph: what changes for the user. Benefits, not features. Outcomes, not implementation.}
+
+> "{Leader/founder quote — the vision beyond the feature list.}"
+> — {Name, Title/Role}
+
+### How It Works
+
+{The user experience, step by step. Written from THEIR perspective. How they discover it, start using it, and get value from it.}
+
+> "{User quote — what a real person would say after using this. Must sound human, not like marketing copy.}"
+> — {Name, Role}
+
+### Getting Started
+
+{Clear, concrete path to first value. How to access, try, adopt, or contribute.}
+
+---
+
+## Customer FAQ
+
+### Q: {Hardest customer question first}
+
+A: {Honest, specific answer}
+
+### Q: {Next question}
+
+A: {Answer}
+
+---
+
+## Internal FAQ
+
+### Q: {Hardest internal question first}
+
+A: {Honest, specific answer}
+
+### Q: {Next question}
+
+A: {Answer}
+
+---
+
+## The Verdict
+
+{Concept strength assessment — what's forged in steel, what needs more heat, what has cracks in the foundation.}

package/skills/BMAD/bmm-skills/1-analysis/bmad-prfaq/bmad-manifest.json

@@ -0,0 +1,16 @@
+{
+  "module-code": "bmm",
+  "capabilities": [
+    {
+      "name": "working-backwards",
+      "menu-code": "WB",
+      "description": "Produces battle-tested PRFAQ document and optional LLM distillate for PRD input.",
+      "supports-headless": true,
+      "phase-name": "1-analysis",
+      "preceded-by": ["brainstorming", "perform-research"],
+      "followed-by": ["create-prd"],
+      "is-required": false,
+      "output-location": "{planning_artifacts}"
+    }
+  ]
+}

package/skills/BMAD/bmm-skills/1-analysis/bmad-prfaq/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-prfaq. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All briefs must include a regulatory-risk section."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches its terminal stage (Stage 5: The Verdict),
+# after the PRFAQ and distillate have been delivered. Override wins. Leave empty for
+# no custom post-completion behavior.
+
+on_complete = ""

package/skills/BMAD/bmm-skills/1-analysis/bmad-prfaq/references/customer-faq.md

@@ -0,0 +1,55 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence.
+**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit).
+
+# Stage 3: Customer FAQ
+
+**Goal:** Validate the value proposition by asking the hardest questions a real user would ask — and crafting answers that hold up under scrutiny.
+
+## The Devil's Advocate
+
+You are now the customer. Not a friendly early-adopter — a busy, skeptical person who has been burned by promises before. You've read the press release. Now you have questions.
+
+**Generate 6-10 customer FAQ questions** that cover these angles:
+
+- **Skepticism:** "How is this different from [existing solution]?" / "Why should I switch from what I use today?"
+- **Trust:** "What happens to my data?" / "What if this shuts down?" / "Who's behind this?"
+- **Practical concerns:** "How much does it cost?" / "How long does it take to get started?" / "Does it work with [thing I already use]?"
+- **Edge cases:** "What if I need to [uncommon but real scenario]?" / "Does it work for [adjacent use case]?"
+- **The hard question they're afraid of:** Every product has one question the team hopes nobody asks. Find it and ask it.
+
+**Don't generate softball questions.** "How do I sign up?" is not a FAQ — it's a CTA. Real customer FAQs are the objections standing between interest and adoption.
+
+**Calibrate to concept type.** For non-commercial concepts (internal tools, open-source, community projects), adapt question framing: replace "cost" with "effort to adopt," replace "competitor switching" with "why change from current workflow," replace "trust/company viability" with "maintenance and sustainability."
+
+## Coaching the Answers
+
+Present the questions and work through answers with the user:
+
+1. **Present all questions at once** — let the user see the full landscape of customer concern.
+2. **Work through answers together.** The user drafts (or you draft and they react). For each answer:
+   - Is it honest? If the answer is "we don't do that yet," say so — and explain the roadmap or alternative.
+   - Is it specific? "We have enterprise-grade security" is not an answer. What certifications? What encryption? What SLA?
+   - Would a customer believe it? Marketing language in FAQ answers destroys credibility.
+3. **If an answer reveals a real gap in the concept**, name it directly and force a decision: is this a launch blocker, a fast-follow, or an accepted trade-off?
+4. **The user can add their own questions too.** Often they know the scary questions better than anyone.
+
+## Headless Mode
+
+Generate questions and best-effort answers from available context. Flag answers with low confidence so a human can review.
+
+## Updating the Document
+
+Append the Customer FAQ section to the output document. Update frontmatter: `status: "customer-faq"`, `stage: 3`, `updated` timestamp.
+
+## Coaching Notes Capture
+
+Before moving on, append a `<!-- coaching-notes-stage-3 -->` block to the output document: gaps revealed by customer questions, trade-off decisions made (launch blocker vs fast-follow vs accepted), competitive intelligence surfaced, and any scope or requirements signals.
+
+## Stage Complete
+
+This stage is complete when every question has an honest, specific answer — and the user has confronted the hardest customer objections their concept faces. No softballs survived.
+
+Route to `./internal-faq.md`.