@softspark/ai-toolkit 1.0.0

package/app/skills/performance-profiling/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: performance-profiling
+description: "Loaded when user asks about performance profiling or optimization"
+effort: medium
+allowed-tools: Bash, Grep
+user-invocable: false
+---
+
+# Performance Profiling Skill
+
+## Optimization Golden Rule
+**"Don't optimize without a baseline."**
+Always measure -> change -> measure.
+
+## Critical Metrics (The 4 Golden Signals)
+1. **Latency**: Time it takes to serve a request. (p50, p95, p99)
+2. **Traffic**: Demand on your system (req/sec).
+3. **Errors**: Rate of requests that fail.
+4. **Saturation**: How "full" your service is (CPU/Memory usage).
+
+## Profiling Tools & Techniques
+
+### Python
+- **CPU Sampling**: `py-spy`
+  ```bash
+  # Record flamegraph
+  py-spy record -o profile.svg --pid <pid>
+  ```
+- **Function Profiling**: `cProfile`
+  ```python
+  import cProfile
+  cProfile.run('main()')
+  ```
+
+### Node.js
+- **Flamegraphs**: `0x` or built-in profiler.
+  ```bash
+  node --prof app.js
+  node --prof-process isolate-0xnnnnn.log > processed.txt
+  ```
+- **Event Loop**: `clinic doctor`
+
+### Database (SQL)
+- **Explain Plan**: Analyze query cost.
+  ```sql
+  EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM users WHERE active = 1;
+  ```
+- **N+1 Problem**: Look for loop-generated queries.
+
+### Frontend (Browser)
+- **Lighthouse**: Core Web Vitals (LCP, CLS, INP).
+- **Chrome Performance Tab**: Main thread blocking time.
+- **Network Waterfall**: Time to First Byte (TTFB).
+
+## Optimization Hierarchy
+1. **Database/IO**: (Indexing, Caching, Batching) - *Biggest Gains*
+2. **Algorithm**: (O(n²) -> O(n log n))
+3. **Memory**: (Allocation churn, GC pressure)
+4. **Micro-optimization**: (Loop unrolling, etc.) - *Smallest Gains*

package/app/skills/plan/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: plan
+description: "Plan implementation with tasks and success criteria"
+user-invocable: true
+effort: high
+argument-hint: "[goal]"
+allowed-tools: Read, Grep, Glob
+---
+
+# Project Planning
+
+$ARGUMENTS
+
+Create a structured plan for a new project or feature.
+
+## Usage
+
+```
+/plan [description]
+```
+
+## What This Command Does
+
+1. **Analyzes** the request
+2. **Identifies** project type and tech stack
+3. **Breaks down** into tasks
+4. **Creates** plan file with agent assignments
+
+## Plan File Output
+
+Creates a `{project-slug}.md` file in project root:
+
+```markdown
+# {Project Name} - Implementation Plan
+
+## Overview
+- **Type**: [Web App / Mobile App / API / etc.]
+- **Stack**: [Tech choices]
+- **Complexity**: [Low / Medium / High]
+
+## Requirements
+1. [Requirement 1]
+2. [Requirement 2]
+
+## Task Breakdown
+
+### Phase 1: Foundation
+- [ ] Task 1 (Agent: backend-specialist)
+- [ ] Task 2 (Agent: database-architect)
+
+### Phase 2: Core Features
+- [ ] Task 3 (Agent: frontend-specialist)
+- [ ] Task 4 (Agent: backend-specialist)
+
+### Phase 3: Polish
+- [ ] Task 5 (Agent: test-engineer)
+- [ ] Task 6 (Agent: devops-implementer)
+
+## Agent Assignment
+
+| Task | Agent | Dependencies |
+|------|-------|--------------|
+| Database | database-architect | None |
+| API | backend-specialist | Database |
+| UI | frontend-specialist | API |
+| Tests | test-engineer | All above |
+
+## File Structure
+```
+project/
+├── src/
+└── ...
+```
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+## Project Type Detection
+
+| Keywords | Type | Primary Agents |
+|----------|------|----------------|
+| landing, website | Static Site | frontend-specialist |
+| dashboard, admin | Web App | frontend + backend |
+| api, rest | API Only | backend-specialist |
+| mobile, ios, android | Mobile | mobile-developer |
+| game, unity | Game | game-developer |
+
+## PLAN MODE RULES
+
+During planning:
+- Create plan documents
+- Define tasks and structure
+- NO code writing
+- NO file creation (except plan)
+
+## Next Steps
+
+After plan approval:
+1. Use `/orchestrate` to execute with agents
+2. Or manually invoke specific agents
+
+## KB Integration
+
+Before planning:
+```python
+smart_query("project template: {type}")
+hybrid_search_kb("architecture {pattern}")
+```

package/app/skills/plan/templates/plan-template.md

@@ -0,0 +1,40 @@
+# Implementation Plan: [Title]
+
+## Context
+[Why this change is needed — problem, trigger, intended outcome]
+
+## Success Criteria
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+- [ ] [Measurable outcome 3]
+
+## Pre-Mortem
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| [Risk 1] | Low/Med/High | Low/Med/High | [How to prevent/handle] |
+| [Risk 2] | Low/Med/High | Low/Med/High | [How to prevent/handle] |
+
+## Tasks
+
+### Phase 1: [Name]
+- [ ] Task 1 — [file(s) affected]
+- [ ] Task 2 — [file(s) affected]
+
+### Phase 2: [Name]
+- [ ] Task 3 — [file(s) affected]
+- [ ] Task 4 — [file(s) affected]
+
+## Dependencies
+```
+Phase 1 → Phase 2 → Phase 3
+```
+
+## Verification
+1. [How to test the changes end-to-end]
+2. [What commands to run]
+3. [What to check manually]
+
+## Agent Assignments
+| Task | Agent | Model |
+|------|-------|-------|
+| [Task] | [agent-name] | opus/sonnet |

package/app/skills/plan-writing/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: plan-writing
+description: "Loaded when user asks to write an implementation plan or pre-mortem"
+effort: medium
+user-invocable: false
+---
+
+# Plan Writing Skill
+
+## Plan Structure
+
+### Basic Plan Template
+
+```markdown
+# [Project Name] - Implementation Plan
+
+## Overview
+- **Type**: [Project type]
+- **Stack**: [Tech choices]
+- **Complexity**: [Low/Medium/High]
+- **Estimated Effort**: [Days/Weeks]
+
+## Goals
+1. [Primary goal]
+2. [Secondary goal]
+
+## Requirements
+
+### Functional
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR1 | [Requirement] | Must |
+| FR2 | [Requirement] | Should |
+
+### Non-Functional
+| ID | Requirement | Metric |
+|----|-------------|--------|
+| NFR1 | Performance | < 2s load |
+| NFR2 | Security | OWASP compliant |
+
+## Task Breakdown
+
+### Phase 1: Foundation
+- [ ] Task 1.1
+- [ ] Task 1.2
+
+### Phase 2: Core
+- [ ] Task 2.1
+- [ ] Task 2.2
+
+### Phase 3: Polish
+- [ ] Task 3.1
+- [ ] Task 3.2
+
+## Dependencies
+
+```mermaid
+graph TD
+    A[Database Schema] --> B[API Endpoints]
+    B --> C[UI Components]
+    C --> D[Tests]
+    D --> E[Deployment]
+```
+
+## Agent Assignment
+
+| Task | Agent | Dependencies |
+|------|-------|--------------|
+| Schema | database-architect | None |
+| API | backend-specialist | Schema |
+| UI | frontend-specialist | API |
+| Tests | test-engineer | UI |
+
+## Success Criteria
+- [ ] All tests passing
+- [ ] Performance targets met
+- [ ] Security review complete
+
+## Risks
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk] | High/Med/Low | High/Med/Low | [Plan] |
+```
+
+---
+
+## Task Breakdown Principles
+
+### SMART Tasks
+- **S**pecific: Clear deliverable
+- **M**easurable: Done/not done
+- **A**ssignable: One owner
+- **R**ealistic: Achievable
+- **T**ime-bound: Estimated duration
+
+### Good vs Bad Tasks
+
+| ❌ Bad | ✅ Good |
+|--------|--------|
+| "Implement authentication" | "Create login API endpoint with JWT" |
+| "Build UI" | "Create user dashboard component" |
+| "Fix bugs" | "Fix login redirect on mobile" |
+| "Optimize" | "Reduce API response time to <200ms" |
+
+---
+
+## Dependency Management
+
+### Dependency Types
+
+| Type | Example |
+|------|---------|
+| **Hard** | API must exist before UI can call it |
+| **Soft** | Tests can start when 50% features done |
+| **External** | Waiting for third-party API access |
+
+### Identifying Dependencies
+
+```
+For each task, ask:
+1. What must exist before this can start?
+2. What does this task produce?
+3. Who/what consumes that output?
+```
+
+---
+
+## Estimation Patterns
+
+### T-Shirt Sizing
+
+| Size | Effort | Example |
+|------|--------|---------|
+| XS | <2 hours | Fix typo, add field |
+| S | 2-4 hours | Simple component, basic API |
+| M | 1-2 days | Feature with tests |
+| L | 3-5 days | Complex feature |
+| XL | 1-2 weeks | Major subsystem |
+
+### Cone of Uncertainty
+
+| Phase | Accuracy |
+|-------|----------|
+| Initial idea | 4x variance |
+| After discovery | 2x variance |
+| After design | 1.5x variance |
+| After development | 1.1x variance |
+
+---
+
+## Phase Templates
+
+### MVP Launch
+
+```
+Phase 1: Core (Week 1-2)
+- Database schema
+- Authentication
+- Core feature 1
+
+Phase 2: Essential (Week 3-4)
+- Core feature 2
+- Basic UI
+- Critical integrations
+
+Phase 3: Launch (Week 5)
+- Testing
+- Deployment
+- Documentation
+```
+
+### Feature Addition
+
+```
+Phase 1: Preparation
+- Research existing code
+- Define acceptance criteria
+- Design solution
+
+Phase 2: Implementation
+- Backend changes
+- Frontend changes
+- Integration
+
+Phase 3: Validation
+- Testing
+- Code review
+- Deploy to staging
+```
+
+---
+
+## Review Checklist
+
+Before finalizing plan:
+- [ ] All requirements captured
+- [ ] Tasks are SMART
+- [ ] Dependencies identified
+- [ ] Agents assigned
+- [ ] Risks documented
+- [ ] Success criteria defined

package/app/skills/plugin-creator/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: plugin-creator
+description: "Creates experimental opt-in Claude Code plugin packs with manifests, conventions, and optional module scaffolding"
+effort: high
+disable-model-invocation: true
+argument-hint: "[plugin pack name or domain]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Plugin Creator
+
+$ARGUMENTS
+
+Create a new experimental opt-in Claude Code plugin pack following ai-toolkit conventions.
+
+## Workflow
+
+1. **Capture scope** -- what domain should the plugin pack own?
+2. **Pick packaging model** -- domain pack, policy pack, or hook/observability pack?
+3. **Define manifest** -- name, description, version, domain, compatibility, included assets
+4. **Select assets** -- agents, skills, rules, hooks, docs, templates
+5. **Add scaffolding** -- create `plugin.json`, `README.md`, and optional subdirectories
+6. **Validate** -- manifest JSON, included asset references, executable hooks, documentation links
+
+## Directory Layout
+
+```text
+app/plugins/<plugin-name>/
+├── plugin.json
+├── README.md
+├── agents/           # optional
+├── skills/           # optional
+├── hooks/            # optional
+├── rules/            # optional
+└── templates/        # optional
+```
+
+## Manifest Template
+
+```json
+{
+  "name": "security-pack",
+  "description": "Domain plugin pack for secure coding, review, and hardening workflows.",
+  "version": "1.0.0",
+  "domain": "security",
+  "type": "plugin-pack",
+  "status": "experimental",
+  "requires": {
+    "ai-toolkit": ">=1.0.0",
+    "claude-code": ">=1.0.33"
+  },
+  "includes": {
+    "agents": ["security-auditor", "security-architect"],
+    "skills": ["review", "security-patterns"],
+    "rules": [],
+    "hooks": []
+  }
+}
+```
+
+## Authoring Rules
+
+- Keep packs **domain-scoped**, not generic junk drawers
+- Prefer referencing existing toolkit assets before duplicating them
+- Pack manifests must be valid JSON with `name`, `description`, `version`, `domain`, `type`, `status`, and `includes`
+- Optional hooks must be executable and documented in the pack README
+- If the pack introduces policy or hook behavior, document install/opt-in semantics clearly, including that the pack is not part of the default install
+- Experimental packs should remain opt-in and must not silently alter default global install behavior
+
+## Validation Checklist
+
+- [ ] `app/plugins/<plugin-name>/plugin.json` exists and parses as JSON
+- [ ] `README.md` explains purpose, included assets, and opt-in flow
+- [ ] Referenced agents and skills exist or are created in the same change set
+- [ ] Optional hooks are executable and use `#!/bin/bash`
+- [ ] `scripts/validate.py` passes
+- [ ] Public docs mention the pack only after the manifest and README exist
+

package/app/skills/pr/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: pr
+description: "Create pull requests with pre-flight validation"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[title or branch]"
+allowed-tools: Bash, Read, Grep
+---
+
+# Pull Request
+
+$ARGUMENTS
+
+Create a GitHub pull request.
+
+## Project context
+
+- Recent commits: !`git log --oneline main..HEAD 2>/dev/null | head -20`
+
+## Usage
+
+```
+/pr [title]
+```
+
+## Automated PR Summary Generation
+
+Generate a structured PR summary from the commit history before writing the PR description:
+
+```bash
+python3 "$(dirname "$0")/scripts/pr-summary.py" [base_branch]
+# Default base branch: main
+# Example: python3 scripts/pr-summary.py develop
+```
+
+The script outputs JSON with:
+- **title_suggestion**: auto-generated PR title from dominant commit type and scope
+- **commits[]**: each commit parsed into type, scope, description (conventional commits)
+- **groups**: commits grouped by type (Features, Bug Fixes, etc.)
+- **summary_bullets**: ready-to-use summary lines for the PR body
+- **has_breaking**: whether any BREAKING CHANGE markers were found
+- **breaking_changes[]**: list of breaking change descriptions
+- **files_changed**: total files in the diff
+- **test_files_changed**: count of test files modified
+- **has_tests**: whether the PR includes test changes
+
+Use the output to populate the PR template fields below.
+
+---
+
+## PR Creation Workflow
+
+### 1. Pre-PR Checks
+
+```bash
+# Run CI checks
+ruff check . && mypy src/ && pytest tests/
+
+# Check branch status
+git status
+git diff main...HEAD --stat
+```
+
+### 2. Create PR
+
+```bash
+gh pr create --title "feat: add multi-hop reasoning" --body "$(cat <<'EOF'
+## Summary
+- Implement query decomposition for complex questions
+- Add iterative retrieval with reasoning
+- Include answer synthesis from aggregated context
+
+## Test plan
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] Manual testing with sample queries
+
+Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+## PR Template
+
+```markdown
+## Summary
+<1-3 bullet points describing changes>
+
+## Changes
+- [ ] Feature implementation
+- [ ] Tests added/updated
+- [ ] Documentation updated
+
+## Test plan
+- [ ] CI checks pass (lint, typecheck, tests)
+- [ ] Manual testing completed
+- [ ] No regressions
+
+## Screenshots
+<if applicable>
+
+Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+## PR Checklist
+
+Before creating PR:
+- [ ] All tests pass: `pytest tests/`
+- [ ] Linting passes: `ruff check .`
+- [ ] Type checking passes: `mypy src/`
+- [ ] Documentation updated if needed
+- [ ] Commit messages follow conventional commits
+- [ ] Branch is up to date with main
+
+## Useful gh Commands
+
+```bash
+# View PR
+gh pr view
+
+# Check PR status
+gh pr checks
+
+# Request review
+gh pr edit --add-reviewer username
+
+# Merge PR
+gh pr merge --squash
+```