@kudusov.takhir/ba-toolkit 3.3.0 → 3.4.1

package/CHANGELOG.md

@@ -11,6 +11,34 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [3.4.1] — 2026-04-09
+
+### Fixed
+
+- **Content-hygiene audit pass after the v3.4.0 ship.** Five drift / staleness fixes flagged by a cross-file consistency check, all behaviour-neutral:
+  - **`skills/references/interview-protocol.md` "When this protocol applies"** — the enumerated list of interview-phase skills had drifted out of sync. `/discovery` (added in v3.2.0 with a literal `### 4. Interview` heading) was missing from the canonical list. Reordered the list to match the actual pipeline order (`discovery → principles → brief → srs → …`) and added `/discovery` to rule 8's "entry-point skills" sub-list alongside `/brief` and `/principles`. Added a follow-up paragraph documenting that `/publish` and `/implement-plan` also follow the protocol via differently-named sections (`### Format selection` and embedded calibration interview inside `### Tech stack resolution` respectively) — the existing `interview-protocol-link` regression test only matches a literal `Interview` heading, so these two skills are not auto-enforced and have to be kept in sync by hand.
+  - **`skills/discovery/SKILL.md` domain count** — two locations (the "Domain catalog" paragraph and required-topic 3) said "9 supported domain references" with the pre-v3.3.0 enumeration. Bumped to 12 and added the `edtech`, `govtech`, `ai-ml` references that shipped in v3.3.0.
+  - **`skills/wireframes/SKILL.md` closing message** — two places hardcoded "Pipeline complete" against the v3.1.0 single-source-of-truth rule (the `/done` description and the trailing line under "Available commands"). Wireframes is stage 9, not the terminal stage. Replaced with the standard "Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md`" instruction every other pipeline-stage skill uses.
+  - **`skills/scenarios/SKILL.md` closing message** — same pattern: hardcoded "Pipeline complete. Proceed to `/handoff`" line that bypassed the lookup table and was logically self-contradictory ("complete" + "proceed"). Replaced with the standard delegation. Existing `closing-message.md` lookup table already had the correct row, so the user-facing behaviour was already right when an AI agent followed the rules — the fix is purely about bringing the SKILL.md text into the same single-source-of-truth pattern.
+- **Existing regression tests still pass without modification** — the new `interview-protocol-link`, `closing-message-link`, `Recommended marker`, `5-rows-cap`, frontmatter parser, and skill-folder-count tests all auto-cover the edits since none of them changed the public surface area or the literal patterns the tests look for. 188/188 still green.
+
+---
+
+## [3.4.0] — 2026-04-09
+
+### Added
+
+- **New `/implement-plan` skill — sequenced implementation plan for AI coding agents.** New stage 12 of the BA Toolkit pipeline, runs after `/handoff` and produces `12_implplan_{slug}.md`. Reads every prior pipeline artifact and emits a phase-by-phase plus DAG-by-task plan an AI coding agent (Claude Code, Cursor, Codex) can execute step by step. **Phase ladder** is the canonical 9 phases — Foundation → Data Layer → Auth & Identity → Core Domain → API Surface → UI / Wireframes → Integrations → Quality & NFRs → Validation & Launch Prep — with phases that have no tasks for the current project automatically dropped (e.g. UI for a CLI tool). **Each task** is atomic (30–120 min), has an id `T-<phase>-<seq>`, an imperative title, an explicit `dependsOn` list, at least one `references` id back to the BA artifacts (`FR-NNN`, `US-NNN`, `AC-NNN-NN`, `Entity:Name`, `Endpoint: METHOD /path`, `WF-NNN`, `SC-NNN`), an optional `files` list of paths to create or modify, and a `definitionOfDone` checklist pulled from the linked AC where possible. **Tech stack** is resolved with priority order: (1) parsed from `07a_research_{slug}.md` if `/research` was run; (2) short calibration interview (frontend / backend / database / hosting / auth / mandatory integrations) following the standard interview-protocol rules; (3) `[TBD: <slot>]` placeholder if neither yields a value, with a matching row in the new "Open Assumptions" section telling the AI agent to stop and ask before touching that slot. **Output** carries a Tech Stack header, "How to use this plan (for AI coding agents)" instructions, the per-phase task list, an "Open Assumptions" section, and a Task DAG appendix as a markdown table that a topo-sort can traverse. Per-phase merge on rerun via `/revise [phase]` (mirror of `/sprint`'s per-sprint merge). Includes the standard `/clarify`, `/expand`, `/validate`, `/done` subcommands. AGENTS.md migration: if an existing project predates v3.4 and has no row 12, the skill appends one and reports the migration in its reply.
+- **`/handoff` now points at `/implement-plan` as the canonical follow-up.** The handoff template's "Recommended Next Steps" section gains a sixth bullet (run `/implement-plan` to produce a phase-and-DAG plan). The handoff SKILL.md closing-message instruction stops hardcoding "pipeline complete" and instead reads the new row from the lookup table — same single-source-of-truth pattern every other pipeline skill has used since v3.1.0.
+
+### Changed
+
+- **Pipeline lookup table in `skills/references/closing-message.md` extended.** The `/scenarios → /handoff` row now lists `/implement-plan` in its "After that" cell. The previously terminal `/handoff → (none) Pipeline complete` row is replaced with `/handoff → /implement-plan`, and a new terminal `/implement-plan → (none) Pipeline complete` row is added. Pipeline reads top-to-bottom in the table; no other rows changed.
+- **`agents-template.md` Pipeline Status table gains row 12 (`/implement-plan`)**. Existing rows 0–11 are untouched, so AGENTS.md files for projects scaffolded under v3.3 and earlier keep working unchanged.
+- **Skill count bumped from 23 to 24** in every place that enumerated skills: `package.json` description, `README.md` (badge, intro, install/cursor/windsurf, Pipeline table row 12, Minimum-viable-pipeline section now includes `/implement-plan` in all three paths and bumps the Lean / Full step counts from 9 / 16 to 10 / 17), `COMMANDS.md`, `CLAUDE.md` §1 + §4, `docs/USAGE.md` (interview-phase skill list, time-estimate appendix), `docs/FAQ.md` (new Q/A: "How do I hand the BA pipeline to an AI coding agent so it can actually build the project?"), `bin/ba-toolkit.js` stale comment, and the `test/cli.test.js` skill-folder-count assertion (raised from `>= 23` to `>= 24`).
+
+---
+
 ## [3.3.0] — 2026-04-09
 
 ### Added
@@ -483,7 +511,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.3.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.4.1...HEAD
+[3.4.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.4.0...v3.4.1
+[3.4.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.2.0...v3.3.0
 [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

package/COMMANDS.md

@@ -1,6 +1,6 @@
 # BA Toolkit — Command Reference
 
-Quick reference for all 23 skills and subcommands.
+Quick reference for all 24 skills and subcommands.
 
 ---
 
@@ -24,6 +24,7 @@ Run these in order. Each skill reads the output of all previous steps.
 | 9 | `/wireframes` | `09_wireframes_{slug}.md` | Textual Wireframe Descriptions: screens, components, navigation flows |
 | 10 | `/scenarios` | `10_scenarios_{slug}.md` | End-to-end Validation Scenarios linking US → AC → WF → API |
 | 11 | `/handoff` | `11_handoff_{slug}.md` | Development Handoff Package: artifact inventory, MVP scope, open items |
+| 12 | `/implement-plan` | `12_implplan_{slug}.md` | Implementation Plan for AI coding agents: phase ladder + Task DAG appendix; every task references the FR/US/AC it implements and carries its own Definition of Done |
 
 ---
 

package/README.md

@@ -2,9 +2,9 @@
 
 # 📋 BA Toolkit
 
-Structured BA pipeline for AI coding agents — concept to handoff, 23 skills, 12 domains, one-command Notion + Confluence publish.
+Structured BA pipeline for AI coding agents — concept to a phase-and-DAG implementation plan, 24 skills, 12 domains, one-command Notion + Confluence publish.
 
-<img src="https://img.shields.io/badge/skills-23-blue" alt="Skills">
+<img src="https://img.shields.io/badge/skills-24-blue" alt="Skills">
 <img src="https://img.shields.io/badge/domains-12-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 — concept to handoff, 23 skills, 1
 
 ## What is this
 
-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.
+BA Toolkit is a set of 24 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`. After `/handoff`, run `/implement-plan` to produce a phase-and-DAG implementation plan an AI coding agent (Claude Code, Cursor, Codex) can execute step by step — every task references the FR / US / AC it implements and carries its own Definition of Done. 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 12 industries (SaaS, Fintech, E-commerce, Healthcare, Logistics, On-demand, Social/Media, Real Estate, iGaming, EdTech, GovTech, AI/ML) 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 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.
+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 24 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 23 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 24 skills there natively. Reload the Windsurf window to pick them up.
 
 ### Aider
 
@@ -195,6 +195,7 @@ Full traceability: FR → US → UC → AC → NFR → Entity → ADR → API
 | 9 | `/wireframes` | Textual Wireframe Descriptions | `09_wireframes_{slug}.md` |
 | 10 | `/scenarios` | End-to-end Validation Scenarios — user journeys linking US, AC, WF, API | `10_scenarios_{slug}.md` |
 | 11 | `/handoff` | Development Handoff Package — artifact inventory, MVP scope, open items | `11_handoff_{slug}.md` |
+| 12 | `/implement-plan` | Implementation Plan for AI coding agents — phase ladder + Task DAG, every task references the FR/US/AC it implements | `12_implplan_{slug}.md` |
 | — | `/trace` | Traceability Matrix + coverage gaps | `00_trace_{slug}.md` |
 | — | `/clarify [focus]` | Targeted ambiguity resolution for any artifact | _(updates existing artifact)_ |
 | — | `/analyze` | Cross-artifact quality report with severity table | `00_analyze_{slug}.md` |
@@ -274,23 +275,23 @@ Every artifact links back to its predecessors, forming the chain `FR → US →
 
 ## Minimum viable pipeline
 
-Not every project needs all 23 skills. Three common paths:
+Not every project needs all 24 skills. Three common paths:
 
 **Concept-first** (when you don't yet know what to build):
 ```
-/discovery → /brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff
+/discovery → /brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff → /implement-plan
 ```
 
-**Lean** (fastest path to handoff when you already have a project in mind — 9 steps):
+**Lean** (fastest path from a known idea to an AI-actionable plan — 10 steps):
 ```
-/brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff
+/brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff → /implement-plan
 ```
 
-**Full** (complete traceability and quality gates — 16 steps):
+**Full** (complete traceability and quality gates — 17 steps):
 ```
 /discovery → /principles → /brief → /srs → /stories → /usecases → /ac → /nfr → /datadict
           → /research → /apicontract → /wireframes → /scenarios
-          → /trace → /analyze → /handoff
+          → /trace → /analyze → /handoff → /implement-plan
 ```
 
 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 23 skills natively in this layout for every agent. No
+// installs the 24 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.
 //

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "3.3.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.",
+  "version": "3.4.1",
+  "description": "AI-powered Business Analyst pipeline — 24 skills from concept discovery to a sequenced implementation plan an AI coding agent can execute, with one-command Notion + Confluence publish. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
   "keywords": [
     "business-analyst",
     "requirements",

package/skills/discovery/SKILL.md

@@ -27,9 +27,9 @@ If `01_brief_*.md` already exists in the same output directory, the project has
 
 ### 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`.
+The 12 supported domain references live in `references/domains/` (`saas`, `fintech`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, `real-estate`, `igaming`, `edtech`, `govtech`, `ai-ml`). 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.
+If none of the 12 fits, record the recommended domain as `custom:{name}` and let `/brief` continue with general questions only.
 
 ### 4. Interview
 
@@ -44,7 +44,7 @@ Cover 5–7 topics in 2 rounds. Do not generate the artifact until you can recom
 **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.
+3. Domain shortlist — narrow to 1 of the 12 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).

package/skills/handoff/SKILL.md

@@ -110,6 +110,7 @@ Must-priority items confirmed for the first release:
 3. **Task breakdown** — import Must-priority US from section 2 into your backlog tool (Jira, Linear, GitHub Issues).
 4. **Spec-driven implementation** — consider using [Spec Kit](https://github.com/github/spec-kit) with `/speckit.specify` to generate implementation tasks from this handoff.
 5. **Validation** — use `10_scenarios_{slug}.md` (if present) for end-to-end acceptance testing scenarios.
+6. **Generate the implementation plan** — run `/implement-plan` to produce a phase-and-DAG plan an AI coding agent can execute step by step. Output: `12_implplan_{slug}.md`.
 
 ---
 
@@ -139,7 +140,7 @@ After saving the artifact, present the following summary (see `references/closin
 
 Available commands: `/revise [section]` · `/analyze` · `/trace`
 
-Pipeline complete. This document is the development handoff package.
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (look up the row where `Current` is `/handoff`). Do not hardcode the next step here — that table is the single source of truth and now points at `/implement-plan` as the canonical follow-up after a handoff.
 
 ## Style
 

package/skills/implement-plan/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: implement-plan
+description: >
+  Generate a sequenced implementation plan for an AI coding agent based on the BA Toolkit pipeline artifacts. Use on /implement-plan command, or when the user asks to "create an implementation plan", "what to build first", "how to implement this project", "build order", "agent task list", "buildplan", "next steps for an AI coding agent", "hand the project to Claude Code". Optional final step of the BA Toolkit pipeline — runs after /handoff. Produces 12_implplan_{slug}.md with a phase-by-phase roadmap and a machine-traversable Task DAG appendix.
+---
+
+# /implement-plan — Implementation Plan for AI Coding Agents
+
+Final step of the BA Toolkit pipeline. Reads every artifact produced by the earlier skills and emits a sequenced implementation plan an AI coding agent (Claude Code, Cursor, Codex, …) can execute step by step. The output bridges the gap between the BA artifacts and actual development.
+
+`/implement-plan` is **not the same as** `/sprint`. `/sprint` groups stories into time-based sprints by team velocity for a scrum master. `/implement-plan` produces a dependency-ordered build sequence with per-task file paths, references back to FRs / US / AC, and a tech-stack header — for an AI coding agent that wants to build the project, not for a person planning a quarter.
+
+## 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 `12_implplan_*.md` already exists, load it and offer to:
+- View the current plan.
+- Amend a specific phase (`/revise [phase]`) — regenerates one phase against the latest source artifacts without touching the others.
+- Regenerate from scratch.
+
+### 3. Context loading
+
+Read every BA Toolkit artifact present in the output directory. The plan quality scales with how complete the pipeline is.
+
+**Required minimum:**
+- `01_brief_*.md` — project name, domain, business goals.
+- `02_srs_*.md` — functional requirements (the source of truth for what to build).
+
+**Strongly recommended:**
+- `03_stories_*.md` — user-story decomposition for sequencing within phases.
+- `05_ac_*.md` — acceptance criteria (drives Definition of Done per task).
+- `07_datadict_*.md` — entities for the Data Layer phase.
+- `08_apicontract_*.md` — endpoints for the API Surface phase.
+- `09_wireframes_*.md` — screens for the UI phase.
+
+**Auto-consumed if present (optional):**
+- `00_principles_*.md` — language, ID conventions, Definition of Ready, NFR baseline.
+- `00_estimate_*.md` — task sizing hints.
+- `00_sprint_*.md` — if a sprint plan exists, use sprint-level dependencies as cross-phase prerequisite hints.
+- `00_risks_*.md` — elevate tasks that mitigate Critical / High risks within their phase.
+- `06_nfr_*.md` — drives Phase 8 (Quality & NFRs).
+- `07a_research_*.md` — primary tech-stack source (see step 4).
+- `04_usecases_*.md` — flow context for Phase 4 (Core Domain) tasks.
+- `10_scenarios_*.md` — drives Phase 9 (Validation) tasks.
+- `11_handoff_*.md` — open items become explicit pre-launch tasks in Phase 9.
+
+If `02_srs_*.md` is missing, **stop**. Tell the user there is nothing to sequence without functional requirements and ask them to run `/srs` first.
+
+### 4. Tech stack resolution
+
+The plan must record an explicit tech stack so an AI coding agent can pick file extensions, framework idioms, and dependency files without guessing.
+
+**Step 1 — `07a_research_*.md` (primary source).** If the research artifact exists, parse the chosen frontend, backend, database, hosting, auth, and integration choices from its sections. Record where each value came from so it appears in the output's "Tech stack" header (`Source: 07a_research`).
+
+**Step 2 — calibration interview (fallback).** If `/research` was not run, OR if `/research` left specific decisions as TBD, run a short calibration 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 `/implement-plan` (e.g., `/implement-plan use Next.js, FastAPI, and Postgres on Fly.io`), parse it as the tech-stack hint and skip whichever interview questions it already answers.
+
+Required topics for the calibration interview (skip any topic already answered by `07a_research` or inline context):
+1. Frontend stack (framework, language, build tool).
+2. Backend / API stack (framework, language, runtime).
+3. Database (engine, version, hosting model).
+4. Hosting / deployment target.
+5. Auth / identity approach (in-house vs. SSO vs. managed service).
+6. Mandatory integrations from `02_srs` (carry over verbatim — do not re-decide them).
+
+**Step 3 — TBD slots.** If neither `/research` nor the interview yields a value for a slot (e.g. user picked "Other" without a concrete answer), record `[TBD: <slot>]` in the output's "Tech stack" header AND add a row to the "Open Assumptions" section so the AI coding agent knows it must ask before starting any task that touches that slot.
+
+### 5. Phase derivation
+
+Build a phase ladder from the canonical 9 phases below. **Drop any phase that has no tasks for the current project** — for example, a CLI tool drops Phase 6 (UI), an infra-only project drops Phases 5–6, an analytics dashboard with a managed auth provider can shrink Phase 3 to a single integration task.
+
+Canonical phase order:
+
+1. **Foundation** — repo init, language toolchain, lint / format / test scaffolding, CI skeleton, environment-variable scheme, secret management. **Always present.**
+2. **Data Layer** — schema from `07_datadict`, migrations, ORM / query layer, seed data, backup config. Skipped only if no datadict and no entities are inferable from `02_srs`.
+3. **Auth & Identity** — sign-up / sign-in / session, SSO / OAuth if mandated by `02_srs` or `06_nfr`, password / token policy, RBAC scaffolding from roles in `02_srs`. Skipped only if `02_srs` has zero auth-related FRs.
+4. **Core Domain** — Must-priority FRs and their corresponding US, ordered by `03_stories` epic and dependencies recorded in `02_srs` or `00_sprint`.
+5. **API Surface** — endpoints from `08_apicontract` mapped to the core-domain handlers built in Phase 4. Skipped if no API contract artifact.
+6. **UI / Wireframes** — screens from `09_wireframes` wired to the API. Skipped if no wireframes artifact.
+7. **Integrations** — external systems listed in `02_srs` / `07a_research` (payment provider, email, search, analytics, third-party APIs). One task per integration, naming the integration and the FR it fulfils.
+8. **Quality & NFRs** — observability, performance budgets from `06_nfr`, security hardening from `06_nfr`, accessibility checks if domain mandates them (govtech, edtech, healthcare).
+9. **Validation & Launch Prep** — end-to-end scenario tests from `10_scenarios`, pre-launch checks from `11_handoff` "Open Items", documentation, deployment runbook.
+
+For each surviving phase, derive:
+- **Goal** — one sentence describing the user-facing or build-output outcome ("Stand up the foundation so every later phase has a working CI loop", "Make every Must FR addressable via a typed endpoint").
+- **Prerequisites** — which earlier phases must be done. By default phase N depends on phase N−1; cross-phase prerequisites are explicit (e.g. Phase 5 API tasks depend on Phase 2 Data Layer for the entities they read).
+- **Reads** — which BA Toolkit artifact files this phase consults.
+- **Tasks** — ordered list (see step 6).
+
+### 6. Task derivation
+
+Each task is one atomic, AI-actionable unit of work. Rules:
+
+- **Atomicity:** a task should be completable in 30–120 minutes by an experienced developer. If a derived task is bigger, split it; if smaller, merge with the next task in the same phase.
+- **id:** `T-<phase>-<seq>`, e.g. `T-04-007`. Phase number → first segment; sequence → second segment, zero-padded to 3 digits.
+- **title:** imperative, ≤ 10 words ("Create `users` table with email-unique constraint", "Implement `POST /auth/login` handler").
+- **dependsOn:** list of task ids that must complete first. Defaults to the previous task in the same phase, plus any explicit cross-phase prerequisites. Empty for the first task in Phase 1.
+- **references:** list of `FR-NNN`, `US-NNN`, `UC-NNN`, `AC-NNN-NN`, `NFR-NNN`, `Entity:Name`, `Endpoint: METHOD /path`, `WF-NNN`, `SC-NNN` ids that this task implements. **Always at least one.** Phase 1 tasks (Foundation) are the only exception and may reference `01_brief` or `00_principles` as their source.
+- **files:** list of file paths the AI agent should create or modify (best-effort; framework-dependent). Optional. Examples: `src/db/schema.sql`, `apps/api/src/auth/login.controller.ts`. **If unknown, omit rather than guess.**
+- **definitionOfDone:** bullet list of acceptance hooks. Pull from the linked AC where possible ("AC-001-03 passes", "endpoint returns 401 on invalid credentials"). Always include a type-check / lint hook on backend tasks and a render-state hook on UI tasks.
+
+Within a phase, order tasks so each task's `dependsOn` list points only at tasks already listed. Risk-elevated tasks (mitigating Critical / High risks from `00_risks_*.md`) come earliest within their priority tier.
+
+### 7. Generation
+
+**File:** `12_implplan_{slug}.md`
+
+```markdown
+# Implementation Plan: {Project Name}
+
+**Domain:** {domain}
+**Date:** {date}
+**Slug:** {slug}
+**Generated from:** {ordered list of artifact filenames actually consumed}
+
+---
+
+## Tech Stack
+
+| Layer | Choice | Source |
+|-------|--------|--------|
+| Frontend | {value or [TBD]} | 07a_research / interview / TBD |
+| Backend | {…} | … |
+| Database | {…} | … |
+| Hosting | {…} | … |
+| Auth | {…} | … |
+| Mandatory integrations | {…} | … |
+
+---
+
+## How to use this plan (for AI coding agents)
+
+- Phases are ordered. Do not start phase N+1 until every task in phases 1..N is complete (or explicitly waived in writing).
+- Within a phase, follow task ids in ascending order unless `dependsOn` says otherwise.
+- Every task has a `references` list — read those BA artifact sections before writing code.
+- Every task has a `definitionOfDone` — do not mark a task complete until every box is checked.
+- The Task DAG appendix is the machine-readable source of truth for dependencies.
+- If you encounter a `[TBD]` slot or a task that depends on an open assumption, **stop and ask the user** before generating code.
+
+---
+
+## Phase 1 — Foundation
+
+**Goal:** {one sentence}
+**Prerequisites:** —
+**Reads:** 01_brief, 00_principles
+
+### T-01-001 — {title}
+- **References:** {ids}
+- **Files:** {paths or —}
+- **Definition of Done:**
+  - [ ] {hook 1}
+  - [ ] {hook 2}
+
+### T-01-002 — {title}
+- **dependsOn:** T-01-001
+- **References:** {ids}
+- **Files:** {paths or —}
+- **Definition of Done:**
+  - [ ] {hook 1}
+
+---
+
+## Phase 2 — Data Layer
+
+**Goal:** {one sentence}
+**Prerequisites:** Phase 1
+**Reads:** 07_datadict, 02_srs
+
+### T-02-001 — {title}
+- **References:** Entity:User, FR-001
+- **Files:** {paths}
+- **Definition of Done:** …
+
+…
+
+---
+
+## Phase 3 — Auth & Identity
+
+…
+
+## Phase 4 — Core Domain
+
+…
+
+## Phase 5 — API Surface
+
+…
+
+## Phase 6 — UI / Wireframes
+
+…
+
+## Phase 7 — Integrations
+
+…
+
+## Phase 8 — Quality & NFRs
+
+…
+
+## Phase 9 — Validation & Launch Prep
+
+…
+
+---
+
+## Open Assumptions
+
+Items the plan could not resolve from existing artifacts. The AI coding agent must ask the user before starting any task that touches them.
+
+- {assumption 1 with reason and which task ids depend on it}
+- {assumption 2}
+
+---
+
+## Task DAG (appendix)
+
+Machine-readable dependency graph. A topological sort of this table yields a valid execution order.
+
+| id | phase | title | dependsOn | references |
+|----|-------|-------|-----------|------------|
+| T-01-001 | 1 | {title} | — | {ids} |
+| T-01-002 | 1 | {title} | T-01-001 | {ids} |
+| T-02-001 | 2 | {title} | T-01-003 | Entity:User, FR-001 |
+| … | … | … | … | … |
+```
+
+### 8. AGENTS.md update
+
+`ba-toolkit init` already created `AGENTS.md` next to where the artifact lives. After saving `12_implplan_{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 single-project layouts).
+
+**Update only the `## Pipeline Status` row for `/implement-plan`** — 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`.
+
+If the existing `AGENTS.md` predates v3.4 and has no `/implement-plan` row in its Pipeline Status table, append a new row at stage `12` (the existing rows 0–11 stay as they are, no renumbering). Mention the migration in your reply so the user knows their AGENTS.md was updated.
+
+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.1 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.
+
+### 9. Iterative refinement
+
+- `/clarify [focus]` — targeted ambiguity pass.
+- `/revise [phase]` — regenerate one phase against the latest source artifacts without touching the others (mirror of how `/sprint` regenerates one sprint at a time).
+- `/expand [phase]` — add more tasks or detail to one phase.
+- `/validate` — check that every task has at least one reference, every `dependsOn` id exists in the table, and the Task DAG has no cycles.
+- `/done` — finalize and update `AGENTS.md`.
+
+### 10. Closing message
+
+After saving the artifact, present the following summary to the user (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Phase count and total task count (e.g. "8 phases, 47 tasks").
+- Tech stack one-liner ("React + FastAPI + Postgres on Fly.io").
+- Number of `[TBD]` slots remaining in "Open Assumptions" — if > 0, warn that the AI coding agent will have to stop and ask before touching those areas.
+- Length of the longest dependency chain in the Task DAG (so the user has a sense of critical-path depth).
+
+Available commands for this artifact: `/clarify [focus]` · `/revise [phase]` · `/expand [phase]` · `/validate` · `/done`
+
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (look up the row where `Current` is `/implement-plan`). Do not hardcode the next step here — that table is the single source of truth.
+
+## Style
+
+Formal, neutral, imperative. No emoji in the saved file. Phase goals are user-outcome sentences, not task lists. Task titles are imperative verbs ("Create", "Implement", "Wire", "Migrate", "Document"). Definition-of-Done bullets are checkable, not aspirational. Generate the artifact in the language of the user's request; section headings, table headers, and labels also in the user's language. ID columns and code identifiers (`T-04-007`, `FR-001`, `Entity:User`, file paths) stay ASCII.

package/skills/references/closing-message.md

@@ -55,8 +55,9 @@ Skills use this table as the single source of truth for the `Next step:` block.
 | /research    | /apicontract    | API Contract — endpoints, request/response schemas, errors      | 20–35 min    | /wireframes — Textual Wireframe Descriptions        |
 | /apicontract | /wireframes     | Textual Wireframe Descriptions — screens, components, nav       | 25–40 min    | /scenarios — End-to-end Validation Scenarios        |
 | /wireframes  | /scenarios      | End-to-end Validation Scenarios linking US, AC, WF, API         | 15–25 min    | /trace + /analyze — coverage + cross-artifact QA    |
-| /scenarios   | /handoff        | Development Handoff Package — inventory, MVP scope, open items  | 5–10 min     | (pipeline complete)                                 |
-| /handoff     | (none)          | Pipeline complete                                               | —            | Run /trace and /analyze for final coverage check    |
+| /scenarios   | /handoff        | Development Handoff Package — inventory, MVP scope, open items  | 5–10 min     | /implement-plan — sequenced plan for AI coding agents |
+| /handoff     | /implement-plan | Sequenced implementation plan for AI coding agents              | 10–20 min    | (pipeline complete — hand to Claude Code / Cursor)  |
+| /implement-plan | (none)       | Pipeline complete                                               | —            | Hand 12_implplan_<slug>.md to your AI coding agent  |
 
 ## Cross-cutting commands (no Next step line)
 

package/skills/references/interview-protocol.md

@@ -83,4 +83,6 @@ If the user's first message was in Russian, the same question is rendered with R
 
 ## When this protocol applies
 
-This protocol applies to every skill that has an `### Interview` (or `## Interview`) section in its SKILL.md — currently: `brief`, `srs`, `stories`, `usecases`, `ac`, `nfr`, `datadict`, `apicontract`, `wireframes`, `scenarios`, `research`, `principles`. Each of those skills MUST link to this file from its Interview section and follow rules 1–7 + rules 9–11. Rule 8 (open-ended lead-in question) applies only to entry-point skills — currently `/brief` and `/principles` when no `01_brief_*.md` or `00_principles_*.md` is present in the output directory yet.
+This protocol applies to every skill that has an `### Interview` (or `## Interview`) section in its SKILL.md — currently: `discovery`, `principles`, `brief`, `srs`, `stories`, `usecases`, `ac`, `nfr`, `datadict`, `research`, `apicontract`, `wireframes`, `scenarios`. Each of those skills MUST link to this file from its Interview section and follow rules 1–7 + rules 9–11. Rule 8 (open-ended lead-in question) applies only to entry-point skills — currently `/discovery`, `/brief`, and `/principles` when no `00_discovery_*.md`, `01_brief_*.md`, or `00_principles_*.md` is present in the output directory yet.
+
+Two additional skills follow rules 1–11 via differently-named sections rather than a literal `Interview` heading: `/publish` uses a `### Format selection` section to ask which target (Notion / Confluence / both), and `/implement-plan` uses an embedded calibration interview inside its `### Tech stack resolution` step to gather frontend / backend / database / hosting / auth choices when `07a_research_*.md` is absent or incomplete. Both carry the same one-line protocol summary block as the canonical interview-phase skills and must be kept in sync with rules 1–11 even though the existing `interview-protocol-link` regression test in `test/cli.test.js` only matches skills with a literal `Interview` heading and therefore does not enforce them automatically.

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

@@ -30,6 +30,7 @@
 | 9 | /wireframes | ⬜ Not started | — |
 | 10 | /scenarios | ⬜ Not started | — |
 | 11 | /handoff | ⬜ Not started | — |
+| 12 | /implement-plan | ⬜ Not started | — |
 
 ## Cross-cutting Tools
 

package/skills/scenarios/SKILL.md

@@ -110,7 +110,7 @@ After saving the artifact, present the following summary (see `references/closin
 
 Available commands: `/clarify [focus]` · `/revise [SC-NNN]` · `/expand [SC-NNN]` · `/split [SC-NNN]` · `/validate` · `/done`
 
-Pipeline complete. Proceed to `/handoff` to package all artifacts for development.
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (look up the row where `Current` is `/scenarios`). Do not hardcode the next step here — that table is the single source of truth.
 
 ## Style
 

package/skills/wireframes/SKILL.md

@@ -91,7 +91,7 @@ Overall navigation structure: sections, hierarchy, transitions.
 - `/split [WF-NNN]` — extract modals etc.
 - `/clarify [focus]` — targeted ambiguity pass.
 - `/validate` — all Must-US have a screen; API links correct; 4 states described; navigation connected.
-- `/done` — pipeline complete. Suggest running `/trace`.
+- `/done` — finalize and move to the next pipeline step.
 
 ## Closing message
 
@@ -104,7 +104,7 @@ After saving the artifact, present the following summary to the user (see `refer
 
 Available commands: `/clarify [focus]` · `/revise [WF-NNN]` · `/expand [WF-NNN]` · `/split [WF-NNN]` · `/validate` · `/done`
 
-Pipeline complete. Run `/trace` to check full coverage or `/analyze` for a cross-artifact quality report.
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (look up the row where `Current` is `/wireframes`). Do not hardcode the next step here — that table is the single source of truth.
 
 ## Style