aw-ecc 1.4.21

package/.cursor/hooks/pre-compact.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+const { runNamedCursorAwPhase } = require('./aw-phase-adapter');
+const { PHASE_NAMES } = require('./shared/aw-phase-definitions');
+
+readStdin().then(raw => {
+  return runNamedCursorAwPhase({
+    phaseName: PHASE_NAMES.PRE_COMPACT,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

package/.cursor/hooks/session-end.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+const { runNamedCursorAwPhase } = require('./aw-phase-adapter');
+const { PHASE_NAMES } = require('./shared/aw-phase-definitions');
+
+readStdin().then(raw => {
+  return runNamedCursorAwPhase({
+    phaseName: PHASE_NAMES.SESSION_END,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

package/.cursor/hooks/session-start.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+const { runNamedCursorAwPhase } = require('./aw-phase-adapter');
+const { PHASE_NAMES } = require('./shared/aw-phase-definitions');
+
+readStdin().then(raw => {
+  return runNamedCursorAwPhase({
+    phaseName: PHASE_NAMES.SESSION_START,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

package/.cursor/hooks/shared/aw-phase-definitions.js

@@ -0,0 +1,190 @@
+const SHARED_AW_PHASE_STEPS = Object.freeze({
+  'session-start': [
+    {
+      hookId: 'session:start',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'shell',
+      relativeScriptPath: '.cursor/hooks/shared/session-start.sh',
+      payloadMode: 'raw',
+    },
+  ],
+  'user-prompt-submit': [
+    {
+      runner: 'shell',
+      relativeScriptPath: '.cursor/hooks/shared/user-prompt-submit.sh',
+      payloadMode: 'raw',
+    },
+  ],
+  'pre-tool-use-shell': [
+    {
+      hookId: 'pre:bash:dev-server-block',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-bash-dev-server-block.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'pre:bash:tmux-reminder',
+      allowedProfiles: ['strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-bash-tmux-reminder.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'pre:bash:git-push-reminder',
+      allowedProfiles: ['strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-bash-git-push-reminder.js',
+      payloadMode: 'claude',
+    },
+  ],
+  'pre-tool-use-mcp': [
+    {
+      hookId: 'pre:mcp-health-check',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/mcp-health-check.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'pre:mcp:audit-log',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-mcp-log.js',
+      payloadMode: 'raw',
+    },
+  ],
+  'post-tool-use-shell': [
+    {
+      hookId: 'post:bash:pr-created',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-bash-pr-created.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'post:bash:build-complete',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-bash-build-complete.js',
+      payloadMode: 'claude',
+    },
+  ],
+  'post-tool-use-file-edit': [
+    {
+      hookId: 'post:quality-gate',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/quality-gate.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'post:edit:format',
+      allowedProfiles: ['strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-edit-format.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'post:edit:typecheck',
+      allowedProfiles: ['strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-edit-typecheck.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'post:edit:console-warn',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-edit-console-warn.js',
+      payloadMode: 'claude',
+    },
+  ],
+  'post-tool-use-mcp': [
+    {
+      hookId: 'post:mcp:audit-log',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-mcp-log.js',
+      payloadMode: 'raw',
+    },
+  ],
+  'pre-compact': [
+    {
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-compact.js',
+      payloadMode: 'claude',
+    },
+  ],
+  'session-end': [
+    {
+      hookId: 'session:end:marker',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/session-end-marker.js',
+      payloadMode: 'claude',
+    },
+  ],
+  stop: [
+    {
+      hookId: 'stop:check-console-log',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/check-console-log.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'stop:session-end',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/session-end.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'stop:evaluate-session',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/evaluate-session.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'stop:cost-tracker',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/cost-tracker.js',
+      payloadMode: 'claude',
+    },
+  ],
+});
+
+/**
+ * Canonical string constants for all AW hook phase names.
+ * Use these instead of raw string literals to get typo-safety and IDE
+ * auto-complete in files that call runNamedCursorAwPhase() or equivalent.
+ */
+const PHASE_NAMES = Object.freeze({
+  SESSION_START: 'session-start',
+  USER_PROMPT_SUBMIT: 'user-prompt-submit',
+  PRE_TOOL_USE_SHELL: 'pre-tool-use-shell',
+  PRE_TOOL_USE_MCP: 'pre-tool-use-mcp',
+  POST_TOOL_USE_SHELL: 'post-tool-use-shell',
+  POST_TOOL_USE_FILE_EDIT: 'post-tool-use-file-edit',
+  POST_TOOL_USE_MCP: 'post-tool-use-mcp',
+  PRE_COMPACT: 'pre-compact',
+  SESSION_END: 'session-end',
+  STOP: 'stop',
+});
+
+function getSharedAwPhaseSteps(phaseName) {
+  const steps = SHARED_AW_PHASE_STEPS[phaseName];
+  if (!steps) {
+    throw new Error(`Unknown shared AW phase: ${phaseName}`);
+  }
+  return steps;
+}
+
+module.exports = {
+  PHASE_NAMES,
+  SHARED_AW_PHASE_STEPS,
+  getSharedAwPhaseSteps,
+};

package/.cursor/hooks/shared/aw-phase-runner.js

@@ -0,0 +1,61 @@
+function shouldRunStep(step, runtime) {
+  if (!step.hookId) {
+    return true;
+  }
+
+  return runtime.hookEnabled(step.hookId, step.allowedProfiles || ['standard', 'strict']);
+}
+
+function resolveStepPayload(step, raw, parsedInput, claudeInput) {
+  switch (step.payloadMode) {
+    case 'raw':
+      return raw;
+    case 'parsed':
+      return parsedInput;
+    case 'claude':
+    default:
+      return claudeInput;
+  }
+}
+
+function executeStep(runtime, step, payload) {
+  if (step.runner === 'shell') {
+    return runtime.runManagedShellHook(step.relativeScriptPath, payload);
+  }
+
+  return runtime.runManagedNodeHook(step.relativeScriptPath, payload);
+}
+
+async function runSharedAwPhase({ raw, steps, deps = {} }) {
+  const runtime = {
+    transformToClaude: deps.transformToClaude,
+    runManagedNodeHook: deps.runManagedNodeHook,
+    runManagedShellHook: deps.runManagedShellHook,
+    hookEnabled: deps.hookEnabled,
+  };
+
+  let parsedInput = {};
+  try {
+    parsedInput = JSON.parse(raw || '{}');
+  } catch {
+    return raw;
+  }
+
+  const needsClaudeInput = steps.some(step => (step.payloadMode || 'claude') === 'claude');
+  const claudeInput = needsClaudeInput ? runtime.transformToClaude(parsedInput) : null;
+
+  for (const step of steps) {
+    if (!shouldRunStep(step, runtime)) {
+      continue;
+    }
+
+    const payload = resolveStepPayload(step, raw, parsedInput, claudeInput);
+    await executeStep(runtime, step, payload);
+  }
+
+  return raw;
+}
+
+module.exports = {
+  runSharedAwPhase,
+};

package/.cursor/hooks/shared/session-start.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+CANDIDATES=(
+  "$ROOT_DIR/skills/using-aw-skills/hooks/session-start.sh"
+  "$HOME/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"
+  "$HOME/.aw/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"
+)
+
+for TARGET_SCRIPT in "${CANDIDATES[@]}"; do
+  if [[ -f "$TARGET_SCRIPT" ]]; then
+    exec bash "$TARGET_SCRIPT"
+  fi
+done
+
+echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "WARNING: AW session-start hook not found in the installed aw-ecc bundle or ~/.aw_registry."}}'
+exit 0

package/.cursor/hooks/shared/user-prompt-submit.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — inject a compact AW routing reminder plus scoped rule reminders
+#
+# Output is printed to stdout as a plain-text prompt reminder.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TMPFILE=$(mktemp) || exit 0
+trap 'rm -f "$TMPFILE"' EXIT
+
+PYTHON_CMD=""
+PYTHON_ARGS=()
+
+resolve_python_cmd() {
+  if [ -n "${CLV2_PYTHON_CMD:-}" ] && command -v "$CLV2_PYTHON_CMD" >/dev/null 2>&1; then
+    PYTHON_CMD="$CLV2_PYTHON_CMD"
+    PYTHON_ARGS=()
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    PYTHON_CMD="python3"
+    PYTHON_ARGS=()
+    return 0
+  fi
+
+  if command -v python >/dev/null 2>&1; then
+    PYTHON_CMD="python"
+    PYTHON_ARGS=()
+    return 0
+  fi
+
+  if command -v py >/dev/null 2>&1; then
+    PYTHON_CMD="py"
+    PYTHON_ARGS=(-3)
+    return 0
+  fi
+
+  return 1
+}
+
+resolve_python_cmd || exit 0
+
+if [ "${#PYTHON_ARGS[@]}" -gt 0 ]; then
+  echo "$INPUT" | "$PYTHON_CMD" "${PYTHON_ARGS[@]}" -c "
+import os, sys, json, re
+d = json.load(sys.stdin)
+cwd = d.get('cwd', '')
+prompt = d.get('prompt', '')
+cwd = re.sub(r'[^a-zA-Z0-9./_@:\\\\~\ -]', '', cwd)
+prompt = prompt[:500]
+stack_overlays_enabled = os.environ.get('AW_ENABLE_STACK_OVERLAY_RULES') == '1'
+print(f'CWD={cwd}')
+prompt_lower = prompt.lower()
+if any(k in prompt_lower for k in ['controller', 'service', 'module', '@body', 'nestjs', 'worker', 'dto']):
+    print('DOMAIN=backend')
+    if stack_overlays_enabled and any(k in prompt_lower for k in ['nestjs', '@body', '@controller', '@module', 'class-validator', 'dto']):
+        print('STACK=nestjs')
+    elif stack_overlays_enabled and any(k in prompt_lower for k in ['connectrpc', 'connect-go', 'buf.gen', 'protoc-gen-connect-go']):
+        print('STACK=go-connect')
+elif any(k in prompt_lower for k in ['vue', 'component', 'template', 'frontend', '<script', 'nuxt']):
+    print('DOMAIN=frontend')
+    if stack_overlays_enabled and any(k in prompt_lower for k in ['nuxt', 'app.vue', 'useasyncdata', 'definepagemeta']):
+        print('STACK=nuxt')
+    elif stack_overlays_enabled and any(k in prompt_lower for k in ['vue', '<script', 'script setup', 'composable']):
+        print('STACK=vue')
+elif any(k in prompt_lower for k in ['mongo', 'redis', 'schema', 'migration', 'database', 'index']):
+    print('DOMAIN=data')
+elif any(k in prompt_lower for k in ['helm', 'terraform', 'kubernetes', 'k8s', 'deploy', 'dockerfile']):
+    print('DOMAIN=infra')
+else:
+    print('DOMAIN=universal')
+" > "$TMPFILE" 2>/dev/null || exit 0
+else
+  echo "$INPUT" | "$PYTHON_CMD" -c "
+import os, sys, json, re
+d = json.load(sys.stdin)
+cwd = d.get('cwd', '')
+prompt = d.get('prompt', '')
+cwd = re.sub(r'[^a-zA-Z0-9./_@:\\\\~\ -]', '', cwd)
+prompt = prompt[:500]
+stack_overlays_enabled = os.environ.get('AW_ENABLE_STACK_OVERLAY_RULES') == '1'
+print(f'CWD={cwd}')
+prompt_lower = prompt.lower()
+if any(k in prompt_lower for k in ['controller', 'service', 'module', '@body', 'nestjs', 'worker', 'dto']):
+    print('DOMAIN=backend')
+    if stack_overlays_enabled and any(k in prompt_lower for k in ['nestjs', '@body', '@controller', '@module', 'class-validator', 'dto']):
+        print('STACK=nestjs')
+    elif stack_overlays_enabled and any(k in prompt_lower for k in ['connectrpc', 'connect-go', 'buf.gen', 'protoc-gen-connect-go']):
+        print('STACK=go-connect')
+elif any(k in prompt_lower for k in ['vue', 'component', 'template', 'frontend', '<script', 'nuxt']):
+    print('DOMAIN=frontend')
+    if stack_overlays_enabled and any(k in prompt_lower for k in ['nuxt', 'app.vue', 'useasyncdata', 'definepagemeta']):
+        print('STACK=nuxt')
+    elif stack_overlays_enabled and any(k in prompt_lower for k in ['vue', '<script', 'script setup', 'composable']):
+        print('STACK=vue')
+elif any(k in prompt_lower for k in ['mongo', 'redis', 'schema', 'migration', 'database', 'index']):
+    print('DOMAIN=data')
+elif any(k in prompt_lower for k in ['helm', 'terraform', 'kubernetes', 'k8s', 'deploy', 'dockerfile']):
+    print('DOMAIN=infra')
+else:
+    print('DOMAIN=universal')
+" > "$TMPFILE" 2>/dev/null || exit 0
+fi
+
+CWD="" DOMAIN="universal" STACK=""
+while IFS='=' read -r key value; do
+  # Strip trailing \r from Windows Python CRLF output
+  key="${key%$'\r'}"
+  value="${value%$'\r'}"
+  case "${key:-}" in
+    CWD)    CWD="$value" ;;
+    DOMAIN) DOMAIN="$value" ;;
+    STACK)  STACK="$value" ;;
+  esac
+done < "$TMPFILE"
+
+RULES_DIR=""
+DOMAIN_AGENTS=""
+STACK_AGENTS=""
+
+if [ -d "$CWD/.aw_registry/.aw_rules/platform" ]; then
+  RULES_DIR="$CWD/.aw_registry/.aw_rules/platform"
+  DOMAIN_AGENTS="$RULES_DIR/$DOMAIN/AGENTS.md"
+elif [ -d "$CWD/.aw_rules" ]; then
+  RULES_DIR="$CWD/.aw_rules"
+  DOMAIN_AGENTS="$RULES_DIR/$DOMAIN/AGENTS.md"
+fi
+
+[ -n "$RULES_DIR" ] || exit 0
+[ -f "$DOMAIN_AGENTS" ] || exit 0
+
+if [ -n "$STACK" ] && [ -f "$RULES_DIR/$DOMAIN/$STACK/AGENTS.md" ]; then
+  STACK_AGENTS="$RULES_DIR/$DOMAIN/$STACK/AGENTS.md"
+fi
+
+DOMAIN_RULES=$(head -20 "$DOMAIN_AGENTS" 2>/dev/null || echo "")
+STACK_RULES=""
+if [ -n "$STACK_AGENTS" ]; then
+  STACK_RULES=$(head -20 "$STACK_AGENTS" 2>/dev/null || echo "")
+fi
+
+RULE_BULLETS=$(printf '%s\n%s\n' "$DOMAIN_RULES" "$STACK_RULES" | grep -E "^\- .*(MUST|Never)" | awk '!seen[$0]++' | head -8 2>/dev/null || true)
+
+[ -z "$DOMAIN_RULES" ] && [ -z "$STACK_RULES" ] && exit 0
+
+cat << EOF
+[AW Router reminder] Re-apply using-aw-skills for this prompt and re-select the smallest correct AW route and stage skill before substantive work.
+[Rule reminder — $RULES_DIR/$DOMAIN${STACK_AGENTS:+/$STACK}] Active MUST rules for this scope. Follow them.
+${RULE_BULLETS:-See $DOMAIN_AGENTS${STACK_AGENTS:+ and $STACK_AGENTS}}
+EOF
+
+exit 0

package/.cursor/hooks/stop.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+const { runNamedCursorAwPhase } = require('./aw-phase-adapter');
+const { PHASE_NAMES } = require('./shared/aw-phase-definitions');
+
+readStdin().then(raw => {
+  return runNamedCursorAwPhase({
+    phaseName: PHASE_NAMES.STOP,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

package/.cursor/hooks/subagent-start.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const agent = input.agent_name || input.agent || 'unknown';
+    console.error(`[ECC] Agent spawned: ${agent}`);
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/subagent-stop.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const agent = input.agent_name || input.agent || 'unknown';
+    console.error(`[ECC] Agent completed: ${agent}`);
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks.json

@@ -0,0 +1,115 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "node .cursor/hooks/session-start.js",
+        "event": "sessionStart",
+        "description": "Load previous context and detect environment"
+      }
+    ],
+    "sessionEnd": [
+      {
+        "command": "node .cursor/hooks/session-end.js",
+        "event": "sessionEnd",
+        "description": "Persist session state and evaluate patterns"
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "command": "npx block-no-verify@1.1.2",
+        "event": "beforeShellExecution",
+        "description": "Block git hook-bypass flag to protect pre-commit, commit-msg, and pre-push hooks from being skipped"
+      },
+      {
+        "command": "node .cursor/hooks/before-shell-execution.js",
+        "event": "beforeShellExecution",
+        "description": "Tmux dev server blocker, tmux reminder, git push review"
+      }
+    ],
+    "afterShellExecution": [
+      {
+        "command": "node .cursor/hooks/after-shell-execution.js",
+        "event": "afterShellExecution",
+        "description": "PR URL logging, build analysis"
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "node .cursor/hooks/after-file-edit.js",
+        "event": "afterFileEdit",
+        "description": "Auto-format, TypeScript check, console.log warning"
+      }
+    ],
+    "beforeMCPExecution": [
+      {
+        "command": "node .cursor/hooks/before-mcp-execution.js",
+        "event": "beforeMCPExecution",
+        "description": "MCP audit logging and untrusted server warning"
+      }
+    ],
+    "afterMCPExecution": [
+      {
+        "command": "node .cursor/hooks/after-mcp-execution.js",
+        "event": "afterMCPExecution",
+        "description": "MCP result logging"
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": "node .cursor/hooks/before-read-file.js",
+        "event": "beforeReadFile",
+        "description": "Warn when reading sensitive files (.env, .key, .pem)"
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "node .cursor/hooks/before-submit-prompt.js",
+        "event": "beforeSubmitPrompt",
+        "description": "Detect secrets in prompts (sk-, ghp_, AKIA patterns)"
+      }
+    ],
+    "subagentStart": [
+      {
+        "command": "node .cursor/hooks/subagent-start.js",
+        "event": "subagentStart",
+        "description": "Log agent spawning for observability"
+      }
+    ],
+    "subagentStop": [
+      {
+        "command": "node .cursor/hooks/subagent-stop.js",
+        "event": "subagentStop",
+        "description": "Log agent completion"
+      }
+    ],
+    "beforeTabFileRead": [
+      {
+        "command": "node .cursor/hooks/before-tab-file-read.js",
+        "event": "beforeTabFileRead",
+        "description": "Block Tab from reading secrets (.env, .key, .pem, credentials)"
+      }
+    ],
+    "afterTabFileEdit": [
+      {
+        "command": "node .cursor/hooks/after-tab-file-edit.js",
+        "event": "afterTabFileEdit",
+        "description": "Auto-format Tab edits"
+      }
+    ],
+    "preCompact": [
+      {
+        "command": "node .cursor/hooks/pre-compact.js",
+        "event": "preCompact",
+        "description": "Save state before context compaction"
+      }
+    ],
+    "stop": [
+      {
+        "command": "node .cursor/hooks/stop.js",
+        "event": "stop",
+        "description": "Console.log audit on all modified files"
+      }
+    ]
+  }
+}

package/.cursor/rules/common-agents.md

@@ -0,0 +1,53 @@
+---
+description: "Agent orchestration: available agents, parallel execution, multi-perspective analysis"
+alwaysApply: true
+---
+# Agent Orchestration
+
+## Available Agents
+
+Located in `~/.claude/agents/`:
+
+| Agent | Purpose | When to Use |
+|-------|---------|-------------|
+| planner | Implementation planning | Complex features, refactoring |
+| architect | System design | Architectural decisions |
+| tdd-guide | Test-driven development | New features, bug fixes |
+| code-reviewer | Code review | After writing code |
+| security-reviewer | Security analysis | Before commits |
+| build-error-resolver | Fix build errors | When build fails |
+| e2e-runner | E2E testing | Critical user flows |
+| refactor-cleaner | Dead code cleanup | Code maintenance |
+| doc-updater | Documentation | Updating docs |
+
+## Immediate Agent Usage
+
+No user prompt needed:
+1. Complex feature requests - Use **planner** agent
+2. Code just written/modified - Use **code-reviewer** agent
+3. Bug fix or new feature - Use **tdd-guide** agent
+4. Architectural decision - Use **architect** agent
+
+## Parallel Task Execution
+
+ALWAYS use parallel Task execution for independent operations:
+
+```markdown
+# GOOD: Parallel execution
+Launch 3 agents in parallel:
+1. Agent 1: Security analysis of auth module
+2. Agent 2: Performance review of cache system
+3. Agent 3: Type checking of utilities
+
+# BAD: Sequential when unnecessary
+First agent 1, then agent 2, then agent 3
+```
+
+## Multi-Perspective Analysis
+
+For complex problems, use split role sub-agents:
+- Factual reviewer
+- Senior engineer
+- Security expert
+- Consistency reviewer
+- Redundancy checker