@arthai/agents 1.0.0

package/dist/plugins/spark/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "spark",
+  "description": "Project setup and onboarding — calibrate, scan, bootstrap",
+  "version": "1.0.0",
+  "author": "Arth AI"
+}

package/dist/plugins/spark/agents/explore-light.md

@@ -0,0 +1,52 @@
+---
+name: explore-light
+description: Fast, cheap codebase exploration using Haiku. Use for finding files, searching code, reading and summarizing code structure. Returns structured findings for deeper analysis.
+model: haiku
+tools:
+  - Glob
+  - Grep
+  - Read
+  - WebSearch
+  - WebFetch
+---
+
+You are a fast codebase explorer. Your job is to efficiently find and summarize information.
+
+## Guidelines
+
+- Be concise - return findings, not analysis
+- Use Glob for file patterns, Grep for content search
+- Read only the files needed to answer the question
+- Structure your response as:
+  - **Found:** List of relevant files/locations
+  - **Summary:** Brief description of what you found
+  - **Snippets:** Key code excerpts (if requested)
+
+## Do NOT
+
+- Make architectural recommendations
+- Modify any files
+- Perform deep reasoning about tradeoffs
+- Exceed 500 words in responses
+
+## Example Responses
+
+**Good response:**
+```
+Found:
+- src/api/routes/auth.py (lines 45-89)
+- src/middleware/auth_middleware.py
+
+Summary:
+Authentication uses JWT tokens. The auth.py file handles login/logout endpoints.
+The middleware validates tokens on protected routes.
+```
+
+**Bad response:**
+```
+I found the authentication system. It's quite interesting how they've
+implemented it. I think they should consider using OAuth instead because...
+[lengthy analysis continues]
+```
+
+Keep it short. Find and report.

package/dist/plugins/spark/agents/setup.md

@@ -0,0 +1,134 @@
+---
+name: setup
+description: Project setup agent — bootstraps repos from scratch with env, infra, credentials, CI, deploy, and Discord
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+---
+
+# Setup Agent — Project Bootstrap
+
+You bootstrap projects from empty repo to deployed app. You adapt to any stack by
+discovering the project's technology, services, and conventions at runtime.
+
+## Project Context Discovery
+
+Before any work, discover the project environment:
+
+1. **Read `CLAUDE.md`** for tech stack, services, test commands, infrastructure
+2. **Read `.env.example`** (or `.env.local`, `backend/.env`) for required credentials
+3. **Scan project files** if CLAUDE.md is incomplete:
+   - `package.json` — frontend framework, scripts, port
+   - `requirements.txt` / `pyproject.toml` — backend framework, deps
+   - `docker-compose.yml` — container services, ports
+   - `alembic/` / `prisma/` / `migrations/` — migration tool
+   - `Dockerfile` / `Procfile` / `railway.json` — deploy target
+4. **Read project plans** in `.claude/plans/` for architecture context
+
+## Execution Model
+
+Work through modules sequentially. For each module:
+1. **Check** if already complete (idempotent)
+2. **Execute** if needed
+3. **Verify** the result
+4. **Report** status before moving on
+
+Skip modules that are already complete. Never redo work that's already done.
+
+## Module Sequence
+
+### 0. Prerequisites
+- Check required software is installed (language runtime, Docker, gh, deploy CLI)
+- Identify accounts needed from env var patterns
+- Show status table of what's ready vs missing
+
+### 1. Repo Structure
+- Ensure `.git/` exists
+- Ensure `.gitignore` covers secrets and build artifacts
+- Verify project directory structure matches the stack
+
+### 2. Dependencies
+- Python: create venv, pip install requirements
+- Node: npm install
+- Go: go mod download
+- Pre-download ML models if applicable (sentence-transformers, fastText, etc.)
+- Validate imports work
+
+### 3. Infrastructure
+- Start Docker services: `docker compose up -d`
+- Wait for health checks to pass
+- Report connection details
+
+### 4. Database
+- Detect migration tool (Alembic, Prisma, Django, Knex, Drizzle)
+- Run migrations
+- Run seed scripts if they exist
+- Verify with row count queries
+
+### 5. Credentials
+- Detect env file convention from project config
+- Create from template if missing
+- Auto-generate what's possible (SECRET_KEY, webhook secrets)
+- Identify placeholders that need real values
+- Guide user through each missing credential with validation commands
+- Final check: import project settings to verify all loads
+
+### 6. Profiles (if applicable)
+- Bot profiles (Twitter/X, Telegram, Discord)
+- Only if project has bot/service integrations
+
+### 7. Local Verify
+- Start the application
+- Hit health endpoints
+- Run test suite
+- Report pass/fail
+
+### 8. Claude Agents
+- Install toolkit: `~/.claude-agents/install.sh --init .`
+- Run `/scan` to populate CLAUDE.md
+- Check for remaining TODO placeholders
+
+### 9. Arth
+- Run `/arth add` if `.arth.json` missing
+
+### 10. GitHub CI
+- Generate CI workflow based on detected stack
+- Include service containers matching docker-compose
+- Use fake env vars for external APIs (tests should mock)
+
+### 11. Discord
+- Guide through server + channel creation
+- Guide through bot creation
+- Set up GitHub webhook to #deployments
+- Configure discord-mcp for ChatOps
+
+### 12. Secrets Sync
+- Identify real values in env file (skip placeholders)
+- Sync to GitHub Secrets
+- Sync to cloud provider (Railway, Vercel, etc.)
+- Confirm before pushing
+
+### 13. Deploy
+- Detect deploy target (Railway, Vercel, AWS, etc.)
+- Set up project on platform
+- Deploy
+- Run post-deploy tasks (migrations, seeds, webhook registration)
+
+### 14. Prod Verify
+- Health checks against production URL
+- End-to-end smoke tests
+- Check logs for errors
+
+### 15. Monitoring
+- Set up Sentry if SENTRY_DSN is in env template
+- Optional, skip if not needed
+
+## Rules
+
+- **Never store credentials yourself** — ask the user to paste values
+- **Never echo credentials back** to the user
+- **Always verify before reporting success** — check the command output, hit the endpoint, query the table
+- **Detect, don't assume** — always discover the stack from project files, never hardcode frameworks
+- **Idempotent** — every module can be re-run safely
+- **Skip what's done** — check before executing, don't redo work
+- **Ask when blocked** — if 2-3 attempts fail, ask the user for guidance
+- **Show progress** — report status after each module completes

package/dist/plugins/spark/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-bootstrap.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/plugins/spark/hooks/session-bootstrap.sh

@@ -0,0 +1,379 @@
+#!/bin/bash
+# SessionStart hook: Gather project context and inject a compact briefing.
+# Runs once when Claude Code opens. Outputs 2-5 lines of context.
+# Non-blocking — degrades gracefully if tools are missing.
+#
+# stdout is injected as context into the conversation.
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# ---------------------------------------------------------------------------
+# Clear triage marker — forces full routing table on first message
+# ---------------------------------------------------------------------------
+rm -f "$PROJECT_DIR/.claude/.triage-full-emitted" 2>/dev/null || true
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# Check if a command exists silently
+has_cmd() { command -v "$1" &>/dev/null; }
+
+# Run a command with timeout, return empty on failure
+# Uses perl fallback on macOS where GNU timeout doesn't exist
+safe_run() {
+    local timeout_s="${1:-3}"
+    shift
+    if command -v timeout &>/dev/null; then
+        timeout "$timeout_s" "$@" 2>/dev/null || true
+    else
+        # macOS fallback: run directly (no timeout protection, but at least it works)
+        "$@" 2>/dev/null || true
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# 1. Project detection
+# ---------------------------------------------------------------------------
+
+project_name=$(basename "$PROJECT_DIR")
+claude_md_exists=false
+[ -f "$PROJECT_DIR/CLAUDE.md" ] && claude_md_exists=true
+
+# Detect greenfield vs brownfield
+is_greenfield=true
+if $claude_md_exists; then
+    is_greenfield=false
+elif [ -f "$PROJECT_DIR/package.json" ] || [ -f "$PROJECT_DIR/requirements.txt" ] || \
+     [ -f "$PROJECT_DIR/go.mod" ] || [ -f "$PROJECT_DIR/Cargo.toml" ] || \
+     [ -d "$PROJECT_DIR/src" ] || [ -d "$PROJECT_DIR/app" ]; then
+    is_greenfield=false
+fi
+
+# ---------------------------------------------------------------------------
+# 2. Git context (fast — local only)
+# ---------------------------------------------------------------------------
+
+branch=""
+uncommitted=0
+ahead_behind=""
+last_commit=""
+stash_count=0
+has_git=false
+
+if [ -d "$PROJECT_DIR/.git" ]; then
+    has_git=true
+    cd "$PROJECT_DIR"
+
+    branch=$(safe_run 2 git rev-parse --abbrev-ref HEAD)
+    uncommitted=$(safe_run 2 git status --short | wc -l | tr -d ' ')
+
+    # Ahead/behind remote
+    upstream=$(safe_run 2 git rev-parse --abbrev-ref '@{upstream}') || true
+    if [ -n "$upstream" ]; then
+        local_rev=$(safe_run 2 git rev-parse HEAD)
+        remote_rev=$(safe_run 2 git rev-parse "$upstream")
+        if [ "$local_rev" != "$remote_rev" ]; then
+            ahead=$(safe_run 2 git rev-list --count "$upstream..HEAD")
+            behind=$(safe_run 2 git rev-list --count "HEAD..$upstream")
+            parts=()
+            [ "${ahead:-0}" -gt 0 ] && parts+=("${ahead} ahead")
+            [ "${behind:-0}" -gt 0 ] && parts+=("${behind} behind")
+            if [ ${#parts[@]} -gt 0 ]; then
+                ahead_behind=$(IFS=', '; echo "${parts[*]}")
+            fi
+        fi
+    fi
+
+    # Last commit (short)
+    last_commit=$(safe_run 2 git log -1 --format='%s (%cr)' 2>/dev/null) || true
+
+    # Stash count
+    stash_count=$(safe_run 2 git stash list | wc -l | tr -d ' ')
+
+    cd - >/dev/null 2>&1 || true
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Environment health (from CLAUDE.md + docker + alembic)
+# ---------------------------------------------------------------------------
+
+docker_status=""
+alembic_status=""
+mcp_status=""
+
+# Docker container health (if docker is available and CLAUDE.md mentions docker)
+if has_cmd docker && docker info &>/dev/null 2>&1; then
+    running_containers=$(safe_run 3 docker ps --format '{{.Names}}' | tr '\n' ' ')
+    # Check common DB containers
+    for svc in postgres redis mysql mongo; do
+        if echo "$running_containers" | grep -qi "$svc"; then
+            docker_status="${docker_status}${svc} ✓ "
+        else
+            # Only flag if the project likely uses this service
+            if [ -f "$PROJECT_DIR/docker-compose.yml" ] && grep -qi "$svc" "$PROJECT_DIR/docker-compose.yml" 2>/dev/null; then
+                docker_status="${docker_status}${svc} ✗ "
+            fi
+        fi
+    done
+    docker_status=$(echo "$docker_status" | sed 's/ $//')
+fi
+
+# Alembic migration status (if alembic dir exists)
+if [ -d "$PROJECT_DIR/backend/migrations" ] || [ -d "$PROJECT_DIR/migrations" ] || [ -d "$PROJECT_DIR/alembic" ]; then
+    # Find the venv
+    venv_activate=""
+    for v in "$PROJECT_DIR/backend/.venv/bin/activate" "$PROJECT_DIR/.venv/bin/activate" "$PROJECT_DIR/venv/bin/activate"; do
+        if [ -f "$v" ]; then
+            venv_activate="$v"
+            break
+        fi
+    done
+
+    if [ -n "$venv_activate" ]; then
+        alembic_dir=""
+        for d in "$PROJECT_DIR/backend" "$PROJECT_DIR"; do
+            if [ -f "$d/alembic.ini" ]; then
+                alembic_dir="$d"
+                break
+            fi
+        done
+
+        if [ -n "$alembic_dir" ]; then
+            current=$(cd "$alembic_dir" && source "$venv_activate" && safe_run 3 alembic current 2>/dev/null | head -1 | awk '{print $1}') || true
+            head_rev=$(cd "$alembic_dir" && source "$venv_activate" && safe_run 3 alembic heads 2>/dev/null | head -1 | awk '{print $1}') || true
+            if [ -n "$current" ] && [ -n "$head_rev" ]; then
+                if [ "$current" = "$head_rev" ]; then
+                    alembic_status="✓"
+                else
+                    alembic_status="⚠ pending migrations"
+                fi
+            fi
+        fi
+    fi
+fi
+
+# Railway MCP check (if configured)
+if has_cmd railway; then
+    railway_check=$(safe_run 3 railway whoami 2>&1) || true
+    if echo "$railway_check" | grep -qi "error\|not logged\|unauthenticated"; then
+        mcp_status="Railway: expired (run railway login)"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 4. GitHub context (if gh available — PRs, issues)
+# ---------------------------------------------------------------------------
+
+pr_summary=""
+issue_summary=""
+
+if has_cmd gh && $has_git; then
+    cd "$PROJECT_DIR"
+
+    # My open PRs
+    my_prs=$(safe_run 5 gh pr list --author @me --json number,title,reviewDecision,comments --limit 5 2>/dev/null) || true
+    if [ -n "$my_prs" ] && [ "$my_prs" != "[]" ]; then
+        pr_count=$(echo "$my_prs" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null) || true
+        if [ "${pr_count:-0}" -gt 0 ]; then
+            pr_summary="${pr_count} open PR(s)"
+            # Check for unresolved review comments
+            needs_review=$(echo "$my_prs" | python3 -c "
+import json,sys
+prs=json.load(sys.stdin)
+needs=sum(1 for p in prs if p.get('reviewDecision') in ('CHANGES_REQUESTED',None) and p.get('comments',0)>0)
+if needs: print(f', {needs} need attention')
+" 2>/dev/null) || true
+            pr_summary="${pr_summary}${needs_review}"
+        fi
+    fi
+
+    # My assigned issues
+    my_issues=$(safe_run 5 gh issue list --assignee @me --json number,title --limit 5 2>/dev/null) || true
+    if [ -n "$my_issues" ] && [ "$my_issues" != "[]" ]; then
+        issue_count=$(echo "$my_issues" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null) || true
+        if [ "${issue_count:-0}" -gt 0 ]; then
+            issue_summary="${issue_count} assigned issue(s)"
+        fi
+    fi
+
+    cd - >/dev/null 2>&1 || true
+fi
+
+# ---------------------------------------------------------------------------
+# 5. Active plans
+# ---------------------------------------------------------------------------
+
+active_plan=""
+if [ -d "$PROJECT_DIR/.claude/plans" ]; then
+    plan_files=$(find "$PROJECT_DIR/.claude/plans" -name "*.md" -newer "$PROJECT_DIR/.claude" 2>/dev/null | head -1) || true
+    if [ -n "$plan_files" ]; then
+        active_plan=$(basename "$plan_files")
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Session continuity (previous session detection)
+# ---------------------------------------------------------------------------
+
+session_hint=""
+
+# Check for existing session-state summary (written by /continue skill)
+if [ -f "$PROJECT_DIR/.claude/session-state/latest.md" ]; then
+    # Check if it's less than 7 days old
+    if [ "$(uname)" = "Darwin" ]; then
+        file_age=$(( $(date +%s) - $(stat -f%m "$PROJECT_DIR/.claude/session-state/latest.md") ))
+    else
+        file_age=$(( $(date +%s) - $(stat -c%Y "$PROJECT_DIR/.claude/session-state/latest.md") ))
+    fi
+    if [ "$file_age" -lt 604800 ]; then
+        # Extract first "What Was Done" bullet for a preview
+        preview=$(grep -m1 "^- " "$PROJECT_DIR/.claude/session-state/latest.md" 2>/dev/null | head -c 80) || true
+        if [ -n "$preview" ]; then
+            session_hint="Previous session: ${preview}... — /continue for details"
+        else
+            session_hint="Previous session summary available — /continue for details"
+        fi
+    fi
+fi
+
+# If no session-state, check for recent transcript JSONL
+if [ -z "$session_hint" ]; then
+    TRANSCRIPT_DIR_NAME=$(echo "$PROJECT_DIR" | sed 's|/|-|g')
+    TRANSCRIPT_DIR="$HOME/.claude/projects/${TRANSCRIPT_DIR_NAME}"
+    if [ -d "$TRANSCRIPT_DIR" ]; then
+        # Find the 2nd newest JSONL (newest is current session)
+        prev_transcript=$(ls -t "$TRANSCRIPT_DIR"/*.jsonl 2>/dev/null | sed -n '2p') || true
+        if [ -n "$prev_transcript" ]; then
+            # Check if it's less than 3 days old
+            if [ "$(uname)" = "Darwin" ]; then
+                t_age=$(( $(date +%s) - $(stat -f%m "$prev_transcript") ))
+            else
+                t_age=$(( $(date +%s) - $(stat -c%Y "$prev_transcript") ))
+            fi
+            if [ "$t_age" -lt 259200 ]; then
+                session_hint="Recent session detected — /continue to pick up where you left off"
+            fi
+        fi
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 7. Output — compact briefing (max 6 lines)
+# ---------------------------------------------------------------------------
+
+# Line 1: Project + branch
+line1="📋 ${project_name}"
+if $is_greenfield; then
+    line1="${line1} — new project (no code detected)"
+elif $has_git && [ -n "$branch" ]; then
+    line1="${line1} — ${branch}"
+    [ -n "$ahead_behind" ] && line1="${line1} (${ahead_behind})"
+fi
+echo "$line1"
+
+# Line 2: Red flags (only if there are problems)
+flags=()
+[ -n "$docker_status" ] && echo "$docker_status" | grep -q "✗" && flags+=("Docker: ${docker_status}")
+[ "$alembic_status" = "⚠ pending migrations" ] && flags+=("Alembic: ${alembic_status}")
+[ -n "$mcp_status" ] && flags+=("⚠ ${mcp_status}")
+
+if [ ${#flags[@]} -gt 0 ]; then
+    echo "   $(IFS=' · '; echo "${flags[*]}")"
+fi
+
+# Line 3: Context (uncommitted, plan, last commit)
+context_parts=()
+[ "${uncommitted:-0}" -gt 0 ] && context_parts+=("${uncommitted} uncommitted files")
+[ -n "$active_plan" ] && context_parts+=("Plan: ${active_plan}")
+[ "${stash_count:-0}" -gt 0 ] && context_parts+=("${stash_count} stash(es)")
+
+if [ ${#context_parts[@]} -gt 0 ]; then
+    echo "   $(IFS=' · '; echo "${context_parts[*]}")"
+fi
+
+# Line 4: GitHub context (PRs, issues)
+gh_parts=()
+[ -n "$pr_summary" ] && gh_parts+=("$pr_summary")
+[ -n "$issue_summary" ] && gh_parts+=("$issue_summary")
+
+if [ ${#gh_parts[@]} -gt 0 ]; then
+    echo "   $(IFS=' · '; echo "${gh_parts[*]}")"
+fi
+
+# Line 5: Toolkit status (show what's active)
+toolkit_parts=()
+if [ -f "$PROJECT_DIR/.claude/hooks/triage-router.sh" ] || [ -L "$PROJECT_DIR/.claude/hooks/triage-router.sh" ]; then
+    toolkit_parts+=("Triage router: active")
+fi
+if [ -f "$PROJECT_DIR/.claude/hooks/pre-bash-guard.sh" ] || [ -L "$PROJECT_DIR/.claude/hooks/pre-bash-guard.sh" ]; then
+    toolkit_parts+=("Guard rails: on")
+fi
+if [ ${#toolkit_parts[@]} -gt 0 ]; then
+    echo "   $(IFS=' · '; echo "${toolkit_parts[*]}")"
+fi
+
+# Session continuity hint (if not greenfield)
+if ! $is_greenfield && [ -n "$session_hint" ]; then
+    echo "   $session_hint"
+fi
+
+# Greenfield hint
+if $is_greenfield; then
+    echo "   Tip: describe what you're building, or type /onboard for guided setup"
+fi
+
+# Calibration hint — show for brownfield projects that haven't been calibrated
+if ! $is_greenfield; then
+    if [ ! -f "$PROJECT_DIR/.claude/project-profile.md" ]; then
+        # Only show if calibrate skill is installed
+        if [ -d "$PROJECT_DIR/.claude/skills/calibrate" ] || [ -L "$PROJECT_DIR/.claude/skills/calibrate" ]; then
+            echo "   Tip: run /calibrate to deep-learn your project and configure MCP servers + agents"
+        fi
+    else
+        # Check knowledge base change detection for drift
+        CHANGE_DETECT="$PROJECT_DIR/.claude/knowledge/meta/change-detection.md"
+        if [ -f "$CHANGE_DETECT" ]; then
+            drift_found=false
+            for keyfile in package.json requirements.txt pyproject.toml docker-compose.yml Podfile Package.swift build.gradle pubspec.yaml; do
+                if [ -f "$PROJECT_DIR/$keyfile" ]; then
+                    current_hash=$(shasum -a 256 "$PROJECT_DIR/$keyfile" 2>/dev/null | cut -c1-8)
+                    stored_hash=$(grep "$keyfile" "$CHANGE_DETECT" 2>/dev/null | awk '{print $4}' | head -1)
+                    if [ -n "$stored_hash" ] && [ -n "$current_hash" ] && [ "$stored_hash" != "$current_hash" ]; then
+                        drift_found=true
+                        break
+                    fi
+                fi
+            done
+            if $drift_found; then
+                echo "   ⚠ Project files changed since last calibration — run /calibrate rescan"
+            fi
+        fi
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 8. Write project state cache (other hooks read this instead of re-computing)
+# ---------------------------------------------------------------------------
+
+CACHE_FILE="$PROJECT_DIR/.claude/.project-state-cache.json"
+_cache_json=$(cat <<CACHE_EOF
+{
+  "timestamp": $(date +%s),
+  "project_name": "$project_name",
+  "is_greenfield": $is_greenfield,
+  "has_git": $has_git,
+  "branch": "${branch:-}",
+  "uncommitted": ${uncommitted:-0},
+  "ahead_behind": "${ahead_behind:-}",
+  "stash_count": ${stash_count:-0},
+  "docker_status": "${docker_status:-}",
+  "alembic_status": "${alembic_status:-}",
+  "mcp_status": "${mcp_status:-}",
+  "active_plan": "${active_plan:-}"
+}
+CACHE_EOF
+)
+echo "$_cache_json" > "$CACHE_FILE" 2>/dev/null || true