Skip to content
BA Toolkit

Getting started

BA Toolkit ships as a single npm package with zero runtime dependencies. Install once, scaffold a project, then run the pipeline inside any supported AI agent.

Prerequisites

Section titled “Prerequisites”

Before you start, make sure you have the following:

  • Node.js 18 or later. Node.js is a free runtime that lets you run JavaScript outside a browser. To check if you have it, open a terminal (Terminal on Mac, Command Prompt or PowerShell on Windows) and type node --version. If you see v18.x.x or higher, you are ready. If not, download the LTS version from nodejs.org and install it — the defaults are fine.
  • An AI coding agent. BA Toolkit skills run inside an AI agent, not in the terminal. You need one of these installed:
    • Claude Code — Anthropic’s CLI agent (free tier available)
    • Cursor — AI-powered code editor (free tier available)
    • Codex CLI — OpenAI’s terminal agent
    • Gemini CLI — Google’s terminal agent
    • Windsurf — AI-powered code editor

You do not need to know how to code. The agent asks you questions and generates all the documents for you.

1. Install

Section titled “1. Install”
Terminal window
# Full setup in one command — prompts for project name, domain, and AI agent.
npx '@kudusov.takhir/ba-toolkit' init


# Or install globally and reuse across projects.
npm install -g '@kudusov.takhir/ba-toolkit'
ba-toolkit init

init creates AGENTS.md at the project root and output/ for artifacts, then installs the 29 skills into your chosen agent’s native skills directory. No conversion step — every supported agent reads SKILL.md directly.

2. Open your AI agent in the project folder

Section titled “2. Open your AI agent in the project folder”
Terminal window
claude   # or: codex / gemini / cursor / windsurf

Open your AI agent at the project root (where AGENTS.md was created). Artifacts are saved to output/.

3. Run the pipeline

Section titled “3. Run the pipeline”

Here is the full pipeline at a glance. Steps marked “(optional)” can be skipped — the lean path takes ~3–4 hours, the full path ~5–8 hours.

  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
  │ /discovery  │────▶│   /brief    │────▶│    /srs     │────▶│  /stories   │
  │  (optional) │     │  Goals &    │     │ Requirements│     │ User Stories│
  └─────────────┘     │ Stakeholders│     │  (IEEE 830) │     │  by Epic    │
                      └─────────────┘     └─────────────┘     └──────┬──────┘
                                                                     │
                 ┌───────────────────────────────────────────────────┘
                 │
                 ▼
  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
  │  /usecases  │────▶│    /ac      │────▶│    /nfr     │────▶│  /datadict  │
  │  (optional) │     │ Acceptance  │     │ Performance,│     │  Entities & │
  │             │     │  Criteria   │     │  Security…  │     │   Fields    │
  └─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘
                                                                     │
                 ┌───────────────────────────────────────────────────┘
                 │
                 ▼
  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
  │  /research  │────▶│/apicontract │────▶│ /wireframes │────▶│ /scenarios  │
  │  (optional) │     │  Endpoints  │     │   Screens   │     │  (optional) │
  │  Tech ADRs  │     │ & Schemas   │     │ & Navigation│     │  E2E Flows  │
  └─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘
                                                                     │
                 ┌───────────────────────────────────────────────────┘
                 │
                 ▼
  ┌─────────────┐     ┌─────────────┐
  │  /handoff   │────▶│/implement-  │     ╔═══════════════════════════════╗
  │  Dev-ready  │     │   plan      │     ║  UTILITY SKILLS (any stage)  ║
  │  Package    │     │ Task DAG    │     ║                               ║
  └─────────────┘     │ for AI Agent│     ║  /trace    — coverage matrix  ║
                      └─────────────┘     ║  /clarify  — fix ambiguities  ║
                                          ║  /analyze  — quality report   ║
                                          ║  /estimate — story points     ║
                                          ║  /glossary — term consistency ║
                                          ║  /risk     — risk register    ║
                                          ║  /sprint   — sprint plan      ║
                                          ║  /export   — Jira/GitHub/CSV  ║
                                          ║  /publish  — Notion/Confluence║
                                          ╚═══════════════════════════════╝

Want to see what the output looks like? Browse the complete example project.

Type /discovery in the agent if you have only a vague idea of what to build, or jump straight to /brief if the project is clear:

/discovery I think there's a need for a tool that helps freelance designers track invoices and chase late payments

The agent walks you through a structured interview (one question at a time, 4 multiple-choice options plus a free-text “Other”, one option marked Recommended based on your domain), then generates a Markdown artifact in the project folder. Move through the pipeline:

/discovery   →  00_discovery_<slug>.md
/brief       →  01_brief_<slug>.md
/srs         →  02_srs_<slug>.md
/stories     →  03_stories_<slug>.md
/usecases    →  04_usecases_<slug>.md
/ac          →  05_ac_<slug>.md
/nfr         →  06_nfr_<slug>.md
/datadict    →  07_datadict_<slug>.md
/research    →  07a_research_<slug>.md
/apicontract →  08_apicontract_<slug>.md
/wireframes  →  09_wireframes_<slug>.md
/scenarios   →  10_scenarios_<slug>.md
/handoff     →  11_handoff_<slug>.md
/implement-plan →  12_implplan_<slug>.md

You don’t have to run every step. The lean path (/brief → /srs → /stories → /ac → /nfr → /datadict → /apicontract → /wireframes → /handoff → /implement-plan) takes ~3–4 hours and gives you a complete BA package plus an AI-actionable implementation plan.

4. Hand off to a coding agent

Section titled “4. Hand off to a coding agent”

After /handoff and /implement-plan, point your AI coding agent at 12_implplan_<slug>.md. The plan is structured as 9 phases (Foundation → Data → Auth → Core → API → UI → Integrations → Quality → Validation) with atomic tasks. Each task references the requirements and acceptance criteria it implements, and carries its own checklist for completion. The agent can step through it without re-reading the whole pipeline every time.

5. Optional — share with stakeholders

Section titled “5. Optional — share with stakeholders”
Terminal window
ba-toolkit publish        # bundles for both Notion (Markdown) and Confluence (HTML)

Drag-and-drop the generated folders into Notion’s Import → Markdown & CSV dialog or zip them and upload via Confluence’s Space settings → Content tools → Import → HTML. No API tokens, no network calls — the conversion happens entirely on disk.

What’s next

Section titled “What’s next”
  • The full usage guide walks through every skill in detail.
  • The command reference lists every shipped skill.
  • The FAQ answers common questions about language support, offline use, and editing past artifacts.
  • The glossary explains all the acronyms and standards referenced in the artifacts.
  • The roadmap covers what is planned next and what is explicitly out of scope.