aw-ecc 1.4.21

package/.codex/INSTALL.md

@@ -0,0 +1,64 @@
+# AW SDLC Install for Codex
+
+## Goal
+
+Use this repo as a repo-local AW SDLC control plane inside Codex without depending on a machine-global router.
+
+## Required Repo Paths
+
+Codex should treat these repo-local paths as the source of truth:
+
+- `AGENTS.md`
+- `commands/`
+- `skills/`
+- `defaults/aw-sdlc/`
+- `docs/aw-sdlc-command-contracts.md`
+- `docs/aw-sdlc-command-skill-architecture.md`
+
+The root `AGENTS.md` should provide the first repo-local instruction layer so Codex does not fall back to a parent workspace prompt when running AW SDLC flows in isolation.
+
+## Runtime Rule
+
+At session start, prefer the repo-local router:
+
+- `skills/using-aw-skills/SKILL.md`
+
+Only fall back to an external `.aw_registry` when the repo does not provide its own AW SDLC routing layer.
+
+## Public Commands
+
+The canonical public surface must remain:
+
+- `/aw:plan`
+- `/aw:execute`
+- `/aw:verify`
+- `/aw:deploy`
+- `/aw:ship`
+
+Internal helpers such as `aw-brainstorm`, `aw-prepare`, `aw-review-loop`, `aw-systematic-debugging`, and `aw-finish` should stay behind the public stage boundary.
+
+## Smoke Test
+
+A minimal Codex install is healthy when all of the following are true:
+
+1. a planning request resolves to `/aw:plan`
+2. an implementation request resolves to `/aw:execute`
+3. a review request resolves to `/aw:verify`
+4. a release request resolves to `/aw:deploy`
+5. the repo-local router wins over any global fallback
+
+## Artifact Contract
+
+Deterministic stage artifacts should continue to live under:
+
+- `.aw_docs/features/<feature_slug>/`
+
+with stage-specific outputs such as:
+
+- `prd.md`
+- `design.md`
+- `spec.md`
+- `tasks.md`
+- `execution.md`
+- `verification.md`
+- `state.json`

package/.codex/agents/docs-researcher.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Verify APIs, framework behavior, and release-note claims against primary documentation before changes land.
+Cite the exact docs or file paths that support each claim.
+Do not invent undocumented behavior.
+"""

package/.codex/agents/explorer.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Stay in exploration mode.
+Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
+Prefer targeted search and file reads over broad scans.
+"""

package/.codex/agents/reviewer.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Review like an owner.
+Prioritize correctness, security, behavioral regressions, and missing tests.
+Lead with concrete findings and avoid style-only feedback unless it hides a real bug.
+"""

package/.codex/config.toml

@@ -0,0 +1,108 @@
+#:schema https://developers.openai.com/codex/config-schema.json
+
+# Everything Claude Code (ECC) — Codex Reference Configuration
+#
+# Copy this file to ~/.codex/config.toml for global defaults, or keep it in
+# the project root as .codex/config.toml for project-local settings.
+#
+# Official docs:
+# - https://developers.openai.com/codex/config-reference
+# - https://developers.openai.com/codex/multi-agent
+
+# Model selection
+# Leave `model` and `model_provider` unset so Codex CLI uses its current
+# built-in defaults. Uncomment and pin them only if you intentionally want
+# repo-local or global model overrides.
+
+# Top-level runtime settings (current Codex schema)
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+web_search = "live"
+persistent_instructions = true
+
+# External notifications receive a JSON payload on stdin.
+notify = [
+  "terminal-notifier",
+  "-title", "Codex ECC",
+  "-message", "Task completed!",
+  "-sound", "default",
+]
+
+# Prefer AGENTS.md and project-local .codex/AGENTS.md for instructions.
+# model_instructions_file replaces built-in instructions instead of AGENTS.md,
+# so leave it unset unless you intentionally want a single override file.
+# model_instructions_file = "/absolute/path/to/instructions.md"
+
+# MCP servers
+# Keep the default project set lean. API-backed servers inherit credentials from
+# the launching environment or can be supplied by a user-level ~/.codex/config.toml.
+[mcp_servers.github]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-github"]
+
+[mcp_servers.context7-mcp]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp@latest"]
+
+[mcp_servers.exa]
+url = "https://mcp.exa.ai/mcp"
+
+[mcp_servers.memory]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-memory"]
+
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@playwright/mcp@latest", "--extension"]
+
+[mcp_servers.sequential-thinking]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+
+# Additional MCP servers (uncomment as needed):
+# [mcp_servers.supabase]
+# command = "npx"
+# args = ["-y", "supabase-mcp-server@latest", "--read-only"]
+#
+# [mcp_servers.firecrawl]
+# command = "npx"
+# args = ["-y", "firecrawl-mcp"]
+#
+# [mcp_servers.fal-ai]
+# command = "npx"
+# args = ["-y", "fal-ai-mcp-server"]
+#
+# [mcp_servers.cloudflare]
+# command = "npx"
+# args = ["-y", "@cloudflare/mcp-server-cloudflare"]
+
+[features]
+# Codex multi-agent support is experimental as of March 2026.
+multi_agent = true
+
+# Profiles — switch with `codex -p <name>`
+[profiles.strict]
+approval_policy = "on-request"
+sandbox_mode = "read-only"
+web_search = "cached"
+
+[profiles.yolo]
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+web_search = "live"
+
+[agents]
+max_threads = 6
+max_depth = 1
+
+[agents.explorer]
+description = "Read-only codebase explorer for gathering evidence before changes are proposed."
+config_file = "agents/explorer.toml"
+
+[agents.reviewer]
+description = "PR reviewer focused on correctness, security, and missing tests."
+config_file = "agents/reviewer.toml"
+
+[agents.docs_researcher]
+description = "Documentation specialist that verifies APIs, framework behavior, and release notes."
+config_file = "agents/docs-researcher.toml"

package/.codex/hooks/aw-post-tool-use.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Reserved AW PostToolUse phase for Codex home routing.
+exit 0

package/.codex/hooks/aw-pre-tool-use.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Reserved AW PreToolUse phase for Codex home routing.
+exit 0

package/.codex/hooks/aw-session-start.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TARGETS=(
+  "$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 in "${TARGETS[@]}"; do
+  if [[ -f "$target" ]]; then
+    exec bash "$target"
+  fi
+done
+
+CONTEXT="# AW Session Context
+
+WARNING: AW using-aw-skills hook not found in ~/.aw_registry. Run aw init or aw pull platform."
+
+JSON_CONTEXT=$(printf '%s' "$CONTEXT" | python3 -c 'import json, sys; print(json.dumps(sys.stdin.read()))')
+
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":${JSON_CONTEXT}}}"

package/.codex/hooks/aw-stop.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Reserved AW Stop phase for Codex home routing.
+exit 0

package/.codex/hooks/aw-user-prompt-submit.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TARGET="$HOME/.aw-ecc/scripts/hooks/session-start-rules-context.sh"
+if [[ -f "$TARGET" ]]; then
+  exec bash "$TARGET"
+fi
+
+exit 0

package/.codex/hooks.json

@@ -0,0 +1,62 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'bash \"$HOME/.codex/hooks/aw-session-start.sh\"'"
+          }
+        ],
+        "description": "Load AW routing context at session start"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'bash \"$HOME/.codex/hooks/aw-user-prompt-submit.sh\"'"
+          }
+        ],
+        "description": "Inject compact AW routing and rule reminders on each prompt"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'bash \"$HOME/.codex/hooks/aw-pre-tool-use.sh\"'"
+          }
+        ],
+        "description": "Reserved AW pre-tool-use phase for Codex home installs"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'bash \"$HOME/.codex/hooks/aw-post-tool-use.sh\"'"
+          }
+        ],
+        "description": "Reserved AW post-tool-use phase for Codex home installs"
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'bash \"$HOME/.codex/hooks/aw-stop.sh\"'"
+          }
+        ],
+        "description": "Reserved AW stop phase for Codex home installs"
+      }
+    ]
+  }
+}

package/.cursor/INSTALL.md

@@ -0,0 +1,40 @@
+# AW SDLC Install for Cursor
+
+## Goal
+
+Use AW SDLC as the repo-local control plane while Cursor continues to provide the editor and execution runtime.
+
+## Required Repo Paths
+
+Cursor-facing rules or prompts should point at:
+
+- `AGENTS.md`
+- `commands/`
+- `skills/`
+- `defaults/aw-sdlc/`
+- `docs/aw-sdlc-command-contracts.md`
+- `docs/aw-sdlc-command-skill-architecture.md`
+
+## Public Commands
+
+Map intent to the same public stage surface:
+
+- `/aw:plan`
+- `/aw:execute`
+- `/aw:verify`
+- `/aw:deploy`
+- `/aw:ship`
+
+## Contract Rule
+
+Cursor-specific prompt wrappers may exist, but they should stay thinner than the AW SDLC stage skills and must not introduce extra public stages.
+
+## Artifact Rule
+
+Deterministic artifacts stay under:
+
+- `.aw_docs/features/<feature_slug>/`
+
+## Smoke Bar
+
+The install is healthy when a planning request, implementation request, review request, release request, and full ship request all resolve to the AW SDLC stage model instead of a Cursor-only workflow vocabulary.

package/.cursor/hooks/adapter.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Cursor-to-Claude Code Hook Adapter
+ * Transforms Cursor stdin JSON to Claude Code hook format,
+ * then delegates to existing scripts/hooks/*.js
+ */
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);
+    });
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+function getPluginRoot() {
+  return path.resolve(__dirname, '..', '..');
+}
+
+function transformToClaude(cursorInput, overrides = {}) {
+  const server = cursorInput.server || cursorInput.mcp_server || '';
+  const tool = cursorInput.tool || cursorInput.mcp_tool || '';
+  const inferredToolName = cursorInput.tool_name
+    || (server && tool ? `mcp__${server}__${tool}` : '');
+
+  return {
+    tool_name: inferredToolName,
+    server,
+    tool,
+    tool_input: {
+      command: cursorInput.command || cursorInput.args?.command || '',
+      file_path: cursorInput.path || cursorInput.file || cursorInput.args?.filePath || '',
+      server,
+      mcp_server: server,
+      tool,
+      mcp_tool: tool,
+      ...overrides.tool_input,
+    },
+    tool_output: {
+      output: cursorInput.output || cursorInput.result || '',
+      ...overrides.tool_output,
+    },
+    transcript_path: cursorInput.transcript_path || cursorInput.transcriptPath || cursorInput.session?.transcript_path || '',
+    _cursor: {
+      conversation_id: cursorInput.conversation_id,
+      hook_event_name: cursorInput.hook_event_name,
+      workspace_roots: cursorInput.workspace_roots,
+      model: cursorInput.model,
+    },
+  };
+}
+
+function runManagedCommand(command, args, stdinData) {
+  try {
+    const stdout = execFileSync(command, args, {
+      input: typeof stdinData === 'string' ? stdinData : JSON.stringify(stdinData),
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 15000,
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    });
+
+    return {
+      stdout: stdout || '',
+      stderr: '',
+    };
+  } catch (e) {
+    if (e.status === 2) process.exit(2);
+
+    return {
+      stdout: typeof e.stdout === 'string' ? e.stdout : String(e.stdout || ''),
+      stderr: typeof e.stderr === 'string' ? e.stderr : String(e.stderr || ''),
+    };
+  }
+}
+
+function runExistingHook(scriptName, stdinData) {
+  const scriptPath = path.join(getPluginRoot(), 'scripts', 'hooks', scriptName);
+  return runManagedCommand('node', [scriptPath], stdinData);
+}
+
+function runManagedShellHook(relativeScriptPath, stdinData) {
+  const scriptPath = path.join(getPluginRoot(), relativeScriptPath);
+  return runManagedCommand('bash', [scriptPath], stdinData);
+}
+
+function hookEnabled(hookId, allowedProfiles = ['standard', 'strict']) {
+  const rawProfile = String(process.env.ECC_HOOK_PROFILE || 'standard').toLowerCase();
+  const profile = ['minimal', 'standard', 'strict'].includes(rawProfile) ? rawProfile : 'standard';
+
+  const disabled = new Set(
+    String(process.env.ECC_DISABLED_HOOKS || '')
+      .split(',')
+      .map(v => v.trim().toLowerCase())
+      .filter(Boolean)
+  );
+
+  if (disabled.has(String(hookId || '').toLowerCase())) {
+    return false;
+  }
+
+  return allowedProfiles.includes(profile);
+}
+
+module.exports = {
+  readStdin,
+  getPluginRoot,
+  transformToClaude,
+  runExistingHook,
+  runManagedShellHook,
+  hookEnabled,
+};

package/.cursor/hooks/after-file-edit.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.POST_TOOL_USE_FILE_EDIT,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

package/.cursor/hooks/after-mcp-execution.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.POST_TOOL_USE_MCP,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

package/.cursor/hooks/after-shell-execution.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.POST_TOOL_USE_SHELL,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

package/.cursor/hooks/after-tab-file-edit.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+const { readStdin, runExistingHook, transformToClaude } = require('./adapter');
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const claudeInput = transformToClaude(input, {
+      tool_input: { file_path: input.path || input.file || '' }
+    });
+    runExistingHook('post-edit-format.js', JSON.stringify(claudeInput));
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

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

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+const {
+  transformToClaude,
+  runExistingHook,
+  runManagedShellHook,
+  hookEnabled,
+} = require('./adapter');
+const { getSharedAwPhaseSteps: getCursorAwPhaseSteps } = require('./shared/aw-phase-definitions');
+const { runSharedAwPhase } = require('./shared/aw-phase-runner');
+
+function runManagedNodeHook(relativeScriptPath, payload) {
+  const scriptName = String(relativeScriptPath || '')
+    .replace(/^scripts\/hooks\//, '')
+    .replace(/^\.cursor\/hooks\//, '');
+  return runExistingHook(scriptName, payload);
+}
+
+async function runCursorAwPhase({ raw, steps, deps = {} }) {
+  return runSharedAwPhase({
+    raw,
+    steps,
+    deps: {
+      transformToClaude: deps.transformToClaude || transformToClaude,
+      runManagedNodeHook: deps.runManagedNodeHook || runManagedNodeHook,
+      runManagedShellHook: deps.runManagedShellHook || runManagedShellHook,
+      hookEnabled: deps.hookEnabled || hookEnabled,
+    },
+  });
+}
+
+function runNamedCursorAwPhase({ phaseName, raw, deps = {} }) {
+  return runCursorAwPhase({
+    raw,
+    steps: getCursorAwPhaseSteps(phaseName),
+    deps,
+  });
+}
+
+module.exports = {
+  runCursorAwPhase,
+  runNamedCursorAwPhase,
+};

package/.cursor/hooks/before-mcp-execution.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_TOOL_USE_MCP,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

package/.cursor/hooks/before-read-file.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const filePath = input.path || input.file || '';
+    if (/\.(env|key|pem)$|\.env\.|credentials|secret/i.test(filePath)) {
+      console.error('[ECC] WARNING: Reading sensitive file: ' + filePath);
+      console.error('[ECC] Ensure this data is not exposed in outputs');
+    }
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/before-shell-execution.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_TOOL_USE_SHELL,
+    raw,
+  }).then(output => process.stdout.write(output));
+}).catch(() => process.exit(0));

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

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+const { readStdin, runManagedShellHook } = require('./adapter');
+
+function emitAwPromptReminder(raw) {
+  const result = runManagedShellHook('.cursor/hooks/shared/user-prompt-submit.sh', raw);
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+  if (result.stdout) {
+    process.stderr.write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+  }
+}
+
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const prompt = input.prompt || input.content || input.message || '';
+    const secretPatterns = [
+      /sk-[a-zA-Z0-9]{20,}/,       // OpenAI API keys
+      /ghp_[a-zA-Z0-9]{36,}/,      // GitHub personal access tokens
+      /AKIA[A-Z0-9]{16}/,          // AWS access keys
+      /xox[bpsa]-[a-zA-Z0-9-]+/,   // Slack tokens
+      /-----BEGIN (RSA |EC )?PRIVATE KEY-----/, // Private keys
+    ];
+    for (const pattern of secretPatterns) {
+      if (pattern.test(prompt)) {
+        console.error('[ECC] WARNING: Potential secret detected in prompt!');
+        console.error('[ECC] Remove secrets before submitting. Use environment variables instead.');
+        break;
+      }
+    }
+  } catch (_error) {
+    // Best-effort prompt scanning should never block prompt submission.
+  }
+  try {
+    emitAwPromptReminder(raw);
+  } catch (_error) {
+    // Reminder emission is advisory and should not break the prompt flow.
+  }
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/before-tab-file-read.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const filePath = input.path || input.file || '';
+    if (/\.(env|key|pem)$|\.env\.|credentials|secret/i.test(filePath)) {
+      console.error('[ECC] BLOCKED: Tab cannot read sensitive file: ' + filePath);
+      process.exit(2);
+    }
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));