@arthai/agents 1.0.4 → 1.0.6

package/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/hooks/sync-agents.sh

@@ -22,8 +22,9 @@ if [ ! -d "$AGENTS_DIR/.git" ]; then
     exit 0
 fi
 
-# Exit silently if no license
-if [ ! -f "$LICENSE_FILE" ]; then
+# Exit silently if no license found in any path
+ARTHAI_LICENSE_PATH="$REAL_HOME/.arthai/license"
+if [ ! -f "$LICENSE_FILE" ] && [ ! -f "$ARTHAI_LICENSE_PATH" ] && [ -z "${ARTHAI_LICENSE_KEY:-}" ]; then
     exit 0
 fi
 
@@ -108,6 +109,27 @@ fi
 
 # --- Step 2: Check license (with revocation enforcement) ---
 NOW=$(date +%s)
+WORKER_URL="https://license-worker.muddassar-shaikh.workers.dev"
+
+# Resolve license key: ~/.claude-agents/.license takes priority (existing clone-install users),
+# fall back to ~/.arthai/license (npm activate users).
+ARTHAI_LICENSE_KEY_VALUE="${ARTHAI_LICENSE_KEY:-}"
+RESOLVED_KEY=""
+if [ -n "$ARTHAI_LICENSE_KEY_VALUE" ]; then
+    RESOLVED_KEY="$ARTHAI_LICENSE_KEY_VALUE"
+elif [ -f "$LICENSE_FILE" ]; then
+    RESOLVED_KEY=$(cat "$LICENSE_FILE" 2>/dev/null | tr -d '[:space:]' || echo "")
+elif [ -f "$REAL_HOME/.arthai/license" ]; then
+    RESOLVED_KEY=$(cat "$REAL_HOME/.arthai/license" 2>/dev/null | tr -d '[:space:]' || echo "")
+fi
+
+# Validate key format before using it in any JSON payload — prevents JSON injection
+# via a crafted key value in the env var or license file.
+KEY_FORMAT='^ARTH-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$'
+if [ -n "$RESOLVED_KEY" ] && ! echo "$RESOLVED_KEY" | grep -qE "$KEY_FORMAT"; then
+    # Key has invalid format — don't use it for Worker call or local check
+    RESOLVED_KEY=""
+fi
 
 # Detect if authorized-keys.txt changed in the pull — force re-check if so
 AK_HASH_FILE="$AGENTS_DIR/.ak-hash"
@@ -128,6 +150,49 @@ fi
 # Store current hash for next comparison
 [ -n "$AK_CURRENT_HASH" ] && echo "$AK_CURRENT_HASH" > "$AK_HASH_FILE" 2>/dev/null || true
 
+# validate_with_worker: call Worker /validate with the resolved key.
+# Sets WORKER_RESULT: "valid", "invalid" (definitive), or "network_error".
+validate_with_worker() {
+    local key="$1"
+    if [ -z "$key" ]; then
+        WORKER_RESULT="invalid"
+        return
+    fi
+
+    local payload="{\"key\":\"$key\"}"
+    local response
+    local curl_exit
+
+    # Pass payload via stdin (--data @-) so the key is not visible in the process list
+    response=$(printf '%s' "$payload" | curl \
+        --silent \
+        --max-time 10 \
+        --connect-timeout 5 \
+        --request POST \
+        --header "Content-Type: application/json" \
+        --data "@-" \
+        "$WORKER_URL/validate" 2>/dev/null)
+    curl_exit=$?
+
+    if [ $curl_exit -ne 0 ] || [ -z "$response" ]; then
+        WORKER_RESULT="network_error"
+        return
+    fi
+
+    # Parse "valid" field from JSON — minimal grep-based parse, no jq dependency
+    local valid_field
+    valid_field=$(echo "$response" | grep -o '"valid"[[:space:]]*:[[:space:]]*[a-z]*' | head -1 | grep -o '[a-z]*$')
+
+    if [ "$valid_field" = "true" ]; then
+        WORKER_RESULT="valid"
+    elif [ "$valid_field" = "false" ]; then
+        WORKER_RESULT="invalid"
+    else
+        # Unexpected response format — treat as network error (fail safe)
+        WORKER_RESULT="network_error"
+    fi
+}
+
 LICENSE_VALID=true
 if [ -f "$LICENSE_CACHE" ]; then
     LAST_CHECK=$(cat "$LICENSE_CACHE" 2>/dev/null || echo "0")
@@ -136,19 +201,41 @@ if [ -f "$LICENSE_CACHE" ]; then
         # Cache is fresh, skip validation
         :
     else
-        # Re-validate
-        if ! "$AGENTS_DIR/install.sh" --check-license-only 2>/dev/null; then
+        # Re-validate: try Worker first, fall back to local only on network error
+        validate_with_worker "$RESOLVED_KEY"
+        if [ "$WORKER_RESULT" = "valid" ]; then
+            echo "$NOW" > "$LICENSE_CACHE"
+        elif [ "$WORKER_RESULT" = "invalid" ]; then
+            # Worker says definitively invalid — no local fallback, clear cache
+            rm -f "$LICENSE_CACHE" 2>/dev/null || true
             LICENSE_VALID=false
         else
-            echo "$NOW" > "$LICENSE_CACHE"
+            # Network error — fall back to local authorized-keys.txt check
+            echo "License server unavailable. Retrying with local validation..." >&2
+            if ! "$AGENTS_DIR/install.sh" --check-license-only 2>/dev/null; then
+                LICENSE_VALID=false
+            else
+                echo "$NOW" > "$LICENSE_CACHE"
+            fi
         fi
     fi
 else
-    # First check (or cache was invalidated by AK change)
-    if ! "$AGENTS_DIR/install.sh" --check-license-only 2>/dev/null; then
+    # First check (or cache was invalidated by AK change): try Worker first
+    validate_with_worker "$RESOLVED_KEY"
+    if [ "$WORKER_RESULT" = "valid" ]; then
+        echo "$NOW" > "$LICENSE_CACHE"
+    elif [ "$WORKER_RESULT" = "invalid" ]; then
+        # Worker says definitively invalid — no local fallback, ensure cache stays clear
+        rm -f "$LICENSE_CACHE" 2>/dev/null || true
         LICENSE_VALID=false
     else
-        echo "$NOW" > "$LICENSE_CACHE"
+        # Network error — fall back to local authorized-keys.txt check
+        echo "License server unavailable. Retrying with local validation..." >&2
+        if ! "$AGENTS_DIR/install.sh" --check-license-only 2>/dev/null; then
+            LICENSE_VALID=false
+        else
+            echo "$NOW" > "$LICENSE_CACHE"
+        fi
     fi
 fi
 
@@ -182,12 +269,12 @@ if ! $LICENSE_VALID; then
 
         # Remove CLAUDE.md managed block
         CLAUDEMD="$PROJECT_DIR/CLAUDE.md"
-        if [ -f "$CLAUDEMD" ] && grep -qF "<!-- >>> claude-agents toolkit -->" "$CLAUDEMD" 2>/dev/null; then
+        if [ -f "$CLAUDEMD" ] && grep -qF "<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->" "$CLAUDEMD" 2>/dev/null; then
             tmp=$(mktemp)
             in_block=false
             skip_next_blank=false
             while IFS= read -r line; do
-                if echo "$line" | grep -qF "<!-- >>> claude-agents toolkit -->"; then
+                if echo "$line" | grep -qF "<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"; then
                     in_block=true
                     continue
                 fi
@@ -218,8 +305,8 @@ if ! $LICENSE_VALID; then
         rm -f "$LICENSE_CACHE" 2>/dev/null || true
     fi
 
-    echo "⚠ License revoked. Toolkit has been disabled for this project."
-    echo "  Contact support to renew your license."
+    echo "Invalid license key. Toolkit has been disabled for this project."
+    echo "  Check your key or get one at arthai.dev/pricing"
     exit 0
 fi
 

package/install.sh

@@ -114,7 +114,7 @@ get_category_items() {
             echo "agents/architect.md agents/code-reviewer.md agents/design-studio-create.md agents/design-studio-critique.md agents/design-studio-think.md agents/gtm-expert.md agents/product-manager.md agents/stakeholder-reporter.md agents/meeting-prep.md agents/content-strategist.md agents/user-researcher.md agents/competitive-analyst.md"
             ;;
         development)
-            echo "agents/frontend.md agents/python-backend.md agents/ops.md skills/planning skills/implement skills/fix skills/pr skills/precheck skills/review-pr skills/issue"
+            echo "agents/frontend.md agents/python-backend.md agents/ops.md agents/troubleshooter.md skills/planning skills/implement skills/fix skills/pr skills/precheck skills/review-pr skills/issue"
             ;;
         quality)
             echo "agents/qa.md agents/qa-e2e.md agents/qa-challenger.md agents/qa-test-promoter.md agents/qa-baseline-updater.md agents/qa-domain.md skills/qa skills/ci-fix skills/qa-incident skills/qa-learn"
@@ -126,7 +126,7 @@ get_category_items() {
             echo "hooks/triage-router.sh hooks/session-end.sh"
             ;;
         guardrails)
-            echo "hooks/session-bootstrap.sh hooks/pre-bash-guard.sh hooks/pre-task-context.sh hooks/pre-edit-guard.sh hooks/post-test-summary.sh hooks/post-edit-lint.sh hooks/post-deploy-health.sh hooks/post-diff-test-compare.sh hooks/post-git-state.sh hooks/post-merge-cleanup.sh skills/onboard skills/welcome skills/share skills/templates skills/wizard skills/autopilot skills/continue"
+            echo "hooks/session-bootstrap.sh hooks/pre-bash-guard.sh hooks/pre-task-context.sh hooks/pre-edit-guard.sh hooks/post-test-summary.sh hooks/post-edit-lint.sh hooks/post-deploy-health.sh hooks/post-diff-test-compare.sh hooks/post-git-state.sh hooks/post-merge-cleanup.sh hooks/escalation-guard.sh hooks/project-setup.sh hooks/pre-server-port-guard.sh hooks/post-config-change-restart-reminder.sh hooks/post-server-crash-watch.sh skills/onboard skills/welcome skills/share skills/templates skills/wizard skills/autopilot skills/continue"
             ;;
         railway)
             echo "skills/railway/central-station skills/railway/database skills/railway/deploy skills/railway/deployment skills/railway/domain skills/railway/environment skills/railway/metrics skills/railway/new skills/railway/projects skills/railway/railway-docs skills/railway/service skills/railway/status skills/railway/templates"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arthai/agents",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "AI-powered development toolkit for Claude Code — agents, skills, and hooks",
   "bin": {
     "arthai": "bin/cli.js"

package/portable.manifest

@@ -38,6 +38,7 @@ agent agents/content-strategist.md
 agent agents/user-researcher.md
 agent agents/competitive-analyst.md
 agent agents/ai-consultant.md
+agent agents/troubleshooter.md
 
 # Portable skills (30)
 skill skills/explore.md
@@ -78,7 +79,8 @@ skill-dir skills/solution-architect
 skill-dir skills/deliverable-builder
 skill-dir skills/engagement-tracker
 
-# Portable hooks (13)
+# Portable hooks (14)
+hook hooks/project-setup.sh
 hook hooks/ensure-client-dir.sh
 hook hooks/check-deliverable.sh
 hook hooks/session-summary.sh
@@ -109,4 +111,8 @@ railway-skill-dir skills/railway/railway-docs
 railway-skill-dir skills/railway/service
 railway-skill-dir skills/railway/status
 railway-skill-dir skills/railway/templates
+hook hooks/escalation-guard.sh
+hook hooks/pre-server-port-guard.sh
+hook hooks/post-config-change-restart-reminder.sh
+hook hooks/post-server-crash-watch.sh
 hook hooks/session-end.sh

package/skills/calibrate/SKILL.md

@@ -74,6 +74,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/skills/ci-fix/SKILL.md

@@ -162,6 +162,42 @@ gh run view <FAILED_RUN_ID> --log-failed 2>&1 | tail -200
 | **Build failures** | build errors | Read error, fix import/export/config |
 | **Migration** | Alembic/Django errors | Fix migration file |
 | **Dependency** | pip/npm install failures | Fix requirements/package.json |
+| **Toolkit tests** | 15/20-skill-runtime-safety, manifest-coverage | See Toolkit Test Fixes below |
+
+#### Toolkit-Specific Test Fixes (claude-agents repo)
+
+When CI fails on the mechanical test suite (`tests/run.sh`), these are the common failures and auto-fixes:
+
+| Test | Failure message | Root cause | Auto-fix |
+|------|----------------|-----------|----------|
+| `20-skill-runtime-safety` | "regex-unsafe [brackets] in descriptions" | SKILL.md `description:` or `arguments:` field contains `[text]` | Replace `[text]` with `<text>` in the frontmatter field. Brackets break regex matching in Claude Code. |
+| `20-skill-runtime-safety` | "Skills missing required frontmatter fields" | SKILL.md missing `user-invocable: true` or `arguments:` | Add missing field to the YAML frontmatter between `---` markers. Check `git show HEAD~1:path/to/SKILL.md` for the original. |
+| `15-manifest-coverage` | "entries mapped to categories" | New file in `portable.manifest` not listed in any `get_category_items()` category in `install.sh` | Add the manifest entry to the appropriate category in `install.sh:get_category_items()`. |
+| `15-manifest-coverage` | "Install creates all expected symlinks" | New file in `portable.manifest` but install didn't create the symlink | Usually follows from the category mapping fix above. |
+| `15-manifest-coverage` | "Entry counts are consistent" | Mismatch between manifest entries and installed files | Check that new manifest entries have matching source files. |
+| `19-brownfield-assessment` | "classify_file returns IDENTICAL" | Agent fixture is stale after editing an agent `.md` file | Update fixture: `cp agents/{name}.md tests/fixtures/claude-setups/poweruser/.claude/agents/` |
+
+**Auto-fix sequence for toolkit tests:**
+
+```bash
+# 1. Get the exact failure
+gh run view <ID> --log-failed 2>&1 | grep -E "FAIL|✗" | head -5
+
+# 2. For bracket issues — find and fix ALL bracket descriptions
+grep -rn 'description:.*\[' skills/*/SKILL.md
+# Replace [text] with <text> in each match
+
+# 3. For missing frontmatter — compare against last known good
+git show HEAD~1:path/to/SKILL.md | head -6
+# Restore missing fields
+
+# 4. For manifest coverage — add to install.sh categories
+grep "get_category_items" install.sh
+# Add new entries to the right category
+
+# 5. Verify locally before pushing
+bash tests/run.sh --suite 15,20 --scenario a
+```
 
 **Attempt escalation:**
 - Attempt 1: Apply the obvious fix (auto-fix tools, direct code fix)

package/skills/fix/SKILL.md

@@ -478,6 +478,29 @@ Select the right agent based on which layer the bug is in:
 If `.claude/project-profile.md` exists, read it to determine the platform and pick the right agent.
 If `/calibrate` generated custom agents (e.g., `ios-developer.md`), use those for platform-specific bugs.
 
+**4.2b: Escalation protocol for fix agents**
+
+Include this in the implementation agent's prompt:
+
+```
+## When Your Fix Doesn't Work (MANDATORY)
+
+1. After first failed attempt: re-read the root cause analysis from Step 1.
+   Is the root cause correct? If not, go back to Step 1.
+2. After second failed attempt: consult knowledge base:
+   - .claude/knowledge/qa-knowledge/ (error keywords)
+   - .claude/knowledge/shared/conventions.md (project gotchas)
+   - git log --all --grep="<error keyword>" --oneline -10
+3. After third failed attempt: STOP. Do not try another fix.
+   Generate a STUCK REPORT and send to team-lead:
+   - Error: [exact message]
+   - Root cause hypothesis: [from Step 1]
+   - Fix attempts: [1, 2, 3 with results]
+   - KB consultation results: [what you found]
+   - Recommendation: [re-investigate root cause / ask user for X / try different approach]
+4. If a troubleshooter agent is available, team-lead may spawn one.
+```
+
 **Agent prompt includes:**
 ```
 1. Root cause analysis from Step 1

package/skills/implement/SKILL.md

@@ -29,9 +29,15 @@ If no feature name is provided, use AskUserQuestion to get it.
 If the plan file exists:
 - Read it with the Read tool.
 - Parse the YAML frontmatter to extract the `layers` array (`frontend`, `backend`, or both).
+- Parse the `spec` field from frontmatter (e.g., `spec: specs/feature-name.md`).
 - Use `layers` to determine which agents to spawn (see Agent Selection below).
 - Use the full file content as `PLAN`.
 
+**Also check for a spec file** at `.claude/specs/{feature-name}.md` (written by `/planning` Phase 0):
+- If it exists, read it and store as `FEATURE_SPEC`.
+- Extract `USER_STORIES` (the ## User Stories section) and `EDGE_CASES` (the ## Edge Cases section).
+- These are passed to implementation agents and QA for better coverage.
+
 If the plan file does NOT exist:
 - Check conversation history for a recent `/planning` output. If found, use it as `PLAN` and infer layers from task breakdown.
 - If neither exists, ask the user with AskUserQuestion:
@@ -136,6 +142,43 @@ Include the results in the shared context block below so agents match existing
 patterns instead of inventing new ones. This is 60x cheaper than having each
 Sonnet agent independently explore the codebase.
 
+### 3c. Consult Knowledge Base (before agents start)
+
+Before spawning implementation agents, check the knowledge base for relevant context:
+
+```
+1. .claude/knowledge/shared/conventions.md — coding rules and project gotchas
+2. .claude/knowledge/shared/patterns.md — architecture patterns to follow
+3. .claude/knowledge/qa-knowledge/ — past incidents in the same area
+4. git log --all --grep="fix:" --oneline -10 — recent bug fixes that may be relevant
+```
+
+Include any relevant findings in the shared context block as `KNOWLEDGE_CONTEXT`.
+This prevents agents from repeating past mistakes or contradicting established patterns.
+
+### 3d. Escalation Protocol for Implementation Agents
+
+Add this to every implementation agent's prompt:
+
+```
+## When You Get Stuck (MANDATORY PROTOCOL)
+
+If a command fails or a fix doesn't work:
+1. DO NOT retry the same approach more than twice
+2. After 2 failures with same error: STOP and consult knowledge base
+   - .claude/knowledge/shared/conventions.md
+   - .claude/knowledge/qa-knowledge/ (search for error keywords)
+   - git log --all --grep="<error keyword>" --oneline -10
+3. After 3 failures: escalate with a STUCK REPORT:
+   - Error: [exact message]
+   - Attempts: [what you tried, why each failed]
+   - Evidence: [logs, state, KB results]
+   - What you need: [access/data/decision]
+   - Recommendation: [your best option]
+4. Send the stuck report to team-lead via SendMessage
+5. If a troubleshooter agent is available, team-lead may spawn one to help
+```
+
 ### 4. Build Shared Context Block
 
 ```
@@ -148,6 +191,16 @@ Auth: {AUTH_APPROACH}
 ## Implementation Plan
 {PLAN}
 
+## User Stories (from spec — trace your work to these)
+{USER_STORIES}
+
+(If no spec exists, this section is omitted.)
+
+## Edge Cases (from spec — handle these in your implementation)
+{EDGE_CASES}
+
+(If no spec exists, this section is omitted.)
+
 ## API Contract
 {API_CONTRACT}
 
@@ -206,7 +259,7 @@ Check `.claude/project-profile.md` first (if /calibrate has run). Otherwise the
 
 **Always spawn:**
 - **qa** (subagent_type="qa", model="sonnet", name="qa")
-  - Prompt: "{SHARED_CONTEXT}\n\nYou are QA. Your job: (1) Review backend and frontend implementations as they complete. (2) Ask teammates 'why did you do X?' when something looks wrong. (3) Run validation checks (linters, type checkers, build commands). (4) Report issues back to the responsible teammate. (5) Mark your tasks done when all checks pass. Do NOT write code — only review and validate."
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are QA. Your job: (1) Review backend and frontend implementations as they complete. (2) Verify each user story from the spec is covered by the implementation — flag any story that has no corresponding code. (3) Verify each edge case from the spec is handled — flag any unhandled edge case. (4) Ask teammates 'why did you do X?' when something looks wrong. (5) Run validation checks (linters, type checkers, build commands). (6) Report issues back to the responsible teammate. (7) Mark your tasks done when all checks pass. Do NOT write code — only review and validate.\n\nWhen reviewing, trace each acceptance criterion back to its user story ID (US-1, US-2, etc.) and confirm the implementation satisfies it. Check edge cases (EC-1, EC-2, etc.) have explicit handling in the code."
 
 ### 5b. Red Team Phase
 
@@ -341,6 +394,7 @@ After PASS (or user override of BLOCK):
 
 ### 6. Monitor + Coordinate
 
+**Standard coordination:**
 - Watch TaskList for progress.
 - If backend finishes API endpoints, nudge frontend to unblock.
 - If a teammate is stuck, relay context from the other teammate.
@@ -349,6 +403,50 @@ After PASS (or user override of BLOCK):
 - If `REDTEAM_MODE=once`, defer Step 5b until all implementation steps are complete.
 - Track `REDTEAM_CYCLE`. If a BLOCK verdict is returned from Step 5b.4, pause all progress and escalate to the user before continuing.
 
+**Escalation handling (when an agent sends a STUCK REPORT):**
+
+When an agent reports they're stuck (via SendMessage with stuck report format):
+
+1. **Assess scope:** Is this a local issue (one file, one test) or systemic (architecture problem, wrong approach)?
+
+2. **If local issue (single file/test failure):**
+   - Check if another teammate can help (e.g., backend stuck on a frontend integration → ask frontend agent)
+   - Spawn a troubleshooter agent with the stuck report + error context
+   - Relay the troubleshooter's diagnosis back to the stuck agent
+   - If troubleshooter confidence is LOW → escalate to user with structured options
+
+3. **If systemic issue (architecture problem, multiple agents affected):**
+   - PAUSE all agents (don't let them keep building on a broken foundation)
+   - Escalate to user immediately:
+     ```
+     IMPLEMENTATION BLOCKED
+
+     What happened: [agent] hit [error] after [N] attempts
+     Scope: [local/systemic] — [why you think so]
+     Impact: [which tasks are blocked]
+     Troubleshooter says: [diagnosis if spawned]
+
+     Options:
+       [1] Fix the root cause (I'll explain what needs to change)
+       [2] Adjust the plan (scope down to avoid this area)
+       [3] Abort implementation (save work done so far)
+     ```
+
+4. **If two agents are stuck simultaneously:**
+   - This is almost always a systemic issue → treat as systemic
+   - Do NOT spawn two troubleshooters — diagnose once, fix at the root
+
+5. **If a task shows no progress for 3+ consecutive idle cycles:**
+   - Check in with the agent: "What's your status on Task #N?"
+   - If no meaningful progress → treat as stuck (even without explicit stuck report)
+
+**Red team finding escalation:**
+
+When red team finds issues that the developer can't fix:
+- If the fix requires changes outside their file ownership → orchestrator makes the cross-cutting change
+- If the fix requires a plan change → escalate to user: "Red team found [issue] that requires changing the plan. Original plan said [X], but we need [Y]. Approve?"
+- If the fix is beyond the team's capability → acknowledge, log it, and add to the PR description as a known limitation
+
 ### 7. Cleanup Implementation Team
 
 - Send shutdown_request to all teammates.