@kudusov.takhir/ba-toolkit 1.2.0

package/skills/export/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: ba-export
+description: >
+  Export BA Toolkit artifacts to external formats for import into issue trackers and project management tools. Use on /export command, or when the user asks to "export to Jira", "create GitHub issues", "export stories", "generate Linear tickets", "export to CSV", "import into tracker". Run after /stories and /ac for full export with acceptance criteria.
+---
+
+# /export — Artifact Export
+
+Converts User Stories (and optionally Acceptance Criteria) into structured output files ready for import into issue trackers and project management tools.
+
+## Syntax
+
+```
+/export [format] [optional: scope]
+```
+
+Examples:
+- `/export` — interactive: ask which format
+- `/export jira` — export all stories as Jira-compatible JSON
+- `/export github` — export all stories as GitHub Issues JSON (via `gh` CLI or API)
+- `/export linear` — export all stories as Linear GraphQL mutation payload
+- `/export csv` — export all stories as CSV (universal fallback)
+- `/export jira E-01` — export only Epic E-01 stories
+- `/export github US-007,US-008` — export specific stories
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it and apply ID conventions and language settings.
+1. Load `03_stories_{slug}.md` — required. If it does not exist, stop and ask the user to run `/stories` first.
+2. Load `05_ac_{slug}.md` if it exists — AC scenarios will be embedded in issue descriptions.
+3. Load `00_estimate_*.md` or read `**Estimate:**` fields from stories — include story points in the export if available.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory.
+
+## Format interview
+
+If the format is not specified, ask:
+
+1. **Target tool:** Jira, GitHub Issues, Linear, CSV, or other?
+2. **Scope:** All stories, a specific epic, or specific story IDs?
+3. **Include AC?** Embed acceptance criteria in the issue body? (default: yes)
+4. **Jira-specific:** Project key (e.g., `PROJ`)? Epic link field name (default: `customfield_10014`)? Story Points field name (default: `story_points`)?
+5. **GitHub-specific:** Repository (e.g., `owner/repo`)? Label prefix for epics (e.g., `epic:`)? Milestone name (optional)?
+
+## Export formats
+
+---
+
+### Format: Jira (JSON)
+
+Output file: `export_{slug}_jira.json`
+
+```json
+{
+  "projects": [
+    {
+      "key": "{JIRA_PROJECT_KEY}",
+      "issues": [
+        {
+          "summary": "US-001: {Story title}",
+          "description": {
+            "type": "doc",
+            "version": 1,
+            "content": [
+              {
+                "type": "paragraph",
+                "content": [{ "type": "text", "text": "As a {role}, I want to {action}, so that {benefit}." }]
+              },
+              {
+                "type": "heading",
+                "attrs": { "level": 3 },
+                "content": [{ "type": "text", "text": "Acceptance Criteria" }]
+              },
+              {
+                "type": "bulletList",
+                "content": [
+                  { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Given ... When ... Then ..." }] }] }
+                ]
+              }
+            ]
+          },
+          "issuetype": { "name": "Story" },
+          "priority": { "name": "{Must→High | Should→Medium | Could→Low | Won't→Lowest}" },
+          "labels": ["{slug}", "{epic-id}"],
+          "customfield_10016": {story_points_or_null},
+          "customfield_10014": "{epic_link_or_null}"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Priority mapping:**
+- Must → `High`
+- Should → `Medium`
+- Could → `Low`
+- Won't → `Lowest`
+
+**Instructions to include after the file:**
+```
+Import via: Jira → Project Settings → Issue Import → JSON Import
+Or via CLI: jira import --file export_{slug}_jira.json
+```
+
+---
+
+### Format: GitHub Issues (JSON)
+
+Output file: `export_{slug}_github.json`
+
+Array of issue objects, one per story. Compatible with `gh` CLI batch import.
+
+```json
+[
+  {
+    "title": "US-001: {Story title}",
+    "body": "## User Story\n\nAs a **{role}**, I want to **{action}**, so that **{benefit}**.\n\n---\n\n## Acceptance Criteria\n\n**Scenario 1 — {name}**\n- Given {precondition}\n- When {action}\n- Then {result}\n\n---\n\n**FR Reference:** FR-{NNN}\n**Priority:** {Must | Should | Could | Won't}\n**Estimate:** {N SP | —}",
+    "labels": ["{epic-label}", "user-story", "{priority-label}"],
+    "milestone": "{milestone-name-or-null}"
+  }
+]
+```
+
+**Label strategy:**
+- Epic label: `epic:{epic-id}` (e.g., `epic:E-01`)
+- Priority label: `priority:must` / `priority:should` / `priority:could`
+- Type label: `user-story`
+
+**Instructions to include after the file:**
+```bash
+# Create issues via GitHub CLI (requires: gh auth login)
+cat export_{slug}_github.json | jq -c '.[]' | while read issue; do
+  title=$(echo "$issue" | jq -r '.title')
+  body=$(echo "$issue" | jq -r '.body')
+  labels=$(echo "$issue" | jq -r '.labels | join(",")')
+  gh issue create --repo {owner/repo} --title "$title" --body "$body" --label "$labels"
+done
+```
+
+---
+
+### Format: Linear (JSON)
+
+Output file: `export_{slug}_linear.json`
+
+```json
+{
+  "issues": [
+    {
+      "title": "US-001: {Story title}",
+      "description": "**As a** {role}, **I want to** {action}, **so that** {benefit}.\n\n### Acceptance Criteria\n\n{AC scenarios in markdown}",
+      "priority": "{0=No priority | 1=Urgent | 2=High | 3=Medium | 4=Low}",
+      "estimate": {story_points_or_null},
+      "labelNames": ["{epic-id}", "user-story"],
+      "stateName": "Backlog"
+    }
+  ]
+}
+```
+
+**Priority mapping:**
+- Must → `2` (High)
+- Should → `3` (Medium)
+- Could → `4` (Low)
+- Won't → `0` (No priority)
+
+**Instructions to include after the file:**
+```
+Import via Linear's CSV import or use the Linear API:
+POST https://api.linear.app/graphql with the issueCreate mutation per issue.
+Linear does not have a native bulk JSON import — use the Linear SDK or Zapier.
+```
+
+---
+
+### Format: CSV
+
+Output file: `export_{slug}_stories.csv`
+
+```
+ID,Title,Epic,Role,Action,Benefit,Priority,Estimate,FR Reference,AC Summary
+US-001,"{Story title}",E-01,"{role}","{action}","{benefit}",Must,3 SP,FR-001,"{first AC scenario summary}"
+```
+
+Compatible with Jira CSV import, Trello, Asana, Monday.com, and Google Sheets.
+
+---
+
+## Output
+
+Save the export file to the output directory alongside the artifacts:
+
+```
+output/{slug}/export_{slug}_{format}.json
+output/{slug}/export_{slug}_stories.csv   (CSV format)
+```
+
+## Closing message
+
+After saving, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Format exported.
+- Number of stories exported (and any skipped — e.g., "Won't" priority excluded by default).
+- Whether AC was included.
+- Copy-paste import instructions specific to the chosen format.
+
+Available commands: `/export [format]` (export in another format) · `/estimate` · `/handoff`
+
+## Style
+
+Generate only valid JSON or CSV. Do not include comments inside JSON files. Use double quotes for all JSON strings. Escape newlines in description fields as `\n`. Generate output in English regardless of the artifact language (issue trackers expect English field values unless explicitly told otherwise).

package/skills/glossary/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: ba-glossary
+description: >
+  Unified project glossary extraction and maintenance for BA Toolkit projects. Use on /glossary command, or when the user asks to "build a glossary", "extract terms", "create a glossary", "consolidate terminology", "find terminology drift", "what terms are defined". Cross-cutting command — can run at any pipeline stage once at least one artifact exists.
+---
+
+# /glossary — Unified Project Glossary
+
+Cross-cutting command. Scans all existing artifacts and the domain reference file, extracts defined and used terms, detects terminology drift (same concept, different names), and produces or updates a single `00_glossary_{slug}.md` file.
+
+## Syntax
+
+```
+/glossary [optional: action]
+```
+
+Examples:
+- `/glossary` — build or refresh the full project glossary
+- `/glossary drift` — only show terminology drift findings, do not regenerate
+- `/glossary add [Term]: [Definition]` — manually add a term to the glossary
+
+## Context loading
+
+0. If `00_principles_*.md` exists, load it — apply language convention (section 1) and ID naming convention (section 2).
+1. Scan the output directory for all existing artifacts. Load each one found:
+   - `01_brief_{slug}.md` — Brief Glossary section
+   - `02_srs_{slug}.md` — Definitions and Abbreviations section, User Roles
+   - `03_stories_{slug}.md` — actor names used in "As a..." statements
+   - `04_usecases_{slug}.md` — actor names, system names
+   - `05_ac_{slug}.md` — state names, condition terms
+   - `06_nfr_{slug}.md` — category names, compliance standard names
+   - `07_datadict_{slug}.md` — entity names, field names, enum values
+   - `07a_research_{slug}.md` — technology names, ADR decisions
+   - `08_apicontract_{slug}.md` — error codes, resource names
+   - `09_wireframes_{slug}.md` — screen names, UI component names
+   - `10_scenarios_{slug}.md` — persona names, scenario types
+   - `11_handoff_{slug}.md` — any additional terms
+2. Load `skills/references/domains/{domain}.md` — Domain Glossary section.
+3. If `00_glossary_{slug}.md` already exists, load it to merge rather than replace.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory.
+
+## Analysis pass
+
+### Step 1 — Term extraction
+
+Extract terms from:
+- Explicit glossary sections in artifacts (Brief § Glossary, SRS § Definitions).
+- Entity names from the Data Dictionary.
+- Actor / role names used across all artifacts.
+- Domain Glossary from the domain reference file.
+- Enum values that represent domain states.
+
+For each term, record:
+- The term itself (canonical form).
+- Its definition.
+- Source artifact(s).
+- All variant names found across artifacts (e.g., "User", "Customer", "Account").
+
+### Step 2 — Terminology drift detection
+
+Identify cases where the same concept appears under different names in different artifacts:
+
+```
+⚠️ Drift: "Customer" (Brief), "User" (SRS), "Account" (Data Dictionary) — all refer to the registered buyer entity.
+→ Recommend canonical name: "Customer"
+```
+
+Flag drift as:
+- 🔴 **Critical** — core entity or actor name differs across more than 2 artifacts (impairs traceability).
+- 🟡 **Medium** — synonym used in 1 artifact (easy to harmonise).
+- 🟢 **Low** — informal variation in a description field only.
+
+### Step 3 — Undefined term detection
+
+Identify terms used in requirements but not defined anywhere in the glossary or domain reference:
+```
+⚠️ Undefined: "Vesting schedule" used in FR-007 — not defined in glossary or domain reference.
+```
+
+## Generation
+
+Save `00_glossary_{slug}.md` to the output directory.
+
+```markdown
+# Project Glossary: {PROJECT_NAME}
+
+**Domain:** {DOMAIN}
+**Date:** {DATE}
+**Slug:** {SLUG}
+**Sources:** {list of artifacts scanned}
+
+---
+
+## Terms
+
+| Term | Definition | Source | Variants |
+|------|-----------|--------|---------|
+| [Term] | [Definition] | [artifact file] | [synonym1, synonym2 or —] |
+
+---
+
+## Terminology Drift Report
+
+| Severity | Concept | Variants found | Canonical recommendation |
+|---------|---------|---------------|------------------------|
+| 🔴 Critical | [concept] | [list] | [recommended term] |
+| 🟡 Medium | [concept] | [list] | [recommended term] |
+
+---
+
+## Undefined Terms
+
+| Term | Used in | Recommended action |
+|------|---------|-------------------|
+| [term] | [FR-NNN / US-NNN / etc.] | Define in glossary or remove |
+```
+
+Glossary terms are sorted alphabetically. Domain glossary terms are included but labelled with their source (`domain reference`).
+
+### Merge behaviour
+
+If `00_glossary_{slug}.md` already exists:
+- Preserve manually added definitions (do not overwrite if definition is more detailed than the extracted one).
+- Add new terms found since last run.
+- Update the Sources and Date fields.
+- Re-run drift detection across all artifacts.
+
+## Closing message
+
+After saving, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file: `00_glossary_{slug}.md`
+- Total terms in glossary.
+- Drift findings: N critical, N medium, N low.
+- Undefined terms found: N.
+- If critical drift found: recommend `/clarify` on affected artifacts to harmonise terminology, or offer to apply the canonical names automatically.
+
+Available commands: `/glossary drift` (drift report only) · `/glossary add [Term]: [Def]` · `/clarify [artifact]` · `/analyze`
+
+## Style
+
+Neutral, precise. Term definitions should be one sentence, domain-specific, and consistent with the artifact language set in `00_principles_{slug}.md`. Do not invent definitions — only use what is stated or clearly implied in the artifacts.

package/skills/handoff/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: ba-handoff
+description: >
+  Generate a development handoff package summarising the entire BA Toolkit pipeline: artifact inventory, MVP scope, open items, top risks, and recommended next steps. Use on /handoff command, or when the user asks to "prepare handoff", "create handoff document", "summarise the pipeline", "package for developers", "ready for development", "export to Jira", "what is left to do", "pipeline summary". Optional final step — available after /wireframes.
+---
+
+# /handoff — Development Handoff Package
+
+Optional final step of the BA Toolkit pipeline. Reads all existing artifacts and generates a single handoff document for the development team. No interview — all information is extracted from the pipeline artifacts.
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it and apply its conventions.
+1. Read all pipeline artifacts from the output directory.
+2. Minimum required: `01_brief_*.md` and `02_srs_*.md`. Warn about any missing artifacts and note them as incomplete in the handoff.
+3. If `00_trace_*.md` exists, use it as the source of coverage statistics. If not, compute coverage from available artifacts.
+4. If `00_analyze_*.md` exists, import its open findings into the handoff.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Generation
+
+No interview. All content is derived from the existing artifacts.
+
+**File:** `11_handoff_{slug}.md`
+
+```markdown
+# Development Handoff: {Project Name}
+
+**Date:** {date}
+**Domain:** {domain}
+**Pipeline completion:** {n}/{total} steps completed
+
+---
+
+## 1. Artifact Inventory
+
+| Artifact | File | Status | Key numbers |
+|----------|------|--------|-------------|
+| Project Brief | `01_brief_{slug}.md` | ✓ Complete | {n} goals, {n} risks |
+| SRS | `02_srs_{slug}.md` | ✓ Complete | {n} FR ({must}/{should}/{could}/{wont}) |
+| User Stories | `03_stories_{slug}.md` | ✓ Complete | {n} stories across {n} epics |
+| Use Cases | `04_usecases_{slug}.md` | ✓ / ✗ Missing | {n} UC |
+| Acceptance Criteria | `05_ac_{slug}.md` | ✓ / ✗ Missing | {n} AC |
+| NFR | `06_nfr_{slug}.md` | ✓ / ✗ Missing | {n} NFR across {n} categories |
+| Research | `07a_research_{slug}.md` | ✓ / ✗ Missing / — Not run | {tech decisions} |
+| Data Dictionary | `07_datadict_{slug}.md` | ✓ / ✗ Missing | {n} entities, {n} attributes |
+| API Contract | `08_apicontract_{slug}.md` | ✓ / ✗ Missing | {n} endpoints |
+| Wireframes | `09_wireframes_{slug}.md` | ✓ / ✗ Missing | {n} screens |
+| Scenarios | `10_scenarios_{slug}.md` | ✓ / ✗ Missing / — Not run | {n} scenarios |
+
+---
+
+## 2. MVP Scope
+
+Must-priority items confirmed for the first release:
+
+### Functional Requirements (Must)
+{List of Must FR from SRS with one-line description each}
+
+### User Stories (Must)
+{List of Must US with Epic grouping}
+
+---
+
+## 3. Traceability Coverage
+
+| Chain | Coverage |
+|-------|---------|
+| FR → US | {n}% ({uncovered} uncovered) |
+| US → UC | {n}% |
+| US → AC | {n}% |
+| FR → NFR | {n}% |
+| Entity → FR/US | {n}% |
+| Endpoint → FR/US | {n}% |
+| WF → US | {n}% |
+
+{If coverage is below 100% for any CRITICAL chain, list uncovered items explicitly.}
+
+---
+
+## 4. Open Items
+
+{If 00_analyze_{slug}.md or open findings from /validate exist:}
+
+| ID | Severity | Location | Summary |
+|----|----------|----------|---------|
+| {A1} | CRITICAL | {location} | {summary} |
+
+{If no open items:} No open CRITICAL or HIGH findings. Pipeline is ready for handoff.
+
+---
+
+## 5. Top Risks
+
+{Consolidated from 01_brief risks + any gaps identified during the pipeline:}
+
+| # | Risk | Impact | Source |
+|---|------|--------|--------|
+| 1 | {risk description} | {High/Medium/Low} | Brief / Analysis |
+
+---
+
+## 6. Recommended Next Steps
+
+1. **Resolve open items** — address any CRITICAL findings listed in section 4 before development begins.
+2. **Development environment** — use `07a_research_{slug}.md` (if present) for tech stack decisions and `07_datadict_{slug}.md` for schema initialisation.
+3. **Task breakdown** — import Must-priority US from section 2 into your backlog tool (Jira, Linear, GitHub Issues).
+4. **Spec-driven implementation** — consider using [Spec Kit](https://github.com/github/spec-kit) with `/speckit.specify` to generate implementation tasks from this handoff.
+5. **Validation** — use `10_scenarios_{slug}.md` (if present) for end-to-end acceptance testing scenarios.
+
+---
+
+## 7. Artifact Files Reference
+
+All files are located in: `{output_directory}`
+
+```
+{file tree of all generated artifacts}
+```
+```
+
+## Iterative refinement
+
+- `/revise [section]` — update a section.
+- `/analyze` — run quality analysis before finalising.
+- `/trace` — rebuild traceability matrix before finalising.
+
+## Closing message
+
+After saving the artifact, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Pipeline completion percentage.
+- Count of open CRITICAL/HIGH items.
+- Whether the package is ready for handoff or has blockers.
+
+Available commands: `/revise [section]` · `/analyze` · `/trace`
+
+Pipeline complete. This document is the development handoff package.
+
+## Style
+
+Formal, neutral. No emoji in the saved file. Generate in the artifact language. English for IDs, file names, table column headers, and code.

package/skills/nfr/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: ba-nfr
+description: >
+  Generate Non-functional Requirements (NFR): performance, security, availability, scalability, compliance, localization. Use on /nfr command, or when the user asks for "non-functional requirements", "NFR", "performance requirements", "security requirements", "SLA", "compliance requirements", "load requirements", "uptime requirements", "regulatory requirements", "GDPR". Sixth step of the BA Toolkit pipeline.
+---
+
+# /nfr — Non-functional Requirements
+
+Sixth step of the BA Toolkit pipeline. Generates NFR with measurable metrics.
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it and apply its conventions (artifact language, ID format, traceability requirements, Definition of Ready, quality gate threshold). Pay special attention to section 5 (NFR Baseline) — all listed categories are mandatory for this project.
+1. Read `01_brief_*.md`, `02_srs_*.md`, `03_stories_*.md`. SRS is the minimum requirement.
+2. Extract: slug, domain, integrations, roles, FR list.
+3. If domain supported, load `references/domains/{domain}.md`, section `6. /nfr`. Use mandatory NFR categories for the domain.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory for the current platform. If the file is unavailable, apply the default rule: if `/mnt/user-data/outputs/` exists and is writable, save there (Claude.ai); otherwise save to the current working directory.
+
+## Interview
+
+3–7 questions per round, 2–4 rounds.
+
+**Required topics:**
+1. Performance — target CCU (Concurrent Users), RPS (Requests Per Second), acceptable response time?
+2. Availability — required SLA? Acceptable downtime? Maintenance windows?
+3. Security — encryption, authentication, access audit?
+4. Compliance — applicable standards and laws? Data retention?
+5. Scalability — expected growth, horizontal scaling?
+6. Compatibility — browsers, OS, devices?
+
+Supplement with domain-specific questions and mandatory categories from the reference.
+
+## Generation
+
+**File:** `06_nfr_{slug}.md`
+
+```markdown
+# Non-functional Requirements: {Name}
+
+## NFR-{NNN}: {Category} — {Short Description}
+- **Category:** {performance | security | availability | scalability | compatibility | localization | compliance | audit | ...}
+- **Description:** {detailed description}
+- **Metric:** {measurable criterion}
+- **Verification Method:** {how it will be tested}
+- **Priority:** {Must | Should | Could | Won't}
+- **Linked FR/US:** {references}
+```
+
+**Rules:**
+- Numbering: NFR-001, NFR-002, ...
+- Every NFR must have a measurable metric. Avoid "the system should be fast."
+- Group by category.
+- Domain-specific mandatory categories from the reference.
+
+## Back-reference update
+
+After generation, update section 5 of `02_srs_{slug}.md` with links to specific NFR-{NNN}.
+
+## Iterative refinement
+
+- `/revise [NFR-NNN]` — rewrite.
+- `/expand [category]` — add NFR.
+- `/clarify [focus]` — targeted ambiguity pass (especially useful for surfacing NFR without measurable metrics).
+- `/validate` — mandatory categories covered; every NFR has a metric; links correct.
+- `/done` — finalize. Next step: `/datadict`.
+
+## Closing message
+
+After saving the artifact, present the following summary to the user (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Total number of NFR generated, grouped by category.
+- Confirmation that section 5 of `02_srs_{slug}.md` was updated with NFR links.
+- Any categories flagged as missing or lacking measurable metrics.
+
+Available commands: `/clarify [focus]` · `/revise [NFR-NNN]` · `/expand [category]` · `/validate` · `/done`
+
+Next step: `/datadict`
+
+## Style
+
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request.