@softspark/ai-toolkit 1.0.0

package/app/skills/debugging-tactics/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: debugging-tactics
+description: "Loaded when user is debugging an issue or needs root cause analysis"
+effort: medium
+user-invocable: false
+allowed-tools: Bash, Grep, Read
+---
+
+# Debugging Tactics Skill
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1 (Root Cause Investigation), you cannot propose fixes.
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings — they often contain the answer
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - If not reproducible, gather more data — don't guess
+
+3. **Check Recent Changes**
+   - `git diff`, recent commits, new dependencies
+   - Config changes, environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+   For each component boundary: log what enters, log what exits, verify state at each layer.
+   Run once to gather evidence showing WHERE it breaks, THEN investigate that specific component.
+
+5. **Trace Data Flow**
+   Where does the bad value originate? Trace backward through call stack to the source. Fix at source, not at symptom.
+
+### Phase 2: Pattern Analysis
+
+1. **Find Working Examples** — locate similar working code in same codebase
+2. **Compare Against References** — read reference implementations COMPLETELY, not skimming
+3. **Identify Differences** — list every difference, however small
+4. **Understand Dependencies** — what other components, settings, config does this need?
+
+### Phase 3: Hypothesis and Testing
+
+1. **Form Single Hypothesis** — "I think X is the root cause because Y" (be specific)
+2. **Test Minimally** — smallest possible change, one variable at a time
+3. **Verify Before Continuing** — did it work? If not, form NEW hypothesis. Don't add more fixes on top.
+
+### Phase 4: Implementation
+
+1. **Create Failing Test Case** — MUST have before fixing (use TDD skill)
+2. **Implement Single Fix** — address root cause, ONE change at a time, no "while I'm here" improvements
+3. **Verify Fix** — test passes? No regressions? Issue resolved?
+4. **If Fix Doesn't Work** — count your attempts:
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If >= 3: STOP and question the architecture** (see below)
+
+### Architecture Escalation (3+ Failed Fixes)
+
+**Pattern indicating architectural problem:**
+- Each fix reveals new shared state/coupling in different places
+- Fixes require "massive refactoring" to implement
+- Each fix creates new symptoms elsewhere
+
+**STOP and question fundamentals:**
+- Is this pattern fundamentally sound?
+- Should we refactor architecture vs. continue fixing symptoms?
+- Discuss with user before attempting more fixes
+
+This is NOT a failed hypothesis — this is a wrong architecture.
+
+## Red Flags — STOP and Follow Process
+
+| Excuse | Reality |
+|--------|---------|
+| "Quick fix for now, investigate later" | Systematic is faster than thrashing |
+| "Just try changing X and see" | One variable at a time, with hypothesis |
+| "I'll skip the test, I'll manually verify" | Untested fixes don't stick |
+| "It's probably X, let me fix that" | Seeing symptoms is not understanding root cause |
+| "One more fix attempt" (after 2+) | 3+ failures = architectural problem. STOP. |
+| "Here are the main problems: [list]" | You're proposing fixes without investigation |
+
+## Legacy Reference
+
+## Language-Specific Tactics
+
+### Python
+- **Debugger**: `import pdb; pdb.set_trace()` (or `ipdb`)
+- **Trace**: `traceback.print_stack()`
+- **Memory**: `tracemalloc` for leaks.
+```python
+import tracemalloc
+tracemalloc.start()
+# ... code ...
+snapshot = tracemalloc.take_snapshot()
+top_stats = snapshot.statistics('lineno')
+```
+
+### Node.js / TypeScript
+- **Debugger**: `node --inspect-brk app.js` -> Open `chrome://inspect`.
+- **Memory**: `heapdump` or built-in inspector.
+- **Async Traces**: Ensure `Error.stackTraceLimit = Infinity`.
+
+### PHP (Laravel/Symfony)
+- **Debugger**: Xdebug (`xdebug_break()`).
+- **Logs**: `Log::info('State:', $data);`.
+- **Query Log**: `DB::enableQueryLog(); ... dd(DB::getQueryLog());`.
+
+### Flutter / Dart
+- **Debugger**: `debugger()` statement.
+- **Inspector**: Flutter DevTools (Widget Inspector).
+- **Network**: Network tab in DevTools for API calls.
+
+## "5 Whys" Root Cause Analysis
+Ask "Why?" 5 times to find the real issue:
+- "The app crashed." -> Why? -> "Null pointer exception."
+- -> Why? -> "User object was null."
+- -> Why? -> "API returned 404."
+- -> Why? -> "User ID was invalid."
+- -> Why? -> "Frontend validation allowed negative IDs." (ROOT CAUSE)

package/app/skills/deploy/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: deploy
+description: "Deploy with pre-flight checks and health verification"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[environment]"
+allowed-tools: Bash, Read
+hooks:
+  PostToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "echo 'Reminder: verify health checks pass after deployment'"
+scripts:
+  - scripts/pre_deploy_check.py
+---
+
+# Deploy Application
+
+$ARGUMENTS
+
+Deploy application to target environment.
+
+## Project context
+
+- Docker config: !`cat docker-compose.yml 2>/dev/null || cat Dockerfile 2>/dev/null || echo "no-docker"`
+
+## Usage
+
+```
+/deploy [environment]
+```
+
+## What This Command Does
+
+1. **Validates** deployment prerequisites
+2. **Runs** pre-deployment checks
+3. **Executes** deployment
+4. **Verifies** deployment success
+
+## Environments
+
+| Environment | Description |
+|-------------|-------------|
+| `dev` | Development environment |
+| `staging` | Staging/QA environment |
+| `prod` | Production environment |
+
+## Pre-Deployment Checklist
+
+Run automated pre-deployment checks:
+```bash
+python3 scripts/pre_deploy_check.py [environment]
+```
+
+Returns JSON with pass/fail for each check:
+- `git_clean` - no uncommitted changes
+- `branch` - on main/master for production
+- `docker` - services running (if applicable)
+- `env_file` - .env or .env.$ENV exists
+- `build_artifacts` - dist/build present
+- `tests_ran` - test result artifacts found
+
+Manual verification:
+- [ ] Tests passing
+- [ ] Build successful
+- [ ] Environment variables set
+- [ ] Secrets configured
+- [ ] Database migrations ready
+- [ ] Rollback plan documented
+
+## Deployment Strategies
+
+| Strategy | Use Case |
+|----------|----------|
+| Rolling | Zero-downtime, gradual |
+| Blue-Green | Instant switch, easy rollback |
+| Canary | Risk mitigation, gradual traffic |
+| Recreate | Simple, allows downtime |
+
+## Output Format
+
+```markdown
+## Deployment Report
+
+### Status: Success / Failed
+
+### Details
+- **Environment**: [env]
+- **Version**: [version]
+- **Started**: [timestamp]
+- **Completed**: [timestamp]
+
+### Steps
+1. [Step 1] - Done
+2. [Step 2] - Done
+3. [Step 3] - Failed (if failed)
+
+### Health Check
+- [endpoint]: [status]
+
+### Rollback
+If needed: `[rollback command]`
+```
+
+## PRODUCTION SAFETY
+
+- Always deploy to staging first
+- Verify health checks pass
+- Have rollback plan ready
+- Monitor after deployment
+
+## MANDATORY: Documentation Update
+
+After deployment, update documentation:
+
+### Required Updates
+| Change Type | Update |
+|-------------|--------|
+| New release | CHANGELOG, release notes |
+| Config changes | Deployment docs, procedures |
+| New features | User documentation |
+| Infrastructure | `kb/procedures/deployment-*.md` |
+
+### Post-Deployment Checklist
+- [ ] Deployment successful
+- [ ] Health checks passing
+- [ ] **CHANGELOG updated**
+- [ ] **Deployment docs updated**
+- [ ] Release notes created (if applicable)

package/app/skills/deploy/scripts/pre_deploy_check.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Pre-deployment readiness checklist.
+
+Runs a series of checks (git clean, branch, Docker, env file, build
+artifacts, test results) and returns a JSON object with pass/fail for
+each check, a list of blockers, and an overall ready status.
+
+Usage::
+
+    python3 pre_deploy_check.py [environment]
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def _run(cmd: list[str], *, check: bool = False) -> subprocess.CompletedProcess[str]:
+    """Run a command and return the CompletedProcess.
+
+    Captures stdout/stderr as text. Never raises on non-zero exit unless
+    *check* is True.
+    """
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+
+
+def _git_porcelain() -> str:
+    """Return the porcelain output of ``git status``."""
+    result = _run(["git", "status", "--porcelain"])
+    return result.stdout.strip()
+
+
+def _git_branch() -> str:
+    """Return the current git branch name, or ``unknown``."""
+    result = _run(["git", "branch", "--show-current"])
+    return result.stdout.strip() or "unknown"
+
+
+def _docker_available() -> bool:
+    """Return True if the ``docker`` command is on PATH."""
+    result = _run(["command", "-v", "docker"])
+    # Fallback: just try docker --version
+    if result.returncode != 0:
+        result = _run(["docker", "--version"])
+    return result.returncode == 0
+
+
+def _docker_services_running() -> bool:
+    """Return True if any docker compose service reports running."""
+    result = _run(["docker", "compose", "ps"])
+    if result.returncode != 0:
+        return False
+    return "running" in result.stdout.lower()
+
+
+class _CheckCollector:
+    """Accumulates individual check results and blockers."""
+
+    def __init__(self) -> None:
+        self.checks: dict[str, dict[str, Any]] = {}
+        self.blockers: list[str] = []
+
+    def add(self, name: str, passed: bool, detail: str) -> None:
+        """Record a single check result."""
+        self.checks[name] = {"pass": passed, "detail": detail}
+        if not passed:
+            self.blockers.append(detail)
+
+    @property
+    def ready(self) -> bool:
+        """Return True when there are no blockers."""
+        return len(self.blockers) == 0
+
+
+def _run_checks(env: str) -> _CheckCollector:
+    """Execute all pre-deployment checks and return the collector."""
+    collector = _CheckCollector()
+
+    # 1. Git clean
+    porcelain = _git_porcelain()
+    if not porcelain:
+        collector.add("git_clean", True, "No uncommitted changes")
+    else:
+        collector.add("git_clean", False, "Uncommitted changes detected")
+
+    # 2. Branch
+    branch = _git_branch()
+    if env in ("prod", "production"):
+        if branch in ("main", "master"):
+            collector.add("branch", True, f"On {branch}")
+        else:
+            collector.add("branch", False, f"Not on main/master (on {branch})")
+    else:
+        collector.add("branch", True, f"On {branch}")
+
+    # 3. Docker
+    has_compose = (
+        Path("docker-compose.yml").exists()
+        or Path("compose.yml").exists()
+    )
+    if _docker_available() and has_compose:
+        if _docker_services_running():
+            collector.add("docker", True, "Docker services running")
+        else:
+            collector.add("docker", False, "Docker services not running")
+    else:
+        collector.add("docker", True, "No Docker config (skipped)")
+
+    # 4. Env file
+    if Path(".env").exists() or Path(f".env.{env}").exists():
+        collector.add("env_file", True, "Environment file exists")
+    else:
+        collector.add("env_file", False, f"Missing .env or .env.{env} file")
+
+    # 5. Build artifacts
+    found_artifacts = any(Path(d).is_dir() for d in ("dist", "build"))
+    if found_artifacts:
+        collector.add("build_artifacts", True, "Build artifacts present")
+    else:
+        collector.add(
+            "build_artifacts", True,
+            "No build artifacts expected (interpreted language)",
+        )
+
+    # 6. Test results
+    test_artifacts = [
+        "coverage/.last_run.json",
+        "htmlcov/status.json",
+        ".coverage",
+        "test-results.xml",
+    ]
+    if any(Path(p).exists() for p in test_artifacts):
+        collector.add("tests_ran", True, "Test result artifacts found")
+    else:
+        collector.add(
+            "tests_ran", False,
+            "No recent test results found - run tests first",
+        )
+
+    return collector
+
+
+def main() -> None:
+    """Entry point: run checks and print JSON result to stdout."""
+    env = sys.argv[1] if len(sys.argv) > 1 else "staging"
+    branch = _git_branch()
+    collector = _run_checks(env)
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    output: dict[str, Any] = {
+        "environment": env,
+        "timestamp": now,
+        "branch": branch,
+        "checks": collector.checks,
+        "ready": collector.ready,
+        "blockers": collector.blockers,
+    }
+    print(json.dumps(output, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/app/skills/deploy/templates/deployment-checklist.md

@@ -0,0 +1,31 @@
+# Deployment Checklist
+
+## Pre-Deployment
+- [ ] All tests passing on CI
+- [ ] Code reviewed and approved
+- [ ] No critical security vulnerabilities
+- [ ] Database migrations tested
+- [ ] Environment variables configured
+- [ ] Rollback plan documented
+
+## Deployment
+- [ ] Notify team of deployment start
+- [ ] Create deployment tag/release
+- [ ] Run database migrations
+- [ ] Deploy application
+- [ ] Verify health checks pass
+- [ ] Run smoke tests
+
+## Post-Deployment
+- [ ] Monitor error rates (15 min)
+- [ ] Monitor response times (15 min)
+- [ ] Verify key user flows work
+- [ ] Check logs for unexpected errors
+- [ ] Notify team of deployment completion
+- [ ] Update deployment log
+
+## Rollback Triggers
+- Error rate > 5%
+- P95 latency > 2x baseline
+- Critical user flow broken
+- Data integrity issues detected

package/app/skills/design-an-interface/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: design-an-interface
+description: "Generate multiple radically different interface designs using parallel sub-agents, then compare on simplicity, depth, and correctness. Based on 'Design It Twice' from Ousterhout. Use when user wants to design an API, explore interface options, compare module shapes, or mentions 'design it twice'."
+user-invocable: true
+effort: high
+argument-hint: "[module or interface to design]"
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Design an Interface
+
+$ARGUMENTS
+
+Generate 3+ radically different interface designs using parallel sub-agents, then compare. Based on "Design It Twice" from "A Philosophy of Software Design."
+
+## Usage
+
+```
+/design-an-interface [module or interface to design]
+```
+
+## What This Command Does
+
+1. **Gathers** requirements and constraints
+2. **Spawns** 3+ parallel sub-agents with different design constraints
+3. **Presents** each design with signatures, usage examples, and trade-offs
+4. **Compares** on simplicity, depth, efficiency, and correctness
+5. **Synthesizes** best elements into final recommendation
+
+## Process
+
+### 1. Gather Requirements
+
+Before designing, understand:
+
+- [ ] What problem does this module solve?
+- [ ] Who are the callers? (other modules, external users, tests)
+- [ ] What are the key operations?
+- [ ] Any constraints? (performance, compatibility, existing patterns)
+- [ ] What should be hidden inside vs exposed?
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using Agent tool. Each gets a **radically different** constraint:
+
+| Agent | Constraint |
+|-------|-----------|
+| Agent 1 | Minimize method count — aim for 1-3 methods max |
+| Agent 2 | Maximize flexibility — support many use cases |
+| Agent 3 | Optimize for the most common case |
+| Agent 4 | Take inspiration from a specific paradigm/library |
+
+Each agent outputs:
+1. Interface signature (types/methods)
+2. Usage example (how caller uses it)
+3. What this design hides internally
+4. Trade-offs of this approach
+
+### 3. Present Designs
+
+Show each design sequentially so user can absorb each approach before comparison:
+1. **Interface signature** — types, methods, params
+2. **Usage examples** — how callers actually use it
+3. **What it hides** — complexity kept internal
+
+### 4. Compare Designs
+
+Compare in prose (not tables) on:
+
+| Criterion | Description |
+|-----------|-------------|
+| Interface simplicity | Fewer methods, simpler params |
+| General-purpose vs specialized | Flexibility vs focus |
+| Implementation efficiency | Does shape allow efficient internals? |
+| Depth | Small interface hiding significant complexity (good) vs large interface with thin implementation (bad) |
+| Ease of correct use | vs ease of misuse |
+
+### 5. Synthesize
+
+Often the best design combines insights from multiple options. Give an opinionated recommendation. Ask:
+- Which design best fits the primary use case?
+- Any elements from other designs worth incorporating?
+
+## Visual Companion (Optional)
+
+When upcoming design explorations will involve visual content (mockups, layout comparisons, architecture diagrams), offer the browser companion:
+
+> "Some of these interface designs might be easier to compare visually. I can show diagrams and side-by-side comparisons in a browser. Want to try it?"
+
+**This offer MUST be its own message.** Do not combine with other questions. Wait for response.
+
+If accepted, start the server and use it for visual comparisons only. Text/conceptual questions stay in terminal.
+
+See [../write-a-prd/reference/visual-companion.md](../write-a-prd/reference/visual-companion.md) for details.
+
+## Anti-Patterns
+
+- Don't let sub-agents produce similar designs — enforce radical difference
+- Don't skip comparison — the value is in contrast
+- Don't implement — this is purely about interface shape
+- Don't evaluate based on implementation effort
+
+## READ-ONLY
+
+This skill designs interfaces. It does NOT write implementation code.