@kudusov.takhir/ba-toolkit 4.0.0 → 4.0.2

package/CHANGELOG.md

@@ -11,6 +11,23 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [4.0.2] — 2026-04-12
+
+### Fixed
+
+- **Skills invented their own project slug instead of reading the one `ba-toolkit init` wrote to `AGENTS.md`.** Reproduction: `ba-toolkit init --name "New Test App"` produced `**Slug:** new-test-app` in `AGENTS.md`, but a follow-up `/brief` saved `01_brief_knitted-socks.md` — slug picked from conversation context, not from the scaffold. Root cause: pipeline skills carried v3.x-era wording (`/brief`: *"slug — kebab-case, fixed here for the entire pipeline"*; `/principles`: *"extract the slug from the brief, otherwise ask the user"*; `/discovery`: *"derive from the project name"*) and never read the canonical slug from the managed block of `AGENTS.md` that v4.0 `init` writes. Downstream skills inherited the wrong slug from the brief filename and the project silently desynchronised. Fixed by adding `skills/references/slug-source.md` (the single rule + fallbacks + rationale) and an explicit "Slug source" directive in every pipeline and utility skill that emits a `{slug}` filename: `/brief`, `/discovery`, `/principles`, `/srs`, `/stories`, `/usecases`, `/ac`, `/nfr`, `/datadict`, `/research`, `/apicontract`, `/wireframes`, `/scenarios`, `/handoff`, `/implement-plan`, `/analyze`, `/trace`, `/risk`, `/sprint`, `/glossary`, `/estimate`, `/export`. Each now reads `**Slug:**` from `AGENTS.md` verbatim and refuses to invent a new one. `/discovery` is the one exception — it may still derive a slug if `AGENTS.md` does not yet exist (the brain-storm-before-init flow), and otherwise honours the scaffold value instead of renaming the project.
+- **`ba-toolkit init` crashed on second run with "Input stream closed before all prompts could be answered."** When an existing install was detected after the domain/agent arrow-key menus, the "Replace existing BA Toolkit install?" prompt rejected immediately. Root cause: the raw-mode menu closes the shared readline interface, which sets a sticky `inputClosed` flag that was never reset when `ensureReadline()` recreated the interface for the next `prompt()`. Fixed by clearing the flag on interface recreation.
+
+---
+
+## [4.0.1] — 2026-04-12
+
+### Fixed
+
+- **Removed stale v3.x references from skill files.** `/principles` still offered an "Output folder structure" interview topic with a `{slug}/` subfolder option that no longer exists in v4.0 — removed, topics renumbered (8 → 7). `principles-template.md` subfolder section and Decision Authority rows renumbered to match. `/brief`, `/discovery`, `/srs` SKILL.md files still referenced "per-project AGENTS.md" and "legacy v3.0 single-project layouts" — updated to v4.0 wording (project root, flat output).
+
+---
+
 ## [4.0.0] — 2026-04-11
 
 ### Changed
@@ -871,7 +888,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.10.1...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.2...HEAD
+[4.0.2]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.1...v4.0.2
+[4.0.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.0...v4.0.1
 [4.0.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.13.1...v4.0.0
 [3.13.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.13.0...v3.13.1
 [3.13.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.12.0...v3.13.0

package/bin/ba-toolkit.js

@@ -193,6 +193,12 @@ let inputClosed = false;
 
 function ensureReadline() {
   if (sharedRl) return;
+  // Reset the sticky close flag — a previous interface may have been
+  // torn down by closeReadline() (e.g. before an arrow-key menu took
+  // over stdin in raw mode). Without this reset, the next prompt()
+  // after a menu would immediately reject with INPUT_CLOSED even
+  // though stdin is still perfectly usable.
+  inputClosed = false;
   sharedRl = readline.createInterface({ input: process.stdin, output: process.stdout });
   sharedRl.on('line', (line) => {
     if (waiters.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "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",

package/skills/ac/SKILL.md

@@ -42,6 +42,8 @@ Supplement with domain-specific questions from the reference.
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `05_ac_{slug}.md`
 
 The full per-AC field set lives at `references/templates/ac-template.md` and is the single source of truth. Each AC carries: ID (`AC-NNN-NN`), Type (positive / negative / boundary / performance / security), Given / When / Then, Linked US, Linked UC, Linked FR, Linked NFR (for performance/security ACs), Source (which business rule from `02_srs_{slug}.md` drove this AC), and Verification method (automated test / manual test / observed in production). The artifact also carries a US → AC coverage matrix at the bottom.

package/skills/analyze/SKILL.md

@@ -86,6 +86,8 @@ The 8 canonical categories cover the IEEE 830 §4.3 SRS quality attributes (corr
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `00_analyze_{slug}.md`
 
 The full report layout lives at `references/templates/analyze-template.md` and is the single source of truth. Each finding carries: ID, Severity, Category (one of the 8 above), Location (artifact + element ID), Description, Recommendation, and **Owner** (which role is accountable for fixing the finding — assigned by `00_principles_*.md` §4 Definition of Ready ownership where applicable, otherwise by domain default).

package/skills/apicontract/SKILL.md

@@ -47,6 +47,8 @@ Supplement with domain-specific questions from the reference.
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `08_apicontract_{slug}.md`
 
 ```markdown

package/skills/brief/SKILL.md

@@ -61,7 +61,9 @@ If a domain reference is loaded, supplement general questions with domain-specif
 
 ### 5. Generation
 
-**File:** `01_brief_{slug}.md` (slug — kebab-case, fixed here for the entire pipeline).
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` at the project root (look in cwd first; if cwd is `output/`, check `../AGENTS.md`). Use that value verbatim — do not invent or re-derive a slug from the project name. `ba-toolkit init` is the single source of truth; see [`../references/slug-source.md`](../references/slug-source.md) for fallback rules and rationale.
+
+**File:** `01_brief_{slug}.md`
 
 ```markdown
 # Project Brief: {Project Name}
@@ -103,9 +105,9 @@ If a domain reference is loaded, supplement general questions with domain-specif
 
 `ba-toolkit init` already created `AGENTS.md` at the project root. After saving `01_brief_{slug}.md` to `output/`, find the project's `AGENTS.md` (look in cwd first; if cwd is `output/`, check `../AGENTS.md`).
 
-**Update only the `## Pipeline Status` row for `/brief`** — 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.
+**Update only the `## Pipeline Status` row for `/brief`** — 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 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.
+If you find no `AGENTS.md` at all, warn the user that the project was likely not scaffolded with `ba-toolkit init` and tell them to run it. Do not create one yourself with arbitrary structure.
 
 ### 7. Iterative refinement
 

package/skills/datadict/SKILL.md

@@ -45,6 +45,8 @@ Supplement with domain-specific questions and mandatory entities from the refere
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `07_datadict_{slug}.md`
 
 The full per-entity field set lives at `references/templates/datadict-template.md` and is the single source of truth. Each entity carries: name, **Source** (which FR/US introduced this entity), **Owner** (which team / role curates it), **Sensitivity** (Public / Internal / Confidential / PII / PCI / PHI), description, attribute table (with logical types, not DBMS-specific), relationships with cascade rules, **state machine** (if applicable), indexes (logical, not physical), retention policy, and notes. The artifact carries an FR → Entity coverage matrix at the bottom.

package/skills/discovery/SKILL.md

@@ -54,7 +54,9 @@ If a topic was already covered by inline context or the lead-in answer, skip it
 
 ### 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).
+**Slug:** if `AGENTS.md` exists at the project root with a `**Slug:**` line in its managed block, read that value verbatim and use it as `{slug}` — `ba-toolkit init` is the single source of truth. Do **not** propose a new slug, and do **not** rename the project the user already scaffolded. Only when `AGENTS.md` is absent (the user is brain-storming before running `ba-toolkit init`) may you derive a kebab-case slug from the project name; if the user has not yet picked a name, propose 2–3 candidates and let them choose. See [`../references/slug-source.md`](../references/slug-source.md) for the full rule.
+
+**File:** `00_discovery_{slug}.md`
 
 ```markdown
 # Discovery: {Project Name}
@@ -127,11 +129,11 @@ Things we don't yet know and need to learn before committing real resources.
 
 `ba-toolkit init` already created `AGENTS.md` at the project root. After saving `00_discovery_{slug}.md` to `output/`, find the project's `AGENTS.md` (look in cwd first; if cwd is `output/`, check `../AGENTS.md`).
 
-**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 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.
+**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`.
 
 **Domain field exception (managed block).** `/discovery` is the canonical source of truth for the project domain after `ba-toolkit init`. After saving `00_discovery_{slug}.md`, compare the recommended domain in §8 of the discovery artifact against the `**Domain:**` line inside the managed block of `AGENTS.md`. **If they differ, surgically update only that single line** to the new value — do not modify any other managed-block field (`**Project:**`, `**Slug:**`, `**Language:**`, `**Output folder:**`, the auto-generated date comment). Mention the change in the user-facing reply: "Updated the project domain in AGENTS.md from `<old>` to `<new>` based on the discovery recommendation." This is the only managed-block field `/discovery` may touch; everything else inside `<!-- ba-toolkit:begin managed -->` … `<!-- ba-toolkit:end managed -->` remains owned by `ba-toolkit init`.
 
-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 you find no `AGENTS.md` at all, warn the user that the project was likely not scaffolded with `ba-toolkit init` and tell them to run it. 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.
 

package/skills/estimate/SKILL.md

@@ -87,6 +87,8 @@ This skill produces a **single-estimator analytical pass**. A senior BA running
 
 ## Output
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 ### If scope ≤ 20 stories — update `03_stories_{slug}.md` in-place
 
 Add a `**Estimate:**` field to each US block and append the Estimation Summary table at the end of the file.

package/skills/export/SKILL.md

@@ -197,6 +197,8 @@ Compatible with Jira CSV import, Trello, Asana, Monday.com, and Google Sheets. I
 
 ## Output
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 Save the export file to the output directory alongside the artifacts:
 
 ```

package/skills/glossary/SKILL.md

@@ -99,6 +99,8 @@ Identify terms used in requirements but not defined anywhere in the glossary or
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 Save `00_glossary_{slug}.md` to the output directory.
 
 ```markdown

package/skills/handoff/SKILL.md

@@ -24,6 +24,8 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 No interview. All content is derived from the existing artifacts. The full template lives at `references/templates/handoff-template.md` and is the single source of truth — including the full inventory of pipeline-stage and cross-cutting artifacts (`/discovery`, `/principles`, `/implement-plan`, `/sprint`, `/risk`, `/glossary`, `/trace`, `/analyze`, `/estimate`), the Brief Goal → FR / FR → NFR / FR → API forward-traceability tables, the ADR summary, and the formal Sign-off section.
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `11_handoff_{slug}.md`
 
 ```markdown

package/skills/implement-plan/SKILL.md

@@ -115,6 +115,8 @@ Within a phase, order tasks so each task's `dependsOn` list points only at tasks
 
 ### 7. Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `12_implplan_{slug}.md`
 
 ```markdown

package/skills/nfr/SKILL.md

@@ -48,6 +48,8 @@ Supplement with domain-specific questions and mandatory categories from the refe
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `06_nfr_{slug}.md`
 
 The full per-NFR field set lives at `references/templates/nfr-template.md` and is the single source of truth. Each NFR carries: ID (`NFR-NNN`), ISO 25010 characteristic, sub-characteristic, description, measurable metric, **acceptance threshold** (the bar that says "we passed"), verification method, source (which stakeholder, regulation, or FR drove this NFR), rationale, priority, and linked FRs / USs / Brief constraints. The artifact carries an FR → NFR coverage matrix and a per-characteristic priority summary at the bottom.

package/skills/principles/SKILL.md

@@ -23,7 +23,7 @@ If `00_principles_*.md` already exists, load it and offer to:
 - Amend a specific section (`/revise [section]`).
 - Regenerate from scratch.
 
-If `01_brief_*.md` already exists, extract the slug and domain from it. Otherwise, ask the user for the project name (to derive the slug) and domain.
+**Slug source.** Read the `**Slug:**` line from the managed block of `AGENTS.md` at the project root (cwd, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. `ba-toolkit init` is the single source of truth — do not invent or re-derive a slug. If `AGENTS.md` is missing, warn the user to run `ba-toolkit init` first. See [`../references/slug-source.md`](../references/slug-source.md) for the full rule and fallbacks. The domain comes from the same managed block; if `01_brief_*.md` already exists, prefer the brief's domain over the scaffold default.
 
 ### 3. Interview
 
@@ -40,10 +40,9 @@ If `01_brief_*.md` already exists, extract the slug and domain from it. Otherwis
 2. NFR baseline — which **ISO/IEC 25010** quality characteristics are mandatory beyond the domain defaults? (Performance Efficiency / Reliability / Security / Compatibility / Usability / Maintainability / Portability / Functional Suitability — `/nfr` reads this list verbatim and treats it as a checklist).
 3. Definition of Ready — any project-specific acceptance criteria for finalizing an artifact beyond the `v3.7.0+` baseline DoR per artifact type listed in §4 below? (e.g., stakeholder sign-off, specific review steps).
 4. Quality gate — at what severity level should `/analyze` findings block `/done`? (default: CRITICAL only)
-5. Output folder structure — save all artifacts flat in the output directory (default), or inside a `{slug}/` subfolder? (useful when managing multiple projects side by side)
-6. **Testing strategy** — TDD (tests before implementation), tests-after, integration-only, manual-only, none? Drives whether `/implement-plan` task templates embed "Tests to write first" blocks. **Recommended:** TDD for production-grade systems; tests-after for prototypes; manual-only or none for spike work. *(This is the principles-based approach to the testing-discipline question that batch 6 item 2 surfaced — the right place to declare a testing strategy is here, not as a separate skill.)*
-7. **Stakeholder decision authority** — who has sign-off authority on changes to these principles? Captured by name and role. Without this, principle changes become contentious mid-project.
-8. **Code review and branching policy** — trunk-based / GitFlow / GitHub flow? Required reviewers per PR? `/implement-plan` and downstream skills assume one of these defaults but the principles file is the source of truth.
+5. **Testing strategy** — TDD (tests before implementation), tests-after, integration-only, manual-only, none? Drives whether `/implement-plan` task templates embed "Tests to write first" blocks. **Recommended:** TDD for production-grade systems; tests-after for prototypes; manual-only or none for spike work. *(This is the principles-based approach to the testing-discipline question that batch 6 item 2 surfaced — the right place to declare a testing strategy is here, not as a separate skill.)*
+6. **Stakeholder decision authority** — who has sign-off authority on changes to these principles? Captured by name and role. Without this, principle changes become contentious mid-project.
+7. **Code review and branching policy** — trunk-based / GitFlow / GitHub flow? Required reviewers per PR? `/implement-plan` and downstream skills assume one of these defaults but the principles file is the source of truth.
 
 **Note:** Artifact language is **not** an interview topic — it is detected automatically from the user's first message and recorded in `## 1. Artifact Language` of the generated file. The user can override it later by re-running `/principles`.
 
@@ -157,13 +156,7 @@ For `/analyze` findings — action required before `/done` at the current step:
 - **MEDIUM:** documented and may be deferred.
 - **LOW:** informational only.
 
-## 7. Output Folder Structure
-
-**Mode:** {flat | subfolder}
-
-_(flat = all artifacts in the output directory root; subfolder = all artifacts under `{output_dir}/{slug}/`)_
-
-## 8. Project-Specific Notes
+## 7. Project-Specific Notes
 
 {any_additional_conventions_from_interview}
 ```

package/skills/references/slug-source.md

@@ -0,0 +1,30 @@
+# Slug source — single rule
+
+`ba-toolkit init` is the **single source of truth** for the project slug. It writes the slug into the managed block of `AGENTS.md` at the project root:
+
+```
+<!-- ba-toolkit:begin managed -->
+...
+**Slug:** new-test-app
+...
+<!-- ba-toolkit:end managed -->
+```
+
+Every skill that emits a file whose name contains `{slug}` (e.g. `01_brief_{slug}.md`, `02_srs_{slug}.md`, `00_analyze_{slug}.md`) **must read the slug from this line and use it verbatim**. Do not invent a slug, do not re-derive it from the project name, do not pick one based on conversation context.
+
+## How to read the slug
+
+1. Locate `AGENTS.md`. Look in `cwd` first; if `cwd` is `output/`, check `../AGENTS.md`.
+2. Find the managed block delimited by `<!-- ba-toolkit:begin managed -->` and `<!-- ba-toolkit:end managed -->`.
+3. Inside the block, parse the line that starts with `**Slug:**`. Strip whitespace. The remainder is the slug.
+4. Use that exact string as `{slug}` in every output filename for this run.
+
+## Fallbacks
+
+- **No `AGENTS.md` at the project root.** The project was not scaffolded with `ba-toolkit init`. Stop and tell the user to run `ba-toolkit init` first. Do not invent a slug to keep going.
+- **`AGENTS.md` exists but has no managed block** (legacy file the user authored manually). Look for `01_brief_*.md` in `output/`; the part between `01_brief_` and `.md` is the slug. If no brief file exists either, ask the user for the slug explicitly — do not invent one.
+- **`AGENTS.md` managed block is present but the `**Slug:**` line is missing or empty.** Treat as a corrupted scaffold. Tell the user to re-run `ba-toolkit init` to repair `AGENTS.md`. Do not invent a slug.
+
+## Why
+
+Before v4.0, `/brief` was the entry point and decided the slug. In v4.0, `ba-toolkit init` runs first and fixes the slug at scaffold time, so that `AGENTS.md` and the file names in `output/` are guaranteed to agree from the very first artifact. Skills that still derive a slug locally (from the project name or from conversation context) silently desynchronise the project: `AGENTS.md` says one thing, the artifact filenames say another, downstream skills pick up the wrong slug, and the user sees `01_brief_knitted-socks.md` next to `**Slug:** new-test-app`.

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

@@ -165,14 +165,7 @@ For `/analyze` findings:
 - **MEDIUM:** documented and may be deferred.
 - **LOW:** informational only.
 
-## 7. Output Folder Structure
-
-**Mode:** [flat | subfolder]
-
-- `flat` (default) — all artifacts saved directly in the output directory.
-- `subfolder` — all artifacts saved under `{output_dir}/[SLUG]/`.
-
-## 8. Testing Strategy
+## 7. Testing Strategy
 
 **Strategy:** TDD | Tests-after | Integration-only | Manual-only | None
 
@@ -186,13 +179,13 @@ For `/analyze` findings:
 
 `/implement-plan` reads this section to decide whether to embed test specifications in each task. Default is **TDD** for production-grade systems.
 
-## 9. Code Review and Branching
+## 8. Code Review and Branching
 
 **Branching model:** trunk-based | GitHub flow | GitFlow | other
 **Required reviewers per PR:** [N]
 **Merge gate:** [CI green + N reviews / CODEOWNERS approval / specific reviewer]
 
-## 10. Stakeholder Decision Authority
+## 9. Stakeholder Decision Authority
 
 Who can approve a change to these principles, and to which sections.
 
@@ -204,11 +197,10 @@ Who can approve a change to these principles, and to which sections.
 | §4 Definition of Ready | [Role] | |
 | §5 NFR Baseline | [Role] | |
 | §6 Quality Gates | [Role] | |
-| §7 Output Structure | [Role] | |
-| §8 Testing Strategy | [Role] | |
-| §9 Branching | [Role] | |
+| §7 Testing Strategy | [Role] | |
+| §8 Branching | [Role] | |
 
-## 11. Project-Specific Notes
+## 10. Project-Specific Notes
 
 [ADDITIONAL_CONVENTIONS]
 

package/skills/research/SKILL.md

@@ -53,6 +53,8 @@ Supplement with domain-specific typical integrations from the reference.
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `07a_research_{slug}.md`
 
 ```markdown

package/skills/risk/SKILL.md

@@ -115,6 +115,8 @@ Assign each risk one of the four canonical treatment strategies (PMBOK 7 / ISO 3
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 Save `00_risks_{slug}.md` to the output directory.
 
 ```markdown

package/skills/scenarios/SKILL.md

@@ -41,6 +41,8 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `10_scenarios_{slug}.md`
 
 The full per-scenario field set lives at `references/templates/scenarios-template.md` and is the single source of truth. Each scenario carries: ID (`SC-NNN`), Title, Persona (named with context), Type (happy / negative / edge / performance / security), Priority (P1 / P2 / P3), Entry point, Platform, **Source** (Linked US, Linked FR, Linked NFR), Linked AC, Steps table, Expected Outcome, Failure Conditions. The artifact carries a coverage matrix at the bottom showing US, AC scenario, FR, NFR, and WF coverage.

package/skills/sprint/SKILL.md

@@ -92,6 +92,8 @@ For each sprint, derive a one-sentence goal that describes the primary user-faci
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 Save `00_sprint_{slug}.md` to the output directory. The full layout lives at `references/templates/sprint-template.md` and is the single source of truth — including the per-story Persona column (per v3.5.0+ stories template), the net-velocity header, and the sprint-level Definition of Done.
 
 Sprint IDs are sequential (SP-00, SP-01, SP-02, …). SP-00 is reserved for setup/architecture sprint if requested.

package/skills/srs/SKILL.md

@@ -14,7 +14,7 @@ Second step of the BA Toolkit pipeline. Generates an SRS adapted from IEEE 830.
 
 0. If `00_principles_*.md` exists in the output directory, load it and apply its conventions (artifact language, ID format, traceability requirements, Definition of Ready, quality gate threshold).
 1. Read `01_brief_*.md` from the output directory. If missing, warn and suggest running `/brief`.
-2. Extract: slug, domain, business goals, functionality, stakeholders, constraints, glossary.
+2. Extract: domain, business goals, functionality, stakeholders, constraints, glossary. The slug comes from `AGENTS.md`, not from the brief filename — see [`../references/slug-source.md`](../references/slug-source.md).
 3. If a matching `references/domains/{domain}.md` file exists (currently: `saas`, `fintech`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, `real-estate`, `igaming`, `edtech`, `govtech`, `ai-ml`), load it and apply its section `2. /srs`.
 
 ## Environment
@@ -118,9 +118,9 @@ FR numbering: sequential within each feature area, three-digit, with reserved ra
 
 ## AGENTS.md update
 
-After `/done`, find the project's `AGENTS.md` (look in cwd first; fall back to walking up the directory tree for legacy v3.0 single-project layouts). **Update only the `## Pipeline Status` row for `/srs`** — toggle its status from `⬜ Not started` to `✅ Done` and fill in the artifact filename (`02_srs_{slug}.md`) 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 add `## Artifacts` / `## Key context` sections** — those are not part of the v3.1+ template.
+After `/done`, find the project's `AGENTS.md` (look in cwd first; if cwd is `output/`, check `../AGENTS.md`). **Update only the `## Pipeline Status` row for `/srs`** — toggle its status from `⬜ Not started` to `✅ Done` and fill in the artifact filename (`02_srs_{slug}.md`) 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 you find no `AGENTS.md` at all, 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 file. Do not create one yourself with arbitrary structure.
+If you find no `AGENTS.md` at all, warn the user that the project was likely not scaffolded with `ba-toolkit init` and tell them to run it. Do not create one yourself with arbitrary structure.
 
 ## Iterative refinement
 

package/skills/stories/SKILL.md

@@ -38,6 +38,8 @@ Supplement with domain-specific questions and typical epics from the reference.
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `03_stories_{slug}.md`
 
 The full template lives at `references/templates/stories-template.md` and is the single source of truth for the per-story field set. The fields are:

package/skills/trace/SKILL.md

@@ -33,6 +33,8 @@ If the user invokes `/trace` with no inline hint, ask the following short calibr
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `00_trace_{slug}.md`
 
 The full per-axis matrix layout lives at `references/templates/trace-template.md` and is the single source of truth. The artifact carries: a Forward Traceability matrix (FR → all downstream artifacts), a Reverse Traceability matrix (US, UC, AC, NFR, Entity, API, WF, SC, Task → FR), Coverage Gaps grouped by severity (Critical / High / Medium / Low per the principles thresholds), Coverage Statistics per artifact pair, and Recommended Actions sorted by severity.

package/skills/usecases/SKILL.md

@@ -41,6 +41,8 @@ Supplement with domain-specific questions and typical exceptional flows from the
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `04_usecases_{slug}.md`
 
 The full per-UC field set lives at `references/templates/usecases-template.md` and is the single source of truth. Each UC carries: Goal in Context, Scope, Level, Primary Actor, Supporting Actors, Stakeholders & Interests, Pre-conditions, Trigger, Main Success Scenario (numbered table), Extensions / Alternative Flows, Exception Flows, Post-conditions (success guarantees + minimal guarantees), Source (linked US/FR), Linked WF, Linked AC. The artifact also carries a US → UC coverage matrix at the bottom.

package/skills/wireframes/SKILL.md

@@ -41,6 +41,8 @@ Supplement with domain-specific questions and typical screens from the reference
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `09_wireframes_{slug}.md`
 
 ```markdown