@kudusov.takhir/ba-toolkit 3.13.1 → 4.0.0

package/CHANGELOG.md

@@ -11,6 +11,31 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [4.0.0] — 2026-04-11
+
+### Changed
+
+- **AGENTS.md now lives at the project root** instead of inside `output/<slug>/`. One directory = one project.
+- **Artifacts save to `output/`** (flat) instead of `output/<slug>/`. The slug is still used in filenames (`01_brief_<slug>.md`) but not in directory structure.
+- **`ba-toolkit init` warns** when `output/` already contains artifacts from a previous project, instead of silently creating a new subfolder.
+- **Skills detect AGENTS.md** at cwd or `../AGENTS.md` (when cwd is `output/`), no longer walking up the full directory tree.
+- **`ba-toolkit publish`** error message and help text updated to reference `output/` instead of `output/<slug>/`.
+- **Shell fallbacks** (`init.sh`, `init.ps1`) updated to match the new layout.
+
+### Removed
+
+- **Multi-project support.** The v3.x `output/<slug>/` per-project subfolder layout is removed. Each directory is now a single project. Running `ba-toolkit init` twice in the same directory merges into the existing root `AGENTS.md` (managed-block merge is preserved).
+
+### Migration from v3.x
+
+If you have an existing v3.x project with `output/<slug>/AGENTS.md`:
+1. Move `output/<slug>/AGENTS.md` to the project root.
+2. Move artifacts from `output/<slug>/*.md` to `output/`.
+3. Remove the empty `output/<slug>/` directory.
+4. Run `ba-toolkit upgrade --for <agent>` to refresh the installed skills.
+
+---
+
 ## [3.13.1] — 2026-04-11
 
 ### Added
@@ -847,6 +872,7 @@ 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
+[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
 [3.12.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.11.0...v3.12.0

package/README.md

@@ -40,8 +40,8 @@ Artifacts are generated in whatever language you write in — ask in English, ge
 
 ```bash
 # Full setup in one command — prompts for project name, domain, and
-# AI agent, then creates output/{slug}/, AGENTS.md, and installs the
-# skills into the chosen agent's directory.
+# AI agent, then creates output/, AGENTS.md, and installs the skills
+# into the chosen agent's directory.
 npx @kudusov.takhir/ba-toolkit init
 
 # Non-interactive (e.g. for CI): pass every choice on the command line.
@@ -54,9 +54,8 @@ ba-toolkit init
 
 Supported agents: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. All five use the native Agent Skills format (folder-per-skill with `SKILL.md`) — Claude Code at `.claude/skills/`, Codex at `~/.codex/skills/`, Gemini at `.gemini/skills/`, Cursor at `.cursor/skills/`, Windsurf at `.windsurf/skills/`. Pass `--dry-run` to preview the install step without writing files, or `--no-install` to create only the project structure and install skills later with `ba-toolkit install --for <agent>`.
 
-**New in v3.1** — multi-project + interview UX:
+**New in v3.1** — interview UX:
 
-- **Multi-project: each `ba-toolkit init` creates `output/<slug>/AGENTS.md`**, scoped to that project. Two agent windows in the same repo can `cd output/alpha && claude` and `cd output/beta && claude` independently — no AGENTS.md collision, no shared state.
 - **Interview options as a 2-column table with letter IDs** (`a`, `b`, `c`, …) instead of a numbered list. Renders cleanly across all 5 supported agents, easier to scan, last row is always free-text "Other".
 - **Inline context after slash commands**: `/brief I want to build an online store for construction materials...` is parsed as a lead-in answer; the skill skips redundant questions and jumps straight to what's missing. Works for all 12 interview-phase skills.
 - **Open-ended lead-in question** for `/brief` and `/principles` when there's no inline context — `Tell me about the project in your own words` — instead of dumping a structured table on the first turn.
@@ -140,7 +139,7 @@ bash init.sh
 .\init.ps1
 ```
 
-Equivalent to `npx @kudusov.takhir/ba-toolkit init` — asks for a slug, name, and domain, then creates `output/{slug}/` and an `AGENTS.md` with the pipeline status table.
+Equivalent to `npx @kudusov.takhir/ba-toolkit init` — asks for a slug, name, and domain, then creates `output/` and an `AGENTS.md` with the pipeline status table.
 
 ### Updating a manual install
 
@@ -364,7 +363,7 @@ Use `/clarify` at any step to resolve ambiguities before moving on. Approximate
 
 ## Usage guide
 
-Full walkthrough of the pipeline in day-to-day use — starting a project, moving between steps, `/clarify`, `/analyze`, `/trace`, `/split`, working with multiple projects, and `AGENTS.md` — lives in [docs/USAGE.md](docs/USAGE.md).
+Full walkthrough of the pipeline in day-to-day use — starting a project, moving between steps, `/clarify`, `/analyze`, `/trace`, `/split`, and `AGENTS.md` — lives in [docs/USAGE.md](docs/USAGE.md).
 
 For common issues and fixes, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
 

package/bin/ba-toolkit.js

@@ -956,22 +956,21 @@ async function cmdInit(args) {
   log('');
   log('  ' + green('Creating project structure...'));
 
-  const outputDir = path.join('output', slug);
+  const outputDir = 'output';
   if (!fs.existsSync(outputDir)) {
     fs.mkdirSync(outputDir, { recursive: true });
-    log(`    created  ${outputDir}`);
+    log(`    created  ${outputDir}/`);
   } else {
-    log(`    exists   ${outputDir}`);
+    // Warn if output/ already contains artifacts from a previous project.
+    const existing = fs.readdirSync(outputDir).filter((f) => ARTIFACT_FILE_RE.test(f));
+    if (existing.length > 0) {
+      log('    ' + yellow(`⚠  output/ already has ${existing.length} artifact(s). Pipeline skills may overwrite them.`));
+    } else {
+      log(`    exists   ${outputDir}/`);
+    }
   }
 
-  // AGENTS.md: per-project, lives inside output/<slug>/. Two agent
-  // windows can now work on two different projects in the same repo
-  // without colliding — each cd-s into its own output/<slug>/ folder
-  // and finds its own AGENTS.md there. The merge-on-reinit behaviour
-  // (managed-block anchors) still applies, just at per-project scope.
-  // See mergeAgentsMd for the three branches (created, merged,
-  // preserved).
-  const agentsPath = path.join(outputDir, 'AGENTS.md');
+  const agentsPath = 'AGENTS.md';
   const existingAgents = fs.existsSync(agentsPath)
     ? fs.readFileSync(agentsPath, 'utf8')
     : null;
@@ -1004,34 +1003,32 @@ async function cmdInit(args) {
 
   // --- 7. Final message ---
   log('');
-  log('  ' + cyan(`Project '${name}' (${slug}) is ready in ${outputDir}/.`));
+  log('  ' + cyan(`Project '${name}' (${slug}) is ready.`));
   log('');
   log('  ' + yellow('Next steps:'));
   if (installed === true) {
     log('    1. ' + AGENTS[agentId].restartHint);
-    log('    2. ' + bold(`cd ${outputDir}`) + ' — open your AI agent in this folder.');
-    log('       Each project has its own AGENTS.md, so two agent windows');
-    log('       can work on two different projects in the same repo.');
+    log('    2. Open your AI agent in this folder.');
     log('    3. Optional: run /discovery if you do not yet know what to build,');
     log('       or /principles to define project-wide conventions');
     log('    4. Run /brief to start the BA pipeline');
   } else if (installed === false) {
     log('    1. Skill install was cancelled. To install later, run:');
     log('         ' + gray(`ba-toolkit install --for ${agentId}`));
-    log('    2. ' + bold(`cd ${outputDir}`) + ' and open your AI agent there.');
+    log('    2. Open your AI agent in this folder.');
     log('    3. Optional: run /discovery if you do not yet know what to build,');
     log('       or /principles to define project-wide conventions');
     log('    4. Run /brief to start the BA pipeline');
   } else {
     log('    1. Install skills for your agent:');
     log('         ' + gray('ba-toolkit install --for claude-code'));
-    log('    2. ' + bold(`cd ${outputDir}`) + ' and open your AI agent there.');
+    log('    2. Open your AI agent in this folder.');
     log('    3. Optional: run /discovery if you do not yet know what to build,');
     log('       or /principles to define project-wide conventions');
     log('    4. Run /brief to start the BA pipeline');
   }
   log('');
-  log('  ' + gray(`Artifacts and AGENTS.md live in: ${outputDir}/`));
+  log('  ' + gray('AGENTS.md is at the project root. Artifacts are saved to output/.'));
   log('');
 }
 
@@ -1744,7 +1741,7 @@ async function cmdPublish(args) {
 
   if (artifacts.length === 0) {
     logError(`No BA Toolkit artifacts found in ${cwd}.`);
-    log('  Run this command from inside ' + cyan('output/<slug>/') + ' after generating artifacts.');
+    log('  Run this command from inside ' + cyan('output/') + ' after generating artifacts.');
     process.exit(1);
   }
 
@@ -1867,7 +1864,7 @@ ${bold('USAGE')}
 ${bold('COMMANDS')}
   init                           One-command project setup: prompts for name,
                                  slug, domain, and AI agent, then creates
-                                 output/{slug}/, AGENTS.md, and installs the
+                                 output/, AGENTS.md, and installs the
                                  skills into the chosen agent's directory.
   install --for <agent>          Install (or re-install) skills into an
                                  agent's directory without creating a project.
@@ -1884,7 +1881,7 @@ ${bold('COMMANDS')}
                                  report which versions are installed where.
                                  Read-only; no flags.
   publish [--format <fmt>]       Bundle the artifacts in the current
-                                 output/<slug>/ folder into import-ready
+                                 output/ folder into import-ready
                                  files for Notion (markdown) and Confluence
                                  (HTML). Format: notion, confluence, or
                                  both (default). No API calls, no tokens —
@@ -1944,7 +1941,7 @@ ${bold('EXAMPLES')}
   ba-toolkit status
 
   # Bundle a project's artifacts for Notion + Confluence import.
-  cd output/my-app
+  cd output
   ba-toolkit publish
   ba-toolkit publish --format notion --out ./share
   ba-toolkit publish --format confluence --dry-run

package/package.json

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

@@ -101,7 +101,7 @@ If a domain reference is loaded, supplement general questions with domain-specif
 
 ### 6. AGENTS.md update
 
-`ba-toolkit init` already created `AGENTS.md` next to where the artifact lives — typically in the current working directory (the user is expected to `cd output/<slug>` after running init). After saving `01_brief_{slug}.md`, find the project's `AGENTS.md` (look in cwd first; fall back to walking up the directory tree if cwd has none, for legacy v3.0 single-project layouts).
+`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.
 

package/skills/discovery/SKILL.md

@@ -125,7 +125,7 @@ Things we don't yet know and need to learn before committing real resources.
 
 ### 6. AGENTS.md update
 
-`ba-toolkit init` already created `AGENTS.md` next to where the artifact lives — typically in the current working directory (the user is expected to `cd output/<slug>` after running init). After saving `00_discovery_{slug}.md`, find the project's `AGENTS.md` (look in cwd first; fall back to walking up the directory tree if cwd has none, for legacy v3.0 single-project layouts).
+`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.
 

package/skills/export/SKILL.md

@@ -200,8 +200,8 @@ Compatible with Jira CSV import, Trello, Asana, Monday.com, and Google Sheets. I
 Save the export file to the output directory alongside the artifacts:
 
 ```
-output/{slug}/export_{slug}_{format}.json
-output/{slug}/export_{slug}_stories.csv   (CSV format)
+output/export_{slug}_{format}.json
+output/export_{slug}_stories.csv   (CSV format)
 ```
 
 ## Closing message

package/skills/implement-plan/SKILL.md

@@ -246,13 +246,13 @@ Machine-readable dependency graph. A topological sort of this table yields a val
 
 ### 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).
+`ba-toolkit init` already created `AGENTS.md` at the project root. After saving `12_implplan_{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 `/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.
+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.
 
 ### 9. Iterative refinement
 

package/skills/publish/SKILL.md

@@ -6,7 +6,7 @@ description: >
 
 # /publish — Notion / Confluence Publish
 
-Utility skill. Wraps the `ba-toolkit publish` CLI subcommand, which converts the markdown artifacts in the current `output/<slug>/` folder into folders ready to be dragged into Notion's **Import → Markdown & CSV** dialog or zipped and uploaded via Confluence's **Space settings → Content tools → Import → HTML** tool.
+Utility skill. Wraps the `ba-toolkit publish` CLI subcommand, which converts the markdown artifacts in the current `output/` folder into folders ready to be dragged into Notion's **Import → Markdown & CSV** dialog or zipped and uploaded via Confluence's **Space settings → Content tools → Import → HTML** tool.
 
 The conversion happens entirely on disk — **no API calls, no tokens, no network**. The user does the actual upload manually using each tool's native importer.
 
@@ -20,7 +20,7 @@ This is **not** the same as `/export`. `/export` produces JSON/CSV for issue tra
 
 ### 1. Environment detection
 
-The `ba-toolkit publish` subcommand uses the current working directory as the source — no `references/environment.md` lookup needed. Confirm with the user that they are inside their project's `output/<slug>/` folder before running it. If they are not, ask them to `cd output/<slug>` first.
+The `ba-toolkit publish` subcommand uses the current working directory as the source — no `references/environment.md` lookup needed. Confirm with the user that they are inside their project's `output/` folder before running it. If they are not, ask them to `cd output` first.
 
 ### 2. Pipeline check
 
@@ -47,7 +47,7 @@ Map the answer to a `--format` value: `a` → `both`, `b` → `notion`, `c` →
 
 ### 4. Execution
 
-Invoke the CLI subcommand via the agent's Bash tool from the project's `output/<slug>/` directory:
+Invoke the CLI subcommand via the agent's Bash tool from the project's `output/` directory:
 
 ```bash
 ba-toolkit publish --format <choice>

package/skills/references/closing-message.md

@@ -78,7 +78,7 @@ Their closing block ends after the "Available commands" table. Optionally, they
 
 ## Rules
 
-- `{file_path}` is the full path where the artifact was saved (typically `output/<slug>/{NN}_{name}_{slug}.md`).
+- `{file_path}` is the full path where the artifact was saved (typically `output/{NN}_{name}_{slug}.md`).
 - The summary line is generated dynamically — do not repeat boilerplate; mention actual numbers and decisions ("18 FRs across 3 roles, 4 risks captured", not "the artifact was generated").
 - The "Available commands" table is fixed (5 rows for pipeline skills). Utility skills omit `/done` from the table since they don't have a "finalize" state.
 - The "Next step" block is built from the lookup table above. Do not hardcode it in individual SKILL.md files.

package/skills/references/environment.md

@@ -33,44 +33,26 @@ Skills should not hardcode paths. They reference this file and apply the detecti
 
 ## Output folder structure
 
-**v3.1+ default — per-project subfolder.** `ba-toolkit init` creates `output/<slug>/` and writes the project's `AGENTS.md` inside it. All artifacts for that project also live there:
+`ba-toolkit init` creates `AGENTS.md` at the project root and `output/` for artifacts. One directory = one project.
 
 ```
 repo/
-  output/
-    my-app/                        ← project A
-      AGENTS.md
-      00_principles_my-app.md
-      01_brief_my-app.md
-      02_srs_my-app.md
-      ...
-    other-project/                 ← project B
-      AGENTS.md
-      01_brief_other-project.md
-      ...
-```
-
-The user opens their AI agent inside one of those subfolders (`cd output/my-app && claude` or equivalent for the agent of choice). With cwd set to the project subfolder, every skill — including those that look for prior artifacts via `01_brief_*.md` glob — sees only that project's files. Two agent windows in the same repo, each `cd`-ed into a different `output/<slug>/`, work on two completely independent projects with zero cross-talk.
-
-**Legacy v3.0 single-project layout — still supported.** Projects scaffolded before v3.1 have a single `AGENTS.md` at the repo root and artifacts saved flat under `output/`:
-
-```
-repo/
-  AGENTS.md                        ← legacy single-project
+  AGENTS.md
   output/
     01_brief_my-app.md
     02_srs_my-app.md
+    03_stories_my-app.md
     ...
 ```
 
-When a skill is run with cwd set to the repo root and finds no `AGENTS.md` next to the artifacts, it walks up the directory tree to find the legacy root `AGENTS.md`. New projects scaffolded with v3.1+ should always use the per-project subfolder layout.
+The user opens their AI agent at the project root. Skills find `AGENTS.md` in the current working directory and save artifacts to `output/`.
 
 ## Detection rule for skills
 
 When a skill needs to find the project's `AGENTS.md` (for example, to update its `## Pipeline Status` table after generating an artifact):
 
 1. Check `cwd/AGENTS.md` first. If present, that's the project's file.
-2. Otherwise walk up the directory tree until you find an `AGENTS.md` (legacy v3.0 fallback).
+2. If cwd is `output/`, check `../AGENTS.md` (the project root).
 3. If neither exists, warn the user that the project was likely not scaffolded with `ba-toolkit init` and tell them to run it.
 
-Never create `AGENTS.md` at the repo root from inside a skill — that file is owned by `ba-toolkit init`.
+Never create `AGENTS.md` from inside a skill — that file is owned by `ba-toolkit init`.

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

@@ -9,7 +9,7 @@
 **Slug:** [SLUG]
 **Domain:** [DOMAIN]
 **Language:** English
-**Output folder:** output/[SLUG]/
+**Output folder:** output/
 <!-- ba-toolkit:end managed -->
 
 ## Pipeline Status

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

@@ -124,7 +124,7 @@ Top architectural decisions from `07a_research_[SLUG].md`. Dev team should read
 ## 8. Artifact Files Reference
 
 ```
-output/[SLUG]/
+output/
 ├── 00_discovery_[SLUG].md
 ├── 00_principles_[SLUG].md
 ├── 00_analyze_[SLUG].md