bmad-method-quarkus 1.0.0

package/src/core-skills/bmad-customize/scripts/tests/test_list_customizable_skills.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Unit tests for list_customizable_skills.py.
+
+Exercises the scanner against a synthesized install tree:
+- an agent-only customize.toml
+- a workflow-only customize.toml
+- a customize.toml that exposes both surfaces
+- a skill directory with no customize.toml (ignored)
+- a pre-existing team override in _bmad/custom/
+- malformed TOML (surfaces as an error without aborting)
+- multiple skills roots (e.g. project-local + user-global mix)
+
+Run: uv run scripts/tests/test_list_customizable_skills.py
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPT = Path(__file__).resolve().parent.parent / "list_customizable_skills.py"
+
+
+def _load_module():
+    spec = importlib.util.spec_from_file_location("list_customizable_skills", SCRIPT)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)  # type: ignore[union-attr]
+    return module
+
+
+MODULE = _load_module()
+
+
+def _make_skill(parent: Path, name: str, body: str, skill_md: str | None = None) -> Path:
+    skill_dir = parent / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "customize.toml").write_text(body, encoding="utf-8")
+    if skill_md is not None:
+        (skill_dir / "SKILL.md").write_text(skill_md, encoding="utf-8")
+    return skill_dir
+
+
+class ScannerTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        self.skills = self.root / "skills"
+        self.skills.mkdir(parents=True)
+        self.custom = self.root / "_bmad" / "custom"
+        self.custom.mkdir(parents=True)
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_agent_only_skill_detected(self):
+        _make_skill(
+            self.skills,
+            "bmad-agent-pm",
+            "[agent]\nicon = \"🧠\"\n",
+            "---\nname: bmad-agent-pm\ndescription: Product manager.\n---\n",
+        )
+        result = MODULE.scan_skills([self.skills], self.root)
+        self.assertEqual(len(result["agents"]), 1)
+        self.assertEqual(len(result["workflows"]), 0)
+        entry = result["agents"][0]
+        self.assertEqual(entry["name"], "bmad-agent-pm")
+        self.assertEqual(entry["surface"], "agent")
+        self.assertEqual(entry["description"], "Product manager.")
+        self.assertFalse(entry["has_team_override"])
+        self.assertFalse(entry["has_user_override"])
+
+    def test_workflow_only_skill_detected(self):
+        _make_skill(
+            self.skills,
+            "bmad-create-prd",
+            "[workflow]\npersistent_facts = []\n",
+            "---\nname: bmad-create-prd\ndescription: 'Create a PRD.'\n---\n",
+        )
+        result = MODULE.scan_skills([self.skills], self.root)
+        self.assertEqual(len(result["agents"]), 0)
+        self.assertEqual(len(result["workflows"]), 1)
+        entry = result["workflows"][0]
+        self.assertEqual(entry["description"], "Create a PRD.")
+
+    def test_dual_surface_skill_emits_two_entries(self):
+        _make_skill(
+            self.skills,
+            "bmad-dual",
+            "[agent]\nicon = \"x\"\n\n[workflow]\npersistent_facts = []\n",
+            "---\nname: bmad-dual\ndescription: Dual.\n---\n",
+        )
+        result = MODULE.scan_skills([self.skills], self.root)
+        self.assertEqual(len(result["agents"]), 1)
+        self.assertEqual(len(result["workflows"]), 1)
+        self.assertEqual(result["agents"][0]["name"], "bmad-dual")
+        self.assertEqual(result["workflows"][0]["name"], "bmad-dual")
+
+    def test_skill_without_customize_toml_ignored(self):
+        (self.skills / "bmad-plain").mkdir()
+        (self.skills / "bmad-plain" / "SKILL.md").write_text("# plain\n")
+        result = MODULE.scan_skills([self.skills], self.root)
+        self.assertEqual(len(result["agents"]) + len(result["workflows"]), 0)
+        self.assertEqual(result["errors"], [])
+
+    def test_existing_team_override_flagged(self):
+        _make_skill(
+            self.skills,
+            "bmad-agent-pm",
+            "[agent]\nicon = \"x\"\n",
+            "---\nname: bmad-agent-pm\ndescription: PM.\n---\n",
+        )
+        (self.custom / "bmad-agent-pm.toml").write_text("[agent]\n")
+        result = MODULE.scan_skills([self.skills], self.root)
+        entry = result["agents"][0]
+        self.assertTrue(entry["has_team_override"])
+        self.assertFalse(entry["has_user_override"])
+
+    def test_missing_surface_block_reports_error(self):
+        _make_skill(self.skills, "bmad-broken", "[not_a_surface]\nfoo = 1\n")
+        result = MODULE.scan_skills([self.skills], self.root)
+        self.assertEqual(len(result["agents"]) + len(result["workflows"]), 0)
+        self.assertEqual(len(result["errors"]), 1)
+        self.assertIn("no [agent] or [workflow] block", result["errors"][0])
+
+    def test_malformed_toml_reports_error_without_aborting(self):
+        skill_dir = self.skills / "bmad-bad"
+        skill_dir.mkdir()
+        (skill_dir / "customize.toml").write_text("this is not [valid toml\n")
+        # Plus a good sibling to confirm scanning continues.
+        _make_skill(
+            self.skills,
+            "bmad-good",
+            "[agent]\nicon = \"x\"\n",
+            "---\nname: bmad-good\ndescription: Good.\n---\n",
+        )
+        result = MODULE.scan_skills([self.skills], self.root)
+        self.assertEqual(len(result["agents"]), 1)
+        self.assertEqual(result["agents"][0]["name"], "bmad-good")
+        self.assertTrue(any("failed to parse" in e for e in result["errors"]))
+
+    def test_description_with_double_quotes_stripped(self):
+        _make_skill(
+            self.skills,
+            "bmad-q",
+            "[agent]\nicon = \"x\"\n",
+            '---\nname: bmad-q\ndescription: "Double-quoted desc."\n---\n',
+        )
+        result = MODULE.scan_skills([self.skills], self.root)
+        self.assertEqual(result["agents"][0]["description"], "Double-quoted desc.")
+
+    def test_multiple_skills_roots_are_merged(self):
+        extra_root = self.root / "extra-skills"
+        extra_root.mkdir()
+        _make_skill(
+            self.skills,
+            "bmad-agent-pm",
+            "[agent]\nicon = \"x\"\n",
+            "---\nname: bmad-agent-pm\ndescription: PM.\n---\n",
+        )
+        _make_skill(
+            extra_root,
+            "bmad-agent-dev",
+            "[agent]\nicon = \"y\"\n",
+            "---\nname: bmad-agent-dev\ndescription: Dev.\n---\n",
+        )
+        result = MODULE.scan_skills([self.skills, extra_root], self.root)
+        names = {a["name"] for a in result["agents"]}
+        self.assertEqual(names, {"bmad-agent-pm", "bmad-agent-dev"})
+        self.assertEqual(len(result["scanned_roots"]), 2)
+
+    def test_duplicate_skill_name_across_roots_first_wins(self):
+        extra_root = self.root / "extra-skills"
+        extra_root.mkdir()
+        _make_skill(
+            self.skills,
+            "bmad-agent-pm",
+            "[agent]\nicon = \"primary\"\n",
+            "---\nname: bmad-agent-pm\ndescription: Primary.\n---\n",
+        )
+        _make_skill(
+            extra_root,
+            "bmad-agent-pm",
+            "[agent]\nicon = \"duplicate\"\n",
+            "---\nname: bmad-agent-pm\ndescription: Duplicate.\n---\n",
+        )
+        result = MODULE.scan_skills([self.skills, extra_root], self.root)
+        self.assertEqual(len(result["agents"]), 1)
+        self.assertEqual(result["agents"][0]["description"], "Primary.")
+        self.assertEqual(result["agents"][0]["skills_root"], str(self.skills))
+
+    def test_missing_skills_root_reports_error(self):
+        result = MODULE.scan_skills(
+            [self.root / "does-not-exist", self.skills],
+            self.root,
+        )
+        self.assertTrue(any("skills root does not exist" in e for e in result["errors"]))
+
+    def test_cli_emits_valid_json_and_exits_zero(self):
+        _make_skill(
+            self.skills,
+            "bmad-agent-pm",
+            "[agent]\nicon = \"x\"\n",
+            "---\nname: bmad-agent-pm\ndescription: PM.\n---\n",
+        )
+        proc = subprocess.run(
+            [
+                sys.executable,
+                str(SCRIPT),
+                "--project-root",
+                str(self.root),
+                "--skills-root",
+                str(self.skills),
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+        payload = json.loads(proc.stdout)
+        self.assertEqual(len(payload["agents"]), 1)
+
+    def test_cli_exits_two_on_missing_project_root(self):
+        proc = subprocess.run(
+            [
+                sys.executable,
+                str(SCRIPT),
+                "--project-root",
+                str(self.root / "does-not-exist"),
+                "--skills-root",
+                str(self.skills),
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        self.assertEqual(proc.returncode, 2)
+        self.assertIn("does not exist", proc.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/core-skills/bmad-deep-recon/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: bmad-deep-recon
+description: 'Decision-grade research, three ways: draft a deep-research prompt for the user to run in their own tool (ChatGPT, Gemini, Grok, Perplexity, …), process a finished research report — file it, distill a succinct cited summary with metadata that downstream skills consume without reprocessing — or run the research here through web fan-out. Shipped type packs: market, domain, technical, competitive, user-voice, academic-lit — plus a select shape for choose-between decisions and custom types via overrides. Use when the user says "deep recon", "research this", "draft a research prompt", "process this research report", "market research", "domain research", "technical research", "competitor research", "literature review", or "help me choose between".'
+---
+
+# BMad Deep Recon
+
+## Overview
+
+You are **Deep Recon** — a research director, not a search engine. Your value is framing research worth running and turning whatever comes back into a decision-grade artifact this project consumes without reprocessing. Every engagement serves a **decision** — enter a market, pick a stack, scope a product, commit to a domain — and is shaped by it from the first question to the final artifact.
+
+Three services, freely combined — each detailed in its reference: **Draft** a deep-research prompt the user runs in their own tool, **Process** a finished report into the succinct cited summary downstream skills read, or **Run** the research here through parallel web fan-out. Draft → run externally → Process is the natural loop; Run is fully capable on its own.
+
+**Epistemics — two standing rules, inherited verbatim by every subagent you spawn:**
+
+1. **Never conclude from training data alone.** What you already know proposes hypotheses, queries, and structure; conclusions require evidence retrieved or imported *this run*. A claim you cannot evidence is stated as an unverified belief or not at all.
+2. **The research firewall.** Project context — briefs, PRDs, code, memory, `{workflow.persistent_facts}` — shapes *what to ask*, never *what is true*. It is inadmissible as evidence: every claim in a research artifact traces to a digest or import file with a source. Research subagents receive only their brief — no project files, no ambient context — unless the plan explicitly grants a named document.
+
+## How you work
+
+- **Nothing exists until it is a file.** Every digest, import extraction, and report section is written to the run folder the moment it lands — the conversation is a control channel, never the store. A run that dies mid-flight resumes from disk with nothing lost.
+- **Extract, don't ingest.** Raw reports and search results never enter the parent context whole; subagents return relevance-filtered digests, and the parent reads digest files JIT.
+- **A claim is a sentence with a source.** Publisher, publication date, access date. No naked numbers.
+- **Report what is real.** Thin public data is reported as thin, absence of evidence is a finding, and freshness is part of truth — each pack sets windows per claim class; a market size from three years ago is history, not fact.
+- **Fast by default.** Rigor is bought consciously through the knobs, never accreted through extra passes. One gate, light checkpoints, no ceremony.
+- **The memlog is the process memory.** Every decision, source batch, load-bearing claim, plan change, and assumption is one append-only line, always through the script: `uv run {project-root}/_bmad/scripts/memlog.py` with `--type <decision|source|claim|assumption|question|event>`.
+- Web access is required for Run. If unavailable, say so and offer Draft/Process — never fabricate research.
+
+## Resolution rules
+
+- Bare paths and `{skill-root}` (e.g. `references/run.md`) resolve from this skill's installed directory.
+- `{project-root}` → the project working directory; `{skill-name}` → the skill directory's basename.
+- `{workflow.<name>}` → a merged `customize.toml` field; `{doc_workspace}` → the bound run folder.
+- Forward slashes only. Config variables already contain `{project-root}` in their resolved values — never double-prefix.
+
+## On Activation
+
+**Forwarded activation:** if a caller invoked you with a stated intent, research type, or pre-resolved customization fields (the legacy research shims and Mary's menu do), honor them verbatim — skip your own inference for those values and resolve only the rest.
+
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`.
+2. Resolve config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}`. From the merged JSON resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{project_name}`, `{output_folder}` (under `core`), `{planning_artifacts}` (under `modules.bmm`; absent on core-only installs → `{output_folder}`), and `{date}`; missing keys take neutral defaults, never block.
+3. Headless (no interactive user) → see `## Headless Mode`. Otherwise greet `{user_name}` in `{communication_language}` — and stay in it every turn.
+4. Detect the intent: **draft**, **process** (the user has or names a report), **run**, or lifecycle **refresh** / **deepen** on an existing run folder. When the ask is bare research with no verb ("research X for me"), open the floor first — invite the decision they're facing and anything they already have (briefs, links, a prior report) in one turn, then ask only what's missing — and put the choice up front, once: **Run** it here now, or **Draft** a prompt for a deep-research tool they subscribe to — often cheaper and a strong gatherer, with Process turning its output into the same artifact. State the trade honestly (tokens and minutes here vs. one manual round-trip there); their call, remembered for the session.
+5. If a run folder for this topic already exists under `{workflow.research_output_path}`, offer to resume or extend it (a drafted brief awaiting its report, a report awaiting refresh) rather than start a duplicate.
+
+## Research types and decision shapes
+
+The type set is whatever `{workflow.research_types}` resolves to — shipped: `market`, `domain`, `technical`, `competitive`, `user-voice`, `academic-lit` — each pointing at a pack file. You already know how to research; the pack is where this harness is opinionated — prioritized dimensions, non-obvious source craft, freshness bars and two-source classes per claim class, downstream bindings. Apply it in every mode; don't re-derive it. Overrides replace matching codes and append new ones; never claim a fixed type list — read the resolved set.
+
+Infer the type from the user's ask and each entry's `when` clause; confirm only when genuinely ambiguous. An explicit type (argument, shim, menu) wins without discussion.
+
+Orthogonal to type is the **decision shape**: **explore** (the default — understand, assess, validate) or **select** (choose between candidates). When the shape is select, load `references/selection.md` and layer its method over the type's pack — it shapes drafted prompts and processed summaries as much as native runs.
+
+## Intents
+
+Route on the detected intent and load only what it names. Every intent shares the run-folder workspace shape — `brief.md`, `imports/`, `digests/`, `research.md`, `.memlog.md` — and ends per `references/finalize.md`.
+
+| Intent | What it does | Load |
+| --- | --- | --- |
+| Draft | Compose a deep-research prompt for the user's own tool, carrying the pack's craft | `references/draft.md` |
+| Process | File a finished report, extract its claims, distill the downstream summary | `references/process.md` |
+| Run | Native research: resolve effort, hold the plan gate — the one hard stop — then run the loop | `references/run.md`, then `references/verification.md` + `references/synthesis.md` |
+| Refresh / Deepen | Update or extend an existing run folder | `references/lifecycle.md` |
+
+## Headless Mode
+
+When invoked headless, do not ask. Bare research defaults to **run**; a named report means **process**; a requested prompt means **draft** (the brief file is the deliverable). Plan-and-proceed: infer type, build from the pack, keep configured knobs plus anything in the invocation (red team and workflow orchestration only when set `"on"`), skip checkpoints, log every judgment call as an `assumption`. Halt `blocked` only when topic or target folder cannot be inferred. End with JSON:
+
+```json
+{
+  "status": "complete",
+  "intent": "run",
+  "type": "market",
+  "report": "{doc_workspace}/research.md",
+  "memlog": "{doc_workspace}/.memlog.md",
+  "claims": {"verified": 12, "unverified": 3, "overturned": 0},
+  "open_questions": [],
+  "external_handoffs": []
+}
+```
+
+Omit keys for artifacts not produced; the `claims` counts come from `uv run scripts/recon_kit.py tally {doc_workspace}/.memlog.md`, never hand-counted. Draft adds `"brief"`; process adds `"imports"`; refresh replaces `claims` scope with the refresh set plus a `deltas` array. With `output_format = "auto"`, headless runs produce no briefing; add `"briefing"` when rendered.

package/src/core-skills/bmad-deep-recon/assets/research.template.md

@@ -0,0 +1,18 @@
+---
+title: '{research_type} research: {research_topic}'
+type: '{research_type}'
+topic: '{research_topic}'
+decision: '{decision}'
+source: '{source}'
+status: draft
+preset: '{preset}'
+validation: '{validation}'
+created: '{date}'
+updated: '{date}'
+---
+
+# {research_type} research: {research_topic}
+
+**Decision this research serves:** {decision}
+
+_Sections are appended per the approved research plan; the executive summary is written last and placed here, first._

package/src/core-skills/bmad-deep-recon/customize.toml

@@ -0,0 +1,212 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-deep-recon.
+#
+# Override files (not edited here):
+#   {project-root}/_bmad/custom/bmad-deep-recon.toml         (team)
+#   {project-root}/_bmad/custom/bmad-deep-recon.user.toml    (personal)
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins
+#   arrays (persistent_facts, activation_steps_*, *_sources, doc_standards,
+#   external_*): append
+#   arrays of tables keyed by `code`: matching key replaces, new keys append
+
+# Steps executed on activation: prepend runs before the skill's own
+# activation flow, append runs after it. Each entry is a literal instruction.
+activation_steps_prepend = []
+activation_steps_append = []
+
+# Standing context for framing the research — decision context only, never
+# evidence: the research firewall keeps project material out of findings.
+# Entries prefixed `file:` are paths or globs whose contents load as facts;
+# all others are literal facts. Empty by default so nothing local leaks into
+# research framing unasked.
+persistent_facts = []
+
+# Where research runs live and how each run folder is named. Draft, Process,
+# and Run all use the same folder shape: brief.md (drafted prompts),
+# imports/ (originals, full fidelity), digests/ (extracted claims),
+# research.md (the canonical summary/report), .memlog.md.
+research_output_path = "{planning_artifacts}/research"
+run_folder_pattern = "{research_type}-{topic_slug}-{date}"
+
+# Seed document for a new run.
+research_template = "assets/research.template.md"
+
+# --- Effort (Run mode) ------------------------------------------------------
+# A preset bundles the three effort knobs; any knob set here individually
+# pins that knob over the preset. What the user says in the request beats
+# both.
+#
+#   preset     subagents  sources/round  depth
+#   quick      low (2)    5              1
+#   standard   normal (3) 8              2
+#   deep       high (6)   12             3
+#
+# Grounding: orchestrator-worker research systems document 3-5 parallel
+# workers as the sweet spot (more only for genuinely wide work). Depth and
+# sources are caps, not quotas — dimensions stop early on coverage or
+# novelty exhaustion. Defaults are tuned for a fast run; buy more rigor
+# consciously, per run, in the request.
+
+preset = "standard"
+
+# "" = from preset. Values: none | low | normal | high
+# (0 / 2 / 3 / 6 parallel research assistants, ceiling 10; none also =
+# no-subagent environments, run inline sequentially).
+subagents = ""
+
+# 0 = from preset. Distinct sources actually read per dimension per round.
+# Ceiling 25 — beyond that a single round exceeds what hosted deep-research
+# products spend on an entire run.
+max_sources_per_round = 0
+
+# 0 = from preset. Rounds per dimension: initial pass + lead-following
+# follow-ups. Ceiling 5.
+max_depth = 0
+
+# Verification level, applied as material lands (never an end-of-run pass).
+#   normal  spot-check load-bearing claims only — fast, the default
+#   high    cross-check the pack's two-source classes; red-team major
+#           conclusions
+#   max     cross-check every ledger claim + the red-team pass at full
+#           breadth + primary-source-priority ranking
+validation = "normal"
+
+# Red-team stance pass — fresh-context skeptics hunting disconfirming
+# evidence for major conclusions: "off" (default), "offer" (proposed at the
+# plan gate), or "on" (always; headless honors only "on"). high/max
+# validation includes it for major conclusions regardless.
+red_team = "off"
+
+# Run the acquisition fan-out through the harness's deterministic
+# orchestration when it offers one (e.g. workflows): "off", "offer"
+# (proposed at the plan gate when available), or "on". Orchestrated runs are
+# faster wall-clock but spend more tokens.
+use_workflows = "offer"
+
+# Ordered model preference for spawned research assistants — first model the
+# harness can provide wins; [] lets the harness/skill choose (lead stays on
+# the strongest model; researchers at most one capable tier down; judgment
+# work never on the smallest tier; mechanical extraction may use a fast
+# tier).
+#
+# Example: subagent_models = ["<your-mid-tier-model-id>", "<your-fast-model-id>"]
+subagent_models = []
+
+# Source policy. Preferred sources are consulted first and weighted as more
+# credible; banned sources are never cited (their claims may still be leads
+# to verify elsewhere). Entries are domains or plain-text descriptions.
+# Draft mode writes both policies into drafted prompts.
+preferred_sources = []
+banned_sources = []
+
+# What is presented and handed off — never what exists: research.md (the
+# canonical machine-readable summary/report) always lives in the workspace.
+#   "auto"  html briefing on interactive runs; md only on headless or
+#           skill-invoked runs (the caller reads the md; render later at will)
+#   "html"  always render the briefing page (references/html-briefing.md)
+#   "md"    never render html
+#   "both"  render and present both
+output_format = "auto"
+
+# Theme for the HTML briefing: empty = the shipped neutral professional
+# theme, a `file:` path to a theme/brand spec, or inline directives
+# (e.g. "Canvas #122543, accent #B66D46, sans-serif, dark-mode aware").
+html_theme = ""
+
+# Default audience shaping for the synthesis — freeform, empty = balanced
+# technical/business register. Examples: "executive one-pager first, detail
+# after", "engineering team, keep vendor marketing out".
+audience = ""
+
+# Registry of extra research surfaces — internal knowledge bases or search
+# tools you subscribe to — consulted alongside web research in Run mode; each
+# entry names the tool and when to use it. Installed search-shaped MCP tools
+# are discovered automatically at the plan gate; an entry here adds routing
+# guidance the discovery can't infer.
+#
+# Examples:
+#   external_sources = [
+#     "Tavily MCP (tavily_search/tavily_extract): preferred web search + clean page extraction",
+#     "Perplexity Sonar MCP (perplexity_ask): cited synthesized answers — chase its citations as the sources",
+#     "xAI X Search MCP: live X/Twitter posts and threads, for user-voice and sentiment dimensions",
+#     "Gartner MCP (corp:gartner_query): analyst data on enterprise software markets",
+#   ]
+external_sources = []
+
+# Polish passes applied to research.md at finalize. Entries are `skill:NAME`
+# directives, `file:` style guides, or plain-text instructions.
+doc_standards = ["skill:bmad-review lenses=structure,prose"]
+
+# Handoffs executed at finalize to route the report beyond local files. Each
+# entry names the tool and what to do; unavailable tools are skipped and
+# flagged.
+#
+# Examples:
+#   "NotebookLM (notebooklm-mcp): create a notebook from research.md plus the top sources, generate an audio overview, return the notebook URL"
+#   "Confluence (corp:confluence_upload): publish research.md to the RESEARCH space, return the page URL"
+external_handoffs = []
+
+# Executed after finalize. A string scalar is one instruction; an array is a
+# sequence. Empty = the run ends with the finalize summary.
+on_complete = ""
+
+# ---------------------------------------------------------------------------
+# Research types — subject lenses. Each type is a pack: a policy and craft
+# card (prioritized dimensions, non-obvious source craft, freshness bars,
+# two-source classes, downstream bindings) used by all three modes — it
+# shapes drafted prompts, native runs, and processed-report gap checks
+# alike. `when` guides type inference from the user's ask; an explicitly
+# requested type always wins. The decision shape (explore vs select) is
+# orthogonal — any type can end in a selection matrix.
+#
+# Keyed by `code`: an override with a matching code replaces the shipped
+# type, a new code appends. Empty `pack` disables a type.
+#
+# Example (add an org-specific type in team/user override TOML):
+#   [[workflow.research_types]]
+#   code = "regulatory"
+#   name = "Regulatory Research"
+#   when = "Compliance posture, licensing, or regulatory exposure for a product or market."
+#   pack = "file:{project-root}/_bmad/custom/packs/regulatory.md"
+# ---------------------------------------------------------------------------
+
+[[workflow.research_types]]
+code = "market"
+name = "Market Research"
+when = "Market opportunity, customers, competition, sizing, or go-to-market for a product or business decision."
+pack = "types/market.md"
+
+[[workflow.research_types]]
+code = "domain"
+name = "Domain Research"
+when = "Understanding an industry, sector, or field: structure, players, rules, vocabulary, dynamics."
+pack = "types/domain.md"
+
+[[workflow.research_types]]
+code = "technical"
+name = "Technical Research"
+when = "A technology area's landscape, patterns, integration approaches, and implementation reality."
+pack = "types/technical.md"
+
+[[workflow.research_types]]
+code = "competitive"
+name = "Competitive Research"
+when = "Teardown of specific named competitors: offers, pricing, positioning, trajectory, their customers' sentiment."
+pack = "types/competitive.md"
+
+[[workflow.research_types]]
+code = "user-voice"
+name = "User-Voice Research"
+when = "What users of a product or category actually experience and want: reviews, communities, jobs-to-be-done."
+pack = "types/user-voice.md"
+
+[[workflow.research_types]]
+code = "academic-lit"
+name = "Academic Literature"
+when = "Published research: literature review, state of the art, grounding an approach in papers."
+pack = "types/academic-lit.md"

package/src/core-skills/bmad-deep-recon/references/draft.md

@@ -0,0 +1,8 @@
+# Draft
+
+Build a deep-research prompt the user runs themselves — in conversation, fast, not a project. The pack's craft travels inside the prompt so the outside tool works to this harness's standard.
+
+1. Open the floor before any structured questions: invite the decision they're facing and anything they already have — briefs, links, a prior report, half-formed constraints — in one turn, then ask only what's still missing. Nail the **decision**, topic, and type; load the pack. Ask which tool the prompt is for (it changes phrasing: hosted deep-research agents handle wide scopes and long source lists; social-native tools like Grok earn user-voice and sentiment dimensions; if unknown, write tool-neutral).
+2. Compose the prompt from the pack: the dimensions as explicit research questions pruned to the decision, the freshness bars as recency requirements, the two-source expectation for its critical claim classes, the audience, the source policy — `{workflow.preferred_sources}` named as sources to prefer, `{workflow.banned_sources}` as sources never to cite — and a **non-negotiable citation demand**: every claim with source URL and publication date, contrary evidence reported, gaps admitted rather than padded. Structure the requested output so Process can extract it cleanly (findings per dimension, a source list).
+3. Bind `{doc_workspace}`: expand the folder name deterministically (`uv run scripts/recon_kit.py slug "<topic>" --type <type> --pattern "{workflow.run_folder_pattern}"` — same expansion every mode, so the report comes back to the same folder) under `{workflow.research_output_path}`, init the memlog with the decision context, save the prompt as `{doc_workspace}/brief.md`, and present it paste-ready in chat.
+4. Close the loop: tell the user to run it in their tool and bring the report back — "process it" from here picks up this folder, decision context intact.

package/src/core-skills/bmad-deep-recon/references/finalize.md

@@ -0,0 +1,11 @@
+# Finalize
+
+Every mode ends here once `research.md` is assembled.
+
+1. `research.md` is complete per `references/synthesis.md`: decision-first summary, findings, contrary evidence where found, recommendations with downstream bindings, source appendix, staleness map. Frontmatter metadata (`type`, `topic`, `decision`, `source`, `status`, dates) is what lets every downstream consumer trust it without reprocessing.
+2. **Citation check — mechanical, then semantic.** Run `uv run scripts/recon_kit.py citations {doc_workspace}/research.md` — it diffs inline `[n]` markers against the appendix and lists dangling markers and orphaned rows exactly; fix what it reports. Then a fresh-context subagent does only the judgment half: does each cited source actually say what the text claims? It never rewrites findings — a claim whose source doesn't back it gets its confidence downgraded and the mismatch logged as an `event`.
+3. Render per `{workflow.output_format}` (see `references/html-briefing.md`): `auto` renders the briefing page on interactive runs, skips on headless/skill-invoked; `html`/`both` always; `md` never. `research.md` always exists — the briefing is its regenerable face.
+4. Polish: apply each `{workflow.doc_standards}` entry (a `skill:`, `file:`, or plain-text directive) to `research.md`.
+5. Execute each `{workflow.external_handoffs}` entry (NotebookLM, Confluence, …) — invoke the named tool, surface returned URLs; skip and flag unavailable tools.
+6. Tell the user what exists and where — report, briefing, imports, memlog — plus what the staleness map says to re-check and when, and that Refresh/Deepen handle it. Invoke `bmad-help` to suggest the next step.
+7. Run `{workflow.on_complete}` if non-empty — a string is one instruction, an array is a sequence.

package/src/core-skills/bmad-deep-recon/references/html-briefing.md

@@ -0,0 +1,16 @@
+# HTML Briefing
+
+Generate `research-briefing.html` in `{doc_workspace}` after `research.md` is final, when `{workflow.output_format}` calls for it: `"auto"` renders on interactive runs and skips on headless/skill-invoked runs (the md is always there to render from later), `"html"`/`"both"` always render, `"md"` never. The page is a full-fidelity presentation of the report, never a second source of truth — same claims, same numbers, same citations; nothing is lost by reading it instead of the markdown.
+
+## Requirements
+
+- **Self-contained single file**: inline CSS and JS, no external requests of any kind (no CDN, no fonts, no remote images). It must render from a `file://` open, offline, forever.
+- **Structure**: a header (topic, type, decision, date, depth, verification level) → the executive summary as the opening card → sticky table of contents → dimension sections → contrary evidence (when present) → recommendations → collapsible source appendix → staleness map.
+- **Confidence is visual**: every claim carries its badge — verified / medium / low / `unverified` / disputed — color-coded with the status text always present (never color alone). Unverified and disputed must be *more* prominent than verified, not less.
+- **Sources are live**: inline `[n]` markers link to the appendix row; appendix rows link out to the source URL. Source URLs are untrusted content — never hand-escape them: generate the appendix table with `uv run scripts/recon_kit.py escape-sources {doc_workspace}/research.md` and embed its `html` output, which escapes every cell, anchors each row (`id="src-n"`), and links only validated `http(s)` URLs (anything else renders as plain text; the script lists it in `invalid_urls`). Apply the same escape discipline to any other source-derived text you place in attributes.
+- **Charts sparingly**: only where the data genuinely benefits (market size trajectory, decision matrix scores) — simple inline SVG, labeled axes, no library.
+- **Responsive and theme-aware**: readable on a phone; respect `prefers-color-scheme` for light/dark.
+
+## Theme
+
+`{workflow.html_theme}` governs: a `file:` path loads a theme/brand spec to follow; inline text is applied as directives; empty means the shipped default — neutral, professional, generous whitespace, system font stack, one restrained accent color. Whatever the theme, the confidence-badge semantics above are non-negotiable.

package/src/core-skills/bmad-deep-recon/references/lifecycle.md

@@ -0,0 +1,11 @@
+# Refresh and Deepen
+
+Lifecycle intents on an existing run folder.
+
+## Refresh
+
+Read `research.md` and `.memlog.md` — never re-research from scratch. Build the refresh set mechanically: assemble the claims (`claim`, `class`, `pub_date`) from the ledger, map the pack's freshness bars to a months-per-class JSON, and run `uv run scripts/recon_kit.py staleness <claims.json> --windows '<map>'` — the stale flags are the candidate set. Confirm it in one exchange, re-verify just those claims, and deliver a **delta report** (confirmed / changed / overturned, new sources) appended to `research.md` with the frontmatter `updated` bumped. Claims outside the set keep their status. An overturned load-bearing claim triggers an explicit warning naming the downstream artifacts that consumed it.
+
+## Deepen
+
+Drill into one dimension or add a new one without touching the rest: mini plan gate, acquire → verify for that slice only (or a drafted follow-up prompt when the user's tool is better placed), merge into `research.md`, update only the synthesis sections the new material affects — a deepening that changes no conclusion says so.

package/src/core-skills/bmad-deep-recon/references/process.md

@@ -0,0 +1,10 @@
+# Process
+
+For a report the user names or drops ("there's a research report at <path>, process it"):
+
+1. **File it.** Find or create the run folder: if a drafted brief for this topic exists, that folder is the target; otherwise infer type and topic from the report (confirm in one line), bind `{doc_workspace}` (expand the folder name with `uv run scripts/recon_kit.py slug` as in Draft), and init the memlog. Move or copy the original into `{doc_workspace}/imports/` untouched — full fidelity is preserved there, and nowhere else.
+2. **Record provenance** in the memlog: what produced it (which tool or firm), when (ask if not evident — production date drives staleness), and what the user wants decided from it.
+3. **Extract.** A subagent (fresh context, firewall rules) reads the import and pulls every claim bearing on the decision into digest files under `{doc_workspace}/digests/` — standard shape `{claim, source, publisher, pub_date, accessed, confidence, class}`, keeping the original's citations (the cited source is the publisher; the import is the via). Multiple imports each get their own digest; contradictions between them are findings, not noise.
+4. **Check against the pack**: which of the type's dimensions the material covers, which are open, where its claims fall inside two-source classes but rest on one publisher. Verification per the resolved `validation` level (`references/verification.md`) — at `normal` this is a spot-check of the load-bearing claims only, minutes not hours.
+5. **Distill** into `research.md` per `references/synthesis.md` — the succinct, cited, decision-first summary with full metadata frontmatter (topic, type, decision, `source:` provenance, dates, status). This is the artifact downstream skills read; nobody ever reprocesses the import. Open dimensions are listed honestly with a one-line route: draft a follow-up prompt, or a targeted Run on the gap.
+6. Finalize per `references/finalize.md`.