@softspark/ai-toolkit 1.0.0

package/app/skills/biz-scan/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: biz-scan
+description: "Scan codebase for business opportunities and KPIs"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[area]"
+agent: business-intelligence
+context: fork
+allowed-tools: Read, Grep, Glob
+---
+
+# Biz Scan Command
+
+$ARGUMENTS
+
+Triggers the Business Intelligence agent to find opportunities.
+
+## Usage
+
+```bash
+/biz-scan [scope]
+# Example: /biz-scan schema
+# Example: /biz-scan all
+```
+
+## Protocol
+1. **Model Scan**: Read DB schema / Entities.
+2. **Logic Scan**: Read Controllers / UseCases.
+3. **Synthesis**: Match Data vs Business Goals.
+4. **Report**: Generate Opportunity Report.

package/app/skills/briefing/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: briefing
+description: "Generate executive daily briefing across all agents"
+effort: medium
+disable-model-invocation: true
+agent: chief-of-staff
+context: fork
+allowed-tools: Read, Grep, Glob
+---
+
+# Briefing Command
+
+Triggers the Chief of Staff to generate an executive summary.
+
+## Usage
+
+```bash
+/briefing [period]
+# Example: /briefing today
+# Example: /briefing week
+```
+
+## Protocol
+1. **Collect**: Gather logs from `kb/learnings/`, `maintenance/` logs, and recent runs.
+2. **Synthesize**: Group by category (Ops, Strategy, Actions).
+3. **Filter**: Remove low-priority success logs.
+4. **Present**: Render the Daily Brief.

package/app/skills/build/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: build
+description: "Build the project with auto-detected toolchain"
+effort: low
+disable-model-invocation: true
+argument-hint: "[target]"
+allowed-tools: Bash, Read
+---
+
+# Build Project
+
+$ARGUMENTS
+
+Build the current project.
+
+## Project context
+
+- Project config: !`cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || echo "unknown"`
+
+## Auto-Detection
+
+Run the bundled script to detect build system:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/detect-build.py [dev|prod|docker]
+```
+
+## Usage
+
+```
+/build [target]
+```
+
+## What This Command Does
+
+1. **Detects** project type
+2. **Runs** appropriate build command
+3. **Reports** build status
+
+## Build Commands by Project Type
+
+| Project Type | Build Command |
+|--------------|---------------|
+| Node.js | `npm run build` or `pnpm build` |
+| Python | `poetry build` or `pip install -e .` |
+| Flutter | `flutter build` |
+| Go | `go build ./...` |
+| Rust | `cargo build --release` |
+| Docker | `docker compose build` |
+
+## Output Format
+
+```markdown
+## Build Report
+
+### Status: Success / Failed
+
+### Build Details
+- **Project**: [name]
+- **Type**: [type]
+- **Command**: [command used]
+- **Duration**: [time]
+
+### Artifacts
+- [artifact 1]
+- [artifact 2]
+
+### Warnings
+- [warning if any]
+
+### Errors
+- [error if any]
+```
+
+## Targets
+
+| Target | Description |
+|--------|-------------|
+| `dev` | Development build |
+| `prod` | Production build |
+| `docker` | Docker image build |
+| `all` | Build all targets |
+
+## MANDATORY: Documentation Update
+
+After build configuration changes, update documentation:
+
+### When to Update
+- Build config changes -> Update build docs
+- New dependencies -> Update requirements docs
+- Docker changes -> Update Docker docs
+- CI changes -> Update CI/CD docs
+
+### Post-Build Changes Checklist
+- [ ] Build successful
+- [ ] **README build instructions updated** (if changed)
+- [ ] **CI/CD config documented**

package/app/skills/build/scripts/detect-build.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Detect build system, package manager, and available build/dev/docker commands.
+
+Scans a project directory for Node.js, Python, Flutter/Dart, Go, Rust,
+PHP, and Makefile-based projects. Returns a JSON object describing the
+project type, package manager, suggested build and dev commands, Docker
+build command (if applicable), available Makefile targets, and the
+configuration file used for detection.
+
+Usage::
+
+    python3 detect-build.py [project_directory] [dev|prod|docker]
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+from _lib.detect_utils import parse_makefile_targets, read_json, read_text, run_detector
+
+
+def detect_package_manager(project_dir: Path) -> str | None:
+    """Detect the Node.js package manager from lock files."""
+    checks: list[tuple[str, str]] = [
+        ("bun.lockb", "bun"),
+        ("pnpm-lock.yaml", "pnpm"),
+        ("yarn.lock", "yarn"),
+        ("package-lock.json", "npm"),
+    ]
+    for lockfile, manager in checks:
+        if (project_dir / lockfile).exists():
+            return manager
+    if (project_dir / "package.json").exists():
+        return "npm"
+    return None
+
+
+def detect(project_dir: Path, target: str | None = None) -> dict[str, Any]:
+    """Detect the build system for the given project directory."""
+    result: dict[str, Any] = {
+        "project_type": None, "package_manager": None,
+        "build_command": None, "dev_command": None,
+        "docker_build": None, "makefile_targets": [],
+        "scripts": {}, "detected_from": None,
+    }
+
+    result["makefile_targets"] = parse_makefile_targets(project_dir)
+
+    # Docker detection
+    has_dockerfile = (project_dir / "Dockerfile").exists()
+    has_compose = (project_dir / "docker-compose.yml").exists() or (project_dir / "docker-compose.yaml").exists() or (project_dir / "compose.yml").exists()
+    if has_dockerfile or has_compose:
+        if has_compose:
+            result["docker_build"] = "docker compose build"
+        elif has_dockerfile:
+            result["docker_build"] = "docker build -t app ."
+
+    # Node.js
+    pkg = read_json(project_dir / "package.json")
+    if pkg:
+        pm = detect_package_manager(project_dir)
+        result["project_type"] = "node"
+        result["package_manager"] = pm
+        result["detected_from"] = "package.json"
+        scripts = pkg.get("scripts", {})
+        result["scripts"] = {k: v for k, v in scripts.items() if k in
+                             {"build", "dev", "start", "preview", "lint", "test", "typecheck"}}
+        run_pfx = f"{pm} run" if pm in ("npm", "pnpm") else (f"{pm} run" if pm == "yarn" else f"{pm} run")
+        if pm == "bun":
+            run_pfx = "bun run"
+        result["build_command"] = f"{run_pfx} build" if "build" in scripts else None
+        result["dev_command"] = f"{run_pfx} dev" if "dev" in scripts else (f"{run_pfx} start" if "start" in scripts else None)
+        if target == "docker" and result["docker_build"]:
+            result["build_command"] = result["docker_build"]
+        return result
+
+    # Python
+    pyproject = read_text(project_dir / "pyproject.toml")
+    if pyproject or (project_dir / "setup.py").exists():
+        result["project_type"] = "python"
+        result["detected_from"] = "pyproject.toml" if pyproject else "setup.py"
+        if pyproject and "poetry" in pyproject:
+            result["package_manager"] = "poetry"
+            result["build_command"] = "poetry build"
+            result["dev_command"] = "poetry run python -m app"
+        elif pyproject and "hatchling" in pyproject:
+            result["package_manager"] = "hatch"
+            result["build_command"] = "hatch build"
+        else:
+            result["package_manager"] = "pip"
+            result["build_command"] = "pip install -e ."
+        if target == "docker" and result["docker_build"]:
+            result["build_command"] = result["docker_build"]
+        return result
+
+    # Flutter/Dart
+    if (project_dir / "pubspec.yaml").exists():
+        result.update(project_type="flutter", package_manager="pub",
+                      detected_from="pubspec.yaml",
+                      build_command="flutter build", dev_command="flutter run")
+        return result
+
+    # Go
+    if (project_dir / "go.mod").exists():
+        result.update(project_type="go", package_manager="go",
+                      detected_from="go.mod",
+                      build_command="go build ./...", dev_command="go run .")
+        return result
+
+    # Rust
+    if (project_dir / "Cargo.toml").exists():
+        result.update(project_type="rust", package_manager="cargo",
+                      detected_from="Cargo.toml",
+                      build_command="cargo build --release", dev_command="cargo run")
+        return result
+
+    # PHP
+    if (project_dir / "composer.json").exists():
+        result.update(project_type="php", package_manager="composer",
+                      detected_from="composer.json",
+                      build_command="composer install --no-dev --optimize-autoloader",
+                      dev_command="composer install && php -S localhost:8000 -t public/")
+        return result
+
+    # Fallback: Makefile-only project
+    if result["makefile_targets"]:
+        result["project_type"] = "makefile"
+        result["detected_from"] = "Makefile"
+        if "build" in result["makefile_targets"]:
+            result["build_command"] = "make build"
+        if "dev" in result["makefile_targets"]:
+            result["dev_command"] = "make dev"
+        return result
+
+    result["project_type"] = "unknown"
+    return result
+
+
+if __name__ == "__main__":
+    # Handle target arg (dev/prod/docker) specially
+    target: str | None = None
+    clean_argv = [sys.argv[0]]
+    for arg in sys.argv[1:]:
+        if arg in ("dev", "prod", "docker"):
+            target = arg
+        else:
+            clean_argv.append(arg)
+    sys.argv = clean_argv
+    run_detector(lambda d: detect(d, target))

package/app/skills/chaos/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: chaos
+description: "Inject controlled faults for resilience testing"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[target]"
+context: fork
+agent: chaos-monkey
+allowed-tools: Bash, Read
+---
+
+# Chaos Command
+
+$ARGUMENTS
+
+Triggers a controlled resilience experiment.
+
+## Usage
+
+```bash
+/chaos <experiment> [target]
+# Example: /chaos latency backend-api
+# Example: /chaos kill redis
+```
+
+## Protocol
+1. **Safety Check**: Verify env != PROD.
+2. **Baseline**: Check system health is green.
+3. **Inject**: Run the fault injection.
+4. **Observe**: Monitor logs/metrics for 60s.
+5. **Recover**: Restore system health.
+6. **Report**: Did we survive?

package/app/skills/ci/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: ci
+description: "Detect and run CI pipeline with status reporting"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[platform]"
+allowed-tools: Bash, Read, Write
+agent: devops-implementer
+context: fork
+scripts:
+  - scripts/ci-detect.py
+---
+
+# /ci - CI/CD Pipeline Management
+
+$ARGUMENTS
+
+## What This Command Does
+
+Generate, update, or troubleshoot CI/CD pipeline configuration based on project type.
+
+## Project context
+
+- CI config: !`cat .github/workflows/*.yml 2>/dev/null || cat .gitlab-ci.yml 2>/dev/null || echo "no-ci"`
+
+## CI Detection Script
+
+Detect CI platform and analyze configuration:
+```bash
+python3 scripts/ci-detect.py [directory]
+```
+
+Returns JSON with:
+- `platform` - detected CI platform (github-actions, gitlab-ci, jenkins, bitbucket, circleci)
+- `config_files[]` - CI config file paths
+- `project_type` - detected project type (python, node, flutter, go, rust, php, docker)
+- `jobs_found[]` - job/stage names extracted from config
+- `stages_detected[]` - best-practice stages found (lint, test, build, deploy)
+- `missing_stages[]` - recommended stages not yet configured
+- `suggested_template` - pointer to ci-cd-patterns skill for templates
+
+## Auto-Detection
+
+| File Found | Project Type | Pipeline |
+|------------|-------------|----------|
+| `package.json` | Node.js/TypeScript | npm ci, lint, test, build |
+| `pyproject.toml` / `setup.py` | Python | pip install, ruff, mypy, pytest |
+| `pubspec.yaml` | Flutter/Dart | dart analyze, flutter test, build |
+| `composer.json` | PHP | composer install, phpstan, phpunit |
+| `go.mod` | Go | go vet, go test, go build |
+| `Cargo.toml` | Rust | cargo clippy, cargo test, cargo build |
+| `Dockerfile` | Docker | Build and push image |
+
+## Supported Platforms
+
+- **GitHub Actions** (default): `.github/workflows/ci.yml`
+- **GitLab CI**: `.gitlab-ci.yml`
+
+## Pipeline Stages
+
+1. **Lint** - Static analysis, formatting checks
+2. **Test** - Unit tests, integration tests with coverage
+3. **Build** - Compile, bundle, Docker image
+4. **Deploy** (optional) - Deploy to staging/production
+
+## Usage Examples
+
+```
+/ci                          # Generate CI config for detected project type
+/ci github-actions           # Explicitly use GitHub Actions
+/ci add deploy staging       # Add deployment stage for staging
+/ci fix                      # Troubleshoot failing pipeline
+/ci add matrix node 18,20,22 # Add matrix testing
+```
+
+## Reference Skill
+Use `ci-cd-patterns` skill for pipeline templates and best practices.

package/app/skills/ci/scripts/ci-detect.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Detect CI platform, analyze configuration, and suggest improvements.
+
+Scans a project directory for CI/CD configuration files (GitHub Actions,
+GitLab CI, Jenkins, Bitbucket Pipelines, CircleCI), detects the project
+type, extracts job/stage names, identifies which best-practice stages
+are present, and reports any missing stages with a pointer to the
+``ci-cd-patterns`` skill for templates.
+
+Usage::
+
+    python3 ci-detect.py [directory]
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+from _lib.detect_utils import detect_project_type, run_detector
+
+CI_PLATFORMS: dict[str, str] = {
+    "github-actions": ".github/workflows",
+    "gitlab-ci": ".gitlab-ci.yml",
+    "jenkins": "Jenkinsfile",
+    "bitbucket": "bitbucket-pipelines.yml",
+    "circleci": ".circleci/config.yml",
+}
+
+BEST_PRACTICE_STAGES: dict[str, list[str]] = {
+    "python": ["lint", "test", "build", "deploy"],
+    "node": ["lint", "test", "build", "deploy"],
+    "flutter": ["analyze", "test", "build", "deploy"],
+    "go": ["vet", "test", "build", "deploy"],
+    "rust": ["clippy", "test", "build", "deploy"],
+    "php": ["lint", "test", "build", "deploy"],
+    "docker": ["build", "test", "push", "deploy"],
+}
+
+STAGE_PATTERNS: dict[str, str] = {
+    "lint": r"(?i)(lint|ruff|eslint|flake8|pylint|phpstan|rubocop|golangci)",
+    "test": r"(?i)(test|pytest|jest|vitest|phpunit|go\s+test|cargo\s+test|flutter\s+test)",
+    "build": r"(?i)(build|compile|bundle|docker\s+build|cargo\s+build|go\s+build|flutter\s+build)",
+    "deploy": r"(?i)(deploy|release|publish|push|upload|heroku|aws|gcp|azure)",
+    "analyze": r"(?i)(analyze|dart\s+analyze|static.?analysis)",
+    "vet": r"(?i)(go\s+vet|vet)",
+    "clippy": r"(?i)(clippy|cargo\s+clippy)",
+    "push": r"(?i)(docker\s+push|push.*registry|push.*image)",
+}
+
+
+def detect_platform(project_dir: Path) -> tuple[str | None, list[str]]:
+    """Detect the CI platform and return its config file paths."""
+    for platform, path_pattern in CI_PLATFORMS.items():
+        full_path = project_dir / path_pattern
+        if platform == "github-actions":
+            if full_path.is_dir():
+                configs = sorted(str(f.relative_to(project_dir)) for f in full_path.glob("*.yml"))
+                configs += sorted(str(f.relative_to(project_dir)) for f in full_path.glob("*.yaml"))
+                if configs:
+                    return platform, configs
+        elif full_path.exists():
+            return platform, [str(full_path.relative_to(project_dir))]
+    return None, []
+
+
+def extract_stages_from_config(config_path: Path) -> list[str]:
+    """Extract job/stage names from a CI config file using regex."""
+    try:
+        content = config_path.read_text()
+    except (OSError, UnicodeDecodeError):
+        return []
+
+    stages: list[str] = []
+    for match in re.finditer(r"^\s{2}(\w[\w-]*):\s*$", content, re.MULTILINE):
+        stages.append(match.group(1))
+    for match in re.finditer(r"^(\w[\w-]*):\s*$", content, re.MULTILINE):
+        name = match.group(1)
+        if name not in ("on", "true", "false", "name", "env", "permissions", "concurrency"):
+            stages.append(name)
+    return list(dict.fromkeys(stages))
+
+
+def detect_present_stages(config_files: list[Path], project_type: str | None) -> list[str]:
+    """Detect which best-practice stages are present in the CI config."""
+    all_content = ""
+    for cf in config_files:
+        try:
+            all_content += cf.read_text() + "\n"
+        except (OSError, UnicodeDecodeError):
+            continue
+
+    expected = BEST_PRACTICE_STAGES.get(project_type or "", ["lint", "test", "build", "deploy"])
+    found: list[str] = []
+    for stage in expected:
+        pattern = STAGE_PATTERNS.get(stage)
+        if pattern and re.search(pattern, all_content):
+            found.append(stage)
+    return found
+
+
+def detect(project_dir: Path) -> dict:
+    """Detect CI platform and analyze pipeline stages."""
+    platform, config_files = detect_platform(project_dir)
+    project_type = detect_project_type(project_dir)
+    expected_stages = BEST_PRACTICE_STAGES.get(project_type or "", ["lint", "test", "build", "deploy"])
+
+    config_paths = [project_dir / cf for cf in config_files]
+    stages_detected = detect_present_stages(config_paths, project_type)
+    missing_stages = [s for s in expected_stages if s not in stages_detected]
+
+    job_names: list[str] = []
+    for cp in config_paths:
+        job_names.extend(extract_stages_from_config(cp))
+
+    suggested_template: str | None = None
+    if missing_stages and project_type:
+        suggested_template = f"ci-cd-patterns skill: {project_type} pipeline template"
+
+    return {
+        "platform": platform,
+        "config_files": config_files,
+        "project_type": project_type,
+        "jobs_found": job_names,
+        "stages_detected": stages_detected,
+        "expected_stages": expected_stages,
+        "missing_stages": missing_stages,
+        "suggested_template": suggested_template,
+    }
+
+
+if __name__ == "__main__":
+    run_detector(detect)

package/app/skills/ci/templates/github-actions-node.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Test
+        run: npm test -- --coverage
+
+      - name: Build
+        run: npm run build

package/app/skills/ci/templates/github-actions-python.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type check
+        run: mypy --strict src/
+
+      - name: Test
+        run: pytest --cov=src --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml