@arthai/agents 1.0.0

package/dist/plugins/prime/skills/sre/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: sre
+description: "Run SRE operations. Usage: /sre [command]. Commands: status, health, logs, deploy-check, ci, sleep, wake, debug, rebuild, dialog"
+user-invocable: true
+arguments: "<command> <options>"
+---
+
+# SRE Skill
+
+Wraps the SRE agent for infrastructure operations. Reads project context from CLAUDE.md to route to the right tools.
+
+## Project Context Discovery (Deep)
+
+Before ANY operation, discover the full infrastructure landscape. This runs on every /sre invocation
+to ensure context is current.
+
+### Step 1: Read existing context
+
+Read in this order (skip gracefully if missing):
+1. `CLAUDE.md` — Infrastructure table, services, health endpoints
+2. `.claude/project-profile.md` — Architecture, deploy platform (from /calibrate)
+3. `.claude/knowledge/agents/sre.md` — Past incidents, platform patterns learned
+4. `.claude/knowledge/shared/decisions.md` — Infrastructure decisions made
+5. `.claude/qa-knowledge/incidents/` — Past production incidents
+
+### Step 2: Detect deploy platform (if not in profile)
+
+Scan project files to identify the FULL infrastructure stack:
+
+**Cloud Provider Detection:**
+| Signal | Provider | What to check |
+|--------|----------|--------------|
+| `AWS_*` env vars, `~/.aws/`, `samconfig.toml`, `cdk.json` | AWS | Regions, services, IAM roles |
+| `GOOGLE_*` env vars, `app.yaml`, `cloudbuild.yaml` | GCP | Projects, regions, services |
+| `AZURE_*` env vars, `azure-pipelines.yml` | Azure | Subscriptions, resource groups |
+
+**Platform Detection:**
+| Signal | Platform | CLI | MCP Available |
+|--------|----------|-----|--------------|
+| `railway.json`, `railway.toml`, `Procfile` | Railway | `railway` | Railway MCP |
+| `vercel.json`, `.vercel/` | Vercel | `vercel` | Vercel MCP |
+| `fly.toml` | Fly.io | `flyctl` | — |
+| `render.yaml` | Render | `render` | — |
+| `heroku.yml`, `Procfile` + Heroku remote | Heroku | `heroku` | — |
+| `netlify.toml` | Netlify | `netlify` | — |
+| `terraform/`, `*.tf` | Terraform (IaC) | `terraform` | AWS/GCP MCP |
+| `pulumi/`, `Pulumi.yaml` | Pulumi (IaC) | `pulumi` | AWS/GCP MCP |
+| `cdk/`, `cdk.json` | AWS CDK | `cdk` | AWS MCP |
+| `k8s/`, `helm/`, `Chart.yaml`, `kustomize/` | Kubernetes | `kubectl`, `helm` | K8s MCP |
+| `docker-compose.yml` + no platform | Docker only | `docker` | Docker MCP |
+| `serverless.yml` | Serverless Framework | `sls` | AWS/GCP MCP |
+| `firebase.json` | Firebase | `firebase` | Firebase MCP |
+| `supabase/config.toml` | Supabase | `supabase` | Supabase MCP |
+
+**Database Detection:**
+| Signal | Database | Monitoring |
+|--------|----------|-----------|
+| `DATABASE_URL` contains `postgres` | PostgreSQL | pg_stat, connection pool health |
+| `DATABASE_URL` contains `mysql` | MySQL | slow query log, connection health |
+| `MONGODB_URI` | MongoDB | mongosh status, replica set health |
+| `REDIS_URL` | Redis | `redis-cli info`, memory, connections |
+| `ELASTICSEARCH_URL` | Elasticsearch | cluster health, index status |
+
+**Monitoring/Observability Detection:**
+| Signal | Tool | What it provides |
+|--------|------|-----------------|
+| `SENTRY_DSN` or `@sentry/` import | Sentry | Error tracking, performance |
+| `DATADOG_*` env vars | Datadog | APM, logs, metrics |
+| `NEW_RELIC_*` env vars | New Relic | APM, infrastructure |
+| `GRAFANA_*` or `grafana/` | Grafana | Dashboards, alerting |
+| `PROMETHEUS_*` or `prometheus/` | Prometheus | Metrics collection |
+| `PAGERDUTY_*` env vars | PagerDuty | Incident management |
+| `OPSGENIE_*` env vars | OpsGenie | Alert routing |
+
+**CI/CD Detection (used by /ci-fix but discovered here for completeness):**
+| Signal | CI Platform | CLI |
+|--------|------------|-----|
+| `.github/workflows/` | GitHub Actions | `gh run` |
+| `.gitlab-ci.yml` | GitLab CI | `glab ci` |
+| `Jenkinsfile` | Jenkins | Jenkins API |
+| `.circleci/config.yml` | CircleCI | `circleci` CLI |
+| `bitbucket-pipelines.yml` | Bitbucket Pipelines | Bitbucket API |
+| `.buildkite/` | Buildkite | `buildkite-agent` |
+| `azure-pipelines.yml` | Azure DevOps | `az pipelines` |
+| `.travis.yml` | Travis CI | Travis API |
+
+### Step 3: Recommend missing tools
+
+Based on what was detected, recommend tools the project SHOULD have:
+
+**Format:**
+```
+SRE Recommendations for {project}:
+
+Platform: {detected platform}
+Database: {detected databases}
+Monitoring: {detected or MISSING}
+CI/CD: {detected CI platform}
+
+Missing (recommended):
+  ⚠ No monitoring detected — recommend Sentry (free tier, 5K errors/mo)
+    Install: pip install sentry-sdk / npm install @sentry/node
+  ⚠ No Redis health monitoring — recommend redis-cli in health checks
+  ⚠ No MCP server for {platform} — would enable direct platform queries
+    /calibrate can install this automatically
+
+Data sources to connect:
+  • {platform} logs → available via {CLI/MCP}
+  • {database} metrics → available via {query/MCP}
+  • {monitoring tool} alerts → available via {API/MCP}
+  • Health endpoints: {list from CLAUDE.md or recommend adding}
+```
+
+### Step 4: Write discoveries to knowledge base
+
+After discovery, update these files (if `.claude/knowledge/` exists):
+- Append to `knowledge/agents/sre.md`: platform detected, services found, health endpoints
+- If first time: create the file with initial platform context
+
+## Argument Parsing
+
+Parse from the argument string:
+- `command`: Optional. One of: `status`, `health`, `logs`, `deploy-check`, `ci`, `sleep`, `wake`, `debug`, `rebuild`, `dialog`. Defaults to `status` if omitted.
+- Options vary by command (see below).
+
+## Commands
+
+### `/sre` or `/sre status`
+Full system status — all services, all environments.
+
+Spawn SRE agent:
+```
+subagent_type: "sre"
+model: "sonnet"
+prompt: "Run a full status check. Read CLAUDE.md ## Environments table. For each environment, check status using the appropriate method from the Access Methods table in project-profile.md.
+1. Check deployment platform service status (Railway MCP, Vercel CLI, etc.)
+2. Hit all health endpoints listed in CLAUDE.md
+3. Check latest GitHub Actions: gh run list --branch main --limit 3
+Report a structured pass/fail table."
+```
+
+### `/sre health`
+Quick health check — just hit endpoints.
+
+Spawn SRE agent:
+```
+subagent_type: "sre"
+model: "sonnet"
+prompt: "Quick health check. Read CLAUDE.md ## Environments table. Hit the health endpoint for every listed environment (URL + Health column). Report pass/fail per environment. Skip environments with <!-- TODO --> URLs."
+```
+
+### `/sre logs [service]`
+View recent deploy logs. Default service: first service in Infrastructure table.
+
+Spawn SRE agent:
+```
+subagent_type: "sre"
+model: "sonnet"
+prompt: "Get recent deploy logs for '{service or default}'. Read CLAUDE.md for infrastructure details. Use platform-appropriate tools (Railway MCP, Vercel CLI, etc.). Filter for errors and summarize issues found."
+```
+
+### `/sre deploy-check`
+Verify latest deployment succeeded end-to-end.
+
+Spawn SRE agent:
+```
+subagent_type: "sre"
+model: "sonnet"
+prompt: "Full deployment verification. Read CLAUDE.md for infrastructure.
+1. Check recent CI runs: gh run list --branch main --limit 5
+2. Check deployment platform for latest deploys
+3. Hit all health endpoints
+4. Compare migration state if applicable
+Report structured pass/fail for each step."
+```
+
+### `/sre ci`
+Check CI/CD pipeline status and diagnose failures.
+
+Spawn SRE agent:
+```
+subagent_type: "sre"
+model: "sonnet"
+prompt: "Check CI/CD status:
+1. gh run list --branch main --limit 5
+2. If any failed: gh run view <id> --log-failed
+3. Report which workflows passed/failed, failure details, suggested fixes."
+```
+
+### `/sre sleep`
+Sleep staging to save costs (platform-specific).
+
+Spawn SRE agent:
+```
+subagent_type: "sre"
+model: "sonnet"
+prompt: "Sleep the specified environment (default: first staging-type environment from CLAUDE.md ## Environments table). Read CLAUDE.md for environment details. Use platform-appropriate commands. Verify services scaled to 0. Report estimated savings."
+```
+
+### `/sre wake`
+Wake staging environment.
+
+Spawn SRE agent:
+```
+subagent_type: "sre"
+model: "sonnet"
+prompt: "Wake the specified environment (default: first staging-type environment from CLAUDE.md ## Environments table). Read CLAUDE.md for environment details. Use platform-appropriate commands. Wait for health checks to pass. Report status."
+```
+
+### `/sre debug [description]`
+Systematic debugging of a production issue.
+
+Spawn SRE agent:
+```
+subagent_type: "sre"
+model: "sonnet"
+prompt: "Debug this issue: '{description}'. Read CLAUDE.md for infrastructure.
+Read CLAUDE.md ## Environments table. For each environment, check status using the appropriate
+method from the Access Methods table in project-profile.md.
+
+Systematic approach:
+1. CONFIRM — check health endpoints + metrics for all environments in the Environments table
+2. SCOPE — which service(s) and environment(s) affected?
+3. DIAGNOSE — RED method (Rate/Errors/Duration) for API, USE method (Utilization/Saturation/Errors) for infra
+4. Check deployment logs for errors
+5. Check GitHub Actions for recent failures
+6. ROOT CAUSE — what specifically caused the issue?
+7. CLASSIFY FIX TYPE — determine if this is:
+   a. Infra-only fix (restart, config change, scale, DNS) → fix directly, verify health
+   b. Code bug → escalate to /fix (do NOT fix code directly — /fix has verification pipeline)
+8. IF INFRA FIX:
+   - Apply the fix (restart, config change, etc.)
+   - Verify health endpoints for affected environments
+   - Ask user to smoke-test if config was changed
+   - Write incident report
+9. IF CODE BUG:
+   - Document findings (root cause, affected files, evidence)
+   - Escalate to /fix with all context — /fix will handle QA, testing, and PR
+   - Do NOT write code or create PRs from /sre debug
+
+After root cause is identified, also write a QA incident file at
+.claude/qa-knowledge/incidents/{YYYY-MM-DD}-{slug}.md with root cause, how QA missed it, and regression test recommendation."
+```
+
+**Post-debug handoff:**
+
+After `/sre debug` completes:
+
+| Fix type | What happens next |
+|----------|------------------|
+| Infra fix applied | Verify health → ask user to smoke-test → "What's next?" |
+| Code bug identified | Route to `/fix {description} --severity {severity}` with all gathered evidence. `/fix` handles: root cause verification → scope lock → behavior contract → implement → QA → user test → PR |
+| Inconclusive | Present findings → ask user: "Should I investigate further, or route to /fix?" |
+
+**What's next (after infra fix):**
+```
+Fix applied and verified. Environments healthy.
+
+What's next?
+  [1] Monitor — /sre health in 5 min to confirm fix holds
+  [2] Investigate further — check related systems
+  [3] See project status — /onboard
+  [4] Done for now
+```
+
+### `/sre dialog`
+Analyze the latest local agent interview dialog. Checks verbosity, Q-tag leaks, NOTES leaks, and TTS filter activity.
+
+**Do NOT spawn an agent.** Run directly:
+
+1. Read `/tmp/agent.log`
+2. Extract all `Agent said:` lines (deduplicate — each appears twice in logs)
+3. Report:
+
+```
+## Interview Dialog Analysis
+
+| # | Turn | Response (truncated) | Words | Chars |
+|---|------|---------------------|-------|-------|
+| 1 | Intro | "Hi! I'm Sarah..." | 37 | 186 |
+| 2 | Reaction | "Great answer!..." | 12 | 58 |
+...
+
+**Verbosity**: avg X words/turn (target: <40, Feb 8 baseline: 15-20)
+**Q-tag leaks**: [Q1]-[Q5] found in raw output? YES/NO
+**NOTES leaks**: [NOTES] blocks in raw output? YES/NO
+**TTS filter**: [TTS-FILTER] log entries found? (shows filter activity)
+**Truncation**: Any responses cut off mid-sentence? (sign of token limit)
+**max_completion_tokens**: Read from agent/main.py line with max_completion_tokens
+```
+
+4. If verbosity avg > 40 words, recommend lowering `max_completion_tokens`
+5. If Q-tag leaks found, check if `[TTS-FILTER]` logs show they were stripped before TTS
+
+### `/sre rebuild`
+Clean rebuild of a monorepo — nuke caches, rebuild all packages, restart services.
+
+This is the nuclear option when turbo/next/tsc caching causes stale builds, phantom errors, or "works locally but not in dev server" issues.
+
+Steps to execute directly (do NOT spawn an agent — run these yourself):
+
+1. **Read CLAUDE.md** for project root, build commands, and Local Dev Services table.
+
+2. **Stop running services** using the stop/kill commands from CLAUDE.md:
+   ```bash
+   # Read Local Dev Services table for ports and kill running processes
+   lsof -ti:<port> | xargs kill -9 2>/dev/null
+   ```
+
+3. **Nuke all caches**:
+   ```bash
+   cd <project-root> && rm -rf node_modules/.cache .next .turbo packages/*/dist packages/*/.next packages/*/.turbo
+   ```
+
+4. **Rebuild from scratch** using the project's build command from CLAUDE.md:
+   ```bash
+   cd <project-root> && <build-command>
+   ```
+   For monorepos, if the top-level build fails, try building packages individually in dependency order (read `pnpm-workspace.yaml` or `package.json` workspaces to determine order).
+
+5. **Restart services** using start commands from CLAUDE.md Local Dev Services table.
+
+6. **Verify**:
+   - Hit health endpoints from CLAUDE.md (or the ports listed in Local Dev Services table)
+   - Check no build errors in output
+
+Report success/failure with before/after comparison (which packages rebuilt, any errors).
+
+## Knowledge Base Integration
+
+### On every /sre invocation:
+1. **Read** `.claude/knowledge/agents/sre.md` for past incidents and patterns
+2. **Read** `.claude/qa-knowledge/incidents/` for production issues in this area
+
+### After /sre debug:
+1. **Write** incident to `.claude/qa-knowledge/incidents/{date}-{slug}.md`
+2. **Append** to `.claude/knowledge/agents/sre.md`:
+   ```
+   ### {date} — {incident title}
+   **Platform**: {platform}
+   **Root cause**: {what happened}
+   **Fix**: {what was done}
+   **Prevention**: {how to avoid next time}
+   ```
+
+### After first discovery on a project:
+1. **Write** platform summary to `knowledge/agents/sre.md`
+2. **Update** `project-profile.md` if infrastructure section is incomplete
+3. **Recommend** MCP servers to /calibrate's recommendations
+
+## /calibrate Integration
+
+When `/calibrate` runs, it reads all agent definitions to build recommendations.
+The SRE skill contributes:
+
+1. **Platform detection results** → /calibrate uses for MCP server recommendations
+2. **Missing monitoring tools** → /calibrate includes in "recommended tools"
+3. **Health endpoint inventory** → /calibrate writes to project profile
+4. **CI/CD platform** → /calibrate uses for ci-fix configuration
+
+If `/calibrate` has already run, /sre reads `project-profile.md` instead of re-discovering.
+If `/calibrate` hasn't run, /sre does its own discovery and recommends running `/calibrate`.

package/dist/plugins/prime/skills/sync/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: sync
+description: "Sync claude-agents tooling. Usage: /sync (pull latest), /sync status, /sync push <path> (contribute back)"
+user-invocable: true
+---
+
+# /sync — Claude Agents Sync
+
+Manage the shared claude-agents tooling between your project and the central repo.
+
+## Commands
+
+### `/sync` (no args) — Pull & re-sync
+
+Pull the latest from `~/.claude-agents/` and re-sync symlinks into the current project.
+
+Steps:
+1. `cd ~/.claude-agents && git pull --ff-only`
+2. Run `~/.claude-agents/install.sh` on the current project directory
+3. Report what was created, updated, or skipped
+
+### `/sync status` — Show status
+
+Run `~/.claude-agents/install.sh --status` on the current project directory.
+Report which files are symlinked, overridden, or missing.
+
+### `/sync push <target>` — Contribute back
+
+Push a modified agent, skill, or hook from the current project back to `~/.claude-agents/`.
+
+The `<target>` can be:
+- A name: `/sync push pr`, `/sync push onboard`, `/sync push ops`
+- A path: `/sync push skills/pr/SKILL.md`, `/sync push agents/ops.md`
+- Omitted: `/sync push` — auto-detect what changed (see step 1)
+
+#### Step 1: Resolve the target to a file path
+
+| Target | How to resolve |
+|--------|---------------|
+| No target given | Run `git diff --name-only HEAD` in the project repo. Filter for `.claude/agents/`, `.claude/skills/`, `.claude/hooks/`. If multiple, ask user which one. |
+| A name (e.g., `pr`) | Search for it: `.claude/skills/<name>/SKILL.md`, `.claude/agents/<name>.md`, `.claude/hooks/<name>.sh` — use the first that exists as a regular file (not symlink). |
+| A path (e.g., `skills/pr/SKILL.md`) | Prepend `.claude/` if needed → `.claude/skills/pr/SKILL.md` |
+
+The resolved path must be a **regular file** (not a symlink). If it's a symlink pointing to `~/.claude-agents/`, tell the user: "This file is managed by claude-agents. Edit it directly at `~/.claude-agents/<path>` instead."
+
+#### Step 2: Determine the item type and destination
+
+| Source path pattern | Type | Destination in claude-agents |
+|--------------------|------|------------------------------|
+| `.claude/agents/<name>.md` | agent | `agents/<name>.md` |
+| `.claude/skills/<name>/SKILL.md` | skill | `skills/<name>/SKILL.md` |
+| `.claude/skills/<name>/` (directory) | skill-dir | `skills/<name>/` |
+| `.claude/hooks/<name>.sh` | hook | `hooks/<name>.sh` |
+
+#### Step 3: Check for project-specific content
+
+Read the file. Warn if it contains hardcoded paths (`/Users/`, `~/prepme`), project-specific env vars, service names, or URLs. Ask user to clean up or proceed.
+
+#### Step 4: Copy and commit
+
+```bash
+# Determine branch name
+# If destination exists in claude-agents → update/<name>
+# If new → add/<name>
+BRANCH="update/<name>"  # or add/<name>
+
+cd ~/.claude-agents
+git checkout -b "$BRANCH"
+
+# Copy from project to toolkit
+cp <source> <destination>            # single file
+cp -r <source-dir> <destination-dir> # directory
+
+# If new item, add to manifest
+grep -q "<relative-path>" portable.manifest || echo "<type> <relative-path>" >> portable.manifest
+```
+
+#### Step 4b: Register new hooks in install.sh (HOOKS ONLY)
+
+**If the item type is `hook` AND it is a NEW hook** (not already in install.sh), you MUST register it in `install.sh`. Skipping this will cause the `15-manifest-coverage` CI test to fail.
+
+**4b.1: Detect hook metadata from the script**
+
+Read the first 10 lines of the hook script. Look for a comment declaring the hook type:
+- `# SessionEnd hook` → event: `SessionEnd`, matcher: `""`
+- `# SessionStart hook` → event: `SessionStart`, matcher: `""`
+- `# UserPromptSubmit hook` → event: `UserPromptSubmit`, matcher: `""`
+- `# PreToolUse hook (Bash)` → event: `PreToolUse`, matcher: `"Bash"`
+- `# PreToolUse hook (Edit)` → event: `PreToolUse`, matcher: `"Edit"`
+- `# PostToolUse hook (Bash)` → event: `PostToolUse`, matcher: `"Bash"`
+- Pattern: `# <Event> hook` or `# <Event> hook (<Matcher>)`
+
+If no event comment is found, the hook is a **helper script** (called by other hooks, not by Claude Code directly). Helper scripts only need steps 4b.2 and 4b.3 — skip 4b.4, 4b.5, and 4b.6.
+
+**4b.2: Determine the category**
+
+Ask the user which category. Common mappings:
+- `hooks` — routing, delegation, worktree sync (e.g., triage-router, sync-worktree, session-end)
+- `guardrails` — safety guards, linting, bootstrap (e.g., pre-bash-guard, post-edit-lint, session-bootstrap)
+- `core` — sync infrastructure (e.g., sync-agents)
+- `railway` — Railway-specific (e.g., sync-railway-worktree)
+
+**4b.3: Edit `get_category_items()` in install.sh**
+
+Find the case branch for the chosen category and append `hooks/<name>.sh` to the echo string.
+
+Example — adding `session-end.sh` to the `hooks` category:
+```
+# Before:
+hooks)
+    echo "hooks/triage-router.sh hooks/sync-worktree.sh"
+    ;;
+
+# After:
+hooks)
+    echo "hooks/triage-router.sh hooks/sync-worktree.sh hooks/session-end.sh"
+    ;;
+```
+
+Also update `get_category_label()` to increment the count, and `get_category_desc()` to mention the new hook.
+
+**4b.4: Edit `get_category_hooks()` in install.sh** (settings.json hooks only)
+
+Add the hook name (without `hooks/` prefix and `.sh` suffix) to the category's echo string.
+
+Example:
+```
+# Before:
+hooks)      echo "triage-router" ;;
+
+# After:
+hooks)      echo "triage-router session-end" ;;
+```
+
+**4b.5: Add to `HOOK_DEFS` in install.sh**
+
+Find the `HOOK_DEFS = {` Python dict (inside the `merge_settings_hooks` heredoc) and add a new entry before the closing `}`. Use `$CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh` as the command path. Set timeout to 15 for session hooks, 5 for tool hooks.
+
+Example entry:
+```python
+    "session-end": {
+        "event": "SessionEnd",
+        "entry": {
+            "matcher": "",
+            "hooks": [{
+                "type": "command",
+                "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh",
+                "timeout": 15
+            }]
+        },
+        "fingerprint": "session-end.sh"
+    }
+```
+
+**4b.6: Add to uninstall fallback list**
+
+Find the `hooks_to_remove=` fallback string in `handle_uninstall()` and add the hook name.
+
+#### Step 4c: Commit and push
+
+```bash
+git add <destination> portable.manifest install.sh
+git commit -m "feat: add <name> hook with install.sh registration"
+git push -u origin "$BRANCH"
+gh pr create --title "Add <name> hook" --body "Contributed from <project> repo"
+
+# Return to previous branch
+git checkout -
+```
+
+#### Step 5: Report the PR URL
+
+### `/sync setup` — Re-run interactive setup
+
+Re-run the interactive category selection menu for the current project.
+
+Steps:
+1. Run `~/.claude-agents/install.sh --setup` on the current project directory
+2. The menu will show with current selections pre-populated
+3. User can add or remove categories
+4. Report what changed
+
+## Important Rules
+
+- **Never push directly to main** in claude-agents — always branch + PR
+- **Always check for project-specific content** before contributing
+- **After PR merges**, the file will auto-sync to all projects on next session start
+- The original file in the project stays as a regular file until the next sync converts it to a symlink