@kudusov.takhir/ba-toolkit 1.2.0

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

@@ -0,0 +1,90 @@
+# Software Requirements Specification (SRS): [PROJECT_NAME]
+
+**Domain:** [DOMAIN]
+**Date:** [DATE]
+**Slug:** [SLUG]
+**Reference:** [01_brief_SLUG.md]
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+[What this document describes and who it is for.]
+
+### 1.2 Scope
+
+[System boundaries — what is in scope and what is explicitly out of scope.]
+
+### 1.3 Definitions and Abbreviations
+
+| Term | Definition |
+|------|-----------|
+| [term] | [definition] |
+
+### 1.4 Document References
+
+- Project Brief: `01_brief_[SLUG].md`
+
+## 2. General Description
+
+### 2.1 Product Context
+
+[How the system fits into the broader ecosystem — users, external systems, platform.]
+
+### 2.2 User Roles
+
+| Role | Description | Permissions |
+|------|-------------|------------|
+| [role] | [description] | [what they can do] |
+
+### 2.3 Constraints
+
+[Technical, legal, regulatory, and business constraints.]
+
+### 2.4 Assumptions and Dependencies
+
+[What is assumed to be true; what external systems or services are depended upon.]
+
+## 3. Functional Requirements
+
+### FR-001: [Title]
+
+- **Description:** [What the system must do.]
+- **Actor:** [Role that triggers or benefits from this requirement.]
+- **Input:** [What data or event initiates this.]
+- **Output / Result:** [What the system produces or changes.]
+- **Business Rules:** [Formulas, limits, conditions.]
+- **Priority:** Must | Should | Could | Won't
+
+<!-- Repeat for each FR. Numbering: FR-001, FR-002, ... -->
+
+## 4. Interface Requirements
+
+### 4.1 User Interfaces
+
+[Description of UI requirements at a system level — not screen layouts.]
+
+### 4.2 Software Interfaces (API)
+
+[External APIs the system must call or expose.]
+
+### 4.3 External System Interfaces
+
+[Integrations with third-party systems.]
+
+## 5. Non-functional Requirements
+
+_(Detailed in `/nfr` artifact — `06_nfr_[SLUG].md`)_
+
+| Category | Summary | NFR Reference |
+|----------|---------|---------------|
+| [category] | [brief description] | NFR-[NNN] |
+
+## 6. Priority Matrix (MoSCoW)
+
+| Priority | FR Count | FR IDs |
+|----------|---------|--------|
+| Must | [n] | FR-001, FR-002, … |
+| Should | [n] | … |
+| Could | [n] | … |
+| Won't | [n] | … |

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

@@ -0,0 +1,60 @@
+# User Stories: [PROJECT_NAME]
+
+**Domain:** [DOMAIN]
+**Date:** [DATE]
+**Slug:** [SLUG]
+**References:** `01_brief_[SLUG].md`, `02_srs_[SLUG].md`
+
+## Epic Index
+
+| # | Epic | User Stories |
+|---|------|-------------|
+| E-01 | [Epic name] | US-001 – US-00N |
+
+---
+
+## E-01: [Epic Name]
+
+> [One-sentence description of the epic's goal.]
+
+### US-001: [Story title]
+
+**As a** [role],
+**I want to** [action],
+**so that** [benefit].
+
+**Acceptance Criteria:** → `05_ac_[SLUG].md` → US-001
+**FR Reference:** FR-[NNN]
+**Priority:** Must | Should | Could | Won't
+**Size:** XS | S | M | L | XL
+**Notes:** [Edge cases, out-of-scope clarifications.]
+
+---
+
+### US-002: [Story title]
+
+**As a** [role],
+**I want to** [action],
+**so that** [benefit].
+
+**Acceptance Criteria:** → `05_ac_[SLUG].md` → US-002
+**FR Reference:** FR-[NNN]
+**Priority:** Must | Should | Could | Won't
+**Size:** XS | S | M | L | XL
+**Notes:** [Edge cases, out-of-scope clarifications.]
+
+<!-- Repeat US block for each story. Numbering: US-001, US-002, ... -->
+
+---
+
+## Coverage Summary
+
+| Priority | Story Count | Story IDs |
+|----------|------------|-----------|
+| Must     | [n] | US-001, … |
+| Should   | [n] | … |
+| Could    | [n] | … |
+| Won't    | [n] | … |
+
+**Total stories:** [N]
+**Total epics:** [N]

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

@@ -0,0 +1,59 @@
+# Traceability Matrix: [PROJECT_NAME]
+
+**Domain:** [DOMAIN]
+**Date:** [DATE]
+**Slug:** [SLUG]
+**References:** All artifacts `01_brief_[SLUG].md` → `10_scenarios_[SLUG].md`
+
+---
+
+## Forward Traceability: FR → Downstream Artifacts
+
+| FR | Title | US | UC | AC | NFR | Entity | ADR | API | WF | SC |
+|----|-------|----|----|----|-----|--------|-----|-----|----|----|
+| FR-001 | [Title] | US-[NNN] | UC-[NNN] | US-[NNN] S[N] | NFR-[NNN] | [Entity] | ADR-[NNN] | `POST /[ep]` | WF-[NNN] | SC-[NNN] |
+| FR-002 | [Title] | US-[NNN] | — | US-[NNN] S[N] | — | [Entity] | — | `GET /[ep]` | WF-[NNN] | — |
+
+_Legend: `—` = not applicable or not yet linked_
+
+---
+
+## Reverse Traceability: User Stories → FR
+
+| US | Title | FR | Priority |
+|----|-------|----|---------|
+| US-001 | [Title] | FR-[NNN] | Must |
+
+---
+
+## Coverage Gaps
+
+| Artifact | Orphaned Items | Note |
+|---------|---------------|------|
+| FR | FR-[NNN] | No US linked |
+| US | US-[NNN] | No AC defined |
+| UC | UC-[NNN] | No FR reference |
+| NFR | NFR-[NNN] | No FR or US linked |
+
+---
+
+## Coverage Statistics
+
+| Artifact | Total | Linked | Coverage % |
+|---------|-------|--------|-----------|
+| Functional Requirements | [N] | [N] | [N]% |
+| User Stories | [N] | [N] | [N]% |
+| Use Cases | [N] | [N] | [N]% |
+| Acceptance Criteria (scenarios) | [N] | [N] | [N]% |
+| NFR items | [N] | [N] | [N]% |
+| API Endpoints | [N] | [N] | [N]% |
+| Wireframe Screens | [N] | [N] | [N]% |
+
+**Overall traceability score:** [N]%
+
+---
+
+## Recommended Actions
+
+1. [Action to close gap — e.g. "Add AC for US-NNN"]
+2. [Action — e.g. "Link FR-NNN to an API endpoint"]

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

@@ -0,0 +1,51 @@
+# Use Cases: [PROJECT_NAME]
+
+**Domain:** [DOMAIN]
+**Date:** [DATE]
+**Slug:** [SLUG]
+**References:** `01_brief_[SLUG].md`, `02_srs_[SLUG].md`, `03_stories_[SLUG].md`
+
+## Use Case Index
+
+| ID | Title | Primary Actor | Linked Stories |
+|----|-------|--------------|---------------|
+| UC-001 | [Title] | [Actor] | US-[NNN] |
+
+---
+
+## UC-001: [Use Case Title]
+
+**ID:** UC-001
+**Primary Actor:** [Role]
+**Supporting Actors:** [Other roles or external systems]
+**Trigger:** [What event or action initiates this use case]
+**Pre-conditions:**
+- [Condition that must be true before the use case starts]
+
+**Post-conditions (Success):**
+- [System state after successful completion]
+
+**Post-conditions (Failure):**
+- [System state after failure or cancellation]
+
+### Main Success Scenario
+
+| Step | Actor | Action / System Response |
+|------|-------|--------------------------|
+| 1 | [Actor] | [Does something] |
+| 2 | System | [Responds with something] |
+| 3 | [Actor] | [Continues] |
+
+### Alternative Flows
+
+**Alt 1 — [Name]:** At step [N], if [condition], then [action]. Resume at step [M].
+
+### Exception Flows
+
+**Exc 1 — [Name]:** At step [N], if [error condition], then [system response and outcome].
+
+**Linked Stories:** US-[NNN], US-[NNN]
+**Linked FR:** FR-[NNN]
+**Linked Wireframe:** WF-[NNN]
+
+<!-- Repeat UC block for each use case. Numbering: UC-001, UC-002, ... -->

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

@@ -0,0 +1,96 @@
+# Wireframe Descriptions: [PROJECT_NAME]
+
+**Domain:** [DOMAIN]
+**Date:** [DATE]
+**Slug:** [SLUG]
+**References:** `03_stories_[SLUG].md`, `04_usecases_[SLUG].md`, `05_ac_[SLUG].md`
+
+> These are textual wireframe descriptions, not visual diagrams. Each screen is described with sufficient detail for a designer to produce a high-fidelity mockup.
+
+---
+
+## Screen Index
+
+| ID | Screen Name | Platform | Linked Stories |
+|----|------------|----------|---------------|
+| WF-001 | [Screen name] | Web / iOS / Android / All | US-[NNN] |
+
+---
+
+## WF-001: [Screen Name]
+
+**Platform:** Web | iOS | Android | All
+**Route / Deep link:** `[/path or app://screen]`
+**Entry points:** [Where the user comes from — e.g. Home → tap "Browse"]
+**Linked Stories:** US-[NNN], US-[NNN]
+**Linked UC:** UC-[NNN]
+
+### Layout
+
+**Header / Navigation:**
+[Describe top bar — back button, title, right-side actions.]
+
+**Body:**
+[Describe the main content area top to bottom. Mention each UI element: headings, lists, cards, images, form fields, buttons, empty states.]
+
+**Footer / Bottom navigation:**
+[Describe persistent navigation or action bar if present.]
+
+### States
+
+| State | Description |
+|-------|-------------|
+| Loading | [Skeleton screen / spinner / progress bar] |
+| Empty | [Empty state message and CTA] |
+| Error | [Error message and recovery action] |
+| [Feature state] | [Description, e.g. "item added to cart — badge updates"] |
+
+### Interactions
+
+| Trigger | Action |
+|---------|--------|
+| Tap [element] | [Navigation or action] |
+| Scroll to bottom | [Pagination load / sticky header behaviour] |
+| [Other gesture] | [Result] |
+
+### Design Notes
+
+- [Specific UX note, e.g. "Confirmation dialog before destructive action"]
+- [Accessibility note, e.g. "Form labels must be visible, not only placeholder text"]
+
+---
+
+## WF-002: [Screen Name]
+
+**Platform:** Web | iOS | Android | All
+**Route / Deep link:** `[/path]`
+**Entry points:** [Entry points]
+**Linked Stories:** US-[NNN]
+
+### Layout
+
+**Header / Navigation:** [Description]
+
+**Body:** [Description]
+
+**Footer:** [Description]
+
+### States
+
+| State | Description |
+|-------|-------------|
+| Loading | [Description] |
+| Empty | [Description] |
+| Error | [Description] |
+
+### Interactions
+
+| Trigger | Action |
+|---------|--------|
+| [Trigger] | [Action] |
+
+### Design Notes
+
+- [Note]
+
+<!-- Repeat WF block for each screen. Numbering: WF-001, WF-002, ... -->

package/skills/research/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ba-research
+description: >
+  Generate a technology and constraints research document before committing to API and data design. Covers integration options, API style choices, data storage alternatives, regulatory constraints, and ADR (Architecture Decision Records) with rationale. Use on /research command, or when the user asks for "technology research", "tech decisions", "architecture options", "integration research", "compare options", "what stack to use", "ADR", "architecture decision", "research constraints". Optional step — run after /datadict and before /apicontract.
+---
+
+# /research — Technology Research and Constraints
+
+Optional step between `/datadict` and `/apicontract`. Documents technology decisions, integration options, and architectural constraints before the API contract is committed. Generates Architecture Decision Records (ADR) with rationale for each key choice.
+
+Running this step prevents "beautiful but impractical" API contracts by surfacing constraints early.
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it and apply its conventions.
+1. Read `01_brief_*.md`, `02_srs_*.md`, `07_datadict_*.md`. SRS and Data Dictionary are required.
+2. Extract: domain, integrations listed in SRS, regulatory requirements, entities and their relationships from the Data Dictionary, non-functional requirements (if `06_nfr_*.md` exists).
+3. If domain is supported, load `references/domains/{domain}.md` for domain-typical integration patterns.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Interview
+
+1–2 rounds, 4–6 questions.
+
+**Required topics:**
+1. Existing infrastructure — is there a current backend, database, or API the new system must integrate with or extend?
+2. API style preference — REST, GraphQL, gRPC, or a combination? Any existing API gateway or BFF?
+3. Real-time requirements — do any user stories require live updates (WebSocket, SSE, polling)?
+4. Third-party integrations — which external services are confirmed (payment gateway, auth provider, analytics, CDN)?
+5. Data storage constraints — any vendor lock-in restrictions, cloud provider preferences, on-premise requirements?
+6. Compliance constraints — any restrictions on where data can be stored (jurisdiction, residency)?
+
+Supplement with domain-specific typical integrations from the reference.
+
+## Generation
+
+**File:** `07a_research_{slug}.md`
+
+```markdown
+# Technology Research: {Project Name}
+
+**Date:** {date}
+**Scope:** Decisions informing /apicontract and /datadict
+
+---
+
+## 1. Context Summary
+
+Brief summary of the system from the brief and SRS: what it does, who uses it, key integrations, and non-functional constraints relevant to technical decisions.
+
+## 2. Architecture Decision Records (ADR)
+
+### ADR-001: {Decision Title}
+
+| | |
+|--|--|
+| **Status** | Accepted |
+| **Date** | {date} |
+| **Linked FR/NFR** | {references} |
+
+**Context:** {Why this decision is needed — the problem being solved.}
+
+**Options considered:**
+
+| Option | Pros | Cons |
+|--------|------|------|
+| {Option A} | {pros} | {cons} |
+| {Option B} | {pros} | {cons} |
+
+**Decision:** {Chosen option and rationale.}
+
+**Consequences:** {What becomes easier or harder as a result.}
+
+---
+
+_(Repeat ADR block for each key decision.)_
+
+## 3. Integration Map
+
+| System | Type | Direction | Protocol | Auth | Notes |
+|--------|------|-----------|----------|------|-------|
+| {Name} | {internal/external} | {in/out/bidirectional} | {REST/WS/…} | {JWT/API Key/…} | {notes} |
+
+## 4. Data Storage Decisions
+
+| Entity group | Storage type | Rationale |
+|--------------|-------------|-----------|
+| {e.g., Transactional data} | {e.g., PostgreSQL} | {reason} |
+| {e.g., Session data} | {e.g., Redis} | {reason} |
+
+## 5. Real-time Strategy
+
+{Describe approach for any real-time requirements: WebSocket, SSE, polling interval, or none. Reference the US/FR that require it.}
+
+## 6. Regulatory and Compliance Constraints
+
+{List constraints affecting API design: data residency, PII handling, audit log requirements, encryption standards. Cross-reference NFR where applicable.}
+
+## 7. Open Questions
+
+{Any decisions deferred or requiring external input before /apicontract can proceed.}
+```
+
+**Rules:**
+- ADR numbering: ADR-001, ADR-002, ...
+- Every ADR must include at least two options compared.
+- Decisions must reference FR or NFR that drove the choice.
+- Open Questions section is mandatory — even if empty (write "None").
+
+## Iterative refinement
+
+- `/revise [ADR-NNN]` — update a decision.
+- `/expand [ADR-NNN]` — add more options or consequences.
+- `/clarify [focus]` — targeted ambiguity pass.
+- `/validate` — all integrations from SRS covered; every ADR has a decision; no open questions without an owner.
+- `/done` — finalize. Next step: `/apicontract`.
+
+## Closing message
+
+After saving the artifact, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Total number of ADRs documented.
+- Number of confirmed external integrations.
+- Any open questions that must be resolved before `/apicontract`.
+
+Available commands: `/clarify [focus]` · `/revise [ADR-NNN]` · `/expand [ADR-NNN]` · `/validate` · `/done`
+
+Next step: `/apicontract`
+
+## Style
+
+Formal, neutral. No emoji, slang. Generate in the artifact language. Technical terms (ADR, REST, WebSocket, JWT) remain in English. Architecture option names remain in English.

package/skills/risk/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: ba-risk
+description: >
+  Dedicated risk register for BA Toolkit projects. Use on /risk command, or when the user asks to "identify risks", "create a risk register", "assess project risks", "list risks", "risk matrix". Cross-cutting command — can run at any pipeline stage once Brief or SRS exists. Re-run after Research to capture technical risks.
+---
+
+# /risk — Risk Register
+
+Cross-cutting command. Extracts risks from existing artifacts, classifies them by category, scores them by probability × impact, and produces or updates `00_risks_{slug}.md` with a full risk register.
+
+## Syntax
+
+```
+/risk [optional: action]
+```
+
+Examples:
+- `/risk` — build or refresh the full risk register
+- `/risk add [description]` — manually add a risk and score it interactively
+- `/risk update RISK-03` — update status or mitigation for a specific risk
+
+## Context loading
+
+0. If `00_principles_*.md` exists, load it — apply language convention (section 1) and ID naming convention (section 2).
+1. Load artifacts in order, extracting risk signals from each:
+   - `01_brief_{slug}.md` — Risks and Constraints sections (primary source)
+   - `02_srs_{slug}.md` — Assumptions, Constraints, out-of-scope items
+   - `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.
+3. If `00_risks_{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 — Risk extraction
+
+For each artifact, extract explicit and implicit risks:
+
+- **Explicit:** statements containing "risk", "concern", "unknown", "assumption", "dependency", "TBD", "to be confirmed", "may", "might", "could fail".
+- **Implicit:**
+  - NFR targets with no stated baseline → measurement risk.
+  - Third-party integrations with no documented SLA → dependency risk.
+  - Features marked out of scope that may be expected by stakeholders → scope creep risk.
+  - ADR alternatives rejected due to uncertainty → technical risk.
+
+### Step 2 — Classification
+
+Assign each risk to one category:
+
+| Category | Examples |
+|----------|---------|
+| **Technical** | Architecture unknowns, integration failures, performance uncertainty, security gaps |
+| **Business** | Market assumptions, stakeholder misalignment, budget or timeline pressure |
+| **Compliance** | Regulatory requirements, data privacy (GDPR, HIPAA), licensing constraints |
+| **External** | Third-party API availability, vendor lock-in, geopolitical or infrastructure factors |
+
+### Step 3 — Scoring
+
+Score each risk on two axes (1–5):
+
+| Score | Probability | Impact |
+|-------|------------|--------|
+| 1 | Very unlikely | Negligible — no effect on delivery |
+| 2 | Unlikely | Minor — small rework or delay |
+| 3 | Possible | Moderate — scope or timeline affected |
+| 4 | Likely | Major — milestone at risk |
+| 5 | Very likely | Critical — project viability threatened |
+
+**Risk Score = Probability × Impact** (range 1–25).
+
+Priority thresholds:
+- 🔴 **Critical:** score ≥ 15
+- 🟡 **High:** score 8–14
+- 🟢 **Medium:** score 4–7
+- ⚪ **Low:** score 1–3
+
+## Generation
+
+Save `00_risks_{slug}.md` to the output directory.
+
+```markdown
+# Risk Register: {PROJECT_NAME}
+
+**Domain:** {DOMAIN}
+**Date:** {DATE}
+**Slug:** {SLUG}
+**Sources:** {list of artifacts scanned}
+
+---
+
+## Summary
+
+| Priority | Count |
+|---------|-------|
+| 🔴 Critical | N |
+| 🟡 High | N |
+| 🟢 Medium | N |
+| ⚪ Low | N |
+| **Total** | **N** |
+
+---
+
+## Risk Register
+
+| ID | Title | Category | Probability | Impact | Score | Priority | Status |
+|----|-------|----------|:-----------:|:------:|:-----:|---------|--------|
+| RISK-01 | [Short title] | Technical | 4 | 5 | 20 | 🔴 Critical | Open |
+| RISK-02 | [Short title] | Business | 3 | 3 | 9 | 🟡 High | Open |
+
+---
+
+## Risk Details
+
+### RISK-01 — [Short title]
+
+**Category:** Technical
+**Probability:** 4 / 5 — Likely
+**Impact:** 5 / 5 — Critical
+**Score:** 20 🔴 Critical
+**Status:** Open
+**Source:** `07a_research_{slug}.md`
+
+**Description:**
+[Full description of the risk and the conditions under which it materialises.]
+
+**Mitigation:**
+[Steps to reduce the probability or impact before the risk occurs.]
+
+**Contingency:**
+[Steps to take if the risk materialises despite mitigation.]
+
+**Owner:** [Role responsible — e.g., Tech Lead, Product Manager]
+```
+
+Risks are sorted by Score descending within each section. IDs are sequential (RISK-01, RISK-02, …) assigned in order of discovery, not severity.
+
+### Merge behaviour
+
+If `00_risks_{slug}.md` already exists:
+- Preserve existing risks, their IDs, and manually set statuses.
+- Add new risks found since last run with new sequential IDs.
+- Re-score existing risks only if new information changes the assessment; note the change.
+- Update the Sources and Date fields.
+
+## Closing message
+
+After saving, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file: `00_risks_{slug}.md`
+- Total risks identified: N (N critical, N high, N medium, N low).
+- Top 2–3 critical or high risks by name.
+- If any risks have no mitigation defined: flag them for `/risk update`.
+
+Available commands: `/risk add [description]` · `/risk update RISK-NN` · `/clarify [artifact]` · `/analyze`
+
+## Style
+
+Concise, factual. Risk descriptions state the condition and consequence ("If X happens, then Y will occur"). Do not inflate severity — score based on evidence from artifacts, not speculation. Use the artifact language set in `00_principles_{slug}.md`.