@kudusov.takhir/ba-toolkit 4.0.3 → 4.1.0

package/CHANGELOG.md

@@ -11,6 +11,29 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [4.1.0] — 2026-04-12
+
+### Added
+
+- **5 new refinement skills promoted from inline subcommands to standalone utility skills.** `/validate`, `/revise`, `/expand`, `/split`, and `/done` now have their own `skills/{name}/SKILL.md` files and work as first-class skills in every supported agent. Previously these were documented as "subcommands" but had no SKILL.md — typing them triggered "Unknown skill" errors. Each skill follows the established `/clarify` pattern: YAML frontmatter with trigger phrases, context loading, environment detection, slug source, and closing message format.
+  - **`/validate`** — single-artifact completeness and consistency check: mandatory fields, ID format, cross-references, MoSCoW count verification, Definition of Ready compliance. Reports findings by severity; offers auto-fix.
+  - **`/revise [section]`** — rewrites a specific section based on user feedback or an `/analyze` finding ID (e.g., `/revise A1`). Includes ripple-effect check across downstream artifacts.
+  - **`/expand [section]`** — adds depth and detail to an under-developed section using domain knowledge and prior artifacts. Preserves existing content.
+  - **`/split [element]`** — decomposes an oversized FR, User Story, or Use Case into smaller pieces using INVEST criteria and Mike Cohn's nine story-splitting patterns. Updates cross-references.
+  - **`/done`** — finalizes the current artifact (Version 1.0, Status: Approved), runs a quality gate check (blocks on CRITICAL findings), updates `AGENTS.md` pipeline status, and presents the next pipeline step.
+- **Skill count increased from 24 to 29** across all documentation, package metadata, and test assertions.
+- **"Subcommands" terminology retired** — all references to "subcommands" in documentation updated to "refinement skills". The `## Subcommands` section in COMMANDS.md and README.md replaced with `## Refinement skills` with full skill descriptions.
+
+---
+
+## [4.0.4] — 2026-04-12
+
+### Fixed
+
+- **`/risk` and `/glossary` used wrong path prefix for domain references** — `skills/references/domains/{domain}.md` instead of `references/domains/{domain}.md`. The `skills/` prefix pointed to a repo-root-relative path that does not exist in the installed agent directory (e.g., `.claude/skills/`), so AI agents could fail to load the domain file when running these two skills. All other skills already used the correct relative path.
+
+---
+
 ## [4.0.3] — 2026-04-12
 
 ### Fixed
@@ -899,7 +922,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.3...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.1.0...HEAD
+[4.1.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.4...v4.1.0
+[4.0.4]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.3...v4.0.4
 [4.0.3]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.2...v4.0.3
 [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

package/COMMANDS.md

@@ -1,6 +1,6 @@
 # BA Toolkit — Command Reference
 
-Quick reference for all 24 skills and subcommands. For term and acronym definitions (FR, US, AC, IEEE 830, etc.), see the [glossary](docs/GLOSSARY.md).
+Quick reference for all 29 skills. For term and acronym definitions (FR, US, AC, IEEE 830, etc.), see the [glossary](docs/GLOSSARY.md).
 
 ---
 
@@ -46,17 +46,17 @@ Available at any pipeline stage.
 
 ---
 
-## Subcommands
+## Refinement skills
 
-Available within any active pipeline skill (after generation, before `/done`).
+Available at any pipeline stage after the first artifact exists. These skills refine and validate artifacts without advancing the pipeline (except `/done`, which finalizes and moves on).
 
-| Subcommand | What it does |
-|------------|-------------|
-| `/revise [section]` | Rewrite a specific section with your feedback |
-| `/expand [section]` | Add more detail to a section |
-| `/split [element]` | Break a large element into smaller ones (e.g., split an oversized User Story) |
-| `/validate` | Check completeness, consistency, and alignment with prior artifacts |
-| `/done` | Finalise the current artifact and move to the next pipeline step |
+| Command | Output file | What it generates |
+|---------|-------------|-------------------|
+| `/validate` | _(reports in chat)_ | Completeness and consistency check for a single artifact: mandatory fields, ID format, cross-references, MoSCoW counts, Definition of Ready |
+| `/revise [section]` | _(updates existing artifact)_ | Section rewrite: applies user feedback or resolves an `/analyze` finding, with ripple-effect check across downstream artifacts |
+| `/expand [section]` | _(updates existing artifact)_ | Section expansion: adds depth, detail, and missing elements to an under-developed section |
+| `/split [element]` | _(updates existing artifact)_ | Element decomposition: breaks an oversized FR, User Story, or Use Case into smaller pieces using INVEST criteria and Cohn's splitting patterns |
+| `/done` | _(updates AGENTS.md)_ | Finalize: quality gate check, artifact metadata update (Version 1.0, Status: Approved), AGENTS.md pipeline advancement |
 
 ---
 

package/README.md

@@ -22,7 +22,7 @@ Turn a rough project idea into a complete, structured specification — then han
 
 ## What is this
 
-BA Toolkit turns a rough project idea into a complete, structured specification — requirements, user stories, acceptance criteria, API contracts, wireframes, and a step-by-step implementation plan. It runs as **24 AI-powered skills** inside your coding agent (Claude Code, Cursor, Codex CLI, Gemini CLI, or Windsurf) and produces Markdown documents that are cross-referenced, traceable, and ready for development or stakeholder review.
+BA Toolkit turns a rough project idea into a complete, structured specification — requirements, user stories, acceptance criteria, API contracts, wireframes, and a step-by-step implementation plan. It runs as **29 AI-powered skills** inside your coding agent (Claude Code, Cursor, Codex CLI, Gemini CLI, or Windsurf) and produces Markdown documents that are cross-referenced, traceable, and ready for development or stakeholder review.
 
 **How it works:** you type a slash command (e.g., `/brief`), the agent asks you a series of focused questions about your project, and generates a structured document. Each step builds on the previous ones — requirements link to user stories, stories link to acceptance criteria, and so on through the entire chain. After the last step, you have a complete specification package that a developer or AI coding agent can execute.
 
@@ -119,11 +119,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 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.
+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 29 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 24 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 29 skills there natively. Reload the Windsurf window to pick them up.
 
 ### Aider
 
@@ -318,11 +318,13 @@ Adding a new domain = creating one Markdown file in `skills/references/domains/`
 
 ## How it works
 
-Most pipeline skills follow the same cycle: **Command → Context → Interview → Generate → Refine**. Each skill loads all previous artifacts plus the domain reference and project principles, asks a few rounds of targeted questions, writes a Markdown artifact, and offers refinement subcommands before moving on. `/handoff`, `/trace`, and `/analyze` skip the interview — they extract everything from existing artifacts automatically.
+Most pipeline skills follow the same cycle: **Command → Context → Interview → Generate → Refine**. Each skill loads all previous artifacts plus the domain reference and project principles, asks a few rounds of targeted questions, writes a Markdown artifact, and offers refinement skills before moving on. `/handoff`, `/trace`, and `/analyze` skip the interview — they extract everything from existing artifacts automatically.
 
 Every artifact links back to its predecessors, forming the chain `FR → US → UC → AC → NFR → Entity → ADR → API → WF → Scenario` (see [glossary](docs/GLOSSARY.md) for definitions). Run `/trace` to verify coverage and `/analyze` for severity-rated findings (duplicates, ambiguous terms, terminology drift, invalid references).
 
-### Subcommands
+### Refinement skills
+
+Available at any pipeline stage after the first artifact exists. These skills refine and validate artifacts without advancing the pipeline (except `/done`, which finalizes and moves on).
 
 | Command | What it does |
 |---------|-------------|
@@ -338,7 +340,7 @@ Every artifact links back to its predecessors, forming the chain `FR → US →
 
 ## Minimum viable pipeline
 
-Not every project needs all 24 skills. Three common paths:
+Not every project needs all 29 skills. Three common paths:
 
 **Concept-first** (when you don't yet know what to build):
 ```

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 24 skills natively in this layout for every agent. No
+// installs the 29 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": "4.0.3",
-  "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.",
+  "version": "4.1.0",
+  "description": "AI-powered Business Analyst pipeline — 29 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/done/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: done
+description: >
+  Finalize the current artifact and advance to the next pipeline step. Use on /done command, or when the user says "done with this", "finalize", "lock this artifact", "move on", "next step", "mark as done", "approve this artifact". Gates on CRITICAL findings from /validate or /analyze. Updates AGENTS.md pipeline status.
+---
+
+# /done — Finalize & Advance
+
+Utility skill. Finalizes the current artifact, updates `AGENTS.md`, and presents the next pipeline step. This is the only refinement skill that advances the pipeline.
+
+## Syntax
+
+```
+/done [optional: artifact reference]
+```
+
+Examples:
+- `/done` — finalize the most recent artifact
+- `/done brief` — finalize the brief specifically
+- `/done srs` — finalize the SRS
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it. Use its quality gate (section 6) to determine which severity blocks finalization.
+1. Identify the target artifact:
+   - If the user specifies an artifact name, use it.
+   - Otherwise, use the most recently generated artifact in the output directory.
+2. Read the target artifact fully.
+3. Read `AGENTS.md` to find the pipeline status table.
+4. If `00_analyze_*.md` exists, check for unresolved CRITICAL findings against this artifact.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Slug source
+
+Read `references/slug-source.md` from the `ba-toolkit` directory. Follow its rules to resolve the project slug from `AGENTS.md`.
+
+## Finalization workflow
+
+### Step 1 — Quality gate check
+
+Before finalizing, run a lightweight validation:
+
+1. **Check for CRITICAL findings.** If `00_analyze_*.md` exists and contains unresolved CRITICAL findings for this artifact, block finalization:
+
+```
+Cannot finalize — {N} CRITICAL finding(s) remain:
+- A1: MoSCoW counts mismatch in §6
+- A5: FR-012 referenced but does not exist
+
+Fix these with `/revise` or `/validate`, then retry `/done`.
+```
+
+2. **Quick completeness scan.** Check for placeholder text (`(TBD)`, `(TODO)`, empty required fields). If found, warn but do not block:
+
+```
+⚠ {N} placeholder(s) found — consider resolving before finalizing:
+- §5: "(имя основателя)" in stakeholders table
+- FR-018: Source field is "(TBD)"
+
+Finalize anyway? (yes / fix first)
+```
+
+3. **If no blockers**, proceed to finalization.
+
+### Step 2 — Update artifact metadata
+
+Update the artifact header:
+
+- **Version:** bump to `1.0` (or the next whole number if already versioned).
+- **Status:** change from `Draft` to `Approved`.
+- **Date:** update to today's date.
+
+### Step 3 — Update AGENTS.md
+
+Find the `## Pipeline Status` table in `AGENTS.md`. Update the row for the current skill:
+
+- **Status:** `⬜ Not started` or `🔄 In progress` → `✅ Done`
+- **File:** fill in the artifact filename (e.g., `output/01_brief_sock-market.md`)
+
+**Do not touch the managed block** (`<!-- ba-toolkit:begin managed -->` … `<!-- ba-toolkit:end managed -->`) — that is owned by `ba-toolkit init`.
+
+### Step 4 — Present next step
+
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md`. Look up the row where `Current` matches the skill that produced the finalized artifact, and present the four `→` lines:
+
+```
+✓ Artifact finalized: `{file_path}` — Version 1.0, Status: Approved.
+
+AGENTS.md updated: {skill} → ✅ Done.
+
+Next step: /{next_command}
+
+  → What it produces: {description}
+  → Output file: {NN}_{name}_{slug}.md
+  → Time estimate: {min}–{max} minutes
+  → After that: /{step_after_next} ({description})
+```
+
+If the finalized artifact is from `/implement-plan` (the last pipeline step), present:
+
+```
+✓ Artifact finalized: `{file_path}` — Version 1.0, Status: Approved.
+
+Pipeline complete. Hand `12_implplan_{slug}.md` to your AI coding agent (Claude Code, Cursor, Windsurf, Codex, Gemini) to begin implementation.
+```
+
+## Edge cases
+
+- **Artifact already finalized.** If the artifact's Status is already `Approved` and AGENTS.md already shows `✅ Done`, inform the user and do nothing.
+- **Multiple artifacts pending.** `/done` finalizes one artifact at a time. If the user wants to finalize multiple, they run `/done` once per artifact.
+- **No AGENTS.md.** Warn the user that the project was likely not scaffolded with `ba-toolkit init`. Finalize the artifact metadata but skip the AGENTS.md update.
+
+## Style
+
+Formal, neutral. Generate output in the language of the artifact.

package/skills/expand/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: expand
+description: >
+  Add more depth and detail to an under-developed section of a BA Toolkit artifact. Use on /expand command, or when the user asks to "expand this section", "add more detail", "flesh out", "elaborate on", "go deeper on", "add depth to", "develop further". Utility skill available at any pipeline stage after the first artifact exists.
+---
+
+# /expand — Section Expansion
+
+Utility skill. Adds depth, detail, and coverage to a thin or under-developed section of the target artifact. Updates the artifact in place; does not generate a new file.
+
+## Syntax
+
+```
+/expand [section reference] [optional: inline guidance]
+```
+
+Examples:
+- `/expand risks` — expand the risks section of the most recent artifact
+- `/expand §7` — expand section 7
+- `/expand §3.2 add edge cases for payment failures` — expand with specific direction
+- `/expand assumptions in brief` — expand the assumptions section of the brief
+- `/expand FR-003` — expand a specific functional requirement with more detail
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it.
+1. Identify the target artifact:
+   - If the user specifies an artifact name (e.g., "in brief", "in srs"), use it.
+   - Otherwise, use the most recently generated artifact in the output directory.
+2. Read the target artifact fully.
+3. Read prior artifacts for context that can inform the expansion.
+4. Load the domain reference (`references/domains/{domain}.md`) if available — domain-specific knowledge helps generate richer content.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Slug source
+
+Read `references/slug-source.md` from the `ba-toolkit` directory. Follow its rules to resolve the project slug from `AGENTS.md`.
+
+## Section identification
+
+Use the same identification strategy as `/revise`:
+
+1. **Section number.** `§3`, `section 3`, `§3.2`.
+2. **Section name keyword.** `risks`, `constraints`, `assumptions`, `glossary`.
+3. **Element ID.** `FR-003`, `US-012` — expand that specific element.
+
+If the section cannot be identified, ask the user to clarify.
+
+## Expansion workflow
+
+### Step 1 — Assess current state
+
+Read the target section and assess what is thin or missing:
+
+- **Tables with few rows** — can more rows be added based on the domain reference, prior artifacts, or industry knowledge?
+- **Single-sentence descriptions** — can they be expanded with acceptance criteria, edge cases, or examples?
+- **Missing sub-sections** — does the template for this artifact type include sub-sections that are absent?
+- **Bare elements** — elements with only required fields but no optional fields (Source, Rationale, Verification method, etc.)?
+
+### Step 2 — Generate expansion
+
+If the user provided inline guidance, follow it. Otherwise, use domain knowledge and prior artifacts to determine what to add.
+
+Follow these rules:
+
+1. **Add, don't replace.** Preserve all existing content. New content is appended or inserted at the appropriate position.
+2. **Follow the artifact's conventions.** Match ID scheme, heading levels, table columns, and language.
+3. **Ground in prior artifacts.** Every new element (FR, risk, assumption, etc.) should trace back to something in a prior artifact or in the domain reference. Do not invent requirements that contradict existing decisions.
+4. **Respect MoSCoW.** New elements added during expansion are typically Should or Could priority unless the user explicitly marks them higher.
+5. **Update counts.** If the artifact has a summary table with counts (e.g., MoSCoW distribution), update it after adding new elements.
+
+### Step 3 — Present and confirm
+
+Before saving, present a summary of what will be added:
+
+```
+Expanding §{N}: {section title}
+
+Adding:
+- {N} new {element type}(s): {brief list}
+- {N} fields enriched on existing elements
+- Sub-section "{name}" added
+
+Total section size: {before} → {after} elements.
+
+Apply? (yes / adjust — describe what to change)
+```
+
+For small expansions (fewer than 3 changes), skip the confirmation and apply directly with a one-line acknowledgment.
+
+### Step 4 — Save
+
+Save the updated artifact. Bump the version (e.g., `0.1` → `0.2`) and update the date.
+
+## Closing message
+
+After saving, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Summary of what was added (element counts, new sub-sections).
+- Any new cross-references created.
+
+Available commands: `/expand [section]` (expand another section) · `/validate` · `/clarify [focus]` · `/revise [section]` · `/done`
+
+No pipeline advancement — return to the current artifact's workflow.
+
+## Style
+
+Formal, neutral. Generate output in the language of the artifact.

package/skills/glossary/SKILL.md

@@ -40,7 +40,7 @@ Examples:
    - `10_scenarios_{slug}.md` — persona names, scenario types
    - `11_handoff_{slug}.md` — any additional terms
    - `12_implplan_{slug}.md` — phase names, task ids, technology choices from the Tech Stack header
-2. Load `skills/references/domains/{domain}.md` — Domain Glossary section.
+2. Load `references/domains/{domain}.md` — Domain Glossary section.
 3. If `00_glossary_{slug}.md` already exists, load it to merge rather than replace.
 
 ## Environment

package/skills/revise/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: revise
+description: >
+  Rewrite a specific section of a BA Toolkit artifact with new feedback. Use on /revise command, or when the user asks to "revise a section", "rewrite this part", "update section", "fix section", "change section", "rework this", "apply feedback". Accepts a section name, section number, or an /analyze finding ID. Utility skill available at any pipeline stage after the first artifact exists.
+---
+
+# /revise — Section Rewrite
+
+Utility skill. Rewrites a specific section (or resolves a specific finding) in the target artifact based on the user's feedback. Updates the artifact in place; does not generate a new file.
+
+## Syntax
+
+```
+/revise [section reference or finding ID] [optional: inline feedback]
+```
+
+Examples:
+- `/revise §6` — revise section 6 of the most recent artifact
+- `/revise risks` — revise the risks section
+- `/revise A1` — resolve finding A1 from the latest `/analyze` report
+- `/revise §3 add more detail about payment processing` — revise with inline direction
+- `/revise V-002` — resolve finding V-002 from the latest `/validate` report
+- `/revise section 7 in brief` — revise section 7 of the brief specifically
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it. Use its conventions for maintaining consistency during the rewrite.
+1. Identify the target artifact:
+   - If the user specifies an artifact name (e.g., "in brief", "in srs"), use it.
+   - If the user specifies a finding ID (e.g., `A1`, `V-002`), locate the finding in `00_analyze_*.md` or the last `/validate` output, and use the artifact referenced by that finding.
+   - Otherwise, use the most recently generated artifact in the output directory.
+2. Read the target artifact fully.
+3. Read prior artifacts for cross-reference context (roles, terms, IDs).
+4. If the user referenced an `/analyze` finding, read `00_analyze_*.md` to understand the finding details and recommendation.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Slug source
+
+Read `references/slug-source.md` from the `ba-toolkit` directory. Follow its rules to resolve the project slug from `AGENTS.md`.
+
+## Section identification
+
+Identify the target section using one of these strategies (in order of priority):
+
+1. **Section number.** `§3`, `section 3`, `§3.2` — match the `## 3.` or `### 3.2` heading.
+2. **Section name keyword.** `risks`, `constraints`, `stakeholders`, `MoSCoW`, `glossary` — match the closest heading by keyword.
+3. **Finding ID.** `A1`, `A2`, `V-001` — read the finding's `Location` field to identify the section and element.
+4. **Element ID.** `FR-003`, `US-012` — find the element and its containing section.
+
+If the section cannot be identified, ask the user to clarify.
+
+## Revision workflow
+
+### Step 1 — Understand the change
+
+If the user provided inline feedback (e.g., `/revise §3 add payment processing details`), use it directly.
+
+If the user provided only a section reference, ask one focused question:
+
+```
+Section {N}: {section title} — {current content summary in one line}.
+
+What should change? (Describe the update, or type "apply A1" to use an /analyze recommendation.)
+```
+
+If the user referenced a finding ID, extract the finding's `Recommendation` field and confirm:
+
+```
+Finding {ID}: {summary}. Recommendation: {recommendation}.
+
+Apply this recommendation? (yes / adjust — type your version)
+```
+
+### Step 2 — Rewrite
+
+Rewrite the identified section following these rules:
+
+1. **Preserve structure.** Keep the same heading level, table format, and element ID scheme.
+2. **Preserve unchanged content.** Only modify what needs to change. Do not rewrite adjacent sections.
+3. **Maintain cross-references.** If the rewrite changes an element ID, update all internal references within the artifact.
+4. **Follow artifact conventions.** Match the style, language, and format of the rest of the artifact.
+5. **Update metadata.** Bump the artifact version (e.g., `0.1` → `0.2`) and update the date.
+
+### Step 3 — Ripple-effect check
+
+Before saving, check whether the change affects other artifacts:
+
+- A changed role definition affects `/srs` Roles, `/stories` personas, `/usecases` actors, `/scenarios` personas.
+- A changed business rule affects `/srs` business rules, `/ac` Given/When/Then conditions, `/datadict` constraints, `/apicontract` validation rules.
+- A changed FR affects `/stories` (linked FR), `/usecases` (linked FR), `/ac` (linked US → FR), `/nfr` (if the FR had NFR implications).
+- A removed or renumbered element affects every artifact that references its ID.
+
+If ripple effects are detected, list the affected files and offer to update them:
+
+```
+This change affects {N} other artifact(s):
+- `02_srs_*.md` — roles section references the changed role
+- `03_stories_*.md` — 2 stories link to the modified FR
+
+Update them now? (yes / no / pick files)
+```
+
+### Step 4 — Save
+
+Save the updated artifact. If the user approved ripple-effect updates, save those too.
+
+## Closing message
+
+After saving, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path(s).
+- Summary of what changed (section, element count, nature of change).
+- Any ripple-effect updates applied or deferred.
+
+Available commands: `/revise [section]` (revise another section) · `/validate` · `/clarify [focus]` · `/done`
+
+No pipeline advancement — return to the current artifact's workflow.
+
+## Style
+
+Formal, neutral. Generate output in the language of the artifact.

package/skills/risk/SKILL.md

@@ -28,7 +28,7 @@ Examples:
    - `06_nfr_{slug}.md` — NFR targets that are aggressive or uncertain (performance, security, availability)
    - `07a_research_{slug}.md` — ADR alternatives rejected, integration unknowns, technology risks
    - `08_apicontract_{slug}.md` — third-party API dependencies, rate limits, SLA gaps
-2. Load `skills/references/domains/{domain}.md` — note any domain-specific compliance or regulatory risk categories.
+2. Load `references/domains/{domain}.md` — note any domain-specific compliance or regulatory risk categories.
 3. If `00_risks_{slug}.md` already exists, load it to merge rather than replace.
 
 ## Environment

package/skills/split/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: split
+description: >
+  Break a large element (FR, User Story, Use Case, etc.) into smaller, more manageable pieces. Use on /split command, or when the user asks to "split this story", "break down", "decompose", "this is too big", "split requirement", "make smaller". References INVEST criteria for User Stories and Mike Cohn's nine story-splitting patterns. Utility skill available at any pipeline stage after the first artifact exists.
+---
+
+# /split — Element Decomposition
+
+Utility skill. Breaks a large element (FR, US, UC, AC, NFR) into smaller, well-scoped pieces. Updates the artifact in place; does not generate a new file.
+
+## Syntax
+
+```
+/split [element ID] [optional: split strategy hint]
+```
+
+Examples:
+- `/split US-014` — split User Story 014
+- `/split FR-003` — split Functional Requirement 003
+- `/split US-014 by user role` — split by role (one of Cohn's patterns)
+- `/split UC-005 by happy path vs error paths` — split by flow
+- `/split FR-012 into CRUD operations` — split by operation
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it. Use its ID conventions (section 2) to assign new IDs and its Definition of Ready (section 4) to validate the resulting elements.
+1. Identify the target artifact by finding the element ID in the output directory.
+2. Read the target artifact fully.
+3. Read prior artifacts for context (the element's linked FRs, upstream brief goals, etc.).
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Slug source
+
+Read `references/slug-source.md` from the `ba-toolkit` directory. Follow its rules to resolve the project slug from `AGENTS.md`.
+
+## Split strategies
+
+Use the appropriate strategy based on the element type and the user's hint. If no hint is provided, choose the best strategy automatically.
+
+### For User Stories — INVEST + Cohn's nine patterns
+
+A story should be split when it violates the **S** (Small) or **I** (Independent) criteria of INVEST. Apply one of Mike Cohn's nine story-splitting patterns:
+
+1. **By workflow step.** "As a buyer, I can purchase an item" → separate stories for browse, add-to-cart, checkout, payment, confirmation.
+2. **By business rule variation.** "As a master, I can set pricing" → separate stories for fixed price, auction, bulk discount.
+3. **By data variation.** "As a buyer, I can search" → separate stories for search by keyword, by category, by price range, by material.
+4. **By interface.** "As a user, I can pay" → separate stories for card payment, SBP, e-wallet.
+5. **By user role.** "As a user, I can manage profile" → separate stories for buyer profile vs. master profile.
+6. **By CRUD operation.** "As an admin, I can manage masters" → create, read, update, delete/suspend.
+7. **By happy path vs. exceptions.** "As a buyer, I can place an order" → happy path, out-of-stock, payment failure, address validation error.
+8. **By effort (spike + implementation).** "As a developer, I can integrate payment gateway" → research/spike story + implementation story.
+9. **By platform/channel.** "As a user, I can receive notifications" → email, push, in-app.
+
+### For Functional Requirements
+
+Split by:
+- **Sub-function.** A compound FR ("The system shall manage orders") → separate FRs for order creation, status tracking, cancellation, refund.
+- **Actor.** An FR that serves multiple roles → one FR per role.
+- **Trigger condition.** An FR with multiple triggers → one FR per trigger.
+
+### For Use Cases
+
+Split by:
+- **Goal level.** A summary-level UC → multiple user-goal-level UCs.
+- **Main flow vs. extensions.** A UC with 5+ extensions → promote major extensions to separate UCs.
+
+## Split workflow
+
+### Step 1 — Analyze the element
+
+Read the element and determine:
+- Why it is too large (too many acceptance criteria, too many business rules, too many actors, compound action).
+- Which split strategy fits best.
+- How many pieces it should become (typically 2–4; never more than 6).
+
+### Step 2 — Propose the split
+
+Present the proposed split for user review:
+
+```
+Splitting {element_ID}: "{element title}"
+
+Strategy: {strategy name} (e.g., "by workflow step")
+Reason: {why this element is too large}
+
+| New ID | Title | Priority | Key difference |
+|--------|-------|----------|----------------|
+| US-014a | ... | Must | ... |
+| US-014b | ... | Must | ... |
+| US-014c | ... | Should | ... |
+
+The original {element_ID} will be replaced by these {N} elements.
+
+Cross-references that currently point to {element_ID}:
+- AC-021, AC-022 → will be reassigned to the appropriate new element
+- UC-005 step 3 → will reference US-014a
+
+Apply? (yes / adjust — describe what to change)
+```
+
+### Step 3 — Assign new IDs
+
+Follow the project's ID convention:
+
+- **If the project uses sequential IDs** (FR-001, FR-002, …), assign the next available IDs.
+- **Suffix convention.** If the user prefers, use suffix IDs (US-014a, US-014b, US-014c) to preserve traceability to the original element.
+- **Ask if ambiguous.** If the convention is unclear, ask the user.
+
+### Step 4 — Apply and update references
+
+1. Replace the original element with the new elements in the artifact.
+2. Update all internal cross-references within the artifact (e.g., MoSCoW summary table, forward traceability matrix).
+3. Check for references in other artifacts. List affected files and offer to update:
+
+```
+The following artifacts reference {element_ID}:
+- `05_ac_*.md` — AC-021, AC-022 linked to the original story
+- `04_usecases_*.md` — UC-005 step 3
+
+Update them? (yes / no / pick files)
+```
+
+### Step 5 — Validate result
+
+After applying, run a quick INVEST check on each new User Story (if applicable) and report:
+
+```
+INVEST check:
+- US-014a: ✓ all criteria pass
+- US-014b: ✓ all criteria pass
+- US-014c: ⚠ Testable — no AC linked yet (will be created in /ac step)
+```
+
+## Closing message
+
+After saving, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path(s).
+- Original element replaced by {N} new elements.
+- Cross-reference updates applied or deferred.
+
+Available commands: `/split [element]` (split another element) · `/validate` · `/revise [section]` · `/done`
+
+No pipeline advancement — return to the current artifact's workflow.
+
+## Style
+
+Formal, neutral. Generate output in the language of the artifact.

package/skills/validate/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: validate
+description: >
+  Internal completeness and consistency check for a single BA Toolkit artifact. Use on /validate command, or when the user asks to "validate this artifact", "check completeness", "is this artifact complete", "consistency check", "check if ready", "is it done", "quality gate check". Utility skill available at any pipeline stage after the first artifact exists. Unlike /analyze (cross-artifact), /validate focuses on one artifact at a time.
+---
+
+# /validate — Artifact Completeness & Consistency Check
+
+Utility skill. Performs a single-artifact validation pass: checks that the target artifact is internally complete, consistent, and ready to `/done`. Does not generate a new file — reports findings in chat and optionally fixes issues in place.
+
+## Syntax
+
+```
+/validate [optional: artifact reference]
+```
+
+Examples:
+- `/validate` — validate the most recent artifact
+- `/validate brief` — validate `01_brief_*.md`
+- `/validate srs` — validate `02_srs_*.md`
+- `/validate 03_stories_sock-market.md` — validate a specific file
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it. Use its Definition of Ready (section 4) as the primary checklist, its ID conventions (section 2) to validate ID formats, and its quality gate (section 6) to determine which severity blocks `/done`.
+1. Identify the target artifact:
+   - If the user specifies an artifact name or filename, use it.
+   - Otherwise, use the most recently generated artifact in the output directory.
+2. Read the target artifact fully.
+3. Read prior artifacts for cross-reference spot-checks (roles, terms, IDs referenced from the target).
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Slug source
+
+Read `references/slug-source.md` from the `ba-toolkit` directory. Follow its rules to resolve the project slug from `AGENTS.md`.
+
+## Validation checklist
+
+Run the following checks against the target artifact. Each check maps to a severity level.
+
+### Structural checks (CRITICAL if missing)
+
+1. **Metadata present.** The artifact has a title, version, status, domain, date, and slug in the header.
+2. **All mandatory sections exist.** Compare the artifact's `## N.` headings against the expected template structure for that artifact type.
+3. **ID format consistent.** All element IDs (FR-NNN, US-NNN, UC-NNN, AC-NNN, NFR-NNN, etc.) follow the project's ID convention (from `00_principles_*.md` §2, or the default `XX-NNN` pattern).
+
+### Completeness checks (HIGH if missing)
+
+4. **No placeholder text.** Scan for `(TBD)`, `(TODO)`, `(TBC)`, `(placeholder)`, `(имя основателя)`, `(name)`, empty table cells in required columns.
+5. **Definition of Ready.** If `00_principles_*.md` exists, check each element against the DoR checklist for its type (FR, US, UC, AC, NFR). Report which elements fail which DoR criteria.
+6. **MoSCoW count consistency.** If the artifact has a MoSCoW summary table and individual priorities, verify that the counts match. Report discrepancies with exact numbers.
+7. **Cross-reference validity.** Every ID referenced in the artifact (e.g., `FR-003` in a US's "Linked FR" field) must exist within the artifact or in a prior artifact. Flag dangling references.
+
+### Consistency checks (MEDIUM)
+
+8. **Role consistency.** Roles/actors used in the artifact must match the roles defined in the SRS roles section or the brief stakeholders section. Flag unknown roles.
+9. **Glossary term usage.** Terms that appear in the glossary (if `00_glossary_*.md` exists) should be used consistently. Flag variant spellings or undefined terms.
+10. **Priority distribution.** If every element is marked "Must", warn that the prioritization may not be meaningful.
+
+### Style checks (LOW)
+
+11. **Empty sections.** Sections that exist but contain no content.
+12. **Orphan elements.** Elements with no cross-references to or from other elements within the artifact.
+
+## Output format
+
+Present findings grouped by severity, with a summary count at the top:
+
+```
+Validation results for `{artifact_file}`:
+
+| Severity | Count |
+|----------|-------|
+| CRITICAL | N     |
+| HIGH     | N     |
+| MEDIUM   | N     |
+| LOW      | N     |
+
+### CRITICAL
+
+1. **V-001** [Structural] MoSCoW summary says 25 Must, but 34 FRs are marked Must.
+   → Fix: update the summary table in §6.
+
+### HIGH
+
+2. **V-002** [Completeness] FR-012 has no Source field.
+   → Fix: add `Source: G-2` (brief goal 2).
+
+...
+```
+
+If all checks pass, report:
+
+```
+✓ Validation passed for `{artifact_file}` — no issues found. Ready to `/done`.
+```
+
+## Auto-fix offer
+
+After presenting findings, offer to fix issues automatically:
+
+- If CRITICAL or HIGH findings exist: "Found {N} issues. Want me to fix them? (yes / no / pick specific V-NNN IDs)"
+- If only MEDIUM/LOW: "Found {N} minor issues. Want me to fix them, or proceed to `/done`?"
+
+When fixing, update the artifact in place. After each fix, confirm what changed in one line.
+
+## Closing message
+
+After validation (and optional fixes), present the following summary (see `references/closing-message.md` for format):
+
+- Artifact file path.
+- Summary of findings by severity.
+- Whether the artifact passes the `/done` gate (no CRITICAL findings remaining).
+
+Available commands: `/validate` (re-run) · `/clarify [focus]` · `/revise [section]` · `/done`
+
+No pipeline advancement — return to the current artifact's workflow.
+
+## Style
+
+Formal, neutral. Findings must reference exact element IDs and section numbers. Generate output in the language of the artifact.