@arthai/agents 1.0.0

package/dist/plugins/spark/skills/onboard/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: onboard
+description: "Session onboarding — project briefing, work prioritization, and guided setup. Usage: /onboard"
+user-invocable: true
+arguments: ""
+---
+
+# Onboard Skill — Session Start Intelligence
+
+Helps users get oriented at the start of a session. Detects project state, gathers
+deep context, and suggests what to work on — prioritized by the nature of the project.
+Works for both greenfield and brownfield projects.
+
+**Key principle: Do the legwork, don't be pushy.** Gather context silently, present a
+clear picture, let the user drive.
+
+## Execution Steps
+
+### 1. Detect Project State
+
+Check these signals to determine greenfield vs brownfield:
+
+| Signal | Greenfield | Brownfield |
+|--------|-----------|------------|
+| `CLAUDE.md` exists | No | Yes |
+| Source code dirs (`src/`, `app/`, `backend/`, `frontend/`) | None | Present |
+| `package.json` or `requirements.txt` | None | Present |
+| Git history | 0-2 commits | Many commits |
+| `.claude/plans/` has files | No | Maybe |
+
+### 2A. Greenfield Flow
+
+If the project is greenfield (no meaningful code):
+
+1. Ask the user ONE question using AskUserQuestion:
+   - "What are you building? (1-2 sentences — what it does and who it's for)"
+
+2. Based on their answer, suggest a tech stack:
+   - Check if any config files hint at preferences (empty `package.json`, `requirements.txt`, etc.)
+   - Suggest a stack that matches their description
+   - Ask them to confirm or adjust
+
+3. Take action:
+   - Run `/scan` to scaffold CLAUDE.md with detected/chosen stack
+   - Create a project plan via `/planning` if the feature is non-trivial
+   - Or scaffold directly if it's simple enough
+
+4. Present next steps:
+   - "Project scaffolded. Run `/planning <feature>` to plan your first feature."
+   - "Or just tell me what to build and I'll get started."
+
+### 2B. Brownfield Flow
+
+If the project has existing code:
+
+#### Step 0: Toolkit Update Check (ALWAYS run first)
+
+Check if the claude-agents toolkit has been updated since this project last synced.
+This is the ONLY reliable way to surface toolkit changes to the user — hook stdout
+is unreliable (known Claude Code bugs #13650, #27467 cause silent drops).
+
+```bash
+# Read the per-project last-seen SHA
+TOOLKIT_DIR="$HOME/.claude-agents"
+LAST_SEEN_FILE=".claude/.toolkit-last-seen-sha"
+CURRENT_SHA=$(cd "$TOOLKIT_DIR" && git rev-parse HEAD 2>/dev/null)
+LAST_SEEN_SHA=$(cat "$LAST_SEEN_FILE" 2>/dev/null || echo "")
+
+# Compare — if different, toolkit has changed since last session
+if [ -n "$LAST_SEEN_SHA" ] && [ -n "$CURRENT_SHA" ] && [ "$LAST_SEEN_SHA" != "$CURRENT_SHA" ]; then
+    # Get commit count and details
+    cd "$TOOLKIT_DIR"
+    COMMIT_COUNT=$(git rev-list --count "$LAST_SEEN_SHA..$CURRENT_SHA" 2>/dev/null || echo "0")
+    CHANGELOG=$(git log --format="  • %s" "$LAST_SEEN_SHA..$CURRENT_SHA" 2>/dev/null | grep -iE "feat:|fix:|breaking:|new:" | head -5)
+    NEW_SKILLS=$(git diff --diff-filter=A --name-only "$LAST_SEEN_SHA..$CURRENT_SHA" -- "skills/*/SKILL.md" 2>/dev/null | sed 's|skills/||;s|/SKILL.md||' | tr '\n' ', ' | sed 's/,$//')
+    UPDATED_AGENTS=$(git diff --diff-filter=M --name-only "$LAST_SEEN_SHA..$CURRENT_SHA" -- "agents/*.md" 2>/dev/null | sed 's|agents/||;s|\.md||' | tr '\n' ', ' | sed 's/,$//')
+fi
+
+# Also check if project hasn't been calibrated yet
+HAS_PROFILE=false
+[ -f ".claude/project-profile.md" ] && HAS_PROFILE=true
+```
+
+**If toolkit has changes, show them FIRST in the briefing:**
+
+```
+🔧 Toolkit updated ({COMMIT_COUNT} new commits since last session)
+{CHANGELOG}
+{if NEW_SKILLS: "  New skills: {NEW_SKILLS}"}
+{if UPDATED_AGENTS: "  Updated agents: {UPDATED_AGENTS}"}
+```
+
+**If project hasn't been calibrated, show the hint:**
+
+```
+💡 This project hasn't been calibrated yet. Run /calibrate to deep-learn your
+   codebase and configure MCP servers, agents, and workflows.
+```
+
+**After showing, update the stored SHA:**
+
+```bash
+echo "$CURRENT_SHA" > ".claude/.toolkit-last-seen-sha"
+```
+
+#### Step 1: Deep Context Gathering (no user interaction — run ALL of these)
+
+Use **parallel tool calls** where possible to gather all context fast.
+
+**Git state (local — fast)**:
+```bash
+git branch --show-current
+git status --short
+git log --oneline -20                    # recent commits for work history
+git log --oneline --since="3 days ago"   # what happened since last session
+git stash list
+git branch -a --sort=-committerdate | head -10  # recent branches
+```
+
+**GitHub state (if `gh` available)**:
+
+**Step 1 — fast list (run all in parallel):**
+```bash
+# My open PRs — NO comments field (bot comments are huge HTML and cause errors)
+gh pr list --author @me --json number,title,state,reviewDecision,updatedAt,headRefName,labels --limit 10
+
+# PRs requesting my review (--review-requested is NOT a valid flag; use --search)
+gh pr list --search "review-requested:@me" --json number,title,author,createdAt --limit 5
+
+# My assigned issues — get labels for prioritization
+gh issue list --assignee @me --json number,title,labels,createdAt,updatedAt --limit 10
+
+# Recent merged PRs (context on what shipped recently)
+gh pr list --state merged --limit 5 --json number,title,mergedAt,author
+
+# Open issues (unassigned — available to pick up)
+gh issue list --json number,title,labels,assignees --limit 10
+```
+
+**Step 2 — fetch comment details for PRs that need attention:**
+
+IMPORTANT: After Step 1, for each PR with `reviewDecision: CHANGES_REQUESTED`
+or updated in the last 3 days, fetch its comments individually. This avoids
+pulling massive bot comments in bulk while still getting the detail you need.
+
+```bash
+# Run ONE per PR that needs attention (replace <NUMBER> with actual PR number):
+gh pr view <NUMBER> --json comments,reviews --jq '{
+  comments: [.comments[] | {author: .author.login, age: .createdAt, body: .body[0:200]}] | .[-3:],
+  reviews: [.reviews[] | {author: .author.login, state: .state, body: .body[0:200]}] | .[-3:]
+}'
+```
+
+This gives you: who commented, when, and the first 200 chars of each comment.
+Include these details in the 🟡 Waiting on you section of the briefing.
+
+**Project state**:
+```bash
+ls .claude/plans/*.md                    # active plans
+cat CLAUDE.md | head -5                  # project identity
+```
+
+**Environment health** (read CLAUDE.md `## Environments` table):
+
+If the `## Environments` section exists in CLAUDE.md, validate each environment:
+
+```bash
+# For EACH environment in the Environments table:
+
+# Type: development (local)
+docker ps --format '{{.Names}} {{.Status}}'          # container health
+curl -sf {URL}{Health} > /dev/null && echo "✓" || echo "✗"  # local health endpoint
+# Check migration status (Alembic/Prisma/Drizzle — detect from project)
+ls .env.local > /dev/null 2>&1                        # env file exists
+
+# Type: staging
+curl -sf {URL}{Health} -o /dev/null -w "%{http_code}" # health endpoint
+# Check deploy platform accessibility (Railway MCP query, vercel whoami, etc.)
+
+# Type: production (READ-ONLY — never run mutations)
+curl -sf {URL}{Health} -o /dev/null -w "%{http_code}" # health endpoint only
+```
+
+**Fallback**: If no `## Environments` section exists in CLAUDE.md (project not yet calibrated), fall back to basic checks:
+```bash
+docker ps --format '{{.Names}} {{.Status}}'   # container health
+ls .env.local > /dev/null 2>&1                # env file exists
+# Check node_modules / venv freshness
+```
+
+Include environment status in the briefing output. Add to the existing tier format:
+
+In **🔴 Fix first** tier, add environment failures:
+```
+🔴 Fix first:
+   local — postgres container stopped
+     → Run: docker compose up -d postgres
+   staging — health check failed (503 at https://staging.myapp.com/health)
+     → Check: Railway dashboard or run /sre logs staging
+```
+
+When all environments are healthy, show as a compact status line before the tiers:
+```
+Environments: local ✓ | staging ✓ | production ✓
+```
+
+#### Step 2: Analyze & Prioritize
+
+Read the project's CLAUDE.md to understand the **nature of the project** and use that
+to weight priorities. Different projects care about different things:
+
+| Project Nature | Higher Priority | Lower Priority |
+|----------------|----------------|----------------|
+| Production app (users depend on it) | Prod bugs, failing CI, security issues | Feature requests, tech debt |
+| Early-stage startup | New features, user feedback | Test coverage, docs |
+| Internal tool | Requested features, reliability | Polish, edge cases |
+| Library/SDK | Breaking changes, test failures | New features |
+| CLI tool | UX bugs, install issues | Performance |
+
+**Smart prioritization rules**:
+- Issues with labels like `bug`, `critical`, `urgent`, `P0`, `security` → always 🔴
+- Issues with labels like `feature`, `enhancement` → 🔵 or ⚪ depending on age
+- Stale PRs (no activity > 7 days) → escalate to 🟡
+- PRs with `CHANGES_REQUESTED` → 🟡 (someone is waiting)
+- Branches with work but no PR → might be abandoned or mid-feature
+
+#### Step 3: Build the Briefing
+
+Organize findings into 4 tiers — **only show tiers that have items**:
+
+**🔴 Fix first** (blocking — things that prevent work):
+- Docker containers expected but not running
+- Migration mismatch (local behind head)
+- CI/CD failing on current branch
+- MCP servers disconnected
+- Critical bugs in production
+- Security issues
+
+**🟡 Waiting on you** (aging — things others are waiting for):
+- PR review comments unaddressed > 24h (show who commented, when)
+- PRs requesting your review (show author, title, age)
+- Issues assigned with approaching deadlines
+- Stale PRs with no activity > 7 days (show PR number, title, days stale)
+
+**🔵 Continue** (continuity — what you were doing last):
+- Uncommitted changes (you were mid-work) — list the files changed
+- Active plan file (you were mid-feature) — show which step
+- Current branch != main (you were on a feature) — show branch purpose
+- Recent commits that suggest in-progress work
+- Last session's work summary (group recent commits by area)
+
+**⚪ Available** (opportunity — things you could pick up):
+- Open issues nobody's assigned to (prioritized by label/nature)
+- PRs from teammates that need review
+- Next phase of an active plan
+- Recently merged PRs that might need follow-up (docs, tests, cleanup)
+
+#### Step 4: Present the Briefing
+
+Format as a structured message with actionable detail:
+
+```
+Here's where things stand:
+
+🔴 Fix first:
+   Docker redis is stopped — backend cache won't connect
+   → Run: docker compose up -d redis
+
+🟡 Waiting on you:
+   PR #245 "Fix auth token refresh" — 2 unresolved comments from @motred (3 days ago)
+      Last comment: "Need to handle the edge case where token is expired but refresh fails"
+   PR #251 by @teammate needs your review (opened 2 days ago)
+      "Add rate limiting to API endpoints"
+
+🔵 Continue from last session:
+   Branch: feature/oauth-support (3 uncommitted files: auth.ts, login.tsx, test_auth.py)
+   Plan: oauth-support.md — Step 3/5 (implementing token refresh)
+   Last commits:
+     • 2h ago: "add refresh token endpoint"
+     • 5h ago: "implement token storage in context"
+
+⚪ Available to pick up:
+   Issue #89 "Add password reset flow" (bug, assigned to nobody, 5 days old)
+   Issue #92 "Update onboarding copy" (enhancement, unassigned, 2 days old)
+   Plan: golden-dataset-pipeline.md — Phase 5 not started
+
+What would you like to tackle?
+
+🛠 Available workflows:
+  /planning <feature> → /implement → /qa → /review-pr → /pr     Feature development
+  /fix <bug|#issue>   → /review-pr → /pr                        Bug fix (formal pipeline)
+  /fix --hotfix       → /pr                                      Critical bug (expedited)
+  /calibrate                                                     Deep-learn project (first time)
+  /autopilot                                                     Autonomous work loop
+  /qa [full|staging|prod]                                        Run QA checks
+  /review-pr [#N]                                                Review a PR
+  /incident <description>                                         Something broken? Auto-triage + route
+  /ci-fix                                                        Fix failing CI
+  /sre [status|debug|deploy-check]                               SRE operations
+```
+
+**Key formatting rules**:
+- Show PR/issue numbers so user can reference them
+- Show who is waiting and how long (creates urgency naturally)
+- Show file names for uncommitted changes (reminds user what they were doing)
+- Show plan progress as "Step X/Y" or "Phase X"
+- Group recent commits by feature area (auth, billing, UI, etc.)
+- For stale PRs, show how many days since last activity
+- Include actionable next steps where obvious (run commands, review links)
+
+#### Step 5: Route Based on User's Choice
+
+- If user picks a red flag → route to ops agent or provide the fix command
+- If user picks a PR → route to code-reviewer or read the PR comments
+- If user picks continuing work → read the plan, route to appropriate agent
+- If user picks an issue → read the issue, route to /planning or direct fix
+- If user says "just fix the red flags" → fix them all, then re-present
+- If user says something specific → hand off to normal triage
+
+### 3. Edge Cases
+
+- **No git repo**: Skip all git/GitHub context. Just check for code files.
+- **No GitHub CLI**: Skip PR/issue context. Show git-only state.
+- **No Docker**: Skip container health. Show other context.
+- **User interrupts**: If user types something specific at any point, stop
+  onboarding and let triage handle their request normally.
+- **Nothing to report**: If everything is clean (main branch, no uncommitted,
+  no PRs, no issues), just say "Everything looks clean. What would you like to work on?"
+- **Too much to show**: If there are 10+ items across tiers, show top 3 per tier
+  and note "X more items — ask to see full list"
+
+## Rules
+
+- **Max 1 question** before presenting findings (brownfield: 0 questions)
+- **Never auto-start work** — always present and let user choose
+- **Degrade gracefully** — if a tool is missing, skip that context source
+- **Respect user's time** — if they have a specific task, get out of the way
+- **Toolkit updates go first** — always run Step 0 and show toolkit changes before
+  the project briefing. This is the only reliable way users see what changed.
+- **Calibration hint** — if `.claude/project-profile.md` doesn't exist, always show
+  the `/calibrate` hint. Don't skip it.
+- **Show the PR/issue content** — don't just count them, summarize what they're about
+- **Prioritize by project nature** — read CLAUDE.md to understand what matters most
+- **Use parallel tool calls** — gather all context sources simultaneously for speed

package/dist/plugins/spark/skills/scan/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: scan
+description: "Scan codebase and auto-populate CLAUDE.md with project context (services, ports, test commands, infrastructure). Usage: /scan [section]"
+user-invocable: true
+arguments: "<section>"
+---
+
+# Codebase Scanner
+
+Scans the project and populates CLAUDE.md with structured sections that agents read at runtime. This is how generic agents learn your specific project.
+
+## When This Runs
+
+- **First install**: `install.sh --setup` triggers a scan automatically
+- **On demand**: User runs `/scan` to refresh after codebase changes
+- **Targeted**: `/scan services` to only update the Local Dev Services section
+
+## What Gets Scanned
+
+### 1. Local Dev Services
+
+Detect running services and their configuration:
+
+```bash
+# Check for frontend frameworks
+if [ -f "frontend/package.json" ] || [ -f "package.json" ]; then
+    # Read scripts.dev from package.json
+    # Detect framework: Next.js (port 3000), Vite (5173), CRA (3000), Vue (5173)
+fi
+
+# Check for backend frameworks
+if [ -f "backend/requirements.txt" ] || [ -f "requirements.txt" ]; then
+    # Detect FastAPI/Django/Flask
+    # Default ports: FastAPI 8000, Django 8000, Flask 5000
+fi
+if [ -f "backend/pyproject.toml" ]; then
+    # Read [tool.poetry] or [project] for framework hints
+fi
+
+# Check docker-compose.yml for service definitions
+if [ -f "docker-compose.yml" ] || [ -f "docker-compose.yaml" ]; then
+    # Extract service names, ports, build contexts
+fi
+
+# Check for Procfile (Heroku/Railway)
+if [ -f "Procfile" ]; then
+    # Extract web/worker commands
+fi
+```
+
+Output the **Local Dev Services** table:
+
+```markdown
+## Local Dev Services
+
+| Service  | Port | Directory | Start Command |
+|----------|------|-----------|---------------|
+| Frontend | 3000 | frontend/ | cd frontend && npm run dev |
+| Backend  | 8000 | backend/  | cd backend && source .venv/bin/activate && uvicorn app.main:app --reload --port 8000 |
+```
+
+### 2. Test Commands
+
+Detect test frameworks and commands:
+
+```bash
+# Python tests
+# Look for: pytest.ini, setup.cfg [tool:pytest], pyproject.toml [tool.pytest]
+# Check for: ruff.toml, .flake8, mypy.ini
+
+# JavaScript/TypeScript tests
+# Look for: jest.config.*, vitest.config.*, playwright.config.*, cypress.config.*
+# Read package.json scripts: test, lint, type-check, build
+```
+
+Output the **Test Commands** table:
+
+```markdown
+## Test Commands
+
+| What | Command | Directory |
+|------|---------|-----------|
+| Backend tests | pytest | backend/ |
+| Backend lint | ruff check . | backend/ |
+| Frontend tests | npm test | frontend/ |
+| Frontend lint | npm run lint | frontend/ |
+| Type check | npx tsc --noEmit | frontend/ |
+| E2E tests | npx playwright test | frontend/ |
+```
+
+### 3. Infrastructure
+
+Detect deployment configuration:
+
+```bash
+# Railway
+[ -f "railway.json" ] || [ -f "railway.toml" ]
+
+# Vercel
+[ -f "vercel.json" ] || [ -f ".vercel/project.json" ]
+
+# Fly.io
+[ -f "fly.toml" ]
+
+# AWS
+[ -d ".aws" ] || [ -f "samconfig.toml" ] || [ -f "serverless.yml" ]
+
+# Docker/Kubernetes
+[ -f "Dockerfile" ] || [ -d "k8s" ]
+
+# GitHub Actions
+ls .github/workflows/*.yml 2>/dev/null
+```
+
+Output the **Infrastructure** table:
+
+```markdown
+## Infrastructure
+
+| Platform | Service | Notes |
+|----------|---------|-------|
+| Railway | backend, frontend | Auto-deploy on push to main |
+| GitHub Actions | CI/CD | Lint, test, deploy |
+
+Health endpoints: /health, /api/health
+```
+
+### 4. Domain
+
+Scan for domain entities and business rules:
+
+```bash
+# Look for model files
+# SQLAlchemy: models/*.py, models.py
+# Django: */models.py
+# Prisma: prisma/schema.prisma
+# TypeORM: entities/*.ts
+
+# Look for enum/status definitions
+# State machines, workflow logic
+```
+
+Output the **Domain** section:
+
+```markdown
+## Domain
+
+{App name} is a {detected description} with the following core entities:
+- {Entity1} (statuses: {enum values})
+- {Entity2}
+
+Business rules detected:
+- {Rule from enum constraints, validators, etc.}
+```
+
+### Section 5: Environments
+
+Detect project environments and populate the `## Environments` section in CLAUDE.md.
+
+**Detection steps:**
+
+1. Scan for `.env.*` files in project root:
+   ```bash
+   ls .env.* 2>/dev/null | grep -v '.env.example' | grep -v '.env.local'
+   ```
+   Extract environment names from suffixes (`.env.staging` → staging, `.env.production` → production).
+
+2. Scan CI/CD configs for deploy targets:
+   ```bash
+   # GitHub Actions
+   grep -r 'environment:' .github/workflows/*.yml 2>/dev/null | grep -oP 'environment:\s*\K\w+'
+   ```
+
+3. Scan deploy platform configs:
+   - `railway.json` → Railway environments
+   - `vercel.json` → preview + production
+   - `fly.toml` / `fly.*.toml` → Fly.io environments
+   - Terraform `environments/` directories
+
+4. ALWAYS include `local` as `development` environment using data from Local Dev Services table.
+
+5. For each environment, populate:
+   - **Name**: environment identifier
+   - **Type**: `development` | `staging` | `production` | `preview` | `canary`
+   - **URL**: from env files, deploy config, or `<!-- TODO -->`
+   - **Health**: from Infrastructure section health endpoints or `<!-- TODO -->`
+   - **Deploy**: trigger method (manual, branch push, CI/CD)
+   - **Branch**: associated git branch or `—`
+
+**Output format in CLAUDE.md:**
+
+```markdown
+## Environments
+
+| Name | Type | URL | Health | Deploy | Branch |
+|------|------|-----|--------|--------|--------|
+| local | development | http://localhost:{port} | /health | manual | — |
+| {name} | {type} | {url} | {health} | {deploy} | {branch} |
+
+Access notes: {platform details, env var file locations}
+```
+
+**If no remote environments detected:** Write only the local row with a comment:
+```markdown
+<!-- No remote environments detected. Run /calibrate for full discovery with platform MCP queries. -->
+```
+
+## How It Updates CLAUDE.md
+
+1. Read existing CLAUDE.md
+2. For each section being updated:
+   - If the section exists with `<!-- TODO: -->` placeholders → replace with scanned data
+   - If the section exists with real content → **DO NOT overwrite** (user has customized it)
+   - If the section doesn't exist → append it
+3. Write back the updated CLAUDE.md
+
+**CRITICAL**: Never overwrite sections that the user has already filled in. Only populate empty/placeholder sections.
+
+## Arguments
+
+| User Input | Action |
+|-----------|--------|
+| `/scan` | Full scan — all 5 sections |
+| `/scan services` | Only scan and update Local Dev Services |
+| `/scan tests` | Only scan and update Test Commands |
+| `/scan infra` | Only scan and update Infrastructure |
+| `/scan domain` | Only scan and update Domain |
+| `/scan environments` | Only scan and update Environments |
+
+## If No CLAUDE.md Exists
+
+Create one from the template at `~/.claude-agents/templates/CLAUDE.md.template`, then populate it with scanned data.