@softspark/ai-toolkit 1.0.0

package/app/skills/pr/scripts/pr-summary.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Generate a structured PR summary from the git log.
+
+Parses commits between a base branch and HEAD using the Conventional
+Commits format, groups them by type, detects breaking changes, counts
+file and test statistics, and suggests a PR title. Outputs a JSON
+object suitable for populating a PR template.
+
+Usage::
+
+    python3 pr-summary.py [base_branch]
+    # Default base branch: main
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from typing import Any
+
+
+CONVENTIONAL_TYPES: dict[str, str] = {
+    "feat": "Features",
+    "fix": "Bug Fixes",
+    "docs": "Documentation",
+    "style": "Style",
+    "refactor": "Refactoring",
+    "perf": "Performance",
+    "test": "Tests",
+    "build": "Build",
+    "ci": "CI/CD",
+    "chore": "Chores",
+    "revert": "Reverts",
+}
+
+
+def run(cmd: str) -> str:
+    """Run a shell command and return stripped stdout.
+
+    Args:
+        cmd: Shell command string to execute.
+
+    Returns:
+        Stripped standard output of the command.
+    """
+    r = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+    return r.stdout.strip()
+
+
+def parse_conventional_commit(message: str) -> dict[str, Any]:
+    """Parse a conventional commit message into type, scope, and description.
+
+    Args:
+        message: Single-line commit message.
+
+    Returns:
+        Dictionary with ``type``, ``scope``, ``breaking``, and
+        ``description`` keys.
+    """
+    m = re.match(
+        r"^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.+)$", message
+    )
+    if m:
+        return {
+            "type": m.group(1),
+            "scope": m.group(2) or "",
+            "breaking": bool(m.group(3)),
+            "description": m.group(4),
+        }
+    return {"type": "other", "scope": "", "breaking": False, "description": message}
+
+
+def main() -> None:
+    """Entry point: generate PR summary and print JSON to stdout."""
+    base = sys.argv[1] if len(sys.argv) > 1 else "main"
+
+    # Get oneline log
+    log_output = run(f"git log --oneline {base}..HEAD 2>/dev/null")
+    if not log_output:
+        print(json.dumps({"error": f"No commits found between {base} and HEAD."}))
+        return
+
+    # Parse commits
+    commits: list[dict[str, Any]] = []
+    for line in log_output.split("\n"):
+        if not line.strip():
+            continue
+        parts = line.split(" ", 1)
+        if len(parts) < 2:
+            continue
+        sha = parts[0]
+        message = parts[1]
+        parsed = parse_conventional_commit(message)
+        commits.append({"sha": sha, "message": message, **parsed})
+
+    # Check full commit bodies for BREAKING CHANGE
+    body_output = run(f"git log --format='%B---COMMIT_SEP---' {base}..HEAD 2>/dev/null")
+    breaking_changes: list[str] = []
+    for block in (body_output or "").split("---COMMIT_SEP---"):
+        for bline in block.strip().split("\n"):
+            if bline.startswith("BREAKING CHANGE:") or bline.startswith("BREAKING-CHANGE:"):
+                breaking_changes.append(bline.split(":", 1)[1].strip())
+    # Also check for ! in commit type
+    for c in commits:
+        if c["breaking"] and c["description"] not in breaking_changes:
+            breaking_changes.append(c["description"])
+
+    # Group by type
+    groups: dict[str, list[str]] = {}
+    for c in commits:
+        label = CONVENTIONAL_TYPES.get(c["type"], "Other")
+        groups.setdefault(label, []).append(c["description"])
+
+    # Summary bullets
+    summary_bullets: list[str] = []
+    for label, descriptions in groups.items():
+        if len(descriptions) == 1:
+            summary_bullets.append(f"{label}: {descriptions[0]}")
+        else:
+            summary_bullets.append(f"{label}: {len(descriptions)} changes")
+
+    # File stats
+    diff_stat = run(f"git diff --stat {base}...HEAD 2>/dev/null")
+    files_changed = 0
+    test_files = 0
+    stat_lines = diff_stat.split("\n") if diff_stat else []
+    for sl in stat_lines:
+        sl = sl.strip()
+        if "|" in sl:
+            files_changed += 1
+            fname = sl.split("|")[0].strip()
+            if re.search(r"(test_|_test\.|\.test\.|spec\.|__tests__)", fname, re.IGNORECASE):
+                test_files += 1
+
+    # Suggest title from most common type + scope
+    type_counts: dict[str, int] = {}
+    scope_counts: dict[str, int] = {}
+    for c in commits:
+        type_counts[c["type"]] = type_counts.get(c["type"], 0) + 1
+        if c["scope"]:
+            scope_counts[c["scope"]] = scope_counts.get(c["scope"], 0) + 1
+
+    dominant_type = max(type_counts, key=type_counts.get) if type_counts else "feat"
+    dominant_scope = max(scope_counts, key=scope_counts.get) if scope_counts else ""
+
+    if len(commits) == 1:
+        title_suggestion = commits[0]["message"]
+    else:
+        scope_part = f"({dominant_scope})" if dominant_scope else ""
+        # Use the description of the first commit of dominant type as hint
+        dominant_descs = [c["description"] for c in commits if c["type"] == dominant_type]
+        brief = dominant_descs[0] if dominant_descs else "multiple changes"
+        if len(brief) > 50:
+            brief = brief[:47] + "..."
+        title_suggestion = f"{dominant_type}{scope_part}: {brief}"
+
+    result: dict[str, Any] = {
+        "base": base,
+        "total_commits": len(commits),
+        "title_suggestion": title_suggestion,
+        "commits": commits,
+        "groups": groups,
+        "summary_bullets": summary_bullets,
+        "has_breaking": len(breaking_changes) > 0,
+        "breaking_changes": breaking_changes,
+        "files_changed": files_changed,
+        "test_files_changed": test_files,
+        "has_tests": test_files > 0,
+    }
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/app/skills/prd-to-issues/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: prd-to-issues
+description: "Break a PRD into independently-grabbable GitHub issues using vertical slices with HITL/AFK tagging and dependency ordering. Use when user wants to convert a PRD to issues, create tickets, or break down a PRD into work items."
+effort: medium
+disable-model-invocation: true
+argument-hint: "[PRD issue number]"
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# PRD to Issues
+
+$ARGUMENTS
+
+Break a PRD into independently-grabbable GitHub issues using vertical slices (tracer bullets).
+
+## Usage
+
+```
+/prd-to-issues [PRD issue number]
+```
+
+## What This Command Does
+
+1. **Fetches** PRD from GitHub issue
+2. **Explores** codebase for context
+3. **Drafts** vertical slices with HITL/AFK classification
+4. **Quizzes** user on breakdown
+5. **Creates** GitHub issues in dependency order via `gh issue create`
+
+## Process
+
+### 1. Locate the PRD
+
+Fetch with `gh issue view <number>` (with comments). If no number provided, ask.
+
+### 2. Draft Vertical Slices
+
+Each issue is a thin vertical slice cutting through ALL layers end-to-end.
+
+| Classification | Description |
+|---------------|-------------|
+| **AFK** | Can be implemented and merged without human interaction (prefer) |
+| **HITL** | Requires human decision — architectural choice, design review, etc. |
+
+### 3. Quiz the User
+
+Present as numbered list. For each slice show:
+
+- **Title**: short descriptive name
+- **Type**: HITL / AFK
+- **Blocked by**: which other slices must complete first
+- **User stories covered**: which stories from the PRD
+
+Ask:
+- Granularity right? (too coarse / too fine)
+- Dependency relationships correct?
+- HITL vs AFK classification correct?
+- Any slices to merge or split?
+
+Iterate until approved.
+
+### 4. Create GitHub Issues
+
+Create in dependency order (blockers first) so real issue numbers can be referenced.
+
+Use `gh issue create` with the template below for each slice.
+
+## Issue Template
+
+<issue-template>
+
+## Parent PRD
+
+#{prd-issue-number}
+
+## What to build
+
+Concise description of this vertical slice. End-to-end behavior, not layer-by-layer. Reference parent PRD sections, don't duplicate.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- Blocked by #{issue-number} (if any)
+
+Or "None — can start immediately" if no blockers.
+
+## User stories addressed
+
+Reference by number from the parent PRD:
+
+- User story 3
+- User story 7
+
+</issue-template>
+
+## Rules
+
+- Every issue must be a VERTICAL slice — never horizontal
+- Create in dependency order for real issue number references
+- Do NOT close or modify the parent PRD issue
+- Do NOT ask user to review before creating — file and share URLs
+- Maximize parallelism — independent issues should have no blockers
+- No file paths or line numbers in issue bodies

package/app/skills/prd-to-plan/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: prd-to-plan
+description: "Convert a PRD into a phased implementation plan using tracer-bullet vertical slices. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions tracer bullets."
+user-invocable: true
+effort: high
+argument-hint: "[PRD issue number or paste PRD]"
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# PRD to Plan
+
+$ARGUMENTS
+
+Break a PRD into a phased implementation plan using vertical slices (tracer bullets). Output is a Markdown file in `./plans/`.
+
+## Usage
+
+```
+/prd-to-plan [PRD issue number or description]
+```
+
+## What This Command Does
+
+1. **Loads** the PRD (from GitHub issue or conversation)
+2. **Explores** the codebase to understand architecture
+3. **Identifies** durable architectural decisions
+4. **Drafts** vertical slices (tracer bullets)
+5. **Quizzes** user on granularity
+6. **Writes** plan file to `./plans/`
+
+## Process
+
+### 1. Confirm PRD is in Context
+
+If not provided, ask for the PRD GitHub issue number or content. Fetch with `gh issue view <number>` if needed.
+
+### 2. Explore the Codebase
+
+Use Agent (subagent_type=Explore) to understand current architecture, existing patterns, and integration layers.
+
+### 3. Identify Durable Architectural Decisions
+
+Before slicing, identify decisions unlikely to change:
+- Route structures / URL patterns
+- Database schema shape
+- Key data models
+- Authentication / authorization approach
+- Third-party service boundaries
+
+### 4. Draft Vertical Slices
+
+Break PRD into **tracer bullet** phases. Each phase is a thin vertical slice cutting through ALL layers end-to-end.
+
+| Rule | Description |
+|------|-------------|
+| Complete path | Each slice delivers narrow but COMPLETE path through every layer (schema, API, UI, tests) |
+| Demoable | A completed slice is demoable or verifiable on its own |
+| Thin over thick | Prefer many thin slices over few thick ones |
+| Durable | Do NOT include file names, function names, or implementation details likely to change |
+| Include decisions | DO include durable decisions: route paths, schema shapes, data model names |
+
+### 5. Quiz the User
+
+Present breakdown as numbered list. For each phase show:
+- **Title**: short descriptive name
+- **User stories covered**: which stories from the PRD
+
+Ask:
+- Does the granularity feel right? (too coarse / too fine)
+- Should any phases be merged or split?
+
+Iterate until approved.
+
+### 6. Write Plan File
+
+Create `./plans/` if needed. Write as `./plans/{feature-name}.md`.
+
+## Plan Template
+
+```markdown
+# Plan: {Feature Name}
+
+> Source PRD: #{issue-number}
+
+## Architectural Decisions
+
+Durable decisions that apply across all phases:
+
+- **Routes**: ...
+- **Schema**: ...
+- **Key models**: ...
+
+---
+
+## Phase 1: {Title}
+
+**User stories**: {list from PRD}
+
+### What to build
+
+Concise description of this vertical slice. End-to-end behavior, not layer-by-layer.
+
+### Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+---
+
+## Phase 2: {Title}
+
+(repeat for each phase)
+```
+
+## Rules
+
+- Every phase must be a VERTICAL slice (all layers), never HORIZONTAL (one layer)
+- No file paths or implementation details that couple to current code
+- Each phase must be independently demoable
+- Get user approval before writing the plan file

package/app/skills/predict/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: predict
+description: "Predict regressions and impact before changes land"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[change description]"
+agent: predictive-analyst
+context: fork
+allowed-tools: Read, Grep, Glob
+---
+
+# Predict Command
+
+$ARGUMENTS
+
+Triggers the Predictive Analyst to assess impact.
+
+## Usage
+
+```bash
+/predict [path_or_diff]
+# Example: /predict src/auth
+# Example: /predict --diff (analyzes uncommitted changes)
+```
+
+## Protocol
+1. **Scope**: Identify target files.
+2. **Trace**: Build dependency graph.
+3. **Assess**: Calculate risk score.
+4. **Report**: Generate Impact Prediction.

package/app/skills/qa-session/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: qa-session
+description: "Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session."
+user-invocable: true
+effort: high
+argument-hint: "[area to QA or first bug report]"
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# QA Session
+
+$ARGUMENTS
+
+Interactive QA session. User describes problems, agent clarifies, explores codebase, and files GitHub issues.
+
+## Usage
+
+```
+/qa-session [area to QA or first bug report]
+```
+
+## What This Command Does
+
+1. **Listens** to user's bug report
+2. **Clarifies** with 2-3 focused questions max
+3. **Explores** codebase in background for context and domain language
+4. **Assesses** scope — single issue or breakdown
+5. **Files** GitHub issues via `gh issue create`
+6. **Continues** until user says done
+
+## For Each Issue
+
+### 1. Listen and Lightly Clarify
+
+Let user describe the problem. Ask **at most 2-3 short questions** on:
+- Expected vs actual behavior
+- Steps to reproduce
+- Consistent or intermittent
+
+Don't over-interview. If clear enough, move on.
+
+### 2. Explore Codebase in Background
+
+Kick off Agent (subagent_type=Explore) in background to:
+- Learn domain language (check UBIQUITOUS_LANGUAGE.md)
+- Understand what the feature should do
+- Identify behavior boundaries
+
+This helps write better issues — but issues must NOT reference files/lines.
+
+### 3. Assess Scope
+
+| Decision | When |
+|----------|------|
+| **Single issue** | One behavior wrong in one place |
+| **Breakdown** | Multiple independent areas, separable concerns, distinct failure modes |
+
+### 4. File GitHub Issues
+
+Use `gh issue create`. Do NOT ask to review — file and share URLs.
+
+**Single issue template:**
+
+```
+## What happened
+[Actual behavior in plain language]
+
+## What I expected
+[Expected behavior]
+
+## Steps to reproduce
+1. [Concrete numbered steps]
+2. [Use domain terms, not module names]
+
+## Additional context
+[Extra observations using domain language]
+```
+
+**Breakdown template** (for each sub-issue):
+
+```
+## Parent issue
+#{parent-issue-number} or "Reported during QA session"
+
+## What's wrong
+[This specific behavior problem]
+
+## What I expected
+[Expected behavior for this slice]
+
+## Steps to reproduce
+1. [Steps specific to THIS issue]
+
+## Blocked by
+- #{issue-number} or "None — can start immediately"
+```
+
+### 5. Continue Session
+
+After filing, share URLs and ask: "Next issue, or are we done?"
+
+## Rules
+
+- **No file paths or line numbers** in issues — they go stale
+- **Use project domain language** (check UBIQUITOUS_LANGUAGE.md)
+- **Describe behaviors, not code** — "sync service fails to apply patch" not "applyPatch() throws"
+- **Reproduction steps mandatory** — ask if you can't determine them
+- **Keep concise** — developer should read issue in 30 seconds
+- **Maximize parallelism** — independent issues have no blockers
+- **Create in dependency order** — blockers first for real issue numbers