aw-ecc 1.4.23 → 1.4.31

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aw",
-  "version": "1.4.23",
+  "version": "1.4.25",
   "description": "GoHighLevel Agentic Workspace Engine — agents, skills, commands, hooks, and rules for GHL development workflows.",
   "author": {
     "name": "GoHighLevel",

package/.cursor/INSTALL.md

@@ -11,6 +11,7 @@ Cursor-facing rules or prompts should point at:
 - `AGENTS.md`
 - `commands/`
 - `skills/`
+- `.cursor/rules/common-aw-routing.md`
 - `defaults/aw-sdlc/`
 - `docs/aw-sdlc-command-contracts.md`
 - `docs/aw-sdlc-command-skill-architecture.md`
@@ -29,6 +30,14 @@ Map intent to the same public stage surface:
 
 Cursor-specific prompt wrappers may exist, but they should stay thinner than the AW SDLC stage skills and must not introduce extra public stages.
 
+The global Cursor routing rule should be `alwaysApply: true` and must:
+
+- require `using-aw-skills` first
+- require the smallest correct AW stage route first
+- point Cursor at bundled AW skills under `~/.cursor/skills/`
+- point Cursor at org rules under `~/.aw_rules/platform/`
+- keep repo-local instructions additive only
+
 ## Artifact Rule
 
 Deterministic artifacts stay under:

package/.cursor/hooks/adapter.js

@@ -6,6 +6,7 @@
  */
 
 const { execFileSync } = require('child_process');
+const fs = require('fs');
 const path = require('path');
 
 const MAX_STDIN = 1024 * 1024;
@@ -22,7 +23,18 @@ function readStdin() {
 }
 
 function getPluginRoot() {
-  return path.resolve(__dirname, '..', '..');
+  const homeStyleRoot = path.resolve(__dirname, '..');
+  const repoStyleRoot = path.resolve(__dirname, '..', '..');
+
+  if (
+    fs.existsSync(path.join(repoStyleRoot, 'package.json'))
+    && fs.existsSync(path.join(repoStyleRoot, 'scripts', 'hooks'))
+    && fs.existsSync(path.join(repoStyleRoot, '.cursor', 'hooks'))
+  ) {
+    return repoStyleRoot;
+  }
+
+  return homeStyleRoot;
 }
 
 function transformToClaude(cursorInput, overrides = {}) {
@@ -83,12 +95,31 @@ function runManagedCommand(command, args, stdinData) {
 }
 
 function runExistingHook(scriptName, stdinData) {
-  const scriptPath = path.join(getPluginRoot(), 'scripts', 'hooks', scriptName);
+  const root = getPluginRoot();
+  const candidates = [
+    path.join(root, 'scripts', 'hooks', scriptName),
+    path.join(root, 'hooks', scriptName),
+  ];
+  const scriptPath = candidates.find(candidate => fs.existsSync(candidate)) || candidates[0];
   return runManagedCommand('node', [scriptPath], stdinData);
 }
 
 function runManagedShellHook(relativeScriptPath, stdinData) {
-  const scriptPath = path.join(getPluginRoot(), relativeScriptPath);
+  const root = getPluginRoot();
+  const normalized = String(relativeScriptPath || '').replace(/\\/g, '/');
+  const fallbackCandidates = [
+    normalized,
+    normalized.replace(/^\.cursor\//, ''),
+    normalized.replace(/^scripts\//, ''),
+    normalized.replace(/^hooks\//, ''),
+    path.posix.join('.cursor', normalized),
+    path.posix.join('scripts', normalized),
+    path.posix.join('hooks', normalized),
+  ];
+  const scriptPath = fallbackCandidates
+    .map(candidate => path.join(root, candidate))
+    .find(candidate => fs.existsSync(candidate))
+    || path.join(root, normalized);
   return runManagedCommand('bash', [scriptPath], stdinData);
 }
 

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

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const {
+  SHARED_AW_PHASE_STEPS: CURSOR_AW_PHASE_STEPS,
+  getSharedAwPhaseSteps: getCursorAwPhaseSteps,
+} = require('./shared/aw-phase-definitions');
+
+module.exports = {
+  CURSOR_AW_PHASE_STEPS,
+  getCursorAwPhaseSteps,
+};

package/.cursor/hooks/before-submit-prompt.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+RAW="$(cat || true)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+RESULT="$(printf '%s' "$RAW" | node "$SCRIPT_DIR/before-submit-prompt.js" 2>&1 1>/tmp/aw_cursor_before_submit_stdout.$$)"
+STATUS=$?
+STDOUT_CONTENT="$(cat /tmp/aw_cursor_before_submit_stdout.$$ 2>/dev/null || true)"
+rm -f /tmp/aw_cursor_before_submit_stdout.$$
+
+if [ -n "$RESULT" ]; then
+  printf '%s\n' "$RESULT" >&2
+fi
+
+printf '%s' "${STDOUT_CONTENT:-$RAW}"
+exit "$STATUS"

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

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+RAW="$(cat || true)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+RESULT="$(printf '%s' "$RAW" | bash "$SCRIPT_DIR/shared/session-start.sh")"
+
+if [ -z "$RESULT" ]; then
+  printf '%s' "$RAW"
+  exit 0
+fi
+
+JSON_CONTEXT="$(
+  printf '%s' "$RESULT" | node -e '
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", chunk => input += chunk);
+    process.stdin.on("end", () => {
+      try {
+        const parsed = JSON.parse(input || "{}");
+        const context =
+          (parsed && parsed.hookSpecificOutput && parsed.hookSpecificOutput.additionalContext) ||
+          parsed.additional_context ||
+          "";
+        if (typeof context === "string" && context.trim()) {
+          process.stdout.write(JSON.stringify({ additional_context: context }, null, 2) + "\n");
+          return;
+        }
+      } catch {}
+      process.stdout.write(process.env.ECC_FALLBACK_RAW || "");
+    });
+  ' ECC_FALLBACK_RAW="$RAW"
+)"
+
+printf '%s' "$JSON_CONTEXT"

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

@@ -6,6 +6,7 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
       runner: 'shell',
       relativeScriptPath: '.cursor/hooks/shared/session-start.sh',
       payloadMode: 'raw',
+      outputMode: 'cursor-session-start',
     },
   ],
   'user-prompt-submit': [
@@ -157,24 +158,6 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
   ],
 });
 
-/**
- * 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) {
@@ -184,7 +167,6 @@ function getSharedAwPhaseSteps(phaseName) {
 }
 
 module.exports = {
-  PHASE_NAMES,
   SHARED_AW_PHASE_STEPS,
   getSharedAwPhaseSteps,
 };

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

@@ -26,6 +26,37 @@ function executeStep(runtime, step, payload) {
   return runtime.runManagedNodeHook(step.relativeScriptPath, payload);
 }
 
+function formatCursorSessionStartOutput(stdout, fallbackRaw) {
+  if (typeof stdout !== 'string' || stdout.trim() === '') {
+    return fallbackRaw;
+  }
+
+  try {
+    const payload = JSON.parse(stdout);
+    const additionalContext = payload?.hookSpecificOutput?.additionalContext
+      || payload?.additional_context;
+
+    if (typeof additionalContext === 'string' && additionalContext.trim() !== '') {
+      return `${JSON.stringify({ additional_context: additionalContext }, null, 2)}\n`;
+    }
+  } catch {}
+
+  return fallbackRaw;
+}
+
+function resolveStepOutput(step, execution, fallbackRaw) {
+  if (!execution) {
+    return null;
+  }
+
+  switch (step.outputMode) {
+    case 'cursor-session-start':
+      return formatCursorSessionStartOutput(execution.stdout, fallbackRaw);
+    default:
+      return null;
+  }
+}
+
 async function runSharedAwPhase({ raw, steps, deps = {} }) {
   const runtime = {
     transformToClaude: deps.transformToClaude,
@@ -43,6 +74,7 @@ async function runSharedAwPhase({ raw, steps, deps = {} }) {
 
   const needsClaudeInput = steps.some(step => (step.payloadMode || 'claude') === 'claude');
   const claudeInput = needsClaudeInput ? runtime.transformToClaude(parsedInput) : null;
+  let result = raw;
 
   for (const step of steps) {
     if (!shouldRunStep(step, runtime)) {
@@ -50,10 +82,14 @@ async function runSharedAwPhase({ raw, steps, deps = {} }) {
     }
 
     const payload = resolveStepPayload(step, raw, parsedInput, claudeInput);
-    await executeStep(runtime, step, payload);
+    const execution = await executeStep(runtime, step, payload);
+    const nextResult = resolveStepOutput(step, execution, raw);
+    if (typeof nextResult === 'string') {
+      result = nextResult;
+    }
   }
 
-  return raw;
+  return result;
 }
 
 module.exports = {

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

@@ -1,71 +1,51 @@
 #!/usr/bin/env bash
-# UserPromptSubmit hook — emit a small, reliable AW routing reminder.
-#
-# This hook intentionally stays simple:
-# - drain stdin so the harness can always finish writing payloads
-# - remind the model to re-apply using-aw-skills
-# - point at AGENTS.md and the canonical .aw_rules/platform tree when present
-
 set -euo pipefail
 
-cat >/dev/null || true
-
-# On Windows (Git Bash / MSYS), pwd returns POSIX paths (/tmp/...)
-# but callers use native Windows paths (C:\Users\...).
-# Convert via cygpath when available so paths match the caller's format.
-if command -v cygpath >/dev/null 2>&1; then
-  CWD="$(cygpath -w "$(pwd)")"
-else
-  CWD="$(pwd)"
-fi
-AGENTS_PATH="$CWD/AGENTS.md"
-RULES_ROOT=""
-
-for candidate in \
-  "$CWD/.aw_rules/platform" \
-  "$HOME/.aw_rules/platform" \
-  "$HOME/.aw/.aw_rules/platform"
-do
-  if [ -d "$candidate" ]; then
-    RULES_ROOT="$candidate"
-    break
-  fi
-done
-
-RULE_REFS=()
+RAW="$(cat || true)"
+
+extract_workspace_root() {
+  printf '%s' "$1" | sed -n 's/.*"workspace_roots"[[:space:]]*:[[:space:]]*\[[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1
+}
+
+extract_cwd() {
+  printf '%s' "$1" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1
+}
+
+resolve_rules_root() {
+  local root="${1:-}"
+  local cwd_dir
+  cwd_dir="$(pwd)"
+  local candidate
+
+  for candidate in \
+    "$root/.aw/.aw_rules/platform" \
+    "$root/.aw_rules/platform" \
+    "$cwd_dir/.aw/.aw_rules/platform" \
+    "$cwd_dir/.aw_rules/platform" \
+    "$HOME/.aw/.aw_rules/platform" \
+    "$HOME/.aw_rules/platform" \
+    "$HOME/.aw/.aw_registry/.aw_rules/platform"
+  do
+    if [ -n "$candidate" ] && [ -d "$candidate" ]; then
+      printf '%s' "$candidate"
+      return 0
+    fi
+  done
 
-if [ -f "$AGENTS_PATH" ]; then
-  RULE_REFS+=("$AGENTS_PATH")
-fi
+  return 1
+}
 
-if [ -n "$RULES_ROOT" ]; then
-  if [ -f "$RULES_ROOT/universal/AGENTS.md" ]; then
-    RULE_REFS+=("$RULES_ROOT/universal/AGENTS.md")
-  fi
-  if [ -f "$RULES_ROOT/security/AGENTS.md" ]; then
-    RULE_REFS+=("$RULES_ROOT/security/AGENTS.md")
-  fi
-  RULE_SCOPE="Applicable domain rules live under $RULES_ROOT."
-else
-  RULE_SCOPE="Applicable domain rules live under .aw_rules/platform when synced."
+WORKSPACE_ROOT="$(extract_workspace_root "$RAW")"
+if [ -z "$WORKSPACE_ROOT" ]; then
+  WORKSPACE_ROOT="$(extract_cwd "$RAW")"
 fi
 
-if [ "${#RULE_REFS[@]}" -gt 0 ]; then
-  RULE_PATHS=""
-  while IFS= read -r line; do
-    if [ -z "$RULE_PATHS" ]; then
-      RULE_PATHS="$line"
-    else
-      RULE_PATHS="$RULE_PATHS, $line"
-    fi
-  done < <(printf '%s\n' "${RULE_REFS[@]}" | awk '!seen[$0]++')
-else
-  RULE_PATHS="AGENTS.md"
+RULES_ROOT="$(resolve_rules_root "$WORKSPACE_ROOT" || true)"
+if [ -z "$RULES_ROOT" ]; then
+  RULES_ROOT="$HOME/.aw_rules/platform"
 fi
 
 cat <<EOF
-[AW Router reminder] Re-apply using-aw-skills for this prompt and select the smallest correct AW route and stage skill before substantive work.
-[Rules reminder] Start with $RULE_PATHS. Universal and security rules always apply. $RULE_SCOPE
+[AW Router reminder] Re-apply using-aw-skills and select the smallest correct AW route before substantive work.
+[Rule reminder] Read ${RULES_ROOT}/universal/AGENTS.md and ${RULES_ROOT}/security/AGENTS.md, then the touched domain AGENTS.md plus references/ on demand.
 EOF
-
-exit 0

package/.cursor/hooks.json

@@ -3,14 +3,14 @@
   "hooks": {
     "sessionStart": [
       {
-        "command": "node .cursor/hooks/session-start.js",
+        "command": "bash -lc \"for candidate in \\\"$PWD/.cursor/hooks/session-start.sh\\\" \\\"$HOME/.cursor/hooks/session-start.sh\\\"; do if [ -f \\\"$candidate\\\" ]; then exec bash \\\"$candidate\\\"; fi; done; exit 0\"",
         "event": "sessionStart",
         "description": "Load previous context and detect environment"
       }
     ],
     "sessionEnd": [
       {
-        "command": "node .cursor/hooks/session-end.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"session-end.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "sessionEnd",
         "description": "Persist session state and evaluate patterns"
       }
@@ -22,91 +22,91 @@
         "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",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"before-shell-execution.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "beforeShellExecution",
         "description": "Tmux dev server blocker, tmux reminder, git push review"
       }
     ],
     "afterShellExecution": [
       {
-        "command": "node .cursor/hooks/after-shell-execution.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"after-shell-execution.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "afterShellExecution",
         "description": "PR URL logging, build analysis"
       }
     ],
     "afterFileEdit": [
       {
-        "command": "node .cursor/hooks/after-file-edit.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"after-file-edit.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "afterFileEdit",
         "description": "Auto-format, TypeScript check, console.log warning"
       }
     ],
     "beforeMCPExecution": [
       {
-        "command": "node .cursor/hooks/before-mcp-execution.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"before-mcp-execution.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "beforeMCPExecution",
         "description": "MCP audit logging and untrusted server warning"
       }
     ],
     "afterMCPExecution": [
       {
-        "command": "node .cursor/hooks/after-mcp-execution.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"after-mcp-execution.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "afterMCPExecution",
         "description": "MCP result logging"
       }
     ],
     "beforeReadFile": [
       {
-        "command": "node .cursor/hooks/before-read-file.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"before-read-file.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "beforeReadFile",
         "description": "Warn when reading sensitive files (.env, .key, .pem)"
       }
     ],
     "beforeSubmitPrompt": [
       {
-        "command": "node .cursor/hooks/before-submit-prompt.js",
+        "command": "bash -lc \"for candidate in \\\"$PWD/.cursor/hooks/before-submit-prompt.sh\\\" \\\"$HOME/.cursor/hooks/before-submit-prompt.sh\\\"; do if [ -f \\\"$candidate\\\" ]; then exec bash \\\"$candidate\\\"; fi; done; exit 0\"",
         "event": "beforeSubmitPrompt",
         "description": "Detect secrets in prompts (sk-, ghp_, AKIA patterns)"
       }
     ],
     "subagentStart": [
       {
-        "command": "node .cursor/hooks/subagent-start.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"subagent-start.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "subagentStart",
         "description": "Log agent spawning for observability"
       }
     ],
     "subagentStop": [
       {
-        "command": "node .cursor/hooks/subagent-stop.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"subagent-stop.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "subagentStop",
         "description": "Log agent completion"
       }
     ],
     "beforeTabFileRead": [
       {
-        "command": "node .cursor/hooks/before-tab-file-read.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"before-tab-file-read.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "beforeTabFileRead",
         "description": "Block Tab from reading secrets (.env, .key, .pem, credentials)"
       }
     ],
     "afterTabFileEdit": [
       {
-        "command": "node .cursor/hooks/after-tab-file-edit.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"after-tab-file-edit.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "afterTabFileEdit",
         "description": "Auto-format Tab edits"
       }
     ],
     "preCompact": [
       {
-        "command": "node .cursor/hooks/pre-compact.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"pre-compact.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "preCompact",
         "description": "Save state before context compaction"
       }
     ],
     "stop": [
       {
-        "command": "node .cursor/hooks/stop.js",
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"stop.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
         "event": "stop",
         "description": "Console.log audit on all modified files"
       }

package/.cursor/rules/common-aw-routing.md

@@ -0,0 +1,43 @@
+---
+description: "AW global routing: use the AW router skill first, then apply org rules and references by domain"
+alwaysApply: true
+---
+# AW Global Routing
+
+- Before any substantive response, load `using-aw-skills` from `~/.cursor/skills/using-aw-skills/SKILL.md`.
+- Select the smallest correct AW route first:
+  - `/aw:plan`
+  - `/aw:build`
+  - `/aw:investigate`
+  - `/aw:test`
+  - `/aw:review`
+  - `/aw:deploy`
+  - `/aw:ship`
+- For non-trivial requests, the first substantive line should be `Selected AW Route: <route>`.
+- After the route is known, load the matching AW stage skill from `~/.cursor/skills/` and only the smallest supporting skills needed.
+
+## Org Rules
+
+- Always read:
+  - `~/.aw_rules/platform/universal/AGENTS.md`
+  - `~/.aw_rules/platform/security/AGENTS.md`
+- Then pick the smallest correct domain rule based on the requirement and current context, and read it before acting:
+  - `api-design` -> `~/.aw_rules/platform/api-design/AGENTS.md`
+  - `backend` -> `~/.aw_rules/platform/backend/AGENTS.md`
+  - `data` -> `~/.aw_rules/platform/data/AGENTS.md`
+  - `frontend` -> `~/.aw_rules/platform/frontend/AGENTS.md`
+  - `infra` -> `~/.aw_rules/platform/infra/AGENTS.md`
+  - `mobile` -> `~/.aw_rules/platform/mobile/AGENTS.md`
+  - `sdet` -> `~/.aw_rules/platform/sdet/AGENTS.md`
+- Load `references/` under the chosen domain on demand when implementation details or canonical links matter.
+- If repo-local instructions conflict with org-level AW rules, follow the org-level AW rules.
+
+## Route Hints
+
+- Ideas, architecture, specs, planning, new project setup, and database choice -> `/aw:plan`
+- Implementation, bug fixing, and build work -> `/aw:build`
+- Unclear failures, alerts, or root-cause hunting -> `/aw:investigate`
+- QA proof, regression evidence, and validation -> `/aw:test`
+- Findings, readiness, and approval decisions -> `/aw:review`
+- One release action -> `/aw:deploy`
+- Rollout, rollback readiness, and closeout -> `/aw:ship`

package/.cursor/skills/api-and-interface-design/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: api-and-interface-design
+description: Designs stable APIs and module boundaries. Use when changing public contracts, service interfaces, component props, or any boundary another system or team depends on.
+origin: ECC
+---
+
+# API and Interface Design
+
+## Overview
+
+Design interfaces that are stable, documented, and hard to misuse.
+This applies to REST and GraphQL APIs, TypeScript contracts, event payloads, component props, database-informed boundaries, and service-to-service interfaces.
+
+## When to Use
+
+- designing or changing API endpoints
+- defining interfaces between modules, services, or teams
+- shaping component props or shared library contracts
+- planning data contracts that other code depends on
+- changing existing public behavior that consumers may already rely on
+
+**When NOT to use**
+
+- the change is fully internal and does not cross a meaningful boundary
+- the work is purely implementation with no contract implications
+
+## Workflow
+
+1. Name the boundary and its consumers first.
+   Clarify who consumes the interface and what kind of compatibility risk exists:
+   user clients, internal services, frontend callers, workers, or shared packages.
+2. Define the contract before the implementation.
+   Write the request and response shape, error semantics, idempotency rules, and ordering guarantees before coding the handler.
+   Use `../../references/interface-stability.md` and `api-design` when the surface is HTTP-facing.
+3. Treat observable behavior as part of the contract.
+   Apply Hyrum's Law thinking:
+   if consumers can observe it, they may depend on it.
+   Avoid leaking implementation details, inconsistent error patterns, or unstable defaults.
+4. Validate at the boundary, not everywhere.
+   Validate user input, third-party responses, environment configuration, and external payloads where they enter the system.
+   Keep internal code paths simpler once the boundary is trusted.
+5. Prefer extension over breaking change.
+   Add optional fields, new endpoints, new event versions, or adapters before removing or changing existing semantics.
+   If a breaking change is unavoidable, load `deprecation-and-migration`.
+6. Record the long-lived design decision.
+   For important public or architectural contracts, update docs or ADRs through `documentation-and-adrs`.
+   In GHL- or AW-governed repos, align the contract with `.aw_rules`, platform APIs, and baseline expectations.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "We can document the contract later." | The contract is the design. If it is unclear now, implementation will drift. |
+| "Nobody depends on that behavior." | If it is observable, somebody eventually will. |
+| "We can just support two versions forever." | Version sprawl multiplies maintenance and creates dependency pain. |
+| "Validation everywhere is safer." | Boundary validation is safer and simpler than repeating checks throughout internal code. |
+
+## Red Flags
+
+- different endpoints or modules expose inconsistent error behavior
+- breaking changes are introduced without migration or compatibility planning
+- boundary validation is missing for user or third-party input
+- implementation details leak into public behavior or naming
+- the team cannot explain what part of the behavior is contract versus accident
+
+## Verification
+
+After designing or changing an interface, confirm:
+
+- [ ] the consumers and compatibility surface are explicit
+- [ ] the contract exists before or alongside implementation
+- [ ] error semantics and validation boundaries are consistent
+- [ ] additions were preferred over breaking changes where possible
+- [ ] deprecation or migration is planned for any unavoidable break
+- [ ] important interface decisions are documented for future engineers and agents