@quybt93/pcgf 0.0.1

package/.agents/skills/bmad-party-mode/scripts/resolve_party.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve the party-mode roster, lazily.
+
+Merges the installed BMAD agents with the user's custom `party_members`
+into one collective, then projects only what the moment needs:
+
+  * default (no flag) — the active roster to load on entry: the
+    `default_party` group if one is configured, else the whole collective.
+    Other groups come back as names only, so nothing you aren't using is
+    loaded into the party.
+  * --list-groups — just id + name + size for every configured group. The
+    cheap menu for "which room?", with no member detail.
+  * --party <id> — full member detail for one chosen group, on demand
+    (e.g. when the user switches rooms). Unknown id returns the available
+    names instead of an error wall.
+
+The merge is deterministic (a keyed union; a custom member whose code
+matches an installed agent overrides it), so the orchestrator consumes a
+resolved roster instead of re-deriving it every session.
+
+Stdlib only (Python 3.11+ for tomllib). Shells out to the project's
+resolve_config.py and resolve_customization.py; falls back to reading
+customize.toml directly if the customization resolver is unavailable.
+
+  resolve_party.py --project-root P --skill S
+  resolve_party.py --project-root P --skill S --list-groups
+  resolve_party.py --project-root P --skill S --party writers-room
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:  # pragma: no cover - guarded for <3.11
+    sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib`).\n")
+    sys.exit(3)
+
+
+def _run_json(cmd):
+    """Run a resolver script and parse its JSON stdout. None on any failure."""
+    try:
+        out = subprocess.run(
+            cmd, capture_output=True, text=True, encoding="utf-8", timeout=60
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0 or not out.stdout.strip():
+        return None
+    try:
+        return json.loads(out.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def load_agents(project_root: Path):
+    """Installed agents as {code: entry}. Empty dict (with a flag) on failure."""
+    script = project_root / "_bmad" / "scripts" / "resolve_config.py"
+    data = _run_json([sys.executable, str(script), "--project-root", str(project_root), "--key", "agents"])
+    if data is None:
+        return {}, False
+    return data.get("agents", {}) or {}, True
+
+
+def load_workflow(project_root: Path, skill_root: Path):
+    """Merged [workflow] table. Falls back to the skill's base customize.toml."""
+    script = project_root / "_bmad" / "scripts" / "resolve_customization.py"
+    data = _run_json(
+        [sys.executable, str(script), "--skill", str(skill_root), "--project-root", str(project_root), "--key", "workflow"]
+    )
+    if data is not None and "workflow" in data:
+        return data["workflow"]
+    # Fallback: read the skill's base customize.toml directly (no override merge).
+    toml_path = skill_root / "customize.toml"
+    if toml_path.exists():
+        try:
+            with toml_path.open("rb") as f:
+                return tomllib.load(f).get("workflow", {})
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+    return {}
+
+
+def _alias(code: str) -> str:
+    """Short alias for an installed agent code: bmad-agent-analyst -> analyst."""
+    for prefix in ("bmad-agent-", "bmad-"):
+        if code.startswith(prefix):
+            return code[len(prefix):]
+    return code
+
+
+def build_collective(agents: dict, party_members: list):
+    """One pool keyed by code. Custom members override matching installed agents.
+
+    Returns (collective, index, installed_codes):
+      * collective — every member (installed + custom), the pool groups draw
+        from and the orchestrator can summon by name.
+      * index — maps every resolvable token (code, prefix-stripped alias,
+        lower-cased name) to a canonical code.
+      * installed_codes — the codes occupying an installed-agent slot, in
+        order. This is the DEFAULT room: installed agents (with any custom
+        override applied in place), and NOT the pure-custom additions. So
+        shipping or defining custom members grows the pool without crowding
+        the default party.
+    """
+    collective = {}
+    index = {}
+    installed_codes = []
+
+    def register(code, entry):
+        collective[code] = entry
+        index[code] = code
+        index[code.lower()] = code
+        index[_alias(code).lower()] = code
+        name = entry.get("name")
+        if name:
+            index[name.lower()] = code
+
+    for code, info in agents.items():
+        register(code, {
+            "code": code,
+            "name": info.get("name", code),
+            "icon": info.get("icon", ""),
+            "title": info.get("title", ""),
+            "description": info.get("description", ""),
+            "module": info.get("module", ""),
+            "team": info.get("team", ""),
+            "source": "installed",
+        })
+        installed_codes.append(code)
+
+    for m in (party_members if isinstance(party_members, list) else []):
+        if not isinstance(m, dict):
+            continue
+        code = m.get("code")
+        if not code:
+            continue
+        # A custom member overrides an installed agent it matches by code/alias/name.
+        canonical = index.get(code) or index.get(code.lower()) or code
+        # Start from the installed entry so fields the override omits
+        # (icon, title, description, module, team) survive.
+        entry = dict(collective.get(canonical, {}))
+        entry.update({"code": canonical, "source": "custom"})
+        for field in ("name", "icon", "title", "persona", "capabilities", "model"):
+            if m.get(field) is not None:
+                entry[field] = m[field]
+        entry.setdefault("name", canonical)
+        register(canonical, entry)
+        # An override keeps the installed slot; a brand-new custom does not join it.
+
+    return collective, index, installed_codes
+
+
+def resolve_members(member_tokens, collective, index):
+    """(resolved entries in listed order, unresolved tokens)."""
+    resolved, unresolved = [], []
+    for token in member_tokens or []:
+        if not isinstance(token, str):
+            unresolved.append(token)  # malformed config value — never a key lookup
+            continue
+        code = index.get(token) or index.get(token.lower())
+        if code and code in collective:
+            resolved.append(collective[code])
+        else:
+            unresolved.append(token)
+    return resolved, unresolved
+
+
+def group_menu(groups):
+    """Names only — the cheap menu. Open-cast groups (no roster) are flagged."""
+    out = []
+    for g in groups or []:
+        if not isinstance(g, dict) or not g.get("id"):
+            continue
+        members = g.get("members", []) or []
+        entry = {"id": g["id"], "name": g.get("name", g["id"]),
+                 "member_count": len(members)}
+        if not members:
+            entry["open_cast"] = True
+        out.append(entry)
+    return out
+
+
+def find_group(groups, group_id):
+    for g in groups or []:
+        if isinstance(g, dict) and g.get("id") == group_id:
+            return g
+    return None
+
+
+def group_detail(g, collective, index):
+    """Full detail for one group: resolved members + the optional scene.
+
+    `scene` is a freeform line the orchestrator plays — setting, what's
+    happening, room dynamics, in-the-moment character notes. Surfaced only
+    here (when a group is the active/chosen roster), never in the menu.
+
+    `members` is optional. With none, the group is open-cast: `open_cast`
+    is flagged and the scene describes the pool the orchestrator casts from
+    on the fly (e.g. "figures from the Star Wars Rebels universe"). A few
+    listed members anchor the room; the scene can still invite more.
+    """
+    raw_members = g.get("members", []) or []
+    members, unresolved = resolve_members(raw_members, collective, index)
+    detail = {"active": g["id"], "name": g.get("name", g["id"]),
+              "members": members, "unresolved": unresolved,
+              "memory_enabled": bool(g.get("memory", False))}
+    if g.get("scene"):
+        detail["scene"] = g["scene"]
+    if not raw_members:
+        detail["open_cast"] = True
+    return detail
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Resolve the party-mode roster, lazily.")
+    ap.add_argument("--project-root", required=True)
+    ap.add_argument("--skill", required=True, help="Path to the bmad-party-mode skill dir")
+    ap.add_argument("--party", help="Resolve full detail for this group id")
+    ap.add_argument("--list-groups", action="store_true", help="Group names only")
+    args = ap.parse_args()
+
+    project_root = Path(args.project_root).resolve()
+    skill_root = Path(args.skill).resolve()
+
+    workflow = load_workflow(project_root, skill_root)
+    groups = workflow.get("party_groups", []) or []
+    default_party = workflow.get("default_party", "") or ""
+    party_mode = workflow.get("party_mode", "session") or "session"
+    # The global party_memory flag governs only the DEFAULT installed-agent room;
+    # a named group carries its own `memory` flag (resolved in group_detail).
+    party_memory = bool(workflow.get("party_memory", True))
+
+    # Group menu never needs the (more expensive) installed-agent resolve.
+    if args.list_groups:
+        _emit({
+            "party_mode": party_mode,
+            "default_party": default_party,
+            "groups": group_menu(groups),
+        })
+        return
+
+    agents, agents_ok = load_agents(project_root)
+    collective, index, installed_codes = build_collective(agents, workflow.get("party_members", []))
+
+    if args.party:
+        g = find_group(groups, args.party)
+        if g is None:
+            _emit({"error": "unknown_group", "requested": args.party,
+                   "available": group_menu(groups)})
+            return
+        _emit({**group_detail(g, collective, index), "party_mode": party_mode})
+        return
+
+    # Default: the active roster to load on entry.
+    result = {"party_mode": party_mode, "groups": group_menu(groups),
+              "installed_agents_resolved": agents_ok}
+    g = find_group(groups, default_party) if default_party else None
+    if g is not None:
+        result.update(group_detail(g, collective, index))
+    else:
+        # No default group: the installed agents (custom additions stay in the
+        # pool but don't crowd the default room), exactly like a plain install.
+        result.update({"active": "installed",
+                       "members": [collective[c] for c in installed_codes],
+                       "memory_enabled": party_memory})
+    _emit(result)
+
+
+def _emit(obj):
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8")
+    sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/bmad-party-mode/scripts/tests/test_resolve_party.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Unit tests for resolve_party.py — merge, alias, override, group resolution."""
+
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+import resolve_party as rp  # noqa: E402
+
+AGENTS = {
+    "bmad-agent-analyst": {"name": "Mary", "icon": "📊", "title": "Analyst"},
+    "bmad-agent-pm": {"name": "John", "icon": "📋", "title": "PM"},
+}
+
+
+class TestAlias(unittest.TestCase):
+    def test_strips_known_prefixes(self):
+        self.assertEqual(rp._alias("bmad-agent-analyst"), "analyst")
+        self.assertEqual(rp._alias("bmad-foo"), "foo")
+
+    def test_passes_through_unprefixed(self):
+        self.assertEqual(rp._alias("morpheus"), "morpheus")
+
+
+class TestBuildCollective(unittest.TestCase):
+    def test_installed_agents_indexed_by_code_alias_and_name(self):
+        col, idx, _ = rp.build_collective(AGENTS, [])
+        self.assertEqual(set(col), {"bmad-agent-analyst", "bmad-agent-pm"})
+        self.assertEqual(idx["analyst"], "bmad-agent-analyst")      # alias
+        self.assertEqual(idx["mary"], "bmad-agent-analyst")         # name (ci)
+        self.assertEqual(idx["bmad-agent-pm"], "bmad-agent-pm")     # full code
+        self.assertEqual(col["bmad-agent-analyst"]["source"], "installed")
+
+    def test_custom_member_appends(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus", "persona": "riddles"}])
+        self.assertIn("morpheus", col)
+        self.assertEqual(col["morpheus"]["source"], "custom")
+        self.assertEqual(col["morpheus"]["persona"], "riddles")
+
+    def test_custom_overrides_installed_by_alias(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"code": "analyst", "name": "Mary-Custom", "persona": "p"}])
+        # Override lands on the canonical installed code, not a new "analyst" entry.
+        self.assertNotIn("analyst", col)
+        self.assertEqual(col["bmad-agent-analyst"]["source"], "custom")
+        self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
+
+    def test_member_without_code_skipped(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"name": "Nameless"}])
+        self.assertEqual(set(col), {"bmad-agent-analyst", "bmad-agent-pm"})
+
+
+class TestResolveMembers(unittest.TestCase):
+    def setUp(self):
+        self.col, self.idx, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus"}])
+
+    def test_resolves_in_listed_order_and_flags_unknowns(self):
+        resolved, unresolved = rp.resolve_members(["morpheus", "analyst", "ghost"], self.col, self.idx)
+        self.assertEqual([m["code"] for m in resolved], ["morpheus", "bmad-agent-analyst"])
+        self.assertEqual(unresolved, ["ghost"])
+
+    def test_empty(self):
+        self.assertEqual(rp.resolve_members([], self.col, self.idx), ([], []))
+
+
+class TestGroups(unittest.TestCase):
+    GROUPS = [
+        {"id": "wr", "name": "Writers", "members": ["analyst", "morpheus"]},
+        {"id": "bad"},  # no name -> falls back to id; no members -> count 0
+        {"name": "no-id"},  # dropped from menu
+    ]
+
+    def test_menu_is_names_only_with_counts_and_open_cast_flag(self):
+        menu = rp.group_menu(self.GROUPS)
+        self.assertEqual(menu, [
+            {"id": "wr", "name": "Writers", "member_count": 2},
+            {"id": "bad", "name": "bad", "member_count": 0, "open_cast": True},
+        ])
+
+    def test_find_group(self):
+        self.assertEqual(rp.find_group(self.GROUPS, "wr")["name"], "Writers")
+        self.assertIsNone(rp.find_group(self.GROUPS, "missing"))
+
+
+class TestGroupDetail(unittest.TestCase):
+    def setUp(self):
+        self.col, self.idx, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus"}])
+
+    def test_scene_passes_through_when_present(self):
+        g = {"id": "tos-10-forward", "name": "Ten Forward", "members": ["morpheus"],
+             "scene": "Late evening, a few rounds in."}
+        d = rp.group_detail(g, self.col, self.idx)
+        self.assertEqual(d["scene"], "Late evening, a few rounds in.")
+        self.assertEqual([m["code"] for m in d["members"]], ["morpheus"])
+
+    def test_scene_omitted_when_absent_or_empty(self):
+        for g in ({"id": "g", "members": ["morpheus"]},
+                  {"id": "g", "members": ["morpheus"], "scene": ""}):
+            self.assertNotIn("scene", rp.group_detail(g, self.col, self.idx))
+
+    def test_anchored_group_is_not_open_cast(self):
+        g = {"id": "g", "members": ["morpheus"]}
+        self.assertNotIn("open_cast", rp.group_detail(g, self.col, self.idx))
+
+    def test_open_cast_group_flagged_with_empty_members(self):
+        g = {"id": "rebels", "name": "Star Wars Rebels",
+             "scene": "Figures from the Rebels universe drop in as the topic calls for them."}
+        d = rp.group_detail(g, self.col, self.idx)
+        self.assertTrue(d["open_cast"])
+        self.assertEqual(d["members"], [])
+        self.assertEqual(d["scene"][:7], "Figures")
+
+    def test_memory_enabled_follows_group_flag_and_defaults_off(self):
+        on = rp.group_detail({"id": "g", "members": ["morpheus"], "memory": True}, self.col, self.idx)
+        self.assertTrue(on["memory_enabled"])
+        off = rp.group_detail({"id": "g", "members": ["morpheus"], "memory": False}, self.col, self.idx)
+        self.assertFalse(off["memory_enabled"])
+        absent = rp.group_detail({"id": "g", "members": ["morpheus"]}, self.col, self.idx)
+        self.assertFalse(absent["memory_enabled"])  # opt-in per named group
+
+
+class TestInstalledCodesIsDefaultRoom(unittest.TestCase):
+    """The default room is installed agents only; pure customs stay in the pool."""
+
+    def test_pure_custom_excluded_override_kept_in_default_room(self):
+        col, _, installed = rp.build_collective(AGENTS, [
+            {"code": "morpheus", "name": "Morpheus"},                 # pure custom
+            {"code": "analyst", "name": "Mary-Custom", "persona": "p"},  # override
+            {"code": "sec-hawk", "name": "Vex"},                      # shipped crew member
+        ])
+        # Pure customs are in the pool...
+        self.assertIn("morpheus", col)
+        self.assertIn("sec-hawk", col)
+        # ...but NOT in the default room.
+        self.assertEqual(installed, ["bmad-agent-analyst", "bmad-agent-pm"])
+        default_room = [col[c]["code"] for c in installed]
+        self.assertEqual(default_room, ["bmad-agent-analyst", "bmad-agent-pm"])
+        # An override keeps its installed slot (and its custom content).
+        self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
+
+
+class TestResolverInvocation(unittest.TestCase):
+    """The wrapper knows the project root, so it must not let the resolver
+    infer one from the working directory (#2796)."""
+
+    def _captured_command(self, tmp):
+        captured = []
+        original = rp._run_json
+        rp._run_json = lambda cmd: captured.append(cmd) or {"workflow": {}}
+        try:
+            rp.load_workflow(Path(tmp) / "project", Path(tmp) / "skill")
+        finally:
+            rp._run_json = original
+        return captured[0]
+
+    def test_passes_project_root_to_the_customization_resolver(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cmd = self._captured_command(tmp)
+            self.assertIn("--project-root", cmd)
+            self.assertEqual(cmd[cmd.index("--project-root") + 1], str(Path(tmp) / "project"))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/.agents/skills/bmad-prd/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: bmad-prd
+description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD
+---
+# BMad PRD
+
+You are a master facilitator and coach helping the user create, edit, or validate a high quality PRD scoped to the level and rigor appropriate to their stated needs. Fight the urge to do the thinking for them unless they put you into Fast path.
+
+## Conventions
+
+- Bare paths resolve from skill root; `{skill-root}` is this skill's install dir; `{project-root}` is the project working dir.
+- `{workflow.<name>}` resolves to fields in `customize.toml`'s `[workflow]` table (overrides win per BMad merge rules).
+- `{doc_workspace}` is the bound run folder.
+- **File roles.** `.memlog.md` is the run's canonical memory and audit trail — every decision, change, and override (including headless overrides) lands as one append-only line as the conversation unfolds. All writes go through the shared script, never by hand: `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type <decision|change|override|assumption|event> --text "<one-line gist, reason included>"` (atomic; read it back only to resume or audit). The PRD is distilled toward it; whatever isn't logged is lost on resume. `addendum.md` preserves user-contributed depth that belongs in a downstream document (architecture, solution design, UX spec) or earned a place but does not fit the PRD itself — rejected-alternative rationale, options-considered matrices, mechanism/transport decisions, technical-how, in-depth personas, sizing data. Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum.
+
+## On Activation
+
+**Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields (e.g. the `bmad-create-prd` / `bmad-edit-prd` / `bmad-validate-prd` shims), honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
+
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. Research itself fires during Discovery — see **Research subagents**.
+3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.
+4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-build`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`; agent skill or custom agent → `bmad-workflow-builder`), suggest they might want the other options before continuing.
+5. Detect intent: **Create** (no PRD), **Update** (existing PRD), **Validate** (critique only). If ambiguous, ask. For Create intent, before binding a fresh workspace, scan `{workflow.prd_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `prd.md` frontmatter `status` is not `final`); if any exist, offer to resume rather than starting over.
+
+Run `{workflow.activation_steps_append}`.
+
+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.
+
+## Intent Modes
+
+**Create.** Bind `{doc_workspace}` to `{workflow.prd_output_path}/{workflow.run_folder_pattern}/`. Write `prd.md` with YAML frontmatter (title, status, created, updated — initial `status: draft`), and seed the memlog with `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic="<PRD/product name>"` so subsequent decisions land in a known file. Tell the user the path. Run `## Discovery`, then `## Finalize`.
+
+**Update.** Reconcile the PRD with a change signal. Source-extract against PRD, addendum, `.memlog.md`, and original inputs (extract, don't ingest). If `.memlog.md` is missing, init it with `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace}`, then spawn a one-time bootstrap subagent to reverse-engineer a thin log from the PRD (one `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type decision --text "<recovered decision>"` per recovered decision) before continuing. Surface conflicts with prior decisions before applying. Then `## Finalize`.
+
+**Validate** (or *analyze*). Critique without changing. Load `references/validate.md`.
+
+## Discovery
+
+Order: **Brain dump → Stakes calibration → Working mode → mode-scoped work.** Get to working mode fast — two or three turns, not ten. Users in a hurry must not be held hostage by upstream probing.
+
+**Brain dump.** Always the first move, even when the user opens with paragraphs of context (that is intake, not the dump). Ask for verbal context *and* any existing inputs they want you to read — product brief, research, customer transcripts, competitive analysis, prior PRD draft, design docs. Paths or paste; big docs are fine, you will subagent-extract. A simple "anything else?" surfaces what they almost forgot.
+
+**Research subagents (default).** During Discovery, spawn web-research subagents to ground the picture: what exists in the space, how comparables position themselves, current landscape. Subagent does the search; parent receives a digest.
+
+**Elicitation, not direction.** Discovery pulls the user's vision out; it does not insert yours. Open-ended "tell me about X" beats multiple choice. When you find yourself naming wedges, picking MVP cuts, or proposing phases, stop — you have crossed from elicitation into authoring. Hand the pen back. Infer-and-confirm ("I'm assuming X works like Y — right?") is fine; quizzing the user through a tree of LLM-shaped choices is not.
+
+**Stakes calibration.** One short probe before working mode: hobby / internal / launch — enough to calibrate rigor and section depth. Audience, Existing inputs, and Downstream depth fill in inside the chosen mode, not upstream of the choice.
+
+**Working mode.** Offer the choice in the user's language:
+
+- **Fast path** — I batch remaining gaps into one or two consolidated questions, then draft the full PRD with `[ASSUMPTION]` tags where I inferred. You review and we iterate. The initial quality depends on how much you gave me upfront.
+- **Coaching path** — we walk PM-thinking sections together. Once chosen, I ask which entry point fits: **Vision + Features** (capability-first — for enterprise, dev products, internal tools, anyone who thinks in features), **Journey-led** (user-first — for consumer, UX-heavy, multi-stakeholder products; journeys with named protagonists carry persona context inline, no standalone persona section), or *let me suggest* based on what I heard. The chosen entry sets the section order.
+
+The workspace persists; stop and resume freely.
+
+**Concern scan.** As you read what the user gave you, name the concerns this product actually carries — compliance, integration density, operational SLAs, hardware constraints, public-API contracts, monetization, data governance, whatever applies. The list is open; recognize what's there, do not classify into a fixed shape. These concerns drive which template sections to pull in from the Adapt-In Menu and which to invent when no cluster names them.
+
+**Form-factor.** If not stated in sources, probe — mobile / web / desktop / multi-surface / hardware / API.
+
+**User Journeys are captured, not authored.** When UJs are warranted (consumer / multi-stakeholder B2B / meaningful UX — drop or downscale for internal tooling with a single operator role, regulatory-only updates, hobby/solo, pure technical PRDs), prompt the user to narrate a real session with a named protagonist (Mary, mom of three — not "the user") — what the person does, in what order, where it lands — then structure the answer into UJ-N form and confirm. Persona context lives inline at the moments that matter; no standalone persona section.
+
+## PRD Discipline
+
+**Shape.** Features grouped; FRs nested with globally numbered stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices. Capabilities, not implementation — tech choices live in `addendum.md`. Treat `{workflow.prd_template}` as expert prior knowledge, not a checklist. The **Essential Spine** is the expected default — present it unless the product genuinely doesn't need a section, and when you drop one, do so for a reason a reviewer would agree with. The **Adapt-In Menu** is conditional: pull in the clusters the product's concerns need to best define the requirements. When the product carries a concern the menu doesn't name, invent the section — name it well, decide what belongs in it, place it where it serves the reader or the PRD. Reorder and combine for readability. Never include a section because it appears; never skip a concern because no template section covered it. Counter-metrics named when Success Metrics exist.
+
+**Extract, don't ingest.** Source documents go to subagents for extraction; the parent assembles from extracts. Only load source documents into the parent context wholesale when no subagents are available.
+
+**Length scales with stakes.** Hobby / solo PRDs aim for about two pages. Internal tools land around five to eight. Launch and chain-top PRDs run as long as their FRs and concerns require. Whatever the length, detail that doesn't earn its place in the PRD's main narrative belongs in `addendum.md` — moving overflow there is correct; padding the PRD to look thorough is not.
+
+## Reviewer Gate
+
+Used by the Validate intent and at Finalize step 3.
+
+Assemble the menu: rubric walker against `{workflow.validation_checklist_template}` (the PRD quality rubric) + each entry in `{workflow.finalize_reviewers}` + any ad-hoc reviewers the artifact warrants. Stakes-calibrated — hobby/solo may run quietly or skip; higher stakes get the explicit all/subset/skip menu.
+
+Dispatch entries as parallel subagents against `prd.md` (and `addendum.md` if present) using the standard prefix convention (`skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings, file path) — the parent never holds full review text. The rubric walker uses the prompt and output format in `references/validate.md`. If subagents are unavailable, run sequentially: write the file *before* anything else, then flush the review from working context.
+
+Surface findings tiered, never dumped. Lead with a one-sentence gate verdict, then walk critical + high findings; medium/low roll into a single tail ("plus N more in {file}"). Read the full `review-{slug}.md` only when the user drills into a specific finding. Per finding: autofix, discuss, defer to open items, or ignore.
+
+Under Validate intent, the parent additionally runs the synthesis pipeline in `references/validate.md` — folding every selected reviewer's output into a single HTML + markdown report and opening the HTML.
+
+## Finalize
+
+Tell the user the sequence in one sentence, then walk it. Polish goes last so it does not redo work after reviewer fixes.
+
+1. **Memlog audit.** Walk `.memlog.md` with the user; each entry captured in PRD, in addendum, or set aside.
+2. **Input reconciliation.** Subagent per user-supplied input against `prd.md` + `addendum.md`. Each writes its extract to `{doc_workspace}/reconcile-{slug}.md` and returns ONLY a compact summary (input name, gaps 2-5, file path). Surface gaps — especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish.
+3. **Reviewer pass.** Run `## Reviewer Gate`. Resolve before polish.
+4. **Triage open items.** All Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts. Phase-blockers (would make the PRD unsafe for UX/architecture/epics) surfaced one at a time and resolved; non-blockers deferred with owner + revisit condition logged via `memlog.py append`. If phase-blocker count is high, flag it.
+5. **Polish.** Apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` in declared order (structural passes before prose — prose should not polish soon-to-be-cut text). Parallelize across documents, sequential within.
+6. **External handoffs.** Execute `{workflow.external_handoffs}`; surface returned URLs/IDs. Skip and flag unavailable tools.
+7. **Close.** Set `prd.md` frontmatter `status: final` and `updated` to `{date}` so future invocations distinguish this PRD from in-progress drafts. Record finalization via `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type event --text "PRD finalized"`. Share artifact paths. Common next: `bmad-ux`, `bmad-architecture`, `bmad-create-epics-and-stories`; invoke `bmad-help` for authoritative routing.
+8. Run `{workflow.on_complete}` if non-empty.

package/.agents/skills/bmad-prd/assets/headless-schemas.md

@@ -0,0 +1,76 @@
+# Headless Mode JSON Schemas
+
+Every headless run ends with one of these payloads. Omit keys for artifacts not produced.
+
+## Common fields
+
+- `status` — `"complete"`, `"blocked"`, or `"partial"`
+- `intent` — `"create"`, `"update"`, or `"validate"` (matches the detected intent)
+- `reason` — required when `status` is `"blocked"`; one-sentence explanation
+- `assumptions` — array of inferred values that were not directly confirmed by inputs
+- `open_questions` — array of items that need a human decision before the artifact can be considered final
+
+## Create
+
+```json
+{
+  "status": "complete",
+  "intent": "create",
+  "prd": "{doc_workspace}/prd.md",
+  "addendum": "{doc_workspace}/addendum.md",
+  "memlog": "{doc_workspace}/.memlog.md",
+  "open_questions": [],
+  "assumptions": [],
+  "external_handoffs": [
+    {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"}
+  ]
+}
+```
+
+## Update
+
+```json
+{
+  "status": "complete",
+  "intent": "update",
+  "prd": "{doc_workspace}/prd.md",
+  "memlog": "{doc_workspace}/.memlog.md",
+  "changes_summary": "1-3 sentences describing what changed and why",
+  "conflicts_with_prior_decisions": [],
+  "open_questions": [],
+  "external_handoffs": [
+    {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"}
+  ]
+}
+```
+
+## Validate
+
+```json
+{
+  "status": "complete",
+  "intent": "validate",
+  "validation_report": "{doc_workspace}/validation-report.md",
+  "findings_summary": {
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0
+  },
+  "offer_to_update": true
+}
+```
+
+`validation_report` is always written for Validate intent — the path here is required, not optional.
+
+## Blocked
+
+```json
+{
+  "status": "blocked",
+  "intent": "update",
+  "reason": "Change signal ambiguous — could be a scope expansion or a clarification; no inferred direction"
+}
+```
+
+Always include the intent (best-guess if not certain) and a one-sentence `reason`.