@kudusov.takhir/ba-toolkit 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -11,6 +11,41 @@ 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
+
+- **Interview options table is now capped at 5 rows total** (`skills/references/interview-protocol.md` rule 3). Previously rule 3 allowed "3–5 variants per question" with the free-text "Other" row on top, so a single question could surface up to 6 options and overwhelm the user. The new cap is **up to 4 predefined variants + exactly 1 free-text "Other" row = 5 rows max**, no exceptions. Fewer than 4 predefined rows is still fine when the topic only has 2–3 sensible options. The one-line protocol summary in all 12 interview-phase skills (`brief`, `srs`, `stories`, `usecases`, `ac`, `nfr`, `datadict`, `apicontract`, `wireframes`, `scenarios`, `research`, `principles`) was updated to match. New regression test in `test/cli.test.js` walks every shipped SKILL.md with an Interview heading and fails if any of them carry the legacy `3–5 domain-appropriate options` wording or omit the new `5 rows max` reminder.
+- **Exactly one variant per question is now marked `**Recommended**`** (`skills/references/interview-protocol.md` new rule 10). The AI picks the row using, in priority order, (a) the loaded `references/domains/{domain}.md` for the current skill, (b) the user's prior interview answers, (c) the inline context from rule 9, (d) widely-accepted industry default. The free-text "Other" row is never recommended. If none of (a)–(d) gives a defensible choice the AI omits the marker entirely rather than guessing — a missing recommendation is better than a misleading one. Rendered as `**Recommended**` appended to the end of the `Variant` cell so it stays visible even when the table wraps. Translated together with the variant text per rule 11 (e.g. `**Рекомендуется**`, `**Recomendado**`). All 12 interview-phase SKILL.md summaries point at rule 10. New regression test in `test/cli.test.js` enforces that every Interview-section SKILL.md mentions the marker.
+- **Variant text and the `Variant` column header are now rendered in the user's language** (`skills/references/interview-protocol.md` new rule 11), matching the rule the generated artifacts already follow (`skills/brief/SKILL.md:107`). The `ID` column header and the letter IDs (`a`, `b`, …) stay ASCII. Domain reference files in `skills/references/domains/` remain English-only by design (per the project's English-only convention) — the AI translates the variants on the fly when rendering the table for a non-English-speaking user, instead of pasting the English source verbatim or asking the user which language to use. Updated example block in the protocol now shows both an English question with `**Recommended**` and a Russian rendering of the same question to make the rule concrete.
+- **Replaced `example/dragon-fortune/` with `example/lumen-goods/`**, a sustainable home-goods D2C e-commerce walkthrough. The new example is more universally relatable than the iGaming-themed predecessor: 15 cross-referenced artifacts (Brief, Principles, SRS, Stories, Use Cases, AC, NFRs, Data Dictionary, Tech Research, API Contract, Wireframes, Scenarios, Risk Register, Sprint Plan, Handoff) for a fictional D2C online store selling lighting, kitchenware, and textiles to eco-conscious EU/UK buyers. Stack covers Next.js storefront, Stripe (cards / Apple Pay / Klarna / SEPA), Stripe Tax for destination-based VAT, hybrid stock sync between an NL warehouse and a UK 3PL, GDPR/DSAR/cookie consent flows, and a paid Lumen Circle loyalty tier. CLAUDE.md "Do NOT touch" entry, the placeholder warning, the repo-layout block, and the README example table all updated to reference `lumen-goods`. The old `example/dragon-fortune/` folder has been removed.
+
+---
+
 ## [3.1.0] — 2026-04-09
 
 ### Highlights
@@ -440,7 +475,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.1.0...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
 [2.0.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.5.0...v2.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,25 +152,26 @@ Your generated artifacts (`01_brief_*.md`, `02_srs_*.md`, …) are untouched by
 
 ## Example output
 
-A complete example project — **Dragon Fortune** (iGaming Telegram Mini App) — lives in [`example/dragon-fortune/`](example/dragon-fortune/). 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 |
 |---------|------|
-| Project Principles | [`00_principles_dragon-fortune.md`](example/dragon-fortune/00_principles_dragon-fortune.md) |
-| Project Brief | [`01_brief_dragon-fortune.md`](example/dragon-fortune/01_brief_dragon-fortune.md) |
-| Requirements (SRS) | [`02_srs_dragon-fortune.md`](example/dragon-fortune/02_srs_dragon-fortune.md) |
-| User Stories | [`03_stories_dragon-fortune.md`](example/dragon-fortune/03_stories_dragon-fortune.md) |
-| Use Cases | [`04_usecases_dragon-fortune.md`](example/dragon-fortune/04_usecases_dragon-fortune.md) |
-| Acceptance Criteria | [`05_ac_dragon-fortune.md`](example/dragon-fortune/05_ac_dragon-fortune.md) |
-| Non-functional Requirements | [`06_nfr_dragon-fortune.md`](example/dragon-fortune/06_nfr_dragon-fortune.md) |
-| Data Dictionary | [`07_datadict_dragon-fortune.md`](example/dragon-fortune/07_datadict_dragon-fortune.md) |
-| Technology Research | [`07a_research_dragon-fortune.md`](example/dragon-fortune/07a_research_dragon-fortune.md) |
-| API Contract | [`08_apicontract_dragon-fortune.md`](example/dragon-fortune/08_apicontract_dragon-fortune.md) |
-| Wireframes | [`09_wireframes_dragon-fortune.md`](example/dragon-fortune/09_wireframes_dragon-fortune.md) |
-| Validation Scenarios | [`10_scenarios_dragon-fortune.md`](example/dragon-fortune/10_scenarios_dragon-fortune.md) |
-| Development Handoff | [`11_handoff_dragon-fortune.md`](example/dragon-fortune/11_handoff_dragon-fortune.md) |
-| Risk Register | [`00_risks_dragon-fortune.md`](example/dragon-fortune/00_risks_dragon-fortune.md) |
-| Sprint Plan | [`00_sprint_dragon-fortune.md`](example/dragon-fortune/00_sprint_dragon-fortune.md) |
+| 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) |
+| User Stories | [`03_stories_lumen-goods.md`](example/lumen-goods/03_stories_lumen-goods.md) |
+| Use Cases | [`04_usecases_lumen-goods.md`](example/lumen-goods/04_usecases_lumen-goods.md) |
+| Acceptance Criteria | [`05_ac_lumen-goods.md`](example/lumen-goods/05_ac_lumen-goods.md) |
+| Non-functional Requirements | [`06_nfr_lumen-goods.md`](example/lumen-goods/06_nfr_lumen-goods.md) |
+| Data Dictionary | [`07_datadict_lumen-goods.md`](example/lumen-goods/07_datadict_lumen-goods.md) |
+| Technology Research | [`07a_research_lumen-goods.md`](example/lumen-goods/07a_research_lumen-goods.md) |
+| API Contract | [`08_apicontract_lumen-goods.md`](example/lumen-goods/08_apicontract_lumen-goods.md) |
+| Wireframes | [`09_wireframes_lumen-goods.md`](example/lumen-goods/09_wireframes_lumen-goods.md) |
+| Validation Scenarios | [`10_scenarios_lumen-goods.md`](example/lumen-goods/10_scenarios_lumen-goods.md) |
+| Development Handoff | [`11_handoff_lumen-goods.md`](example/lumen-goods/11_handoff_lumen-goods.md) |
+| Risk Register | [`00_risks_lumen-goods.md`](example/lumen-goods/00_risks_lumen-goods.md) |
+| Sprint Plan | [`00_sprint_lumen-goods.md`](example/lumen-goods/00_sprint_lumen-goods.md) |
 
 Full traceability: FR → US → UC → AC → NFR → Entity → ADR → API → WF → Scenario, plus risk register and sprint plan.
 
@@ -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).