@kudusov.takhir/ba-toolkit 1.2.4 β 1.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +19 -3
- package/README.md +118 -672
- package/package.json +1 -2
- package/README.ru.md +0 -846
package/README.md
CHANGED
|
@@ -2,10 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# π BA Toolkit
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
From project brief to development handoff β 21 skills, fully structured pipeline
|
|
7
|
-
|
|
8
|
-
πΊπΈ **English** Β· [π·πΊ Π ΡΡΡΠΊΠΈΠΉ](README.ru.md)
|
|
5
|
+
Structured BA pipeline for AI coding agents β brief to handoff, 21 skills, 9 domains.
|
|
9
6
|
|
|
10
7
|
<img src="https://img.shields.io/badge/skills-21-blue" alt="Skills">
|
|
11
8
|
<img src="https://img.shields.io/badge/domains-9-green" alt="Domains">
|
|
@@ -23,204 +20,17 @@ From project brief to development handoff β 21 skills, fully structured pipeli
|
|
|
23
20
|
|
|
24
21
|
---
|
|
25
22
|
|
|
26
|
-
##
|
|
27
|
-
|
|
28
|
-
- [What is this?](#-what-is-this)
|
|
29
|
-
- [Who is this for?](#who-is-this-for)
|
|
30
|
-
- [Why not just prompt directly?](#why-not-just-prompt-chatgpt--claude-directly)
|
|
31
|
-
- [Platform Compatibility](#-platform-compatibility)
|
|
32
|
-
- [Pipeline](#-pipeline)
|
|
33
|
-
- [Domain Support](#-domain-support)
|
|
34
|
-
- [How Each Skill Works](#-how-each-skill-works)
|
|
35
|
-
- [Installation](#-installation)
|
|
36
|
-
- [Option A: Claude Code](#option-a-claude-code-cli--recommended)
|
|
37
|
-
- [Option B: OpenAI Codex CLI](#option-b-openai-codex-cli)
|
|
38
|
-
- [Option C: Google Gemini CLI](#option-c-google-gemini-cli)
|
|
39
|
-
- [Option D: Cursor, Windsurf, Aider](#option-d-cursor-windsurf-aider)
|
|
40
|
-
- [Starting a new project](#starting-a-new-project)
|
|
41
|
-
- [Updating BA Toolkit](#updating-ba-toolkit)
|
|
42
|
-
- [Repository Structure](#-repository-structure)
|
|
43
|
-
- [Cross-Reference System](#-cross-reference-system)
|
|
44
|
-
- [Minimum Viable Pipeline](#-minimum-viable-pipeline)
|
|
45
|
-
- [Quick Start](#-quick-start)
|
|
46
|
-
- [What the Output Looks Like](#οΈ-what-the-output-looks-like)
|
|
47
|
-
- [Usage Guide](#-usage-guide)
|
|
48
|
-
- [1. Starting a project](#1-starting-a-project)
|
|
49
|
-
- [2. Moving through the pipeline](#2-moving-through-the-pipeline)
|
|
50
|
-
- [3. Using /clarify](#3-using-clarify)
|
|
51
|
-
- [4. Using /analyze](#4-using-analyze)
|
|
52
|
-
- [5. Using /trace](#5-using-trace)
|
|
53
|
-
- [6. Splitting large elements](#6-splitting-large-elements)
|
|
54
|
-
- [7. Working with multiple projects](#7-working-with-multiple-projects)
|
|
55
|
-
- [8. Troubleshooting](#8-troubleshooting)
|
|
56
|
-
- [9. AGENTS.md β persistent project context](#9-agentsmd--persistent-project-context)
|
|
57
|
-
- [FAQ](#-faq)
|
|
58
|
-
- [Contributing](#-contributing)
|
|
59
|
-
- [Adding a New Domain](#adding-a-new-domain)
|
|
60
|
-
- [Changelog](CHANGELOG.md)
|
|
61
|
-
- [License](#-license)
|
|
62
|
-
|
|
63
|
-
---
|
|
64
|
-
|
|
65
|
-
## π― What is this?
|
|
66
|
-
|
|
67
|
-
BA Toolkit is a set of **21 interconnected skills** that turn your AI coding agent into a business analyst. You walk through a structured pipeline β from a high-level project brief to a development handoff package β and get a complete requirements artifact set ready for engineering.
|
|
68
|
-
|
|
69
|
-
Each skill **reads the output of previous steps**, maintains cross-references between artifacts (FR β US β UC β AC β NFR β Entities β ADR β API β Screens β Scenarios), and adapts to your project's domain.
|
|
70
|
-
|
|
71
|
-
**Artifacts are generated in the language you write in.** Ask in English β get English docs. Ask in Russian, Spanish, or any other language β the output follows.
|
|
72
|
-
|
|
73
|
-
### Who is this for?
|
|
74
|
-
|
|
75
|
-
- **Developers** building a product without a dedicated BA β get structured requirements before writing code.
|
|
76
|
-
- **Product managers** who need formal documentation (SRS, AC, NFR) but want to produce it faster.
|
|
77
|
-
- **Business analysts** using AI to accelerate artifact creation and reduce manual cross-referencing.
|
|
78
|
-
- **Startup founders** turning an idea into a spec ready for a development team or investor presentation.
|
|
79
|
-
|
|
80
|
-
### Why not just prompt ChatGPT / Claude directly?
|
|
81
|
-
|
|
82
|
-
| | Ad-hoc prompting | BA Toolkit |
|
|
83
|
-
|--|-----------------|-----------|
|
|
84
|
-
| Structure | One-shot; no memory across messages | 11 interconnected artifacts, each reads all previous ones |
|
|
85
|
-
| Coverage | Easy to miss NFR, edge cases, data model | Structured interview + checklists prevent gaps |
|
|
86
|
-
| Traceability | None | FR β US β AC β API β WF chain with `/trace` |
|
|
87
|
-
| Quality checks | Ad-hoc | `/clarify` and `/analyze` with CRITICAL/HIGH severity ratings |
|
|
88
|
-
| Domain knowledge | Generic | Built-in references for 9 domains (iGaming, Fintech, SaaS, E-commerce, Healthcare, Logistics, On-demand, Social/Media, Real Estate) |
|
|
89
|
-
| Handoff | Chat text | Up to 11 Markdown files ready for Jira, Spec Kit, or dev team |
|
|
90
|
-
|
|
91
|
-
---
|
|
92
|
-
|
|
93
|
-
## π€ Platform Compatibility
|
|
94
|
-
|
|
95
|
-
BA Toolkit uses the open **Agent Skills specification** (SKILL.md format) published by Anthropic in December 2025 and adopted across multiple platforms.
|
|
96
|
-
|
|
97
|
-
| Platform | Support | Installation |
|
|
98
|
-
|----------|:-------:|-------------|
|
|
99
|
-
| **Claude Code** | β
Native | `cp -r skills/ .claude/skills/ba-toolkit/` |
|
|
100
|
-
| **OpenAI Codex CLI** | β
Native | `cp -r skills/ ~/.codex/skills/ba-toolkit/` |
|
|
101
|
-
| **Gemini CLI** | β
Native | Copy the entire `skills/` tree to `~/.gemini/skills/ba-toolkit/` (user) or `.gemini/skills/ba-toolkit/` (workspace) |
|
|
102
|
-
| **Cursor** | π Convert | SKILL.md β `.mdc` rules in `.cursor/rules/` |
|
|
103
|
-
| **Windsurf** | π Convert | SKILL.md β rules in `.windsurf/rules/` |
|
|
104
|
-
| **Aider** | π Convert | SKILL.md β conventions file |
|
|
105
|
-
|
|
106
|
-
> π‘ Platforms marked **Native** read SKILL.md as-is. Platforms marked **Convert** require a one-time format conversion β the content is the same, only the file format differs. Tools like [convert.sh](https://github.com/alirezarezvani/claude-skills/blob/main/scripts/convert.sh) can automate this.
|
|
107
|
-
|
|
108
|
-
### Environment detection
|
|
23
|
+
## What is this
|
|
109
24
|
|
|
110
|
-
|
|
25
|
+
BA Toolkit is a set of 21 interconnected skills that run a full business-analysis pipeline inside your AI coding agent. You go from a rough project brief to a development handoff package, and each skill reads the output of the previous ones β maintaining cross-references between artifacts along the chain `FR β US β UC β AC β NFR β Entity β ADR β API β WF β Scenario`.
|
|
111
26
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
---
|
|
115
|
-
|
|
116
|
-
## π Pipeline
|
|
117
|
-
|
|
118
|
-
```
|
|
119
|
-
π /principles (optional)
|
|
120
|
-
β
|
|
121
|
-
βΌ
|
|
122
|
-
π /brief β π /srs β π /stories β π /usecases β β
/ac β β‘ /nfr β ποΈ /datadict β π¬ /research β π /apicontract β πΌοΈ /wireframes β π§ͺ /scenarios β π¦ /handoff
|
|
123
|
-
β
|
|
124
|
-
ββββ π /trace (available after /stories)
|
|
125
|
-
|
|
126
|
-
π /clarify [focus] β available at any step, on any artifact
|
|
127
|
-
π /analyze β available at any step after /srs
|
|
128
|
-
```
|
|
27
|
+
Unlike one-shot prompting, every artifact is written to disk as Markdown, every ID links back to its source, and `/trace` verifies coverage across the whole pipeline. `/clarify` and `/analyze` catch ambiguities and quality gaps with CRITICAL/HIGH severity ratings. Domain references for 9 industries (iGaming, Fintech, SaaS, E-commerce, Healthcare, Logistics, On-demand, Social/Media, Real Estate) plug in automatically at `/brief`.
|
|
129
28
|
|
|
130
|
-
|
|
131
|
-
|:---:|---------|-------------------|-------------|
|
|
132
|
-
| 0 | `/principles` | π Project Principles β language, ID conventions, DoR, traceability rules, NFR baseline | `00_principles_{slug}.md` |
|
|
133
|
-
| 1 | `/brief` | π Project Brief β goals, audience, stakeholders, risks | `01_brief_{slug}.md` |
|
|
134
|
-
| 2 | `/srs` | π Requirements Specification (IEEE 830) | `02_srs_{slug}.md` |
|
|
135
|
-
| 3 | `/stories` | π User Stories grouped by Epics | `03_stories_{slug}.md` |
|
|
136
|
-
| 4 | `/usecases` | π Use Cases with main/alt/exception flows | `04_usecases_{slug}.md` |
|
|
137
|
-
| 5 | `/ac` | β
Acceptance Criteria (Given/When/Then) | `05_ac_{slug}.md` |
|
|
138
|
-
| 6 | `/nfr` | β‘ Non-functional Requirements with metrics | `06_nfr_{slug}.md` |
|
|
139
|
-
| 7 | `/datadict` | ποΈ Data Dictionary β entities, types, constraints | `07_datadict_{slug}.md` |
|
|
140
|
-
| 7a | `/research` | π¬ Technology Research β ADRs, integration map, data storage decisions | `07a_research_{slug}.md` |
|
|
141
|
-
| 8 | `/apicontract` | π API Contract β endpoints, schemas, errors | `08_apicontract_{slug}.md` |
|
|
142
|
-
| 9 | `/wireframes` | πΌοΈ Textual Wireframe Descriptions | `09_wireframes_{slug}.md` |
|
|
143
|
-
| 10 | `/scenarios` | π§ͺ End-to-end Validation Scenarios β user journeys linking US, AC, WF, API | `10_scenarios_{slug}.md` |
|
|
144
|
-
| 11 | `/handoff` | π¦ Development Handoff Package β artifact inventory, MVP scope, open items | `11_handoff_{slug}.md` |
|
|
145
|
-
| β | `/trace` | π Traceability Matrix + coverage gaps | `00_trace_{slug}.md` |
|
|
146
|
-
| β | `/clarify [focus]` | π Targeted ambiguity resolution for any artifact | _(updates existing artifact)_ |
|
|
147
|
-
| β | `/analyze` | π Cross-artifact quality report with severity table | `00_analyze_{slug}.md` |
|
|
148
|
-
| β | `/estimate` | π Effort estimation β Fibonacci SP, T-shirt sizes, or person-days | `00_estimate_{slug}.md` |
|
|
149
|
-
| β | `/glossary` | π Unified project glossary with terminology drift detection | `00_glossary_{slug}.md` |
|
|
150
|
-
| β | `/export [format]` | π€ Export User Stories to Jira / GitHub Issues / Linear / CSV | `export_{slug}_{format}.json` / `.csv` |
|
|
151
|
-
| β | `/risk` | β οΈ Risk register β probability Γ impact matrix, mitigation per risk | `00_risks_{slug}.md` |
|
|
152
|
-
| β | `/sprint` | ποΈ Sprint plan β stories grouped by velocity and capacity with sprint goals | `00_sprint_{slug}.md` |
|
|
153
|
-
|
|
154
|
-
> π‘ The project **slug** (e.g., `dragon-fortune`) is set at `/brief` and reused across all files automatically.
|
|
155
|
-
|
|
156
|
-
---
|
|
157
|
-
|
|
158
|
-
## π Domain Support
|
|
159
|
-
|
|
160
|
-
The pipeline is **domain-agnostic** by default. At the `/brief` stage, you pick a domain β and every subsequent skill loads domain-specific interview questions, mandatory entities, NFR categories, and glossary terms.
|
|
161
|
-
|
|
162
|
-
| Domain | Industries covered |
|
|
163
|
-
|--------|-------------------|
|
|
164
|
-
| π° **iGaming** | Online slots, sports betting, casino lobbies, Telegram Mini Apps, promo mechanics |
|
|
165
|
-
| π¦ **Fintech** | Neobanks, payment systems, crypto exchanges, investment platforms, P2P lending |
|
|
166
|
-
| βοΈ **SaaS** | B2B platforms, CRM, analytics, marketplaces, EdTech, HRTech |
|
|
167
|
-
| π **E-commerce** | B2C stores, B2B catalogs, multi-vendor marketplaces, D2C brands, digital goods |
|
|
168
|
-
| π₯ **Healthcare** | Telemedicine, patient portals, EHR/EMR, clinic management, mental health apps |
|
|
169
|
-
| π **Logistics** | Last-mile delivery, courier management, freight tracking, WMS, fleet management |
|
|
170
|
-
| π§ **On-demand** | Ride-hailing, home services, task marketplaces, beauty, tutoring, pet care |
|
|
171
|
-
| π± **Social / Media** | Social networks, creator platforms, community forums, newsletters, short-video |
|
|
172
|
-
| π **Real Estate** | Property portals, agency CRM, rental management, property management, mortgage tools |
|
|
173
|
-
| βοΈ **Custom** | Any other domain β works with general interview questions |
|
|
174
|
-
|
|
175
|
-
> β **Adding a new domain** = creating one Markdown file in `skills/references/domains/`. See [Adding a New Domain](#adding-a-new-domain) below.
|
|
176
|
-
|
|
177
|
-
---
|
|
178
|
-
|
|
179
|
-
## π How Each Skill Works
|
|
180
|
-
|
|
181
|
-
Most pipeline skills follow this cycle:
|
|
182
|
-
|
|
183
|
-
```
|
|
184
|
-
βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ
|
|
185
|
-
β 1. Command ββββββΆβ 2. Context ββββββΆβ3. Interview ββββββΆβ 4. Generate β
|
|
186
|
-
β /brief β β Load prior β β 3-7 Q's perβ β Markdown β
|
|
187
|
-
β /srs ... β β artifacts β β round, 2-4 β β artifact + β
|
|
188
|
-
β β β + domain + β β rounds β β summary β
|
|
189
|
-
β β β principles β β β β β
|
|
190
|
-
βββββββββββββββ βββββββββββββββ βββββββββββββββ ββββββββ¬βββββββ
|
|
191
|
-
β
|
|
192
|
-
βΌ
|
|
193
|
-
βββββββββββββββ
|
|
194
|
-
β 5. Refine β
|
|
195
|
-
β β
|
|
196
|
-
β /clarify β
|
|
197
|
-
β /revise β
|
|
198
|
-
β /expand β
|
|
199
|
-
β /split β
|
|
200
|
-
β /validate β
|
|
201
|
-
β /done βββββββΌβββΆ Next step
|
|
202
|
-
βββββββββββββββ
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
> `/handoff`, `/trace`, and `/analyze` skip step 3 β they extract all information from existing artifacts automatically, with no interview.
|
|
206
|
-
|
|
207
|
-
### Subcommands
|
|
208
|
-
|
|
209
|
-
| Command | What it does |
|
|
210
|
-
|---------|-------------|
|
|
211
|
-
| `/clarify [focus]` | Targeted ambiguity pass β surfaces vague terms, missing metrics, conflicting rules |
|
|
212
|
-
| `/revise [section]` | Rewrite a specific section with your feedback |
|
|
213
|
-
| `/expand [section]` | Add more detail to a section |
|
|
214
|
-
| `/split [element]` | Break a large element into smaller ones (e.g., a big user story) |
|
|
215
|
-
| `/validate` | Check completeness, consistency, and alignment with prior artifacts |
|
|
216
|
-
| `/analyze` | Cross-artifact quality report: duplicates, coverage gaps, terminology drift, invalid references |
|
|
217
|
-
| `/done` | Finalize the current artifact and move to the next pipeline step |
|
|
29
|
+
Artifacts are generated in whatever language you write in β ask in English, get English docs; ask in any other language, the output follows.
|
|
218
30
|
|
|
219
31
|
---
|
|
220
32
|
|
|
221
|
-
##
|
|
222
|
-
|
|
223
|
-
### π Easiest: via npm (no clone required)
|
|
33
|
+
## Install
|
|
224
34
|
|
|
225
35
|
```bash
|
|
226
36
|
# One-shot project setup β zero install, just run:
|
|
@@ -232,71 +42,66 @@ npm install -g @kudusov.takhir/ba-toolkit
|
|
|
232
42
|
ba-toolkit install --for claude-code --global
|
|
233
43
|
```
|
|
234
44
|
|
|
235
|
-
Supported agents: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. Cursor and Windsurf installs
|
|
45
|
+
Supported agents: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. Cursor and Windsurf installs auto-convert `SKILL.md` into the `.mdc` rule format. Use `--dry-run` to preview without writing.
|
|
236
46
|
|
|
237
|
-
|
|
47
|
+
`ba-toolkit --help` shows the full CLI reference. Zero runtime dependencies β only Node.js β₯ 18.
|
|
238
48
|
|
|
239
|
-
|
|
49
|
+
<details>
|
|
50
|
+
<summary><strong>Manual install (clone + copy)</strong></summary>
|
|
51
|
+
|
|
52
|
+
Use these if you can't use npm or want to track a specific git commit.
|
|
240
53
|
|
|
241
|
-
###
|
|
54
|
+
### Claude Code CLI
|
|
242
55
|
|
|
243
56
|
```bash
|
|
244
|
-
# Clone and copy the skills directory (includes domain references)
|
|
245
57
|
git clone https://github.com/TakhirKudusov/ba-toolkit.git
|
|
246
58
|
cp -r ba-toolkit/skills/ /path/to/project/.claude/skills/ba-toolkit/
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
Or install globally:
|
|
250
59
|
|
|
251
|
-
|
|
60
|
+
# Or install globally:
|
|
252
61
|
cp -r ba-toolkit/skills/ ~/.claude/skills/ba-toolkit/
|
|
253
62
|
```
|
|
254
63
|
|
|
255
64
|
Keep the full tree: skill folders (`brief/`, `srs/`, β¦) must stay together with `references/` in the same parent directory.
|
|
256
65
|
|
|
257
|
-
###
|
|
66
|
+
### OpenAI Codex CLI
|
|
258
67
|
|
|
259
|
-
Skills load from `$CODEX_HOME/skills` (default `~/.codex/skills`)
|
|
68
|
+
Skills load from `$CODEX_HOME/skills` (default `~/.codex/skills`):
|
|
260
69
|
|
|
261
70
|
```bash
|
|
262
71
|
cp -r ba-toolkit/skills/ ~/.codex/skills/ba-toolkit/
|
|
263
72
|
```
|
|
264
73
|
|
|
265
|
-
If you use a custom Codex home, set `CODEX_HOME` and copy under `$CODEX_HOME/skills/ba-toolkit
|
|
74
|
+
If you use a custom Codex home, set `CODEX_HOME` and copy under `$CODEX_HOME/skills/ba-toolkit/`.
|
|
266
75
|
|
|
267
|
-
###
|
|
268
|
-
|
|
269
|
-
Same layout as Codex: one directory that contains all skill subfolders **and** `references/`:
|
|
76
|
+
### Google Gemini CLI
|
|
270
77
|
|
|
271
78
|
```bash
|
|
272
79
|
# User-wide (all projects)
|
|
273
80
|
cp -r ba-toolkit/skills/ ~/.gemini/skills/ba-toolkit/
|
|
274
81
|
|
|
275
|
-
# Or project-only
|
|
82
|
+
# Or project-only
|
|
276
83
|
cp -r ba-toolkit/skills/ /path/to/project/.gemini/skills/ba-toolkit/
|
|
277
84
|
```
|
|
278
85
|
|
|
279
86
|
Reload the CLI after copying.
|
|
280
87
|
|
|
281
|
-
###
|
|
88
|
+
### Cursor, Windsurf, Aider
|
|
282
89
|
|
|
283
|
-
These
|
|
90
|
+
These use their own rules format instead of `SKILL.md`. Convert first, then copy:
|
|
284
91
|
|
|
285
92
|
```bash
|
|
286
|
-
# Option 1:
|
|
93
|
+
# Option 1: community converter
|
|
287
94
|
# https://github.com/alirezarezvani/claude-skills/blob/main/scripts/convert.sh
|
|
288
95
|
./convert.sh --tool cursor --target /path/to/project
|
|
289
96
|
./convert.sh --tool windsurf --target /path/to/project
|
|
290
97
|
|
|
291
|
-
# Option 2:
|
|
98
|
+
# Option 2: ask your AI agent
|
|
292
99
|
# "Convert all SKILL.md files in skills/ to Cursor .mdc rule format"
|
|
293
100
|
```
|
|
294
101
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
### Starting a new project
|
|
102
|
+
Cursor rules live in [`.cursor/rules/`](https://cursor.com/docs/rules) as `.mdc` files with YAML frontmatter (`description`, optional `globs`, `alwaysApply`). A plain rename of `SKILL.md` to `.mdc` is not enough β the metadata block is required. [Cursor CLI](https://cursor.com/docs/cli/using) reads the same `.cursor/rules` setup and may also pick up `AGENTS.md` / `CLAUDE.md` at repo root.
|
|
298
103
|
|
|
299
|
-
|
|
104
|
+
### Starting a new project (shell scripts)
|
|
300
105
|
|
|
301
106
|
```bash
|
|
302
107
|
# macOS / Linux
|
|
@@ -306,219 +111,25 @@ bash init.sh
|
|
|
306
111
|
.\init.ps1
|
|
307
112
|
```
|
|
308
113
|
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
---
|
|
312
|
-
|
|
313
|
-
### Updating BA Toolkit
|
|
114
|
+
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.
|
|
314
115
|
|
|
315
|
-
|
|
116
|
+
### Updating a manual install
|
|
316
117
|
|
|
317
118
|
```bash
|
|
318
119
|
cd ba-toolkit
|
|
319
120
|
git pull
|
|
320
|
-
|
|
321
|
-
# Claude Code β project-level
|
|
322
|
-
cp -r skills/ /path/to/project/.claude/skills/ba-toolkit/
|
|
323
|
-
|
|
324
|
-
# Claude Code β global
|
|
325
|
-
cp -r skills/ ~/.claude/skills/ba-toolkit/
|
|
326
|
-
|
|
327
|
-
# Codex CLI
|
|
328
|
-
cp -r skills/ ~/.codex/skills/ba-toolkit/
|
|
329
|
-
|
|
330
|
-
# Gemini CLI (user-wide)
|
|
331
|
-
cp -r skills/ ~/.gemini/skills/ba-toolkit/
|
|
121
|
+
cp -r skills/ /path/to/install/location/
|
|
332
122
|
```
|
|
333
123
|
|
|
124
|
+
Your generated artifacts (`01_brief_*.md`, `02_srs_*.md`, β¦) are untouched by updates.
|
|
334
125
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
---
|
|
338
|
-
|
|
339
|
-
## π Repository Structure
|
|
340
|
-
|
|
341
|
-
```
|
|
342
|
-
ba-toolkit/
|
|
343
|
-
β
|
|
344
|
-
βββ skills/ # π§ Source SKILL.md files (install this directory)
|
|
345
|
-
β βββ ac/SKILL.md # Step 5: Acceptance Criteria
|
|
346
|
-
β βββ apicontract/SKILL.md # Step 8: API Contract
|
|
347
|
-
β βββ brief/SKILL.md # Step 1: Project Brief
|
|
348
|
-
β βββ datadict/SKILL.md # Step 7: Data Dictionary
|
|
349
|
-
β βββ nfr/SKILL.md # Step 6: Non-functional Requirements
|
|
350
|
-
β βββ srs/SKILL.md # Step 2: Requirements (SRS)
|
|
351
|
-
β βββ stories/SKILL.md # Step 3: User Stories
|
|
352
|
-
β βββ principles/SKILL.md # Step 0 (optional): Project Principles
|
|
353
|
-
β βββ trace/SKILL.md # Cross-cutting: Traceability Matrix
|
|
354
|
-
β βββ clarify/SKILL.md # Cross-cutting: Targeted Ambiguity Resolution
|
|
355
|
-
β βββ analyze/SKILL.md # Cross-cutting: Cross-Artifact Quality Report
|
|
356
|
-
β βββ usecases/SKILL.md # Step 4: Use Cases
|
|
357
|
-
β βββ wireframes/SKILL.md # Step 9: Wireframe Descriptions
|
|
358
|
-
β βββ research/SKILL.md # Step 7a (optional): Technology Research & ADRs
|
|
359
|
-
β βββ scenarios/SKILL.md # Step 10 (optional): End-to-end Validation Scenarios
|
|
360
|
-
β βββ handoff/SKILL.md # Step 11 (optional): Development Handoff Package
|
|
361
|
-
β βββ estimate/SKILL.md # Utility: Effort Estimation (SP / T-shirt / person-days)
|
|
362
|
-
β βββ glossary/SKILL.md # Utility: Unified Project Glossary
|
|
363
|
-
β βββ export/SKILL.md # Utility: Export to Jira / GitHub Issues / Linear / CSV
|
|
364
|
-
β βββ risk/SKILL.md # Utility: Risk Register (probability Γ impact matrix)
|
|
365
|
-
β βββ sprint/SKILL.md # Utility: Sprint Plan (velocity-based story grouping)
|
|
366
|
-
β βββ references/
|
|
367
|
-
β βββ environment.md # π₯οΈ Platform-specific output paths
|
|
368
|
-
β βββ closing-message.md # π Closing message template (used by all skills)
|
|
369
|
-
β βββ prerequisites.md # β
Per-step prerequisite checklists
|
|
370
|
-
β βββ templates/ # π Base artifact templates with [TOKEN] placeholders
|
|
371
|
-
β β βββ README.md
|
|
372
|
-
β β βββ principles-template.md
|
|
373
|
-
β β βββ brief-template.md
|
|
374
|
-
β β βββ srs-template.md
|
|
375
|
-
β β βββ stories-template.md
|
|
376
|
-
β β βββ usecases-template.md
|
|
377
|
-
β β βββ ac-template.md
|
|
378
|
-
β β βββ nfr-template.md
|
|
379
|
-
β β βββ datadict-template.md
|
|
380
|
-
β β βββ research-template.md
|
|
381
|
-
β β βββ apicontract-template.md
|
|
382
|
-
β β βββ wireframes-template.md
|
|
383
|
-
β β βββ scenarios-template.md
|
|
384
|
-
β β βββ trace-template.md
|
|
385
|
-
β β βββ analyze-template.md
|
|
386
|
-
β β βββ handoff-template.md
|
|
387
|
-
β βββ domains/
|
|
388
|
-
β βββ igaming.md # π° iGaming domain knowledge
|
|
389
|
-
β βββ fintech.md # π¦ Fintech domain knowledge
|
|
390
|
-
β βββ saas.md # βοΈ SaaS domain knowledge
|
|
391
|
-
β βββ ecommerce.md # π E-commerce domain knowledge
|
|
392
|
-
β βββ healthcare.md # π₯ Healthcare / MedTech domain knowledge
|
|
393
|
-
β βββ logistics.md # π Logistics / Delivery domain knowledge
|
|
394
|
-
β βββ on-demand.md # π§ On-demand / Services domain knowledge
|
|
395
|
-
β βββ social-media.md # π± Social / Media domain knowledge
|
|
396
|
-
β βββ real-estate.md # π Real Estate domain knowledge
|
|
397
|
-
β
|
|
398
|
-
βββ bin/
|
|
399
|
-
β βββ ba-toolkit.js # π§° npm CLI entry point (zero runtime deps)
|
|
400
|
-
βββ package.json # π¦ npm package manifest (for `npx @kudusov.takhir/ba-toolkit`)
|
|
401
|
-
βββ init.ps1 # π Project initialiser (Windows PowerShell)
|
|
402
|
-
βββ init.sh # π Project initialiser (macOS / Linux bash)
|
|
403
|
-
βββ CHANGELOG.md # π Version history
|
|
404
|
-
βββ COMMANDS.md # π Command cheat sheet
|
|
405
|
-
βββ LICENSE # MIT license text
|
|
406
|
-
βββ README.md # English version
|
|
407
|
-
βββ README.ru.md # Russian version
|
|
408
|
-
βββ .gitignore
|
|
409
|
-
βββ .github/
|
|
410
|
-
βββ workflows/
|
|
411
|
-
β βββ validate.yml # β
CI: validate artifacts and skill files on PR
|
|
412
|
-
β βββ release.yml # π CD: create GitHub Release on version tag push
|
|
413
|
-
βββ scripts/
|
|
414
|
-
βββ validate_artifacts.py # Python validator used by CI
|
|
415
|
-
```
|
|
416
|
-
|
|
417
|
-
> π‘ **`skills/`** is the directory you install β copy it as one unit so that `references/` stays alongside all skill folders.
|
|
126
|
+
</details>
|
|
418
127
|
|
|
419
128
|
---
|
|
420
129
|
|
|
421
|
-
##
|
|
422
|
-
|
|
423
|
-
Every artifact links back to its predecessors. This chain ensures full traceability from business goals to screen specifications:
|
|
424
|
-
|
|
425
|
-
```
|
|
426
|
-
FR-001 (SRS)
|
|
427
|
-
βββ US-001 (Stories)
|
|
428
|
-
βββ UC-001 (Use Cases)
|
|
429
|
-
βββ AC-001-01 (Acceptance Criteria)
|
|
430
|
-
β
|
|
431
|
-
NFR-003 (Non-functional Requirements)
|
|
432
|
-
β
|
|
433
|
-
User, Bet (Data Dictionary)
|
|
434
|
-
β
|
|
435
|
-
ADR-002 (Research β tech decision driven by this entity)
|
|
436
|
-
β
|
|
437
|
-
POST /bets (API Contract)
|
|
438
|
-
β
|
|
439
|
-
WF-005 (Wireframes)
|
|
440
|
-
β
|
|
441
|
-
SC-003 (Validation Scenario β end-to-end journey)
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
The `/trace` command builds the **complete matrix** of these links and highlights uncovered FRs, stories without AC, orphan entities and endpoints, and coverage percentage per artifact type. The `/analyze` command adds severity-rated findings: duplicates, ambiguous terms, terminology drift, and invalid references.
|
|
445
|
-
|
|
446
|
-
---
|
|
447
|
-
|
|
448
|
-
## β‘ Minimum Viable Pipeline
|
|
449
|
-
|
|
450
|
-
Not every project needs all 21 skills. Two common paths:
|
|
451
|
-
|
|
452
|
-
**Lean** (fastest path to handoff β 9 steps):
|
|
453
|
-
```
|
|
454
|
-
/brief β /srs β /stories β /ac β /nfr β /datadict β /apicontract β /wireframes β /handoff
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
**Full** (complete traceability and quality gates β 15 steps):
|
|
458
|
-
```
|
|
459
|
-
/principles β /brief β /srs β /stories β /usecases β /ac β /nfr β /datadict
|
|
460
|
-
β /research β /apicontract β /wireframes β /scenarios
|
|
461
|
-
β /trace β /analyze β /handoff
|
|
462
|
-
```
|
|
463
|
-
|
|
464
|
-
Use `/clarify` at any step to resolve ambiguities before moving on.
|
|
465
|
-
|
|
466
|
-
**Time estimates** (approximate, depends on project complexity and interview depth):
|
|
467
|
-
|
|
468
|
-
| Step | Lean pipeline | Full pipeline |
|
|
469
|
-
|------|:---:|:---:|
|
|
470
|
-
| `/principles` | β | 5β10 min |
|
|
471
|
-
| `/brief` | 15β25 min | 20β35 min |
|
|
472
|
-
| `/srs` | 25β40 min | 30β50 min |
|
|
473
|
-
| `/stories` | 20β30 min | 25β40 min |
|
|
474
|
-
| `/usecases` | β | 20β35 min |
|
|
475
|
-
| `/ac` | 20β35 min | 25β40 min |
|
|
476
|
-
| `/nfr` | 15β20 min | 15β25 min |
|
|
477
|
-
| `/datadict` | 15β25 min | 20β30 min |
|
|
478
|
-
| `/research` | β | 15β25 min |
|
|
479
|
-
| `/apicontract` | 20β35 min | 25β40 min |
|
|
480
|
-
| `/wireframes` | 25β40 min | 30β50 min |
|
|
481
|
-
| `/scenarios` | β | 15β25 min |
|
|
482
|
-
| `/trace` + `/analyze` | β | 10β15 min |
|
|
483
|
-
| `/handoff` | 5β10 min | 5β10 min |
|
|
484
|
-
| **Total** | **~3β4 hours** | **~5β8 hours** |
|
|
485
|
-
|
|
486
|
-
---
|
|
130
|
+
## Example output
|
|
487
131
|
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
```
|
|
491
|
-
# Optional: define conventions before starting
|
|
492
|
-
You: /principles
|
|
493
|
-
Agent: What language should artifacts be in? What severity blocks /done?
|
|
494
|
-
You: Russian, block on CRITICAL only
|
|
495
|
-
Agent: [generates 00_principles_dragon-fortune.md β applied by all subsequent skills]
|
|
496
|
-
|
|
497
|
-
You: /brief
|
|
498
|
-
Agent: What domain is your project in? (iGaming, Fintech, SaaS, other?)
|
|
499
|
-
You: iGaming β it's an online slot as a Telegram Mini App
|
|
500
|
-
Agent: [asks 5-6 targeted questions about goals, audience, constraints...]
|
|
501
|
-
You: [answer]
|
|
502
|
-
Agent: [generates 01_brief_dragon-fortune.md]
|
|
503
|
-
Artifact saved: 01_brief_dragon-fortune.md
|
|
504
|
-
Covered: 4 business goals, 3 stakeholders, 6 risks identified.
|
|
505
|
-
Next step: /srs
|
|
506
|
-
|
|
507
|
-
You: /done
|
|
508
|
-
Agent: Brief finalized. Next step: /srs
|
|
509
|
-
|
|
510
|
-
You: /srs
|
|
511
|
-
Agent: [reads the brief, asks about roles, integrations, business rules...]
|
|
512
|
-
...
|
|
513
|
-
```
|
|
514
|
-
|
|
515
|
-
Repeat for each step. At any point after `/srs`, run `/clarify [focus]` to resolve ambiguities in the current artifact or `/analyze` for a full cross-artifact quality report. After `/stories`, run `/trace` to check traceability coverage.
|
|
516
|
-
|
|
517
|
-
---
|
|
518
|
-
|
|
519
|
-
## ποΈ What the Output Looks Like
|
|
520
|
-
|
|
521
|
-
A complete example project β **Dragon Fortune** (iGaming Telegram Mini App) β is included in [`example/dragon-fortune/`](example/dragon-fortune/). All 15 artifacts are realistic, cross-referenced, and generated by running the full BA Toolkit pipeline.
|
|
132
|
+
A complete example project β **Dragon Fortune** (iGaming Telegram Mini App) β lives in [`example/dragon-fortune/`](example/dragon-fortune/). All 15 artifacts are realistic, cross-referenced, and generated by running the full BA Toolkit pipeline.
|
|
522
133
|
|
|
523
134
|
| Artifact | File |
|
|
524
135
|
|---------|------|
|
|
@@ -538,305 +149,140 @@ A complete example project β **Dragon Fortune** (iGaming Telegram Mini App)
|
|
|
538
149
|
| Risk Register | [`00_risks_dragon-fortune.md`](example/dragon-fortune/00_risks_dragon-fortune.md) |
|
|
539
150
|
| Sprint Plan | [`00_sprint_dragon-fortune.md`](example/dragon-fortune/00_sprint_dragon-fortune.md) |
|
|
540
151
|
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
---
|
|
544
|
-
|
|
545
|
-
## π Usage Guide
|
|
546
|
-
|
|
547
|
-
### 1. Starting a project
|
|
548
|
-
|
|
549
|
-
Run the first command and the agent takes it from there β it loads domain references, asks questions, and generates the artifact. You never edit SKILL.md files directly.
|
|
550
|
-
|
|
551
|
-
```
|
|
552
|
-
You: /brief
|
|
553
|
-
Agent: What domain is your project in? (iGaming, Fintech, SaaS, other?)
|
|
554
|
-
You: Fintech β a neobank mobile app
|
|
555
|
-
Agent: Great. Let me ask a few questions.
|
|
556
|
-
1. What is the primary business goal β acquiring new users, increasing card usage, or something else?
|
|
557
|
-
2. What geography and currency does the app target?
|
|
558
|
-
3. Are there existing banking partners or will the app be a standalone product?
|
|
559
|
-
You: [answer all three]
|
|
560
|
-
Agent: Two more questions...
|
|
561
|
-
[1-2 more rounds]
|
|
562
|
-
Agent: [generates 01_brief_neobank-app.md]
|
|
563
|
-
|
|
564
|
-
Artifact saved: 01_brief_neobank-app.md
|
|
565
|
-
Covered: 3 business goals, 5 stakeholders, 4 risks.
|
|
566
|
-
Slug fixed for this pipeline: neobank-app
|
|
567
|
-
|
|
568
|
-
Available: /clarify Β· /revise Β· /expand Β· /validate Β· /done
|
|
569
|
-
Next step: /srs
|
|
570
|
-
```
|
|
571
|
-
|
|
572
|
-
The **slug** (`neobank-app`) is derived from the project name at `/brief` and used as a suffix for every subsequent file: `02_srs_neobank-app.md`, `03_stories_neobank-app.md`, and so on.
|
|
152
|
+
Full traceability: FR β US β UC β AC β NFR β Entity β ADR β API β WF β Scenario, plus risk register and sprint plan.
|
|
573
153
|
|
|
574
154
|
---
|
|
575
155
|
|
|
576
|
-
|
|
156
|
+
## Pipeline
|
|
577
157
|
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
158
|
+
| # | Command | What it generates | Output file |
|
|
159
|
+
|:---:|---------|-------------------|-------------|
|
|
160
|
+
| 0 | `/principles` | Project Principles β language, ID conventions, DoR, traceability rules, NFR baseline | `00_principles_{slug}.md` |
|
|
161
|
+
| 1 | `/brief` | Project Brief β goals, audience, stakeholders, risks | `01_brief_{slug}.md` |
|
|
162
|
+
| 2 | `/srs` | Requirements Specification (IEEE 830) | `02_srs_{slug}.md` |
|
|
163
|
+
| 3 | `/stories` | User Stories grouped by Epics | `03_stories_{slug}.md` |
|
|
164
|
+
| 4 | `/usecases` | Use Cases with main/alt/exception flows | `04_usecases_{slug}.md` |
|
|
165
|
+
| 5 | `/ac` | Acceptance Criteria (Given/When/Then) | `05_ac_{slug}.md` |
|
|
166
|
+
| 6 | `/nfr` | Non-functional Requirements with metrics | `06_nfr_{slug}.md` |
|
|
167
|
+
| 7 | `/datadict` | Data Dictionary β entities, types, constraints | `07_datadict_{slug}.md` |
|
|
168
|
+
| 7a | `/research` | Technology Research β ADRs, integration map, storage decisions | `07a_research_{slug}.md` |
|
|
169
|
+
| 8 | `/apicontract` | API Contract β endpoints, schemas, errors | `08_apicontract_{slug}.md` |
|
|
170
|
+
| 9 | `/wireframes` | Textual Wireframe Descriptions | `09_wireframes_{slug}.md` |
|
|
171
|
+
| 10 | `/scenarios` | End-to-end Validation Scenarios β user journeys linking US, AC, WF, API | `10_scenarios_{slug}.md` |
|
|
172
|
+
| 11 | `/handoff` | Development Handoff Package β artifact inventory, MVP scope, open items | `11_handoff_{slug}.md` |
|
|
173
|
+
| β | `/trace` | Traceability Matrix + coverage gaps | `00_trace_{slug}.md` |
|
|
174
|
+
| β | `/clarify [focus]` | Targeted ambiguity resolution for any artifact | _(updates existing artifact)_ |
|
|
175
|
+
| β | `/analyze` | Cross-artifact quality report with severity table | `00_analyze_{slug}.md` |
|
|
176
|
+
| β | `/estimate` | Effort estimation β Fibonacci SP, T-shirt sizes, or person-days | `00_estimate_{slug}.md` |
|
|
177
|
+
| β | `/glossary` | Unified project glossary with terminology drift detection | `00_glossary_{slug}.md` |
|
|
178
|
+
| β | `/export [format]` | Export User Stories to Jira / GitHub Issues / Linear / CSV | `export_{slug}_{format}.json` / `.csv` |
|
|
179
|
+
| β | `/risk` | Risk register β probability Γ impact matrix, mitigation per risk | `00_risks_{slug}.md` |
|
|
180
|
+
| β | `/sprint` | Sprint plan β stories grouped by velocity and capacity with sprint goals | `00_sprint_{slug}.md` |
|
|
181
|
+
|
|
182
|
+
The project **slug** (e.g., `dragon-fortune`) is set at `/brief` and reused across all files automatically.
|
|
596
183
|
|
|
597
184
|
---
|
|
598
185
|
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
Run `/clarify` after generating any artifact to surface ambiguities before moving on. It is faster than realising a problem three steps later.
|
|
602
|
-
|
|
603
|
-
```
|
|
604
|
-
You: /clarify
|
|
605
|
-
Agent: Found 4 ambiguities in 02_srs_neobank-app.md:
|
|
186
|
+
## Platform compatibility
|
|
606
187
|
|
|
607
|
-
|
|
608
|
-
2. [FR-011] "Admin" role is used but not defined in section 2.2 β same as "Compliance Officer"?
|
|
609
|
-
3. [NFR-001] "High availability" β what is the numeric SLA target (%)?
|
|
610
|
-
4. [FR-019 vs FR-024] Both describe currency conversion β are these the same feature?
|
|
188
|
+
BA Toolkit uses the open Agent Skills specification (`SKILL.md` format) published by Anthropic in December 2025 and adopted across multiple platforms.
|
|
611
189
|
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
190
|
+
| Platform | Support | Installation |
|
|
191
|
+
|----------|:-------:|-------------|
|
|
192
|
+
| **Claude Code** | Native | `cp -r skills/ .claude/skills/ba-toolkit/` |
|
|
193
|
+
| **OpenAI Codex CLI** | Native | `cp -r skills/ ~/.codex/skills/ba-toolkit/` |
|
|
194
|
+
| **Gemini CLI** | Native | Copy `skills/` to `~/.gemini/skills/ba-toolkit/` (user) or `.gemini/skills/ba-toolkit/` (workspace) |
|
|
195
|
+
| **Cursor** | Convert | `SKILL.md` β `.mdc` rules in `.cursor/rules/` |
|
|
196
|
+
| **Windsurf** | Convert | `SKILL.md` β rules in `.windsurf/rules/` |
|
|
197
|
+
| **Aider** | Convert | `SKILL.md` β conventions file |
|
|
616
198
|
|
|
617
|
-
|
|
199
|
+
Native platforms read `SKILL.md` as-is. Convert platforms need a one-time format conversion β the content is the same, only the file format differs. `ba-toolkit install --for cursor|windsurf` does this automatically.
|
|
618
200
|
|
|
619
|
-
|
|
620
|
-
You: /clarify security
|
|
621
|
-
You: /clarify FR-015
|
|
622
|
-
```
|
|
201
|
+
Skills do not hardcode platform paths β they reference `skills/references/environment.md`, which contains the output directory logic for each platform. Edit that file to customize; all skills pick up the change automatically.
|
|
623
202
|
|
|
624
203
|
---
|
|
625
204
|
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
Run `/analyze` at any point after `/srs` to get a cross-artifact quality report. Unlike `/trace` (which checks links), `/analyze` also catches duplicates, ambiguous language, and terminology drift.
|
|
629
|
-
|
|
630
|
-
```
|
|
631
|
-
You: /analyze
|
|
632
|
-
Agent: [reads all existing artifacts]
|
|
633
|
-
|
|
634
|
-
Artifact saved: 00_analyze_neobank-app.md
|
|
635
|
-
|
|
636
|
-
Finding Report:
|
|
637
|
-
| ID | Category | Severity | Location | Summary | Recommendation |
|
|
638
|
-
|----|---------------|----------|-------------------|----------------------------------|-----------------------|
|
|
639
|
-
| A1 | Coverage Gap | CRITICAL | srs:FR-008 | No linked user story | Create US or remove |
|
|
640
|
-
| A2 | Ambiguity | HIGH | nfr:NFR-004 | "Scalable" without metric | Add target RPS |
|
|
641
|
-
| A3 | Terminology | HIGH | srs + stories | "Wallet" vs "Balance" drift | Standardize in glossary |
|
|
642
|
-
| A4 | Duplication | MEDIUM | srs:FR-012,FR-017 | Near-duplicate login requirements| Merge |
|
|
643
|
-
|
|
644
|
-
Overall coverage: FRβUS 87% Β· USβAC 94%
|
|
645
|
-
CRITICAL: 1 Β· HIGH: 2 Β· MEDIUM: 1
|
|
646
|
-
|
|
647
|
-
Top actions: fix A1 with /stories, fix A2 with /clarify NFR-004, fix A3 with /revise glossary
|
|
648
|
-
```
|
|
205
|
+
## Domain support
|
|
649
206
|
|
|
650
|
-
|
|
207
|
+
The pipeline is domain-agnostic by default. At `/brief`, you pick a domain, and every subsequent skill loads domain-specific interview questions, mandatory entities, NFR categories, and glossary terms.
|
|
651
208
|
|
|
652
|
-
|
|
|
653
|
-
|
|
654
|
-
|
|
|
655
|
-
|
|
|
656
|
-
|
|
|
657
|
-
|
|
|
658
|
-
|
|
659
|
-
|
|
209
|
+
| Domain | Industries covered |
|
|
210
|
+
|--------|-------------------|
|
|
211
|
+
| **iGaming** | Online slots, sports betting, casino lobbies, Telegram Mini Apps, promo mechanics |
|
|
212
|
+
| **Fintech** | Neobanks, payment systems, crypto exchanges, investment platforms, P2P lending |
|
|
213
|
+
| **SaaS** | B2B platforms, CRM, analytics, marketplaces, EdTech, HRTech |
|
|
214
|
+
| **E-commerce** | B2C stores, B2B catalogs, multi-vendor marketplaces, D2C brands, digital goods |
|
|
215
|
+
| **Healthcare** | Telemedicine, patient portals, EHR/EMR, clinic management, mental health apps |
|
|
216
|
+
| **Logistics** | Last-mile delivery, courier management, freight tracking, WMS, fleet management |
|
|
217
|
+
| **On-demand** | Ride-hailing, home services, task marketplaces, beauty, tutoring, pet care |
|
|
218
|
+
| **Social / Media** | Social networks, creator platforms, community forums, newsletters, short-video |
|
|
219
|
+
| **Real Estate** | Property portals, agency CRM, rental management, property management, mortgage tools |
|
|
220
|
+
| **Custom** | Any other domain β works with general interview questions |
|
|
221
|
+
|
|
222
|
+
Adding a new domain = creating one Markdown file in `skills/references/domains/`. See [docs/DOMAINS.md](docs/DOMAINS.md).
|
|
660
223
|
|
|
661
224
|
---
|
|
662
225
|
|
|
663
|
-
|
|
226
|
+
## How it works
|
|
664
227
|
|
|
665
|
-
|
|
228
|
+
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.
|
|
666
229
|
|
|
667
|
-
|
|
668
|
-
You: /trace
|
|
669
|
-
Agent: [generates 00_trace_neobank-app.md]
|
|
670
|
-
|
|
671
|
-
Coverage Summary:
|
|
672
|
-
FR β US: 24/27 (89%) β FR-008, FR-019, FR-022 uncovered
|
|
673
|
-
US β AC: 41/41 (100%) β
|
|
674
|
-
Entity β FR: 18/20 (90%) β Transaction, AuditLog not linked
|
|
230
|
+
Every artifact links back to its predecessors, forming the chain `FR β US β UC β AC β NFR β Entity β ADR β API β WF β Scenario`. Run `/trace` to verify coverage and `/analyze` for severity-rated findings (duplicates, ambiguous terms, terminology drift, invalid references).
|
|
675
231
|
|
|
676
|
-
|
|
677
|
-
β Create user stories for FR-008, FR-019, FR-022 or remove them from SRS
|
|
678
|
-
β Link Transaction and AuditLog to relevant FR in /datadict
|
|
679
|
-
```
|
|
232
|
+
### Subcommands
|
|
680
233
|
|
|
681
|
-
|
|
234
|
+
| Command | What it does |
|
|
235
|
+
|---------|-------------|
|
|
236
|
+
| `/clarify [focus]` | Targeted ambiguity pass β surfaces vague terms, missing metrics, conflicting rules |
|
|
237
|
+
| `/revise [section]` | Rewrite a specific section with your feedback |
|
|
238
|
+
| `/expand [section]` | Add more detail to a section |
|
|
239
|
+
| `/split [element]` | Break a large element into smaller ones (e.g., a big user story) |
|
|
240
|
+
| `/validate` | Check completeness, consistency, and alignment with prior artifacts |
|
|
241
|
+
| `/analyze` | Cross-artifact quality report: duplicates, coverage gaps, terminology drift, invalid references |
|
|
242
|
+
| `/done` | Finalize the current artifact and move to the next pipeline step |
|
|
682
243
|
|
|
683
244
|
---
|
|
684
245
|
|
|
685
|
-
|
|
246
|
+
## Minimum viable pipeline
|
|
686
247
|
|
|
687
|
-
|
|
248
|
+
Not every project needs all 21 skills. Two common paths:
|
|
688
249
|
|
|
250
|
+
**Lean** (fastest path to handoff β 9 steps):
|
|
689
251
|
```
|
|
690
|
-
|
|
691
|
-
Agent: US-014 covers 4 distinct actions. Suggested split:
|
|
692
|
-
β US-014a: Player views transaction history (read-only)
|
|
693
|
-
β US-014b: Player filters transactions by date and type
|
|
694
|
-
β US-014c: Player exports transactions as PDF
|
|
695
|
-
β US-014d: Player disputes a transaction
|
|
696
|
-
|
|
697
|
-
Shall I apply this split?
|
|
698
|
-
You: Yes, but combine 014a and 014b
|
|
699
|
-
Agent: [rewrites US-014 as two stories: US-014 and US-014b]
|
|
252
|
+
/brief β /srs β /stories β /ac β /nfr β /datadict β /apicontract β /wireframes β /handoff
|
|
700
253
|
```
|
|
701
254
|
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
If you start a new project without changing the output directory, the agent detects existing `01_brief_*.md` files and warns you before overwriting anything.
|
|
709
|
-
|
|
710
|
-
---
|
|
711
|
-
|
|
712
|
-
### 8. Troubleshooting
|
|
713
|
-
|
|
714
|
-
**Agent says it can't find the brief / SRS / previous artifact:**
|
|
715
|
-
The skill looks for files matching `01_brief_*.md` in the output directory. If the file was saved elsewhere, either move it or tell the agent the full path.
|
|
716
|
-
|
|
717
|
-
**Artifact was generated in the wrong language:**
|
|
718
|
-
Run `/principles` and set the artifact language explicitly. Then re-run the current step β all subsequent skills will use the language from `00_principles_{slug}.md`.
|
|
719
|
-
|
|
720
|
-
**Want to redo a step from scratch:**
|
|
721
|
-
Run the command again (e.g., `/srs`). The agent will warn that `02_srs_{slug}.md` already exists and offer to overwrite or create a new version.
|
|
722
|
-
|
|
723
|
-
**A domain reference is not loading:**
|
|
724
|
-
Check that `skills/references/domains/{domain}.md` exists and that the domain name in the brief matches exactly (`igaming`, `fintech`, `saas`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, or `real-estate` β lowercase with hyphens).
|
|
725
|
-
|
|
726
|
-
**`/analyze` reports findings after you already fixed them:**
|
|
727
|
-
Run `/analyze` again β it always re-reads all artifacts fresh. Cached results are never used.
|
|
728
|
-
|
|
729
|
-
---
|
|
730
|
-
|
|
731
|
-
### 9. AGENTS.md β persistent project context
|
|
732
|
-
|
|
733
|
-
After `/brief` completes, the agent creates or updates `AGENTS.md` in your project root. This file stores the project slug, domain, key constraints, artifact paths, and the current pipeline stage.
|
|
734
|
-
|
|
735
|
-
```markdown
|
|
736
|
-
# BA Toolkit β Project Context
|
|
737
|
-
|
|
738
|
-
**Project:** Dragon Fortune
|
|
739
|
-
**Slug:** dragon-fortune
|
|
740
|
-
**Domain:** iGaming
|
|
741
|
-
**Language:** English
|
|
742
|
-
**Pipeline stage:** Brief complete
|
|
743
|
-
|
|
744
|
-
## Artifacts
|
|
745
|
-
- `/outputs/01_brief_dragon-fortune.md` β Project Brief
|
|
746
|
-
|
|
747
|
-
## Key context
|
|
748
|
-
- **Business goal:** Telegram Mini App slot for CIS markets, 50k MAU in 6 months
|
|
749
|
-
- **Key constraints:** Telegram API limits, AML/KYC compliance, certified RTP
|
|
750
|
-
|
|
751
|
-
## Next step
|
|
752
|
-
Run /srs to generate the Requirements Specification.
|
|
255
|
+
**Full** (complete traceability and quality gates β 15 steps):
|
|
256
|
+
```
|
|
257
|
+
/principles β /brief β /srs β /stories β /usecases β /ac β /nfr β /datadict
|
|
258
|
+
β /research β /apicontract β /wireframes β /scenarios
|
|
259
|
+
β /trace β /analyze β /handoff
|
|
753
260
|
```
|
|
754
261
|
|
|
755
|
-
|
|
262
|
+
Use `/clarify` at any step to resolve ambiguities before moving on. Approximate time per step is in [docs/USAGE.md#appendix-time-estimates](docs/USAGE.md#appendix-time-estimates).
|
|
756
263
|
|
|
757
264
|
---
|
|
758
265
|
|
|
759
|
-
##
|
|
760
|
-
|
|
761
|
-
**Do I need all 21 skills?**
|
|
762
|
-
No. The lean pipeline (`/brief β /srs β /stories β /ac β /nfr β /datadict β /apicontract β /wireframes β /handoff`) covers the essentials in ~3β4 hours. Add `/usecases`, `/research`, `/scenarios`, `/trace`, and `/analyze` when you need deeper coverage.
|
|
763
|
-
|
|
764
|
-
**Can I use it in any language?**
|
|
765
|
-
Yes. The agent detects the language of your first message and generates all artifacts in that language. Set it explicitly with `/principles` if you want to lock it regardless of the conversation language.
|
|
766
|
-
|
|
767
|
-
**Does it work offline / without internet?**
|
|
768
|
-
Yes. All skills are local Markdown files. The only network dependency is your AI agent itself (Claude Code, Codex CLI, etc.). No BA Toolkit component calls any external API.
|
|
769
|
-
|
|
770
|
-
**My domain isn't iGaming, Fintech, or SaaS β can I still use it?**
|
|
771
|
-
Yes. Select "Custom" at `/brief` and the skills use general interview questions. You can add your own domain in 30 minutes by creating one Markdown file β see [Adding a New Domain](#adding-a-new-domain).
|
|
772
|
-
|
|
773
|
-
**Can I go back and edit a previous artifact?**
|
|
774
|
-
Yes. Run `/revise [section]` at any step, or re-invoke the skill command (e.g., `/srs`) to regenerate from scratch. The agent warns before overwriting. Subsequent skills will read the updated version automatically.
|
|
266
|
+
## Usage guide
|
|
775
267
|
|
|
776
|
-
|
|
777
|
-
The structured Markdown format and explicit cross-references help smaller models stay on track. For best results, use a model with a context window of at least 32k tokens β the later pipeline steps load multiple large artifacts simultaneously.
|
|
268
|
+
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).
|
|
778
269
|
|
|
779
|
-
|
|
780
|
-
See the update instructions in the [Installation](#-installation) section below.
|
|
270
|
+
For common issues and fixes, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
|
|
781
271
|
|
|
782
272
|
---
|
|
783
273
|
|
|
784
|
-
##
|
|
274
|
+
## FAQ
|
|
785
275
|
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
**New domains** (highest impact, no code required):
|
|
789
|
-
Create `skills/references/domains/{domain}.md` following the template in [Adding a New Domain](#adding-a-new-domain). Open a PR with the file and a brief description of the domain.
|
|
790
|
-
|
|
791
|
-
**Skill improvements:**
|
|
792
|
-
Edit the relevant `skills/{name}/SKILL.md`. Keep changes backward-compatible β avoid renaming sections or changing output file names, as other skills depend on them.
|
|
793
|
-
|
|
794
|
-
**Bug reports:**
|
|
795
|
-
Open a GitHub issue with: the skill name, the command you ran, the agent/platform you used, and what happened vs. what you expected.
|
|
796
|
-
|
|
797
|
-
**Guidelines:**
|
|
798
|
-
- One PR per domain or skill.
|
|
799
|
-
- Test the skill end-to-end before submitting (run the full command, check the output file).
|
|
800
|
-
- Keep the style consistent with existing skills: formal, neutral, no emoji in artifact body, language follows user input.
|
|
276
|
+
Answers to common questions β language support, offline use, custom domains, editing past artifacts, model size, updates β are in [docs/FAQ.md](docs/FAQ.md).
|
|
801
277
|
|
|
802
278
|
---
|
|
803
279
|
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
Create `skills/references/domains/{domain}.md` following this structure:
|
|
807
|
-
|
|
808
|
-
```markdown
|
|
809
|
-
# Domain Reference: {Name}
|
|
810
|
-
|
|
811
|
-
## 1. /brief β Project Brief
|
|
812
|
-
### Domain-specific interview questions
|
|
813
|
-
### Typical business goals
|
|
814
|
-
### Typical risks
|
|
815
|
-
|
|
816
|
-
## 2. /srs β Requirements Specification
|
|
817
|
-
### Domain-specific interview questions
|
|
818
|
-
### Typical functional areas
|
|
819
|
-
|
|
820
|
-
## 3. /stories β User Stories
|
|
821
|
-
### Domain-specific interview questions
|
|
822
|
-
### Typical epics
|
|
823
|
-
|
|
824
|
-
## 4. /usecases β Use Cases
|
|
825
|
-
## 5. /ac β Acceptance Criteria
|
|
826
|
-
## 6. /nfr β Non-functional Requirements
|
|
827
|
-
## 7. /datadict β Data Dictionary
|
|
828
|
-
## 8. /apicontract β API Contract
|
|
829
|
-
## 9. /wireframes β Wireframe Descriptions
|
|
830
|
-
|
|
831
|
-
## Domain Glossary
|
|
832
|
-
| Term | Definition |
|
|
833
|
-
|------|-----------|
|
|
834
|
-
```
|
|
280
|
+
## Contributing
|
|
835
281
|
|
|
836
|
-
|
|
282
|
+
New domains and skill improvements are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the PR workflow, and [docs/DOMAINS.md](docs/DOMAINS.md) for the domain file template.
|
|
837
283
|
|
|
838
284
|
---
|
|
839
285
|
|
|
840
|
-
##
|
|
286
|
+
## License
|
|
841
287
|
|
|
842
288
|
MIT β use freely, modify, distribute. See [LICENSE](LICENSE) for the full text.
|