@kudusov.takhir/ba-toolkit 3.1.1 → 3.2.0

package/CHANGELOG.md

@@ -11,6 +11,30 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [3.2.0] — 2026-04-09
+
+### Highlights
+
+- **New `/discovery` skill — concept brain-storm before `/brief`** for users who don't yet know what to build.
+- **`ba-toolkit publish` CLI subcommand + `/publish` skill** — one-command Notion (Markdown) and Confluence (HTML) import-ready bundles, zero deps, zero tokens, zero network.
+
+### Added
+
+- **New `ba-toolkit publish` CLI subcommand + `/publish` skill — Notion / Confluence bundle export.** Bundles every BA Toolkit artifact in the current `output/<slug>/` folder into import-ready files for two destinations: a clean Markdown bundle (`publish/notion/`) for Notion's bulk **Import → Markdown & CSV** dialog, and an HTML bundle with an `index.html` entry point (`publish/confluence/`) for Confluence's **Space settings → Content tools → Import → HTML** tool. **Zero API calls, zero tokens, zero network** — the conversion happens entirely on disk and the user does the upload manually using each tool's native importer. Cross-references between artifacts (`[FR-001](02_srs_<slug>.md#fr-001)`) are rewritten per target: Notion gets `./02_srs_<slug>.md#fr-001`, Confluence gets `02_srs_<slug>.html#fr-001`, and external HTTP/HTTPS links pass through unchanged. `AGENTS.md` (if present) is included as the first page in both bundles, with the `<!-- ba-toolkit:begin managed -->` block stripped so the management markers don't render as visible text. Surface: `ba-toolkit publish [--format notion|confluence|both] [--out PATH] [--dry-run]`. Default format is `both`, default output is `./publish/`. Comes with a thin `skills/publish/SKILL.md` discoverability layer that the AI agent invokes via the Bash tool when the user types `/publish` in any supported agent (Claude Code, Codex, Gemini, Cursor, Windsurf).
+- **In-tree `markdownToHtml` helper in `bin/ba-toolkit.js`.** Pure function, ~190 lines, handles the bounded Markdown surface used by every shipped artifact template: ATX headings (with auto-generated GitHub-style anchor IDs), paragraphs, bold / italic / inline code with placeholder-based stashing so emphasis inside link labels and code spans round-trips correctly, links, single-level unordered and ordered lists, GFM tables with thead/tbody, fenced code blocks (language hint preserved), blockquotes, horizontal rules, and HTML special-character escaping. Out of scope by design: nested lists, images, footnotes, math, raw HTML pass-through. Exported alongside `htmlEscape`, `slugifyHeading`, `rewriteLinks`, `stripManagedBlock`, `compareArtifactFilenames`, and `ARTIFACT_FILE_RE` so the test suite can cover each piece in isolation.
+- **23 new tests covering the publish flow.** 14 unit tests in `test/cli.test.js` for the converter and supporting helpers (one per supported Markdown element class plus link rewriting, managed-block stripping, the `7 < 7a < 8` filename sort, and the artifact-filename regex). 7 integration tests in `test/cli.integration.test.js` that spawn the real CLI against fixture markdown files inside a temp dir and assert the bundle layout, link rewriting in both modes, the Confluence `index.html` ordering, the AGENTS.md-as-first-page rule, the empty-directory error path, the invalid-format error path, and the `--dry-run` no-write contract. The skill-folder-count assertion bumps from `>= 22` to `>= 23` and the existing protocol-link / closing-message / Recommended-marker / 5-rows-cap regression tests auto-cover `skills/publish/SKILL.md`.
+
+- **New `/discovery` skill — concept brain-storm before `/brief`.** For users who arrive with only a vague hunch and no fixed domain or feature list, `/discovery` runs a structured concept-discovery interview (problem space, target audience hypotheses, candidate domains, reference products, MVP feature ideas, differentiation angle, open validation questions) and writes a hypothesis document to `00_discovery_{slug}.md`. The artifact ends with a concrete recommendation (chosen domain, project name, slug, scope hint) that flows directly into `/brief` as inline context. Modeled on `/principles` (the only other optional pre-brief skill) — same workflow phases, same closing-message contract, same interview-protocol rules (5-row cap, Recommended marker, user-language variants). Lives at `skills/discovery/SKILL.md` with a matching artifact template at `skills/references/templates/discovery-template.md`. Pipeline lookup table in `closing-message.md` gains a new row `/discovery → /brief`. The `agents-template.md` Pipeline Status table inserts `/discovery` at stage `0` and demotes `/principles` to stage `0a` (mirror of how `/research` sits at stage `7a`) — `/brief` stays at stage `1`, no downstream renumbering, no risk of breaking existing AGENTS.md files for projects that already started. Skill is auto-discovered by the CLI from the `skills/` directory — no `bin/ba-toolkit.js` registration needed.
+- **`/brief` consumes `00_discovery_*.md` if present.** `skills/brief/SKILL.md` Pipeline check phase now loads any existing discovery artifact, extracts the problem space, audience hypotheses, recommended domain, MVP feature hypotheses, and scope hint, and uses them to pre-fill the structured interview per protocol rule 9 — skipping any required topic the discovery already answered. The handoff is real, not a hint to copy-paste context manually.
+- **`example/lumen-goods/00_discovery_lumen-goods.md`** — full concept-discovery walkthrough for the Lumen Goods example project. 8 sections matching the new template, length comparable to `00_principles_lumen-goods.md`. Keeps the lumen-goods example end-to-end consistent with the new pipeline entry point.
+
+### Changed
+
+- **Skill count bumped from 22 to 23** in every place that enumerated skills: `package.json` description, `README.md` (badge, intro, install sections, utility table, minimum-viable-pipeline section), `COMMANDS.md` Utility skills table, `CLAUDE.md` §1 and §4, `docs/USAGE.md` (interview-phase skill list, time-estimate appendix, new "Sharing artifacts with stakeholders" section), `docs/FAQ.md` (new Q/A: "How do I share the artifacts with non-developer stakeholders?"), `bin/ba-toolkit.js` stale comment, `skills/references/templates/agents-template.md` Cross-cutting Tools table (new `/publish [format]` row), `skills/references/closing-message.md` Cross-cutting commands list, and the `test/cli.test.js` skill-folder-count assertion (raised from `>= 22` to `>= 23`).
+- **Skill count bumped from 21 to 22** in every place that enumerated skills: `package.json` description, `README.md` (badge, intro, install sections, example table, pipeline table, minimum-viable-pipeline section now lists three paths instead of two), `COMMANDS.md`, `CLAUDE.md` §1 and §4, `docs/USAGE.md` (interview-phase skill list, AGENTS.md sample, time-estimate appendix), `docs/FAQ.md` (new Q/A: "What if I don't know what to build yet?"), `bin/ba-toolkit.js` two stale comments, and the `test/cli.test.js` skill-folder-count assertion (raised from `>= 20` with stale "~21" comment to `>= 22`).
+
+---
+
 ## [3.1.1] — 2026-04-09
 
 ### Changed
@@ -451,7 +475,8 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.1.1...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.2.0...HEAD
+[3.2.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.1.1...v3.2.0
 [3.1.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.1.0...v3.1.1
 [3.1.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.0.0...v3.1.0
 [3.0.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v2.0.0...v3.0.0

package/COMMANDS.md

@@ -1,6 +1,6 @@
 # BA Toolkit — Command Reference
 
-Quick reference for all 21 skills and subcommands.
+Quick reference for all 23 skills and subcommands.
 
 ---
 
@@ -10,7 +10,8 @@ Run these in order. Each skill reads the output of all previous steps.
 
 | # | Command | Output file | What it generates |
 |:---:|---------|-------------|-------------------|
-| 0 | `/principles` | `00_principles_{slug}.md` | Project constitution: language, ID conventions, DoR, traceability rules, NFR baseline |
+| 0 | `/discovery` | `00_discovery_{slug}.md` | Concept Discovery: problem space, audience hypotheses, candidate domains, MVP feature ideas, validation questions. Use when you don't yet know what to build — feeds the chosen domain, name, and scope hint into `/brief` |
+| 0a | `/principles` | `00_principles_{slug}.md` | Project constitution: language, ID conventions, DoR, traceability rules, NFR baseline |
 | 1 | `/brief` | `01_brief_{slug}.md` | Project Brief: goals, audience, stakeholders, constraints, risks. Updates the `AGENTS.md` Pipeline Status table (which `ba-toolkit init` already created) |
 | 2 | `/srs` | `02_srs_{slug}.md` | Requirements Specification (IEEE 830): scope, FRs, constraints, assumptions |
 | 3 | `/stories` | `03_stories_{slug}.md` | User Stories grouped by Epics, with priority and FR references |
@@ -38,6 +39,7 @@ Available at any pipeline stage.
 | `/estimate` | `00_estimate_{slug}.md` | Effort estimation for User Stories: Fibonacci SP, T-shirt sizes, or person-days |
 | `/glossary` | `00_glossary_{slug}.md` | Unified project glossary: scans all artifacts, detects terminology drift, undefined terms |
 | `/export [format]` | `export_{slug}_{format}.json` / `.csv` | Export User Stories to Jira, GitHub Issues, Linear, or CSV |
+| `/publish [format]` | `publish/notion/`, `publish/confluence/` | Bundle artifacts for Notion (Markdown bundle) and Confluence (HTML bundle) — drag-and-drop import, no API tokens. Wraps the `ba-toolkit publish` CLI subcommand |
 | `/risk` | `00_risks_{slug}.md` | Risk register: probability × impact matrix, mitigation and contingency per risk |
 | `/sprint` | `00_sprint_{slug}.md` | Sprint plan: stories grouped into sprints by velocity, capacity, and risk priority |
 

package/README.md

@@ -2,9 +2,9 @@
 
 # 📋 BA Toolkit
 
-Structured BA pipeline for AI coding agents — brief to handoff, 21 skills, 9 domains.
+Structured BA pipeline for AI coding agents — concept to handoff, 23 skills, 9 domains, one-command Notion + Confluence publish.
 
-<img src="https://img.shields.io/badge/skills-21-blue" alt="Skills">
+<img src="https://img.shields.io/badge/skills-23-blue" alt="Skills">
 <img src="https://img.shields.io/badge/domains-9-green" alt="Domains">
 <img src="https://img.shields.io/badge/format-Markdown-orange" alt="Format">
 <img src="https://img.shields.io/badge/language-auto--detect-purple" alt="Language">
@@ -22,7 +22,7 @@ Structured BA pipeline for AI coding agents — brief to handoff, 21 skills, 9 d
 
 ## What is this
 
-BA Toolkit is a set of 21 interconnected skills that run a full business-analysis pipeline inside your AI coding agent. You go from a rough project brief to a development handoff package, and each skill reads the output of the previous ones — maintaining cross-references between artifacts along the chain `FR → US → UC → AC → NFR → Entity → ADR → API → WF → Scenario`.
+BA Toolkit is a set of 23 interconnected skills that run a full business-analysis pipeline inside your AI coding agent. You can start as early as `/discovery` (a brain-storm step for users who don't yet know what to build) or jump straight to `/brief` if you already have a project in mind, then work all the way through to a development handoff package. Each skill reads the output of the previous ones — maintaining cross-references between artifacts along the chain `FR → US → UC → AC → NFR → Entity → ADR → API → WF → Scenario`. When you're ready to share with non-developer stakeholders, `/publish` (or `ba-toolkit publish`) bundles every artifact into import-ready folders for Notion and Confluence — drag-and-drop, no API tokens.
 
 Unlike one-shot prompting, every artifact is written to disk as Markdown, every ID links back to its source, and `/trace` verifies coverage across the whole pipeline. `/clarify` and `/analyze` catch ambiguities and quality gaps with CRITICAL/HIGH severity ratings. Domain references for 9 industries (SaaS, Fintech, E-commerce, Healthcare, Logistics, On-demand, Social/Media, Real Estate, iGaming) plug in automatically at `/brief`.
 
@@ -114,11 +114,11 @@ Reload the CLI after copying.
 
 ### Cursor
 
-Cursor has two separate features — Rules (`.cursor/rules/*.mdc`) and [Agent Skills](https://cursor.com/docs/skills) (`.cursor/skills/<skill>/SKILL.md`). BA Toolkit is a set of skills, not rules, so `ba-toolkit install --for cursor` drops the 21 skills directly into `.cursor/skills/` using the native folder-per-skill `SKILL.md` format — no conversion needed. Reload the Cursor window to pick them up.
+Cursor has two separate features — Rules (`.cursor/rules/*.mdc`) and [Agent Skills](https://cursor.com/docs/skills) (`.cursor/skills/<skill>/SKILL.md`). BA Toolkit is a set of skills, not rules, so `ba-toolkit install --for cursor` drops the 23 skills directly into `.cursor/skills/` using the native folder-per-skill `SKILL.md` format — no conversion needed. Reload the Cursor window to pick them up.
 
 ### Windsurf
 
-Windsurf's [Agent Skills](https://docs.windsurf.com/windsurf/cascade/skills) feature loads skills from `.windsurf/skills/<skill>/SKILL.md`, the same folder-per-skill layout as Claude Code and Cursor. `ba-toolkit install --for windsurf` writes the 21 skills there natively. Reload the Windsurf window to pick them up.
+Windsurf's [Agent Skills](https://docs.windsurf.com/windsurf/cascade/skills) feature loads skills from `.windsurf/skills/<skill>/SKILL.md`, the same folder-per-skill layout as Claude Code and Cursor. `ba-toolkit install --for windsurf` writes the 23 skills there natively. Reload the Windsurf window to pick them up.
 
 ### Aider
 
@@ -152,10 +152,11 @@ Your generated artifacts (`01_brief_*.md`, `02_srs_*.md`, …) are untouched by
 
 ## Example output
 
-A complete example project — **Lumen Goods** (sustainable home-goods D2C online store) — lives in [`example/lumen-goods/`](example/lumen-goods/). All 15 artifacts are realistic, cross-referenced, and generated by running the full BA Toolkit pipeline.
+A complete example project — **Lumen Goods** (sustainable home-goods D2C online store) — lives in [`example/lumen-goods/`](example/lumen-goods/). All 16 artifacts are realistic, cross-referenced, and generated by running the full BA Toolkit pipeline.
 
 | Artifact | File |
 |---------|------|
+| Concept Discovery | [`00_discovery_lumen-goods.md`](example/lumen-goods/00_discovery_lumen-goods.md) |
 | Project Principles | [`00_principles_lumen-goods.md`](example/lumen-goods/00_principles_lumen-goods.md) |
 | Project Brief | [`01_brief_lumen-goods.md`](example/lumen-goods/01_brief_lumen-goods.md) |
 | Requirements (SRS) | [`02_srs_lumen-goods.md`](example/lumen-goods/02_srs_lumen-goods.md) |
@@ -180,7 +181,8 @@ Full traceability: FR → US → UC → AC → NFR → Entity → ADR → API
 
 | # | Command | What it generates | Output file |
 |:---:|---------|-------------------|-------------|
-| 0 | `/principles` | Project Principles — language, ID conventions, DoR, traceability rules, NFR baseline | `00_principles_{slug}.md` |
+| 0 | `/discovery` | Concept Discovery — problem space, audience hypotheses, candidate domains, MVP feature ideas, validation questions | `00_discovery_{slug}.md` |
+| 0a | `/principles` | Project Principles — language, ID conventions, DoR, traceability rules, NFR baseline | `00_principles_{slug}.md` |
 | 1 | `/brief` | Project Brief — goals, audience, stakeholders, risks | `01_brief_{slug}.md` |
 | 2 | `/srs` | Requirements Specification (IEEE 830) | `02_srs_{slug}.md` |
 | 3 | `/stories` | User Stories grouped by Epics | `03_stories_{slug}.md` |
@@ -199,6 +201,7 @@ Full traceability: FR → US → UC → AC → NFR → Entity → ADR → API
 | — | `/estimate` | Effort estimation — Fibonacci SP, T-shirt sizes, or person-days | `00_estimate_{slug}.md` |
 | — | `/glossary` | Unified project glossary with terminology drift detection | `00_glossary_{slug}.md` |
 | — | `/export [format]` | Export User Stories to Jira / GitHub Issues / Linear / CSV | `export_{slug}_{format}.json` / `.csv` |
+| — | `/publish [format]` | Bundle artifacts for Notion (Markdown) and Confluence (HTML) — drag-and-drop import, no API tokens | `publish/notion/`, `publish/confluence/` |
 | — | `/risk` | Risk register — probability × impact matrix, mitigation per risk | `00_risks_{slug}.md` |
 | — | `/sprint` | Sprint plan — stories grouped by velocity and capacity with sprint goals | `00_sprint_{slug}.md` |
 
@@ -268,18 +271,23 @@ Every artifact links back to its predecessors, forming the chain `FR → US →
 
 ## Minimum viable pipeline
 
-Not every project needs all 21 skills. Two common paths:
+Not every project needs all 23 skills. Three common paths:
 
-**Lean** (fastest path to handoff — 9 steps):
+**Concept-first** (when you don't yet know what to build):
+```
+/discovery → /brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff
+```
+
+**Lean** (fastest path to handoff when you already have a project in mind — 9 steps):
 ```
 /brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff
 ```
 
-**Full** (complete traceability and quality gates — 15 steps):
+**Full** (complete traceability and quality gates — 16 steps):
 ```
-/principles → /brief → /srs → /stories → /usecases → /ac → /nfr → /datadict
-           → /research → /apicontract → /wireframes → /scenarios
-           → /trace → /analyze → /handoff
+/discovery → /principles → /brief → /srs → /stories → /usecases → /ac → /nfr → /datadict
+          → /research → /apicontract → /wireframes → /scenarios
+          → /trace → /analyze → /handoff
 ```
 
 Use `/clarify` at any step to resolve ambiguities before moving on. Approximate time per step is in [docs/USAGE.md#appendix-time-estimates](docs/USAGE.md#appendix-time-estimates).

package/bin/ba-toolkit.js

@@ -21,7 +21,7 @@ const PKG = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'),
 // All five supported agents — Claude Code, Codex CLI, Gemini CLI,
 // Cursor, and Windsurf — load Agent Skills as direct subfolders of
 // their skills root: `<skills-root>/<skill-name>/SKILL.md`. The toolkit
-// installs the 21 skills natively in this layout for every agent. No
+// installs the 23 skills natively in this layout for every agent. No
 // .mdc conversion. Confirmed against the Agent Skills documentation
 // for each platform via ctx7 MCP / official docs.
 //
@@ -523,6 +523,7 @@ function stringFlag(args, key) {
 const KNOWN_FLAGS = new Set([
   'name', 'slug', 'domain', 'for', 'no-install',
   'global', 'project', 'dry-run',
+  'format', 'out',
   'version', 'v', 'help', 'h',
 ]);
 
@@ -1008,19 +1009,22 @@ async function cmdInit(args) {
     log('    2. ' + bold(`cd ${outputDir}`) + ' — open your AI agent in this folder.');
     log('       Each project has its own AGENTS.md, so two agent windows');
     log('       can work on two different projects in the same repo.');
-    log('    3. Optional: run /principles to define project-wide conventions');
+    log('    3. Optional: run /discovery if you do not yet know what to build,');
+    log('       or /principles to define project-wide conventions');
     log('    4. Run /brief to start the BA pipeline');
   } else if (installed === false) {
     log('    1. Skill install was cancelled. To install later, run:');
     log('         ' + gray(`ba-toolkit install --for ${agentId}`));
     log('    2. ' + bold(`cd ${outputDir}`) + ' and open your AI agent there.');
-    log('    3. Optional: run /principles to define project-wide conventions');
+    log('    3. Optional: run /discovery if you do not yet know what to build,');
+    log('       or /principles to define project-wide conventions');
     log('    4. Run /brief to start the BA pipeline');
   } else {
     log('    1. Install skills for your agent:');
     log('         ' + gray('ba-toolkit install --for claude-code'));
     log('    2. ' + bold(`cd ${outputDir}`) + ' and open your AI agent there.');
-    log('    3. Optional: run /principles to define project-wide conventions');
+    log('    3. Optional: run /discovery if you do not yet know what to build,');
+    log('       or /principles to define project-wide conventions');
     log('    4. Run /brief to start the BA pipeline');
   }
   log('');
@@ -1061,7 +1065,7 @@ function writeManifest(destDir, items) {
 }
 
 // Detect the v1.x install layout: every previous install path nested
-// our 21 skills under an extra `ba-toolkit/` folder, which made them
+// the v1.x skills under an extra `ba-toolkit/` folder, which made them
 // invisible to every agent's skill loader. Returns the absolute paths
 // of any legacy folders that still exist for the given agent, so the
 // caller can warn the user to clean them up before installing v2.0.
@@ -1472,6 +1476,385 @@ async function cmdUninstall(args) {
   log('');
 }
 
+// --- Publish (Notion / Confluence export) ------------------------------
+
+// Escape the four HTML special characters that matter inside text
+// content. Used by markdownToHtml everywhere user-controlled text is
+// emitted into an HTML attribute or body. Keep this list short and
+// uncontroversial — any further entity table belongs in a real HTML
+// library, which we deliberately avoid (zero deps).
+function htmlEscape(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// GitHub-style heading slug: lowercase, spaces → dashes, drop everything
+// that isn't a word char or dash. Used to give every heading a stable
+// `id` so cross-references like `02_srs.html#fr-001` resolve.
+function slugifyHeading(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-');
+}
+
+// Convert the BA Toolkit subset of Markdown to plain HTML. Scope is
+// intentionally small (no nested lists, no images, no raw HTML, no
+// reference-style links, no footnotes) — these features don't appear in
+// any shipped artifact template. The aim is a converter small enough to
+// audit by hand and fully covered by snapshot tests.
+//
+// Block pass: walk lines, group them into blocks (paragraph, heading,
+// list, table, fenced code, blockquote, hr). Inline pass: rewrite
+// emphasis, links and code spans inside each block's text content.
+function markdownToHtml(src) {
+  const lines = String(src).replace(/\r\n/g, '\n').split('\n');
+  const out = [];
+  let i = 0;
+
+  // Inline-rewrite a single line of text. Order matters: extract code
+  // spans first so we don't touch their contents, then links, then
+  // emphasis. Each step replaces the matched span with a placeholder,
+  // and a final pass swaps placeholders back so emphasis inside link
+  // text still resolves.
+  function inline(text) {
+    const placeholders = [];
+    const stash = (html) => {
+      placeholders.push(html);
+      return `\u0000${placeholders.length - 1}\u0000`;
+    };
+    // Code spans `x` — stashed first so their contents are immune to
+    // every other inline rule.
+    text = text.replace(/`([^`\n]+)`/g, (_, code) => stash(`<code>${htmlEscape(code)}</code>`));
+    // Links [text](url) — also stashed so the raw <a> tag survives the
+    // final htmlEscape pass.
+    text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, label, url) => {
+      // Recursively inline-format the label so emphasis inside links works.
+      const inner = inline(label);
+      return stash(`<a href="${htmlEscape(url)}">${inner}</a>`);
+    });
+    // Bold **x** — stash, otherwise the trailing htmlEscape would
+    // re-escape the `<strong>` tags we just emitted.
+    text = text.replace(/\*\*([^*\n]+)\*\*/g, (_, body) => stash(`<strong>${htmlEscape(body)}</strong>`));
+    // Italic *x* and _x_ — same stashing rule. Narrow patterns avoid
+    // eating any leftover ** (there are none after the bold pass, but
+    // the guard keeps the regex robust against pathological input).
+    text = text.replace(/(^|[^*])\*([^*\n]+)\*(?!\*)/g, (_, pre, body) => `${pre}${stash(`<em>${htmlEscape(body)}</em>`)}`);
+    text = text.replace(/(^|[^_])_([^_\n]+)_(?!_)/g, (_, pre, body) => `${pre}${stash(`<em>${htmlEscape(body)}</em>`)}`);
+    // Escape every character that survived the stashing passes. The
+    // placeholder marker \u0000 is not in the escape list and the
+    // ASCII digits inside the marker are also unaffected, so the swap
+    // below still finds them.
+    text = htmlEscape(text);
+    // Restore placeholders.
+    text = text.replace(/\u0000(\d+)\u0000/g, (_, idx) => placeholders[Number(idx)]);
+    return text;
+  }
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Blank lines separate blocks; collapse runs of them.
+    if (/^\s*$/.test(line)) { i++; continue; }
+
+    // Fenced code block ```lang
+    const fenceMatch = /^```(\w*)\s*$/.exec(line);
+    if (fenceMatch) {
+      const lang = fenceMatch[1];
+      const body = [];
+      i++;
+      while (i < lines.length && !/^```\s*$/.test(lines[i])) {
+        body.push(lines[i]);
+        i++;
+      }
+      // Skip the closing fence (or accept EOF as the close).
+      if (i < lines.length) i++;
+      const cls = lang ? ` class="language-${htmlEscape(lang)}"` : '';
+      out.push(`<pre><code${cls}>${htmlEscape(body.join('\n'))}</code></pre>`);
+      continue;
+    }
+
+    // Heading # … ######
+    const headingMatch = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const text = headingMatch[2].trim();
+      const id = slugifyHeading(text);
+      out.push(`<h${level} id="${htmlEscape(id)}">${inline(text)}</h${level}>`);
+      i++;
+      continue;
+    }
+
+    // Horizontal rule
+    if (/^---+\s*$/.test(line)) {
+      out.push('<hr>');
+      i++;
+      continue;
+    }
+
+    // Table — header row + alignment row + body rows. We require both
+    // the header and the alignment row to exist; otherwise treat the
+    // line as a paragraph.
+    if (/^\|.*\|\s*$/.test(line) && i + 1 < lines.length && /^\|[\s:|-]+\|\s*$/.test(lines[i + 1])) {
+      const splitRow = (row) => row.replace(/^\||\|\s*$/g, '').split('|').map((c) => c.trim());
+      const header = splitRow(line);
+      i += 2; // skip header + alignment
+      const body = [];
+      while (i < lines.length && /^\|.*\|\s*$/.test(lines[i])) {
+        body.push(splitRow(lines[i]));
+        i++;
+      }
+      const thead = '<thead><tr>' + header.map((c) => `<th>${inline(c)}</th>`).join('') + '</tr></thead>';
+      const tbody = body.length > 0
+        ? '<tbody>' + body.map((row) => '<tr>' + row.map((c) => `<td>${inline(c)}</td>`).join('') + '</tr>').join('') + '</tbody>'
+        : '';
+      out.push(`<table>${thead}${tbody}</table>`);
+      continue;
+    }
+
+    // Blockquote
+    if (/^>\s?/.test(line)) {
+      const body = [];
+      while (i < lines.length && /^>\s?/.test(lines[i])) {
+        body.push(lines[i].replace(/^>\s?/, ''));
+        i++;
+      }
+      out.push(`<blockquote><p>${inline(body.join(' '))}</p></blockquote>`);
+      continue;
+    }
+
+    // Unordered list
+    if (/^[-*]\s+/.test(line)) {
+      const items = [];
+      while (i < lines.length && /^[-*]\s+/.test(lines[i])) {
+        items.push(lines[i].replace(/^[-*]\s+/, ''));
+        i++;
+      }
+      out.push('<ul>' + items.map((it) => `<li>${inline(it)}</li>`).join('') + '</ul>');
+      continue;
+    }
+
+    // Ordered list
+    if (/^\d+\.\s+/.test(line)) {
+      const items = [];
+      while (i < lines.length && /^\d+\.\s+/.test(lines[i])) {
+        items.push(lines[i].replace(/^\d+\.\s+/, ''));
+        i++;
+      }
+      out.push('<ol>' + items.map((it) => `<li>${inline(it)}</li>`).join('') + '</ol>');
+      continue;
+    }
+
+    // Default: paragraph (greedy until blank line or another block).
+    const para = [];
+    while (i < lines.length && !/^\s*$/.test(lines[i]) && !/^#{1,6}\s/.test(lines[i]) &&
+           !/^```/.test(lines[i]) && !/^[-*]\s/.test(lines[i]) && !/^\d+\.\s/.test(lines[i]) &&
+           !/^>\s?/.test(lines[i]) && !/^---+\s*$/.test(lines[i]) &&
+           !(/^\|.*\|\s*$/.test(lines[i]) && i + 1 < lines.length && /^\|[\s:|-]+\|\s*$/.test(lines[i + 1]))) {
+      para.push(lines[i]);
+      i++;
+    }
+    out.push(`<p>${inline(para.join(' '))}</p>`);
+  }
+
+  return out.join('\n');
+}
+
+// Match every BA Toolkit artifact filename in a project output dir:
+// `00_discovery_<slug>.md`, `00_principles_<slug>.md`, `01_brief_<slug>.md`,
+// `07a_research_<slug>.md`, `11_handoff_<slug>.md`, `00_risks_<slug>.md`,
+// etc. The pattern is intentionally permissive — anything that starts
+// with two digits (and an optional letter) followed by `_<word>_` is
+// in.
+const ARTIFACT_FILE_RE = /^\d{2}[a-z]?_[a-z]+_.*\.md$/;
+
+// Numeric-aware sort: 01 < 02 < … < 07 < 07a < 08 < … < 11. Strips the
+// suffix letter and uses it only as a tiebreaker so `7a` always sorts
+// after `7` and before `8`.
+function compareArtifactFilenames(a, b) {
+  const m1 = /^(\d{2})([a-z]?)/.exec(a);
+  const m2 = /^(\d{2})([a-z]?)/.exec(b);
+  const n1 = parseInt(m1[1], 10);
+  const n2 = parseInt(m2[1], 10);
+  if (n1 !== n2) return n1 - n2;
+  if (m1[2] !== m2[2]) return m1[2] < m2[2] ? -1 : 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// Rewrite intra-project markdown links inside an artifact body so they
+// survive the import. Mode is one of:
+//   'notion'     — `[txt](02_srs_x.md#anchor)` → `[txt](./02_srs_x.md#anchor)`
+//                  Notion's bulk markdown importer resolves relative
+//                  links between files in the same import batch.
+//   'confluence' — `[txt](02_srs_x.md#anchor)` → `[txt](02_srs_x.html#anchor)`
+//                  HTML import expects sibling .html filenames.
+// External links (http, https, mailto) and anchors-only (#fr-001) pass
+// through unchanged.
+function rewriteLinks(body, mode) {
+  return String(body).replace(/\[([^\]]+)\]\(([^)]+)\)/g, (full, label, url) => {
+    if (/^(https?:|mailto:|#|\/)/i.test(url)) return full;
+    if (!/\.md(\b|$|#)/.test(url)) return full;
+    if (mode === 'notion') {
+      const target = url.startsWith('./') || url.startsWith('../') ? url : './' + url;
+      return `[${label}](${target})`;
+    }
+    if (mode === 'confluence') {
+      const target = url.replace(/\.md(\b|$|#)/, '.html$1');
+      return `[${label}](${target})`;
+    }
+    return full;
+  });
+}
+
+// Strip the managed-block markers that `init` writes into AGENTS.md so
+// the imported page doesn't render the HTML comments as visible text in
+// importers that don't strip comments. Everything between the markers
+// (including the markers themselves) is removed.
+function stripManagedBlock(body) {
+  return String(body).replace(
+    /<!-- ba-toolkit:begin managed -->[\s\S]*?<!-- ba-toolkit:end managed -->\s*/g,
+    '',
+  );
+}
+
+async function cmdPublish(args) {
+  const formatRaw = (stringFlag(args, 'format') || 'both').toLowerCase();
+  const validFormats = new Set(['notion', 'confluence', 'both']);
+  if (!validFormats.has(formatRaw)) {
+    logError(`Unknown --format value: ${formatRaw}`);
+    log('  Valid formats: ' + cyan('notion') + ', ' + cyan('confluence') + ', ' + cyan('both'));
+    process.exit(1);
+  }
+  const dryRun = args.flags['dry-run'] === true;
+  const cwd = process.cwd();
+  const outDir = stringFlag(args, 'out')
+    ? path.resolve(cwd, stringFlag(args, 'out'))
+    : path.join(cwd, 'publish');
+
+  const allFiles = fs.readdirSync(cwd);
+  const artifacts = allFiles.filter((f) => ARTIFACT_FILE_RE.test(f)).sort(compareArtifactFilenames);
+  const hasAgents = allFiles.includes('AGENTS.md');
+
+  if (artifacts.length === 0) {
+    logError(`No BA Toolkit artifacts found in ${cwd}.`);
+    log('  Run this command from inside ' + cyan('output/<slug>/') + ' after generating artifacts.');
+    process.exit(1);
+  }
+
+  log('');
+  log('  ' + cyan('BA Toolkit — Publish'));
+  log('  ' + cyan('===================='));
+  log('');
+  log(`  source:       ${cwd}`);
+  log(`  destination:  ${outDir}`);
+  log(`  format:       ${formatRaw}`);
+  log(`  artifacts:    ${artifacts.length}${hasAgents ? ' (+ AGENTS.md)' : ''}`);
+  if (dryRun) log('  ' + yellow('mode:         dry-run (no files will be written)'));
+  log('');
+
+  const writeFile = (relPath, body) => {
+    const abs = path.join(outDir, relPath);
+    if (dryRun) {
+      log('    ' + gray('would write ') + path.relative(cwd, abs));
+      return;
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, body);
+  };
+
+  // Build the ordered file list once. AGENTS.md goes first if present
+  // so the imported workspace has project context up top.
+  const ordered = [];
+  if (hasAgents) ordered.push('AGENTS.md');
+  ordered.push(...artifacts);
+
+  let notionCount = 0;
+  let confluenceCount = 0;
+
+  if (formatRaw === 'notion' || formatRaw === 'both') {
+    for (const filename of ordered) {
+      let body = fs.readFileSync(path.join(cwd, filename), 'utf8');
+      if (filename === 'AGENTS.md') body = stripManagedBlock(body);
+      body = rewriteLinks(body, 'notion');
+      writeFile(path.join('notion', filename), body);
+      notionCount++;
+    }
+  }
+
+  if (formatRaw === 'confluence' || formatRaw === 'both') {
+    const indexEntries = [];
+    for (const filename of ordered) {
+      let body = fs.readFileSync(path.join(cwd, filename), 'utf8');
+      if (filename === 'AGENTS.md') body = stripManagedBlock(body);
+      body = rewriteLinks(body, 'confluence');
+      const html = markdownToHtml(body);
+      const htmlName = filename.replace(/\.md$/, '.html');
+      // Per-page wrapper. No <head> styles — let Confluence's own page
+      // styling take over after import. Title comes from the filename
+      // so the importer has something to use.
+      const title = filename.replace(/\.md$/, '');
+      const page = `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>${htmlEscape(title)}</title></head>
+<body>
+${html}
+</body>
+</html>`;
+      writeFile(path.join('confluence', htmlName), page);
+      indexEntries.push({ htmlName, title });
+      confluenceCount++;
+    }
+    // index.html — entry point for Confluence's HTML importer. Lists
+    // every page in pipeline order with a basic style block so the
+    // import preview is readable.
+    const indexHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>BA Toolkit — project artifacts</title>
+<style>
+  body { font-family: -apple-system, sans-serif; max-width: 720px; margin: 2em auto; padding: 0 1em; color: #222; }
+  h1 { border-bottom: 1px solid #ddd; padding-bottom: 0.3em; }
+  ul { line-height: 1.8; }
+  a { color: #0052cc; text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  code { background: #f4f5f7; padding: 0.1em 0.3em; border-radius: 3px; font-family: monospace; }
+</style>
+</head>
+<body>
+<h1>BA Toolkit — project artifacts</h1>
+<p>Generated by <code>ba-toolkit publish</code>. Each link below becomes a page in the imported Confluence space.</p>
+<ul>
+${indexEntries.map((e) => `  <li><a href="${htmlEscape(e.htmlName)}">${htmlEscape(e.title)}</a></li>`).join('\n')}
+</ul>
+</body>
+</html>`;
+    writeFile(path.join('confluence', 'index.html'), indexHtml);
+    confluenceCount++;
+  }
+
+  log('');
+  if (formatRaw === 'notion' || formatRaw === 'both') {
+    log(`  ${green('✓')} Notion bundle:      ${path.relative(cwd, path.join(outDir, 'notion'))}/  (${notionCount} files)`);
+  }
+  if (formatRaw === 'confluence' || formatRaw === 'both') {
+    log(`  ${green('✓')} Confluence bundle:  ${path.relative(cwd, path.join(outDir, 'confluence'))}/  (${confluenceCount} files, including index.html)`);
+  }
+  log('');
+  log('  ' + bold('Next steps:'));
+  if (formatRaw === 'notion' || formatRaw === 'both') {
+    log('    Notion:     drag-and-drop ' + cyan(path.relative(cwd, path.join(outDir, 'notion')) + '/') + ' into "Import → Markdown & CSV" in your workspace.');
+  }
+  if (formatRaw === 'confluence' || formatRaw === 'both') {
+    log('    Confluence: zip ' + cyan(path.relative(cwd, path.join(outDir, 'confluence')) + '/') + ' and upload via "Space settings → Content tools → Import → HTML".');
+  }
+  log('');
+}
+
 function cmdHelp() {
   log(`${bold('ba-toolkit')} v${PKG.version} — AI-powered Business Analyst pipeline
 
@@ -1497,6 +1880,12 @@ ${bold('COMMANDS')}
                                  supported agent (project + global) and
                                  report which versions are installed where.
                                  Read-only; no flags.
+  publish [--format <fmt>]       Bundle the artifacts in the current
+                                 output/<slug>/ folder into import-ready
+                                 files for Notion (markdown) and Confluence
+                                 (HTML). Format: notion, confluence, or
+                                 both (default). No API calls, no tokens —
+                                 the user runs the actual import manually.
 
 ${bold('OPTIONS')}
   --name <name>                  init only — skip the project name prompt
@@ -1514,8 +1903,12 @@ ${bold('OPTIONS')}
   --project                      install/uninstall/upgrade — target the
                                  project-level install (default when the
                                  agent supports it)
-  --dry-run                      init/install/uninstall/upgrade — preview
-                                 without writing or removing files
+  --dry-run                      init/install/uninstall/upgrade/publish —
+                                 preview without writing or removing files
+  --format <fmt>                 publish only — notion, confluence, or both
+                                 (default: both)
+  --out <path>                   publish only — output directory for the
+                                 bundles (default: ./publish/)
 
 ${bold('GENERAL OPTIONS')}
   --version, -v                  Print version and exit
@@ -1547,6 +1940,12 @@ ${bold('EXAMPLES')}
   # See where (and which version) BA Toolkit is installed.
   ba-toolkit status
 
+  # Bundle a project's artifacts for Notion + Confluence import.
+  cd output/my-app
+  ba-toolkit publish
+  ba-toolkit publish --format notion --out ./share
+  ba-toolkit publish --format confluence --dry-run
+
 ${bold('LEARN MORE')}
   https://github.com/TakhirKudusov/ba-toolkit
 `);
@@ -1586,6 +1985,9 @@ async function main() {
     case 'status':
       cmdStatus();
       break;
+    case 'publish':
+      await cmdPublish(args);
+      break;
     case 'help':
       cmdHelp();
       break;
@@ -1616,6 +2018,13 @@ module.exports = {
   mergeAgentsMd,
   menuStep,
   renderMenu,
+  markdownToHtml,
+  htmlEscape,
+  slugifyHeading,
+  rewriteLinks,
+  stripManagedBlock,
+  compareArtifactFilenames,
+  ARTIFACT_FILE_RE,
   KNOWN_FLAGS,
   DOMAINS,
   AGENTS,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "3.1.1",
-  "description": "AI-powered Business Analyst pipeline — 21 skills from project brief to development handoff. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
+  "version": "3.2.0",
+  "description": "AI-powered Business Analyst pipeline — 23 skills from concept discovery to development handoff, with one-command Notion + Confluence publish. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
   "keywords": [
     "business-analyst",
     "requirements",

package/skills/brief/SKILL.md

@@ -22,6 +22,8 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 No prior artifacts required. If `01_brief_*.md` already exists, warn the user and offer to overwrite or create a new project.
 
+If `00_discovery_*.md` exists in the output directory, load it as concept context. Extract the problem space (section 1), target audience hypotheses (section 2), recommended domain (section 3), MVP feature hypotheses (section 5), and the scope hint from section 8, and use them to pre-fill the structured interview questions per protocol rule 9. Skip any required topic that the discovery artifact already answers — only ask the user about gaps and open validation questions. Acknowledge the discovery hand-off in one line at the start of the interview so the user knows their concept work was loaded.
+
 If `00_principles_*.md` exists in the output directory, load it and apply its conventions for this and all subsequent pipeline steps (artifact language, ID format, traceability requirements, Definition of Ready, quality gate threshold).
 
 ### 3. Domain selection

package/skills/discovery/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: discovery
+description: >
+  Brain-storm an initial product concept when the user does not yet know what to build, which domain to choose, or which features matter. Use on /discovery command, or when the user asks to "brainstorm an idea", "explore a concept", "validate a project hypothesis", "I'm not sure what to build", "discovery phase", "concept exploration", "shape an idea before the brief". Optional first step of the BA Toolkit pipeline — runs before /brief and /principles. Produces a written concept artifact and recommends a domain, project name, slug, and scope hint to carry into /brief.
+---
+
+# /discovery — Concept Discovery
+
+Optional entry point of the BA Toolkit pipeline. Runs **before** `/brief` for users who arrive with only a vague hunch — no fixed domain, no committed feature list, no clear audience. Generates a structured concept artifact and ends with a concrete recommendation (domain, project name, slug, scope hint) that flows into `/brief` as inline context.
+
+The discovery artifact is a hypothesis document, not a commitment. Its sole job is to converge "I have an idea" into "I have a domain, an audience, and a candidate MVP scope" so the brief is productive instead of paralysing.
+
+## Workflow
+
+### 1. Environment detection
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory for the current platform. If the file is unavailable, apply the default rule: if `/mnt/user-data/outputs/` exists and is writable, save there (Claude.ai); otherwise save to the current working directory.
+
+### 2. Pipeline check
+
+If `00_discovery_*.md` already exists, load it and offer to:
+- View the current concept.
+- Amend a specific section (`/revise [section]`).
+- Regenerate from scratch.
+
+If `01_brief_*.md` already exists in the same output directory, the project has already moved past discovery. Warn the user that discovery is normally the first step and ask whether they really want to backfill a concept document (valid for retrospective concept docs, but uncommon).
+
+### 3. Domain catalog
+
+The 9 supported domain references live in `references/domains/` (`saas`, `fintech`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, `real-estate`, `igaming`). Discovery does **not** load a single domain reference up front — instead, it offers a shortlist of candidate domains during the interview and lets the user pick one. The chosen domain is recorded in section 8 of the artifact and becomes the working domain for `/brief`.
+
+If none of the 9 fits, record the recommended domain as `custom:{name}` and let `/brief` continue with general questions only.
+
+### 4. Interview
+
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/discovery` (e.g., `/discovery I think there's a need for a tool that helps freelance designers track invoices and chase late payments`), parse it as the lead-in answer, acknowledge it in one line, and skip directly to the first structured question that the inline text doesn't already cover.
+>
+> **Open-ended lead-in (protocol rule 8):** if there is NO inline text after `/discovery`, your very first interview question is open-ended and free-text, not a table — `What problem or opportunity are you exploring? Even a vague hunch is fine — one or two sentences about what you've noticed and who it bothers.`. After the user answers, switch to the structured table protocol for all subsequent questions and use the lead-in answer to pre-fill what you can.
+
+Cover 5–7 topics in 2 rounds. Do not generate the artifact until you can recommend a single domain with a defensible rationale.
+
+**Required topics:**
+1. Problem space — what pain point, gap, or opportunity is being explored.
+2. Target audience hypothesis — 1–2 candidate user segments, as concrete as possible.
+3. Domain shortlist — narrow to 1 of the 9 supported domains (or `custom`) with a one-line rationale; mark one row **Recommended** based on the problem/audience answers so far.
+4. Reference products and analogues — what already exists in this space (3–5 examples), and what's missing or done badly.
+5. MVP feature hypotheses — 5–10 candidate features for a first version. Bullet list, not committed scope.
+6. Differentiation angle — why this idea would beat the existing analogues (one or two sentences).
+7. Open validation questions — what we still don't know and would need to learn before committing (target users, willingness to pay, technical feasibility, etc.).
+
+If a topic was already covered by inline context or the lead-in answer, skip it — do not re-ask. Record any topic the user genuinely cannot answer as "unknown — to validate" and move on.
+
+### 5. Generation
+
+**File:** `00_discovery_{slug}.md` (slug — kebab-case, derived from the project name; if the user has not yet picked a name, propose 2–3 candidates and let them choose).
+
+```markdown
+# Discovery: {Project Name}
+
+**Slug:** {slug}
+**Date:** {date}
+**Status:** Concept (pre-brief)
+
+## 1. Problem Space
+
+{One or two paragraphs describing the pain point, gap, or opportunity.
+Focus on what's broken today, who feels the pain, and how often.}
+
+## 2. Target Audience Hypotheses
+
+- **Primary:** {concrete segment, e.g. "freelance UX designers in EU billing 5–20 clients/month"}
+- **Secondary:** {optional second segment if the interview surfaced one}
+
+## 3. Candidate Domains
+
+| Domain | Rationale | Fit |
+|--------|-----------|-----|
+| {domain-1} | {one line} | {High / Medium / Low} |
+| {domain-2} | {one line} | {High / Medium / Low} |
+| {domain-3} | {one line} | {High / Medium / Low} |
+
+**Recommended domain:** `{chosen-domain}` — {one-line justification anchored in the problem space and audience}.
+
+## 4. Reference Products and Analogues
+
+| Product | What it does well | What it does badly / misses |
+|---------|-------------------|------------------------------|
+| {name-1} | {one line} | {one line} |
+| {name-2} | {one line} | {one line} |
+| {name-3} | {one line} | {one line} |
+
+## 5. MVP Feature Hypotheses
+
+Candidate features for a first version. Not committed scope — `/brief` and `/srs` will refine and prioritise.
+
+- {feature 1}
+- {feature 2}
+- {feature 3}
+- {feature 4}
+- {feature 5}
+- {…}
+
+## 6. Differentiation Angle
+
+{One or two sentences on why this idea is worth pursuing given the analogues in section 4. Concrete, not "better UX" or "cheaper".}
+
+## 7. Open Validation Questions
+
+Things we don't yet know and need to learn before committing real resources.
+
+- {question 1 — e.g. "Will the primary segment pay $X/month?"}
+- {question 2}
+- {question 3}
+
+## 8. Recommended Next Step
+
+- **Project name:** {final name}
+- **Slug:** {final slug}
+- **Domain:** {chosen domain}
+- **Scope hint for `/brief`:** {one-sentence summary that the user can paste as inline context: `/brief {scope hint}`}
+- **Suggested first interview focus in `/brief`:** {1–2 topics from the discovery artifact that are now firm enough to anchor the brief}
+```
+
+### 6. AGENTS.md update
+
+`ba-toolkit init` already created `AGENTS.md` next to where the artifact lives — typically in the current working directory (the user is expected to `cd output/<slug>` after running init). After saving `00_discovery_{slug}.md`, find the project's `AGENTS.md` (look in cwd first; fall back to walking up the directory tree if cwd has none, for legacy v3.0 single-project layouts).
+
+**Update only the `## Pipeline Status` row for `/discovery`** — toggle its status from `⬜ Not started` to `✅ Done` and fill in the artifact filename in the `File` column. **Do not touch the managed block** (`<!-- ba-toolkit:begin managed -->` … `<!-- ba-toolkit:end managed -->`) — that's owned by `ba-toolkit init`. **Do not recreate the file at the repo root.** **Do not add `## Artifacts` / `## Key context` sections** — those are not part of the v3.1+ template and would be ignored by future runs.
+
+If you find no `AGENTS.md` at all (neither in cwd nor up the tree), warn the user that the project was likely set up before v3.2 and tell them to run `ba-toolkit init --name "..." --slug {slug}` to scaffold the per-project `AGENTS.md`. Do not create one yourself with arbitrary structure.
+
+If the existing `AGENTS.md` predates v3.2 and has no `/discovery` row in its Pipeline Status table, prepend a new row at stage `0` (and renumber the existing `/principles` row to `0a`) — same convention used by `/research` at stage `7a`. Mention the migration in your reply so the user knows their AGENTS.md was updated.
+
+### 7. Iterative refinement
+
+- `/revise [section]` — rewrite a section.
+- `/expand [section]` — add detail.
+- `/clarify [focus]` — targeted ambiguity pass.
+- `/validate` — check completeness and consistency.
+- `/done` — finalize and update `AGENTS.md`. Next step: `/brief`.
+
+### 8. Closing message
+
+After saving the artifact, present the following summary to the user (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Recommended domain, project name, and slug — confirmed for the pipeline.
+- Count of MVP feature hypotheses captured.
+- List of open validation questions.
+
+Available commands for this artifact: `/clarify [focus]` · `/revise [section]` · `/expand [section]` · `/validate` · `/done`
+
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (look up the row where `Current` is `/discovery`). Do not hardcode `/brief` here — the table is the single source of truth. If the user wants stricter conventions before the brief (e.g. specific traceability rules or definition-of-ready policies), suggest running `/principles` between `/discovery` and `/brief`.
+
+## Style
+
+Formal, neutral, hypothesis-driven. No emoji, slang, or evaluative language ("amazing", "game-changing"). Frame every claim as a hypothesis to validate, not a fact. Generate the artifact in the language of the user's request. Section headings, table headers, and labels also in the user's language.

package/skills/publish/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: publish
+description: >
+  Bundle BA Toolkit artifacts into import-ready files for documentation tools — Notion (markdown bundle) and Confluence (HTML bundle). Use on /publish command, or when the user asks to "export to Notion", "export to Confluence", "publish artifacts", "share with stakeholders", "import into Notion", "import into Confluence", "send the docs to product team". Cross-cutting utility — does not advance the pipeline.
+---
+
+# /publish — Notion / Confluence Publish
+
+Cross-cutting utility skill. Wraps the `ba-toolkit publish` CLI subcommand, which converts the markdown artifacts in the current `output/<slug>/` folder into folders ready to be dragged into Notion's **Import → Markdown & CSV** dialog or zipped and uploaded via Confluence's **Space settings → Content tools → Import → HTML** tool.
+
+The conversion happens entirely on disk — **no API calls, no tokens, no network**. The user does the actual upload manually using each tool's native importer.
+
+## When to use
+
+After generating at least one pipeline artifact (`01_brief_*.md` or later), when the user wants to share the artifacts with non-developer stakeholders who live in Notion or Confluence rather than in the codebase.
+
+This is **not** the same as `/export`. `/export` produces JSON/CSV for issue trackers (Jira, GitHub Issues, Linear). `/publish` produces markdown/HTML page bundles for documentation tools (Notion, Confluence).
+
+## Workflow
+
+### 1. Environment detection
+
+The `ba-toolkit publish` subcommand uses the current working directory as the source — no `references/environment.md` lookup needed. Confirm with the user that they are inside their project's `output/<slug>/` folder before running it. If they are not, ask them to `cd output/<slug>` first.
+
+### 2. Pipeline check
+
+Verify at least one BA Toolkit artifact exists in cwd by listing files matching `[0-9][0-9]*_*.md` (e.g. `01_brief_<slug>.md`). If no artifacts are present, stop and tell the user to run `/brief` (or any later pipeline step) first — there is nothing to publish.
+
+### 3. Format selection
+
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/publish` (e.g., `/publish notion`, `/publish to confluence`, `/publish both`), parse it as the format choice and skip the question entirely.
+
+If no format is given, ask:
+
+> Which target do you want?
+>
+> | ID | Variant                                              |
+> |----|------------------------------------------------------|
+> | a  | Both Notion and Confluence **Recommended**           |
+> | b  | Notion only                                          |
+> | c  | Confluence only                                      |
+> | d  | Other — type your own answer                         |
+
+Map the answer to a `--format` value: `a` → `both`, `b` → `notion`, `c` → `confluence`. For free-text answers, accept the verbatim string only if it is one of `notion`, `confluence`, or `both`; otherwise re-ask.
+
+### 4. Execution
+
+Invoke the CLI subcommand via the agent's Bash tool from the project's `output/<slug>/` directory:
+
+```bash
+ba-toolkit publish --format <choice>
+```
+
+Optional flags the user might ask for:
+
+- `--out <path>` — write the bundles somewhere other than `./publish/`.
+- `--dry-run` — preview the file list without writing anything.
+
+Capture stdout from the command and report it back to the user. The CLI prints a summary of bundle paths, file counts, and the next manual import steps.
+
+### 5. Closing message
+
+Cross-cutting closing block (no `Next step:` line — see `references/closing-message.md` "Cross-cutting commands" section). Show:
+
+- Saved bundle paths and counts per format (taken verbatim from the CLI's stdout summary).
+- The two static "Next steps" lines:
+  - **Notion:** drag-and-drop `publish/notion/` into "Import → Markdown & CSV" in your Notion workspace.
+  - **Confluence:** zip `publish/confluence/` and upload via "Space settings → Content tools → Import → HTML".
+- Optional one-line "Re-run after pipeline updates" hint: re-running `ba-toolkit publish` overwrites the previous bundle, so users can publish again after `/clarify`, `/revise`, or any later pipeline step.
+
+Available commands for this skill: `/publish [format]`
+
+Do not build a `Next step:` block — `/publish` is cross-cutting and does not advance the pipeline.
+
+## Style
+
+Formal, neutral. No emoji. Generate the chat reply in the language of the user's first message. Keep the report under 10 lines: paths, counts, two next-step lines, optional re-run hint.

package/skills/references/closing-message.md

@@ -43,6 +43,7 @@ Skills use this table as the single source of truth for the `Next step:` block.
 
 | Current      | Next            | What it produces                                                | Time         | After that                                          |
 |--------------|-----------------|-----------------------------------------------------------------|--------------|-----------------------------------------------------|
+| /discovery   | /brief          | Project Brief — goals, audience, stakeholders, constraints      | 20–35 min    | /srs — Requirements Specification (IEEE 830)        |
 | /principles  | /brief          | Project Brief — goals, audience, stakeholders, constraints      | 20–35 min    | /srs — Requirements Specification (IEEE 830)        |
 | /brief       | /srs            | Requirements Specification (IEEE 830) — scope, FRs, MoSCoW      | 25–40 min    | /stories — User Stories grouped by Epics            |
 | /srs         | /stories        | User Stories grouped by Epics, with priority and FR refs        | 20–30 min    | /usecases — Use Cases with main/alt/exception flows |
@@ -67,6 +68,7 @@ These skills do not advance the pipeline — they update or report on existing a
 - `/estimate` — effort estimation
 - `/glossary` — glossary maintenance
 - `/export` — export to Jira / GitHub Issues / Linear / CSV
+- `/publish` — bundle artifacts for Notion (Markdown) or Confluence (HTML) import
 - `/risk` — risk register
 - `/sprint` — sprint plan
 

package/skills/references/templates/agents-template.md

@@ -16,7 +16,8 @@
 
 | Stage | Skill | Status | File |
 |-------|-------|--------|------|
-| 0 | /principles | ⬜ Not started | — |
+| 0 | /discovery | ⬜ Not started | — |
+| 0a | /principles | ⬜ Not started | — |
 | 1 | /brief | ⬜ Not started | — |
 | 2 | /srs | ⬜ Not started | — |
 | 3 | /stories | ⬜ Not started | — |
@@ -42,6 +43,7 @@ Utilities available throughout the pipeline. No fixed stage — invoke whenever
 | /estimate | Effort estimation — Fibonacci SP, T-shirt sizes, or person-days |
 | /glossary | Unified project glossary with terminology drift detection |
 | /export [format] | Export User Stories to Jira / GitHub Issues / Linear / CSV |
+| /publish [format] | Bundle artifacts for Notion (Markdown) or Confluence (HTML) — drag-and-drop import |
 | /risk | Risk register — probability × impact matrix, mitigation per risk |
 | /sprint | Sprint plan — stories grouped by velocity and capacity with sprint goals |
 

package/skills/references/templates/discovery-template.md

@@ -0,0 +1,63 @@
+# Discovery: [PROJECT_NAME]
+
+**Slug:** [SLUG]
+**Date:** [DATE]
+**Status:** Concept (pre-brief)
+
+## 1. Problem Space
+
+[One or two paragraphs describing the pain point, gap, or opportunity. Focus on what is broken today, who feels the pain, and how often it bites.]
+
+## 2. Target Audience Hypotheses
+
+- **Primary:** [concrete segment — role, context, scale]
+- **Secondary:** [optional second segment if relevant]
+
+## 3. Candidate Domains
+
+| Domain | Rationale | Fit |
+|--------|-----------|-----|
+| [domain-1] | [one-line reason this domain might fit] | High / Medium / Low |
+| [domain-2] | [one-line reason] | High / Medium / Low |
+| [domain-3] | [one-line reason] | High / Medium / Low |
+
+**Recommended domain:** `[chosen-domain]` — [one-line justification anchored in the problem space and audience above].
+
+## 4. Reference Products and Analogues
+
+| Product | What it does well | What it does badly / misses |
+|---------|-------------------|------------------------------|
+| [name-1] | [one line] | [one line] |
+| [name-2] | [one line] | [one line] |
+| [name-3] | [one line] | [one line] |
+
+## 5. MVP Feature Hypotheses
+
+Candidate features for a first version. Not committed scope — `/brief` and `/srs` will refine and prioritise.
+
+- [feature 1]
+- [feature 2]
+- [feature 3]
+- [feature 4]
+- [feature 5]
+- [...]
+
+## 6. Differentiation Angle
+
+[One or two sentences on why this idea is worth pursuing given the analogues in section 4. Concrete and specific — not "better UX" or "cheaper".]
+
+## 7. Open Validation Questions
+
+Things we do not yet know and need to learn before committing real resources.
+
+- [question 1 — e.g. "Will the primary segment pay X per month?"]
+- [question 2]
+- [question 3]
+
+## 8. Recommended Next Step
+
+- **Project name:** [final name]
+- **Slug:** [final slug]
+- **Domain:** [chosen domain]
+- **Scope hint for `/brief`:** [one-sentence summary the user can paste as inline context: `/brief [scope hint]`]
+- **Suggested first interview focus in `/brief`:** [1–2 topics from this discovery doc that are now firm enough to anchor the brief]