@arthai/agents 1.0.4 → 1.0.6

package/dist/plugins/shield/hooks/project-setup.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# hooks/project-setup.sh — SessionStart hook: first-run project setup for marketplace installs.
+#
+# Runs on every SessionStart. Checks for marker file .claude/.toolkit-setup-done.
+# If missing (or version is stale): creates CLAUDE.md from template, injects managed block,
+# updates .gitignore with toolkit markers.
+#
+# Templates are read from ${CLAUDE_PLUGIN_ROOT}/templates/ (bundled with the plugin).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+MARKER_FILE="$PROJECT_DIR/.claude/.toolkit-setup-done"
+
+# Exit silently if CLAUDE_PLUGIN_ROOT is not set (not running from a plugin context)
+if [ -z "$PLUGIN_ROOT" ]; then
+    exit 0
+fi
+
+TEMPLATES_DIR="$PLUGIN_ROOT/templates"
+TEMPLATE_CLAUDE="$TEMPLATES_DIR/CLAUDE.md.template"
+TEMPLATE_BLOCK="$TEMPLATES_DIR/CLAUDE.md.managed-block"
+
+# Exit silently if templates are not bundled
+if [ ! -f "$TEMPLATE_CLAUDE" ] || [ ! -f "$TEMPLATE_BLOCK" ]; then
+    exit 0
+fi
+
+# Read toolkit version from VERSION file (bundled alongside plugin)
+TOOLKIT_VERSION="0.0.0"
+if [ -f "$PLUGIN_ROOT/VERSION" ]; then
+    TOOLKIT_VERSION=$(cat "$PLUGIN_ROOT/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "0.0.0")
+fi
+
+MANAGED_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+MANAGED_END="<!-- <<< claude-agents toolkit <<< -->"
+GITIGNORE_START="# >>> claude-agents managed (DO NOT EDIT THIS BLOCK) >>>"
+
+# Check marker file — skip if current version is already set up
+if [ -f "$MARKER_FILE" ]; then
+    STORED_VERSION=$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]' || echo "")
+    if [ "$STORED_VERSION" = "$TOOLKIT_VERSION" ]; then
+        exit 0
+    fi
+fi
+
+CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
+GITIGNORE="$PROJECT_DIR/.gitignore"
+
+# 1. Create CLAUDE.md from template if it doesn't exist (never overwrite existing)
+if [ ! -f "$CLAUDE_MD" ]; then
+    PROJECT_NAME=$(basename "$PROJECT_DIR")
+    sed "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" "$TEMPLATE_CLAUDE" > "$CLAUDE_MD"
+fi
+
+# 2. Inject managed block into CLAUDE.md if missing, or update if version is stale
+if [ -f "$CLAUDE_MD" ]; then
+    BLOCK_CONTENT=$(cat "$TEMPLATE_BLOCK")
+    NEW_BLOCK=$(printf '%s\n<!-- version: %s -->\n%s\n%s' \
+        "$MANAGED_START" "$TOOLKIT_VERSION" "$BLOCK_CONTENT" "$MANAGED_END")
+
+    if ! grep -qF "$MANAGED_START" "$CLAUDE_MD"; then
+        # Block missing — append it
+        printf '\n\n%s\n' "$NEW_BLOCK" >> "$CLAUDE_MD"
+    else
+        # Block exists — update if version changed
+        EXISTING_VERSION=$(grep -o '<!-- version: [^>]* -->' "$CLAUDE_MD" 2>/dev/null | head -1 | sed 's/<!-- version: //;s/ -->//' | tr -d '[:space:]' || echo "")
+        if [ "$EXISTING_VERSION" != "$TOOLKIT_VERSION" ]; then
+            # Replace block contents between markers
+            tmp=$(mktemp)
+            in_block=false
+            wrote_block=false
+            while IFS= read -r line; do
+                if echo "$line" | grep -qF "$MANAGED_START"; then
+                    in_block=true
+                    printf '%s\n' "$NEW_BLOCK" >> "$tmp"
+                    wrote_block=true
+                    continue
+                fi
+                if echo "$line" | grep -qF "$MANAGED_END"; then
+                    in_block=false
+                    continue
+                fi
+                if ! $in_block; then
+                    echo "$line" >> "$tmp"
+                fi
+            done < "$CLAUDE_MD"
+            mv "$tmp" "$CLAUDE_MD"
+        fi
+    fi
+fi
+
+# 3. Update .gitignore with toolkit marker block if missing
+if [ ! -f "$GITIGNORE" ] || ! grep -qF "$GITIGNORE_START" "$GITIGNORE" 2>/dev/null; then
+    GITIGNORE_BLOCK=$(printf '%s\n.claude/.toolkit-last-seen-sha\n.claude/.toolkit-setup-done\n.claude/.claude-agents.conf\n%s' \
+        "$GITIGNORE_START" "# <<< claude-agents managed <<<")
+    if [ ! -f "$GITIGNORE" ]; then
+        printf '%s\n' "$GITIGNORE_BLOCK" > "$GITIGNORE"
+    else
+        printf '\n\n%s\n' "$GITIGNORE_BLOCK" >> "$GITIGNORE"
+    fi
+fi
+
+# 4. Write marker file with current version
+mkdir -p "$PROJECT_DIR/.claude"
+printf '%s\n' "$TOOLKIT_VERSION" > "$MARKER_FILE"
+
+exit 0

package/dist/plugins/shield/templates/CLAUDE.md.managed-block

@@ -0,0 +1,123 @@
+## Engineering Principles (MANDATORY — applies to ALL work)
+
+### Research Before Fixing
+- **Never guess.** Before changing code, read the relevant source files, docs, and configs.
+- Understand WHY something is broken before attempting a fix.
+- If your first fix doesn't work, STOP. Don't try another guess. Re-read the code.
+- Use explore-light (Haiku, 1x cost) to scan the codebase before expensive agents investigate.
+
+### No Over-Engineering
+- **Do exactly what's needed.** Don't add abstractions, utilities, or frameworks unless the code already uses them.
+- Match existing patterns — run explore-light to find how similar code is structured before writing new code.
+- A bug fix touches the minimum files possible. A feature matches the existing architecture.
+- If you're creating a new class/helper/utility that nothing else in the codebase uses, you're over-engineering.
+
+### Test Before Shipping
+- **Run tests locally before pushing.** Never push untested code.
+- If the project has `/precheck`, run it. If it has `/qa`, run it in commit mode.
+- After fixing a bug, verify the fix AND verify nothing else broke (differential testing).
+- If 3+ consecutive fix attempts fail, STOP. Step back and reassess the root cause from scratch.
+
+### Deployment Safety
+- **Never modify production systems without explicit confirmation.**
+- Don't change deploy targets, CI pipeline structure, or infrastructure config silently.
+- Don't overwrite existing files during deployment without asking.
+- If a deployment breaks something, investigate before attempting to fix. Don't cascade.
+
+## Toolkit Awareness (MANDATORY — READ THIS FIRST)
+
+You have a **claude-agents toolkit** installed in this project. It provides specialized
+agents, skills, and hooks that handle domain-specific work better and cheaper.
+
+**You are the ORCHESTRATOR.** The triage router fires on every message with a routing
+table and SPEED score. Use it to decide: toolkit or you?
+
+### When to use the toolkit (SPEED score 2+):
+- **Multi-step workflows**: `/pr`, `/deploy`, `/planning`, `/implement`, `/qa`, `/ci-fix`
+  encode battle-tested sequences you'd otherwise do manually and forget steps
+- **Domain expertise**: SRE, QA, frontend, backend agents have project context baked in
+- **Cost savings**: Haiku/Sonnet agents handle 80% of tasks at 1/60th the cost of Opus
+- **Parallelism**: Team skills spawn multiple agents working simultaneously
+
+### When to use YOU directly (SPEED score 0-1):
+- **Quick lookups**: Read/Grep/Glob for finding a file, checking a value, reading code
+- **Small targeted edits**: 1-2 file changes where you already know what to do
+- **Complex reasoning**: Architecture decisions, debugging novel problems, nuanced tradeoffs
+- **Conversation flow**: Follow-up questions, clarifications, explaining code
+- **Creative problem-solving**: When the task doesn't fit any existing pattern
+- **Judgment calls**: Security reviews, design decisions, "should we even do this?"
+
+### The balance:
+The toolkit handles **process** (repeatable workflows, domain-specific checks, multi-step
+sequences). You handle **judgment** (reasoning, creativity, novel problems, architecture).
+
+A senior engineer doesn't do everything themselves — they delegate routine work and focus
+their expertise where it matters most. That's you. The toolkit is your team.
+
+**Don't over-delegate**: If it's faster to just Read a file and answer, do it.
+**Don't under-delegate**: If it's a 5-step workflow the toolkit has a skill for, use it.
+
+### Project Knowledge System
+
+If this project has been calibrated (`/calibrate`), deep context is available:
+
+- **`.claude/project-profile.md`** — Architecture patterns, coding conventions, domain model,
+  testing style. Read this before writing any code to match the project's patterns.
+- **`.claude/knowledge/`** — The toolkit's long-term memory for this project:
+  - `shared/conventions.md` — Coding rules learned from corrections. **Read before writing code.**
+  - `shared/domain.md` — Business rules beyond what's in the code. **Read before domain decisions.**
+  - `shared/vocabulary.md` — What the team calls things. **Use these terms.**
+  - `shared/patterns.md` — Architecture patterns. **Follow these when adding new code.**
+  - `agents/{your-name}.md` — Your past learning. **Read on session start.**
+  - **Write back** when you learn something new — corrections, discoveries, decisions.
+  - See `knowledge/README.md` for the full protocol.
+- **`.claude/knowledge/external/sources.md`** — Where team knowledge lives outside code
+  (Notion, Linear, Figma, etc.). Check before making decisions that might already be documented.
+
+## Session Start Behavior (MANDATORY)
+
+On your FIRST response in every new session, ALWAYS start with a brief status line
+using context from the SessionStart hook. Include:
+- Current branch + uncommitted file count
+- Docker/infra status (if problems detected)
+- Open PRs or assigned issues (if any)
+- Any red flags (pending migrations, expired tokens)
+
+Format: 1-3 compact lines before addressing the user's request. Example:
+```
+📋 project — main | 5 uncommitted | Docker: postgres ✓ redis ✓ | 2 open PRs
+```
+Then proceed with the user's actual request.
+
+**CRITICAL — Greetings and vague first messages**: If the user's first message is a
+greeting ("hey", "hi", "hello", "yo", "sup") or vague ("help", "what's up",
+"what should I work on") or ANY message under 5 words with no specific task —
+**ALWAYS use the `/onboard` skill**. Never respond to greetings yourself. The
+bootstrap hook status line is a quick snapshot — `/onboard` gives the real briefing
+with open PRs, issues, priorities, and actionable next steps.
+
+## Routing Trace (MANDATORY)
+
+On EVERY response, show a compact routing trace so the user understands the decision
+path. Place it at the end of your response in a dimmed block:
+
+```
+🔀 Routing: [what triage decided] → [agent/skill/tool used] ([cost tier])
+   Why: [1-line reason for this routing choice]
+```
+
+Examples:
+```
+🔀 Routing: backend bug fix → python-backend agent (Sonnet, 10x)
+   Why: touches backend/app/services/, needs CLAUDE.md context, SPEED=4
+```
+```
+🔀 Routing: file lookup → Grep (built-in, 0x)
+   Why: single-file search, no project context needed, SPEED=0
+```
+
+Rules:
+- Always show the SPEED score breakdown if score >= 2
+- Show which hook provided the context (triage-router, bootstrap, etc.)
+- If you chose NOT to use the triage router's suggestion, explain why
+- Skip the trace only for simple follow-up messages in an ongoing conversation

package/dist/plugins/shield/templates/CLAUDE.md.template

@@ -0,0 +1,111 @@
+# CLAUDE.md — {{PROJECT_NAME}}
+
+<!-- Generated by claude-agents install.sh --init -->
+<!-- TODO: Replace {{placeholders}} with your project details -->
+
+## Project Overview
+
+{{PROJECT_NAME}} is a {{DESCRIPTION}}.
+
+## Tech Stack
+
+- **Frontend**: <!-- TODO: e.g., Next.js 14, React 18, TypeScript, Tailwind -->
+- **Backend**: <!-- TODO: e.g., FastAPI, SQLAlchemy, PostgreSQL -->
+- **Auth**: <!-- TODO: e.g., Stytch, Auth0, Clerk -->
+- **Deploy**: <!-- TODO: e.g., Railway, Vercel, AWS -->
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── frontend/          <!-- TODO: Frontend directory -->
+├── backend/           <!-- TODO: Backend directory -->
+└── ...
+```
+
+## Key Architecture
+
+<!-- TODO: Describe your auth flow, API patterns, database schema, etc. -->
+
+## Local Dev Services
+
+<!-- TODO: Auto-populated by /scan or fill manually -->
+
+| Service  | Port | Directory | Start Command |
+|----------|------|-----------|---------------|
+| Frontend | <!-- TODO --> | frontend/ | <!-- TODO: e.g., npm run dev --> |
+| Backend  | <!-- TODO --> | backend/  | <!-- TODO: e.g., uvicorn app.main:app --reload --> |
+
+## Test Commands
+
+<!-- TODO: Auto-populated by /scan or fill manually -->
+
+| What | Command | Directory |
+|------|---------|-----------|
+| Backend tests | <!-- TODO: e.g., pytest --> | backend/ |
+| Backend lint | <!-- TODO: e.g., ruff check . --> | backend/ |
+| Frontend tests | <!-- TODO: e.g., npm test --> | frontend/ |
+| Frontend lint | <!-- TODO: e.g., npm run lint --> | frontend/ |
+| Type check | <!-- TODO: e.g., npx tsc --noEmit --> | frontend/ |
+| E2E tests | <!-- TODO: e.g., npx playwright test --> | frontend/ |
+
+## Infrastructure
+
+<!-- TODO: Auto-populated by /scan or fill manually -->
+
+| Platform | Service | Domain |
+|----------|---------|--------|
+| <!-- TODO: e.g., Railway --> | <!-- TODO --> | <!-- TODO --> |
+
+Health endpoints: <!-- TODO: e.g., /health, /api/health -->
+
+## Environments
+
+<!-- TODO: Auto-populated by /scan environments or /calibrate -->
+
+| Name | Type | URL | Health | Deploy | Branch |
+|------|------|-----|--------|--------|--------|
+| local | development | <!-- TODO --> | <!-- TODO: e.g., /health --> | manual | — |
+| <!-- TODO --> | <!-- TODO: staging/production/preview/canary --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+Access notes: <!-- TODO: e.g., Railway MCP for staging/prod. Env vars: .env.local, .env.staging -->
+
+## Domain
+
+<!-- TODO: Auto-populated by /scan or fill manually -->
+<!-- Describe what this app does, its core entities, and business rules. -->
+<!-- Used by qa-domain agent for domain-aware testing. -->
+
+## Running Locally
+
+```bash
+# TODO: Add your local development commands
+# Frontend
+cd frontend && npm run dev
+
+# Backend
+cd backend && source .venv/bin/activate && uvicorn app.main:app --reload
+```
+
+## Critical Rules
+
+<!-- TODO: Add project-specific rules, e.g.: -->
+- Never push to main directly — always create a PR
+- Secrets in .env.local only — never committed
+
+## Agent Customization
+
+The following agents/skills are managed by `claude-agents` (symlinked):
+- Run `~/.claude-agents/install.sh --status` to see what's linked
+- To override any portable file, replace the symlink with a regular file
+- Your override won't be touched by future syncs
+
+### Project-Specific Agents
+
+Add project-specific agents as regular files in `.claude/agents/`:
+- See `~/.claude-agents/examples/agents/` for templates (frontend, backend, ops, sre, qa)
+
+### Project-Specific Skills
+
+Add project-specific skills as regular directories in `.claude/skills/`:
+- See `~/.claude-agents/examples/skills/` for templates (ci-fix, qa, restart)

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

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

package/dist/plugins/spark/VERSION

@@ -0,0 +1 @@
+1.0.6

package/dist/plugins/spark/commands/calibrate.md

@@ -72,6 +72,26 @@ This goes far deeper than `/scan`. Read **actual source code** to understand HOW
 
 #### Step 1.1: Foundation Scan
 
+**Managed block check (belt-and-suspenders — runs before anything else):**
+
+Check if CLAUDE.md has the toolkit managed block. If missing, inject it before proceeding:
+
+```bash
+MANAGED_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+if [ -f "$CLAUDE_PROJECT_DIR/CLAUDE.md" ]; then
+    grep -qF "$MANAGED_START" "$CLAUDE_PROJECT_DIR/CLAUDE.md" || echo "MISSING_BLOCK"
+fi
+```
+
+If the managed block is missing:
+1. Read `~/.claude-agents/templates/CLAUDE.md.managed-block` (or `$CLAUDE_PROJECT_DIR/.claude/hooks/../templates/CLAUDE.md.managed-block` if installed via plugin)
+2. Inject it at the end of CLAUDE.md using the markers:
+   - Start: `<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->`
+   - End: `<!-- <<< claude-agents toolkit <<< -->`
+3. Report: "Injected toolkit managed block into CLAUDE.md (was missing)"
+
+This catches any install path that missed the injection — clone installs, manual setups, or projects that predate the managed block feature.
+
 Run `/scan` first if CLAUDE.md has `<!-- TODO -->` placeholders or doesn't exist. This populates
 the basics (tech stack, services, test commands, infrastructure). Then proceed to deep scan.
 

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

@@ -1,6 +1,16 @@
 {
   "hooks": {
     "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/project-setup.sh",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [

package/dist/plugins/spark/hooks/project-setup.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# hooks/project-setup.sh — SessionStart hook: first-run project setup for marketplace installs.
+#
+# Runs on every SessionStart. Checks for marker file .claude/.toolkit-setup-done.
+# If missing (or version is stale): creates CLAUDE.md from template, injects managed block,
+# updates .gitignore with toolkit markers.
+#
+# Templates are read from ${CLAUDE_PLUGIN_ROOT}/templates/ (bundled with the plugin).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+MARKER_FILE="$PROJECT_DIR/.claude/.toolkit-setup-done"
+
+# Exit silently if CLAUDE_PLUGIN_ROOT is not set (not running from a plugin context)
+if [ -z "$PLUGIN_ROOT" ]; then
+    exit 0
+fi
+
+TEMPLATES_DIR="$PLUGIN_ROOT/templates"
+TEMPLATE_CLAUDE="$TEMPLATES_DIR/CLAUDE.md.template"
+TEMPLATE_BLOCK="$TEMPLATES_DIR/CLAUDE.md.managed-block"
+
+# Exit silently if templates are not bundled
+if [ ! -f "$TEMPLATE_CLAUDE" ] || [ ! -f "$TEMPLATE_BLOCK" ]; then
+    exit 0
+fi
+
+# Read toolkit version from VERSION file (bundled alongside plugin)
+TOOLKIT_VERSION="0.0.0"
+if [ -f "$PLUGIN_ROOT/VERSION" ]; then
+    TOOLKIT_VERSION=$(cat "$PLUGIN_ROOT/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "0.0.0")
+fi
+
+MANAGED_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+MANAGED_END="<!-- <<< claude-agents toolkit <<< -->"
+GITIGNORE_START="# >>> claude-agents managed (DO NOT EDIT THIS BLOCK) >>>"
+
+# Check marker file — skip if current version is already set up
+if [ -f "$MARKER_FILE" ]; then
+    STORED_VERSION=$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]' || echo "")
+    if [ "$STORED_VERSION" = "$TOOLKIT_VERSION" ]; then
+        exit 0
+    fi
+fi
+
+CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
+GITIGNORE="$PROJECT_DIR/.gitignore"
+
+# 1. Create CLAUDE.md from template if it doesn't exist (never overwrite existing)
+if [ ! -f "$CLAUDE_MD" ]; then
+    PROJECT_NAME=$(basename "$PROJECT_DIR")
+    sed "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" "$TEMPLATE_CLAUDE" > "$CLAUDE_MD"
+fi
+
+# 2. Inject managed block into CLAUDE.md if missing, or update if version is stale
+if [ -f "$CLAUDE_MD" ]; then
+    BLOCK_CONTENT=$(cat "$TEMPLATE_BLOCK")
+    NEW_BLOCK=$(printf '%s\n<!-- version: %s -->\n%s\n%s' \
+        "$MANAGED_START" "$TOOLKIT_VERSION" "$BLOCK_CONTENT" "$MANAGED_END")
+
+    if ! grep -qF "$MANAGED_START" "$CLAUDE_MD"; then
+        # Block missing — append it
+        printf '\n\n%s\n' "$NEW_BLOCK" >> "$CLAUDE_MD"
+    else
+        # Block exists — update if version changed
+        EXISTING_VERSION=$(grep -o '<!-- version: [^>]* -->' "$CLAUDE_MD" 2>/dev/null | head -1 | sed 's/<!-- version: //;s/ -->//' | tr -d '[:space:]' || echo "")
+        if [ "$EXISTING_VERSION" != "$TOOLKIT_VERSION" ]; then
+            # Replace block contents between markers
+            tmp=$(mktemp)
+            in_block=false
+            wrote_block=false
+            while IFS= read -r line; do
+                if echo "$line" | grep -qF "$MANAGED_START"; then
+                    in_block=true
+                    printf '%s\n' "$NEW_BLOCK" >> "$tmp"
+                    wrote_block=true
+                    continue
+                fi
+                if echo "$line" | grep -qF "$MANAGED_END"; then
+                    in_block=false
+                    continue
+                fi
+                if ! $in_block; then
+                    echo "$line" >> "$tmp"
+                fi
+            done < "$CLAUDE_MD"
+            mv "$tmp" "$CLAUDE_MD"
+        fi
+    fi
+fi
+
+# 3. Update .gitignore with toolkit marker block if missing
+if [ ! -f "$GITIGNORE" ] || ! grep -qF "$GITIGNORE_START" "$GITIGNORE" 2>/dev/null; then
+    GITIGNORE_BLOCK=$(printf '%s\n.claude/.toolkit-last-seen-sha\n.claude/.toolkit-setup-done\n.claude/.claude-agents.conf\n%s' \
+        "$GITIGNORE_START" "# <<< claude-agents managed <<<")
+    if [ ! -f "$GITIGNORE" ]; then
+        printf '%s\n' "$GITIGNORE_BLOCK" > "$GITIGNORE"
+    else
+        printf '\n\n%s\n' "$GITIGNORE_BLOCK" >> "$GITIGNORE"
+    fi
+fi
+
+# 4. Write marker file with current version
+mkdir -p "$PROJECT_DIR/.claude"
+printf '%s\n' "$TOOLKIT_VERSION" > "$MARKER_FILE"
+
+exit 0

package/dist/plugins/spark/templates/CLAUDE.md.managed-block

@@ -0,0 +1,123 @@
+## Engineering Principles (MANDATORY — applies to ALL work)
+
+### Research Before Fixing
+- **Never guess.** Before changing code, read the relevant source files, docs, and configs.
+- Understand WHY something is broken before attempting a fix.
+- If your first fix doesn't work, STOP. Don't try another guess. Re-read the code.
+- Use explore-light (Haiku, 1x cost) to scan the codebase before expensive agents investigate.
+
+### No Over-Engineering
+- **Do exactly what's needed.** Don't add abstractions, utilities, or frameworks unless the code already uses them.
+- Match existing patterns — run explore-light to find how similar code is structured before writing new code.
+- A bug fix touches the minimum files possible. A feature matches the existing architecture.
+- If you're creating a new class/helper/utility that nothing else in the codebase uses, you're over-engineering.
+
+### Test Before Shipping
+- **Run tests locally before pushing.** Never push untested code.
+- If the project has `/precheck`, run it. If it has `/qa`, run it in commit mode.
+- After fixing a bug, verify the fix AND verify nothing else broke (differential testing).
+- If 3+ consecutive fix attempts fail, STOP. Step back and reassess the root cause from scratch.
+
+### Deployment Safety
+- **Never modify production systems without explicit confirmation.**
+- Don't change deploy targets, CI pipeline structure, or infrastructure config silently.
+- Don't overwrite existing files during deployment without asking.
+- If a deployment breaks something, investigate before attempting to fix. Don't cascade.
+
+## Toolkit Awareness (MANDATORY — READ THIS FIRST)
+
+You have a **claude-agents toolkit** installed in this project. It provides specialized
+agents, skills, and hooks that handle domain-specific work better and cheaper.
+
+**You are the ORCHESTRATOR.** The triage router fires on every message with a routing
+table and SPEED score. Use it to decide: toolkit or you?
+
+### When to use the toolkit (SPEED score 2+):
+- **Multi-step workflows**: `/pr`, `/deploy`, `/planning`, `/implement`, `/qa`, `/ci-fix`
+  encode battle-tested sequences you'd otherwise do manually and forget steps
+- **Domain expertise**: SRE, QA, frontend, backend agents have project context baked in
+- **Cost savings**: Haiku/Sonnet agents handle 80% of tasks at 1/60th the cost of Opus
+- **Parallelism**: Team skills spawn multiple agents working simultaneously
+
+### When to use YOU directly (SPEED score 0-1):
+- **Quick lookups**: Read/Grep/Glob for finding a file, checking a value, reading code
+- **Small targeted edits**: 1-2 file changes where you already know what to do
+- **Complex reasoning**: Architecture decisions, debugging novel problems, nuanced tradeoffs
+- **Conversation flow**: Follow-up questions, clarifications, explaining code
+- **Creative problem-solving**: When the task doesn't fit any existing pattern
+- **Judgment calls**: Security reviews, design decisions, "should we even do this?"
+
+### The balance:
+The toolkit handles **process** (repeatable workflows, domain-specific checks, multi-step
+sequences). You handle **judgment** (reasoning, creativity, novel problems, architecture).
+
+A senior engineer doesn't do everything themselves — they delegate routine work and focus
+their expertise where it matters most. That's you. The toolkit is your team.
+
+**Don't over-delegate**: If it's faster to just Read a file and answer, do it.
+**Don't under-delegate**: If it's a 5-step workflow the toolkit has a skill for, use it.
+
+### Project Knowledge System
+
+If this project has been calibrated (`/calibrate`), deep context is available:
+
+- **`.claude/project-profile.md`** — Architecture patterns, coding conventions, domain model,
+  testing style. Read this before writing any code to match the project's patterns.
+- **`.claude/knowledge/`** — The toolkit's long-term memory for this project:
+  - `shared/conventions.md` — Coding rules learned from corrections. **Read before writing code.**
+  - `shared/domain.md` — Business rules beyond what's in the code. **Read before domain decisions.**
+  - `shared/vocabulary.md` — What the team calls things. **Use these terms.**
+  - `shared/patterns.md` — Architecture patterns. **Follow these when adding new code.**
+  - `agents/{your-name}.md` — Your past learning. **Read on session start.**
+  - **Write back** when you learn something new — corrections, discoveries, decisions.
+  - See `knowledge/README.md` for the full protocol.
+- **`.claude/knowledge/external/sources.md`** — Where team knowledge lives outside code
+  (Notion, Linear, Figma, etc.). Check before making decisions that might already be documented.
+
+## Session Start Behavior (MANDATORY)
+
+On your FIRST response in every new session, ALWAYS start with a brief status line
+using context from the SessionStart hook. Include:
+- Current branch + uncommitted file count
+- Docker/infra status (if problems detected)
+- Open PRs or assigned issues (if any)
+- Any red flags (pending migrations, expired tokens)
+
+Format: 1-3 compact lines before addressing the user's request. Example:
+```
+📋 project — main | 5 uncommitted | Docker: postgres ✓ redis ✓ | 2 open PRs
+```
+Then proceed with the user's actual request.
+
+**CRITICAL — Greetings and vague first messages**: If the user's first message is a
+greeting ("hey", "hi", "hello", "yo", "sup") or vague ("help", "what's up",
+"what should I work on") or ANY message under 5 words with no specific task —
+**ALWAYS use the `/onboard` skill**. Never respond to greetings yourself. The
+bootstrap hook status line is a quick snapshot — `/onboard` gives the real briefing
+with open PRs, issues, priorities, and actionable next steps.
+
+## Routing Trace (MANDATORY)
+
+On EVERY response, show a compact routing trace so the user understands the decision
+path. Place it at the end of your response in a dimmed block:
+
+```
+🔀 Routing: [what triage decided] → [agent/skill/tool used] ([cost tier])
+   Why: [1-line reason for this routing choice]
+```
+
+Examples:
+```
+🔀 Routing: backend bug fix → python-backend agent (Sonnet, 10x)
+   Why: touches backend/app/services/, needs CLAUDE.md context, SPEED=4
+```
+```
+🔀 Routing: file lookup → Grep (built-in, 0x)
+   Why: single-file search, no project context needed, SPEED=0
+```
+
+Rules:
+- Always show the SPEED score breakdown if score >= 2
+- Show which hook provided the context (triage-router, bootstrap, etc.)
+- If you chose NOT to use the triage router's suggestion, explain why
+- Skip the trace only for simple follow-up messages in an ongoing conversation