aw-ecc 1.4.32 → 1.4.48

package/.claude-plugin/plugin.json

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

package/.cursor/INSTALL.md

@@ -20,11 +20,13 @@ Cursor-facing rules or prompts should point at:
 
 Map intent to the same public stage surface:
 
-- `/aw:plan`
-- `/aw:execute`
-- `/aw:verify`
-- `/aw:deploy`
-- `/aw:ship`
+- `/aw-adk` — create, improve, fix, score, audit CASRE artifacts in .aw_registry/
+- `/aw-publish` — push registry content to remote platform-docs via PR
+- `/aw-plan`
+- `/aw-execute`
+- `/aw-verify`
+- `/aw-deploy`
+- `/aw-ship`
 
 ## Contract Rule
 

package/.cursor/hooks/adapter.js

@@ -23,8 +23,9 @@ function readStdin() {
 }
 
 function getPluginRoot() {
-  const homeStyleRoot = path.resolve(__dirname, '..');
+  const os = require('os');
   const repoStyleRoot = path.resolve(__dirname, '..', '..');
+  const awEccHome = path.join(os.homedir(), '.aw-ecc');
 
   if (
     fs.existsSync(path.join(repoStyleRoot, 'package.json'))
@@ -34,7 +35,11 @@ function getPluginRoot() {
     return repoStyleRoot;
   }
 
-  return homeStyleRoot;
+  if (fs.existsSync(path.join(awEccHome, 'scripts', 'lib', 'aw-usage-telemetry.js'))) {
+    return awEccHome;
+  }
+
+  return path.resolve(__dirname, '..');
 }
 
 function transformToClaude(cursorInput, overrides = {}) {
@@ -43,12 +48,17 @@ function transformToClaude(cursorInput, overrides = {}) {
   const inferredToolName = cursorInput.tool_name
     || (server && tool ? `mcp__${server}__${tool}` : '');
 
+  // Preserve original tool_input fields (skill, subagent_type, description, etc.)
+  const originalToolInput = cursorInput.tool_input || {};
+
   return {
     tool_name: inferredToolName,
     server,
     tool,
+    exit_code: cursorInput.exit_code,
     tool_input: {
-      command: cursorInput.command || cursorInput.args?.command || '',
+      ...originalToolInput,
+      command: cursorInput.command || cursorInput.args?.command || originalToolInput.command || '',
       file_path: cursorInput.path || cursorInput.file || cursorInput.args?.filePath || '',
       server,
       mcp_server: server,
@@ -60,7 +70,28 @@ function transformToClaude(cursorInput, overrides = {}) {
       output: cursorInput.output || cursorInput.result || '',
       ...overrides.tool_output,
     },
+    tool_response: {
+      exit_code: cursorInput.exit_code,
+      output: cursorInput.output || cursorInput.result || '',
+    },
     transcript_path: cursorInput.transcript_path || cursorInput.transcriptPath || cursorInput.session?.transcript_path || '',
+    // Cursor common schema fields surfaced at top level for buildEvent()
+    generation_id: cursorInput.generation_id,
+    conversation_id: cursorInput.conversation_id,
+    workspace_roots: cursorInput.workspace_roots,
+    model: cursorInput.model,
+    user_email: cursorInput.user_email,
+    cursor_version: cursorInput.cursor_version,
+    status: cursorInput.status,
+    reason: cursorInput.reason,
+    // Token fields — Cursor sends these on afterAgentResponse and stop hooks
+    input_tokens: cursorInput.input_tokens,
+    output_tokens: cursorInput.output_tokens,
+    cache_read_tokens: cursorInput.cache_read_tokens,
+    cache_write_tokens: cursorInput.cache_write_tokens,
+    // Subagent fields
+    task: cursorInput.task,
+    description: cursorInput.description,
     _cursor: {
       conversation_id: cursorInput.conversation_id,
       hook_event_name: cursorInput.hook_event_name,
@@ -100,7 +131,13 @@ function runExistingHook(scriptName, stdinData) {
     path.join(root, 'scripts', 'hooks', scriptName),
     path.join(root, 'hooks', scriptName),
   ];
-  const scriptPath = candidates.find(candidate => fs.existsSync(candidate)) || candidates[0];
+  const scriptPath = candidates.find(candidate => fs.existsSync(candidate));
+  if (!scriptPath) {
+    if (process.env.AW_HOOK_DEBUG === '1') {
+      process.stderr.write(`[aw] Cannot find hook script: ${scriptName}\n`);
+    }
+    return undefined;
+  }
   return runManagedCommand('node', [scriptPath], stdinData);
 }
 

package/.cursor/hooks/after-agent-response.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Cursor afterAgentResponse hook.
+ *
+ * Fires after EVERY assistant response with token counts directly in the
+ * payload. Emits a `response_completed` telemetry event with tokens, cost,
+ * and the full common schema fields surfaced by adapter.js.
+ */
+
+'use strict';
+
+const path = require('path');
+const { readStdin, transformToClaude, getPluginRoot } = require('./adapter');
+
+readStdin().then(raw => {
+  try {
+    const root = getPluginRoot();
+    const { buildEvent, sendAsync } = require(path.join(root, 'scripts', 'lib', 'aw-usage-telemetry'));
+    const { estimateCost, toNumber } = require(path.join(root, 'scripts', 'lib', 'aw-pricing'));
+
+    const input = JSON.parse(raw);
+    const claudeInput = transformToClaude(input);
+
+    const model = input.model || claudeInput.model || null;
+    const inputTokens = toNumber(input.input_tokens);
+    const outputTokens = toNumber(input.output_tokens);
+    const cacheReadTokens = toNumber(input.cache_read_tokens);
+    const cacheWriteTokens = toNumber(input.cache_write_tokens);
+
+    const payload = {
+      stop_reason: input.status || 'end_turn',
+    };
+
+    if (model) {
+      payload.model = model;
+    }
+
+    if (inputTokens || outputTokens) {
+      payload.input_tokens = inputTokens;
+      payload.output_tokens = outputTokens;
+      payload.estimated_cost_usd = estimateCost(model, inputTokens, outputTokens, {
+        cacheReadTokens: cacheReadTokens,
+        cacheWriteTokens: cacheWriteTokens,
+      });
+    }
+
+    if (cacheReadTokens || cacheWriteTokens) {
+      payload.cache_read_tokens = cacheReadTokens;
+      payload.cache_create_tokens = cacheWriteTokens;
+    }
+
+    const event = buildEvent(claudeInput, 'response_completed', payload);
+    if (model && !event.model) {
+      event.model = model;
+    }
+    sendAsync(event);
+  } catch {
+    // Telemetry is non-blocking.
+  }
+
+  process.stdout.write('{}');
+}).catch(() => process.exit(0));

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const { readStdin, runManagedShellHook } = require('./adapter');
+const { readStdin, runManagedShellHook, runExistingHook, transformToClaude } = require('./adapter');
 
 function emitAwPromptReminder(raw) {
   const result = runManagedShellHook('scripts/hooks/shared/user-prompt-submit.sh', raw);
@@ -37,5 +37,11 @@ readStdin().then(raw => {
   } catch (_error) {
     // Reminder emission is advisory and should not break the prompt flow.
   }
+  try {
+    const claudePayload = transformToClaude(JSON.parse(raw));
+    runExistingHook('aw-usage-prompt-submit.js', JSON.stringify(claudePayload));
+  } catch (_error) {
+    // Telemetry is best-effort and should not block prompt submission.
+  }
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

package/.cursor/hooks/post-tool-use-failure.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Cursor postToolUseFailure hook — fires when any tool fails, times out, or is denied.
+ *
+ * Cursor payload: tool_name, tool_input, error_message, failure_type, duration
+ * Routes to the shared aw-usage-post-tool-use-failure.js telemetry handler.
+ */
+const { readStdin, transformToClaude, runExistingHook } = require('./adapter');
+
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const claudePayload = transformToClaude(input);
+    // Pass through Cursor's native error fields — the shared handler normalizes them
+    claudePayload.tool_name = input.tool_name || 'unknown';
+    claudePayload.error_message = input.error_message || '';
+    claudePayload.failure_type = input.failure_type || 'error';
+    runExistingHook('aw-usage-post-tool-use-failure.js', JSON.stringify(claudePayload));
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/post-tool-use.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * Cursor postToolUse hook — fires after ALL tool completions.
+ *
+ * Shell/Edit/MCP are already handled by afterShellExecution, afterFileEdit,
+ * afterMCPExecution via the phase adapter. This handler covers tools those
+ * miss — primarily Read (for skill_invoked detection).
+ */
+const { readStdin, transformToClaude, runExistingHook } = require('./adapter');
+
+// Tools already covered by specific after* hooks — skip to avoid duplicates
+const COVERED_TOOLS = new Set([
+  'shell', 'bash', 'terminal',           // afterShellExecution
+  'edit', 'write', 'file_edit',          // afterFileEdit
+  'mcp', 'mcp_tool',                     // afterMCPExecution
+]);
+
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const toolName = (input.tool_name || '').toLowerCase();
+
+    // Skip tools already covered by specific hooks
+    if (COVERED_TOOLS.has(toolName)) {
+      process.stdout.write(raw);
+      return;
+    }
+
+    // Transform and route to the shared telemetry handler
+    const claudePayload = transformToClaude(input);
+    claudePayload.tool_name = input.tool_name || 'Read';
+    claudePayload.tool_input = {
+      ...claudePayload.tool_input,
+      file_path: input.tool_input?.file_path || input.tool_input?.path || '',
+    };
+    runExistingHook('aw-usage-post-tool-use.js', JSON.stringify(claudePayload));
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

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

@@ -1,3 +1,16 @@
+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',
+});
+
 const SHARED_AW_PHASE_STEPS = Object.freeze({
   'session-start': [
     {
@@ -8,6 +21,13 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
       payloadMode: 'raw',
       outputMode: 'cursor-session-start',
     },
+    {
+      hookId: 'telemetry:session-start',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/aw-usage-session-start.js',
+      payloadMode: 'claude',
+    },
   ],
   'user-prompt-submit': [
     {
@@ -15,6 +35,13 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
       relativeScriptPath: '.cursor/hooks/shared/user-prompt-submit.sh',
       payloadMode: 'raw',
     },
+    {
+      hookId: 'telemetry:prompt-submit',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/aw-usage-prompt-submit.js',
+      payloadMode: 'claude',
+    },
   ],
   'pre-tool-use-shell': [
     {
@@ -70,6 +97,13 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
       relativeScriptPath: 'scripts/hooks/post-bash-build-complete.js',
       payloadMode: 'claude',
     },
+    {
+      hookId: 'telemetry:post-tool-use',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/aw-usage-post-tool-use.js',
+      payloadMode: 'claude',
+    },
   ],
   'post-tool-use-file-edit': [
     {
@@ -100,6 +134,13 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
       relativeScriptPath: 'scripts/hooks/post-edit-console-warn.js',
       payloadMode: 'claude',
     },
+    {
+      hookId: 'telemetry:post-tool-use',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/aw-usage-post-tool-use.js',
+      payloadMode: 'claude',
+    },
   ],
   'post-tool-use-mcp': [
     {
@@ -109,6 +150,13 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
       relativeScriptPath: 'scripts/hooks/post-mcp-log.js',
       payloadMode: 'raw',
     },
+    {
+      hookId: 'telemetry:post-tool-use',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/aw-usage-post-tool-use.js',
+      payloadMode: 'claude',
+    },
   ],
   'pre-compact': [
     {
@@ -125,6 +173,8 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
       relativeScriptPath: 'scripts/hooks/session-end-marker.js',
       payloadMode: 'claude',
     },
+    // telemetry:session-end removed — afterAgentResponse hook now emits
+    // response_completed per turn with direct token/cost data from Cursor.
   ],
   stop: [
     {
@@ -155,6 +205,8 @@ const SHARED_AW_PHASE_STEPS = Object.freeze({
       relativeScriptPath: 'scripts/hooks/cost-tracker.js',
       payloadMode: 'claude',
     },
+    // telemetry:stop removed — Cursor fires both sessionEnd and stop,
+    // causing duplicate session_ended events. Telemetry is in session-end phase only.
   ],
 });
 
@@ -167,6 +219,7 @@ function getSharedAwPhaseSteps(phaseName) {
 }
 
 module.exports = {
+  PHASE_NAMES,
   SHARED_AW_PHASE_STEPS,
   getSharedAwPhaseSteps,
 };

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

@@ -39,7 +39,9 @@ function formatCursorSessionStartOutput(stdout, fallbackRaw) {
     if (typeof additionalContext === 'string' && additionalContext.trim() !== '') {
       return `${JSON.stringify({ additional_context: additionalContext }, null, 2)}\n`;
     }
-  } catch {}
+  } catch (_error) {
+    return fallbackRaw;
+  }
 
   return fallbackRaw;
 }

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

@@ -1,10 +1,28 @@
 #!/usr/bin/env node
-const { readStdin } = require('./adapter');
+const { readStdin, transformToClaude, runExistingHook } = 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 {}
+    // Cursor subagentStart payload fields (from docs):
+    // subagent_id, subagent_type, task, parent_conversation_id, subagent_model, is_parallel_worker
+    const agentType = input.subagent_type || 'general-purpose';
+    const task = input.task || input.description || '';
+    console.error(`[ECC] Agent spawned: ${agentType} (${task.slice(0, 80)})`);
+
+    // Dispatch agent_spawned telemetry
+    const claudePayload = transformToClaude(input);
+    claudePayload.tool_name = 'Agent';
+    claudePayload.tool_input = {
+      ...claudePayload.tool_input,
+      subagent_type: agentType,
+      description: task.slice(0, 200),
+      subagent_id: input.subagent_id || '',
+      subagent_model: input.subagent_model || '',
+      is_parallel_worker: input.is_parallel_worker || false,
+    };
+    runExistingHook('aw-usage-post-tool-use.js', JSON.stringify(claudePayload));
+  } catch {
+    // Telemetry is best-effort
+  }
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

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

@@ -1,10 +1,27 @@
 #!/usr/bin/env node
-const { readStdin } = require('./adapter');
+const path = require('path');
+const { readStdin, transformToClaude, getPluginRoot } = 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}`);
+
+    // Usage telemetry — Cursor-only rich agent_completed event.
+    try {
+      const root = getPluginRoot();
+      const { buildEvent, sendAsync } = require(path.join(root, 'scripts', 'lib', 'aw-usage-telemetry'));
+      const claudeInput = transformToClaude(input);
+      sendAsync(buildEvent(claudeInput, 'agent_completed', {
+        agent_type: input.subagent_type || input.agent_name || agent,
+        status: input.status || 'unknown',
+        duration_ms: input.duration_ms || null,
+        tool_call_count: input.tool_call_count || null,
+        modified_files: input.modified_files || [],
+      }));
+    } catch {
+      // Telemetry is non-blocking.
+    }
   } catch {}
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

package/.cursor/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "sessionStart": [
       {
-        "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\"",
+        "command": "bash -c 'f=\"$PWD/.cursor/hooks/session-start.sh\"; [ -f \"$f\" ] || f=\"$HOME/.cursor/hooks/session-start.sh\"; exec bash \"$f\"'",
         "event": "sessionStart",
         "description": "Load previous context and detect environment"
       }
@@ -64,7 +64,7 @@
     ],
     "beforeSubmitPrompt": [
       {
-        "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\"",
+        "command": "bash -c 'f=\"$PWD/.cursor/hooks/before-submit-prompt.sh\"; [ -f \"$f\" ] || f=\"$HOME/.cursor/hooks/before-submit-prompt.sh\"; exec bash \"$f\"'",
         "event": "beforeSubmitPrompt",
         "description": "Detect secrets in prompts (sk-, ghp_, AKIA patterns)"
       }
@@ -83,6 +83,20 @@
         "description": "Log agent completion"
       }
     ],
+    "postToolUse": [
+      {
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"post-tool-use.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": "postToolUse",
+        "description": "Telemetry: skill_invoked detection for Read tool and other non-shell/edit/MCP tools"
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"post-tool-use-failure.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": "postToolUseFailure",
+        "description": "Telemetry: tool_error detection on tool failure/timeout/denial"
+      }
+    ],
     "beforeTabFileRead": [
       {
         "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)\"",
@@ -104,6 +118,13 @@
         "description": "Save state before context compaction"
       }
     ],
+    "afterAgentResponse": [
+      {
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"after-agent-response.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": "afterAgentResponse",
+        "description": "Telemetry: response_completed with tokens and cost per turn"
+      }
+    ],
     "stop": [
       {
         "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)\"",

package/.opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecc-universal",
-  "version": "1.4.25",
+  "version": "1.4.47",
   "description": "Everything Claude Code (ECC) plugin for OpenCode - agents, commands, hooks, and skills",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/AGENTS.md

@@ -4,11 +4,11 @@ Use the repo-local AW SDLC files as the source of truth for routing and stage be
 
 ## Catalog Snapshot
 
-Catalog snapshot: providing 28 specialized agents, 158 skills, 69 commands for repo-local AW SDLC routing.
+Catalog snapshot: providing 28 specialized agents, 173 skills, 72 commands for repo-local AW SDLC routing.
 
 agents/ - 28 specialized subagents
-skills/ - 157 workflow skills and domain knowledge
-commands/ - 69 slash commands
+skills/ - 173 workflow skills and domain knowledge
+commands/ - 72 slash commands
 
 ## Public Surface
 

package/README.md

@@ -9,18 +9,18 @@
 The current catalog exposed by this repo is:
 
 - 28 agents
-- 158 skills
-- 69 commands
+- 173 skills
+- 72 commands
 
 ## Quick Start Snapshot
 
-Installing `aw-ecc` gives your workspace access to 28 agents, 158 skills, and 69 commands through the repo-local AW command surface plus GHL-specific skill and policy layers.
+Installing `aw-ecc` gives your workspace access to 28 agents, 173 skills, and 72 commands through the repo-local AW command surface plus GHL-specific skill and policy layers.
 
 | Surface | Availability |
 | --- | --- |
 | Agents | ✅ 28 agents |
-| Skills | ✅ 158 skills |
-| Commands | ✅ 69 commands |
+| Skills | ✅ 173 skills |
+| Commands | ✅ 72 commands |
 
 These catalog counts are validated in CI so the published docs stay aligned with the repo contents.
 

package/commands/adk.md

@@ -0,0 +1,52 @@
+---
+name: aw:adk
+description: "Agent Development Kit — create, improve, fix, delete, score, comply, audit, or health-check any CASRE artifact (Command, Agent, Skill, Rule, Eval). Use /aw:adk to author registry content."
+argument-hint: "[type] [mode] [target] — e.g., 'agent create', 'skill score my-skill', 'rule audit all', 'agent delete my-agent'"
+status: active
+stage: build
+internal_skill: aw-adk
+---
+
+# ADK — Agent Development Kit
+
+Use `/aw:adk` to author, score, fix, delete, or audit any artifact in the AW registry.
+
+## Usage
+
+```
+/aw:adk                          → interactive: ask type, then mode
+/aw:adk agent create             → create a new agent (guided)
+/aw:adk skill improve my-skill   → enrich an existing skill
+/aw:adk agent fix my-agent       → resolve lint failures
+/aw:adk skill score my-skill     → score against rubric
+/aw:adk rule audit all           → audit all rules
+/aw:adk eval create my-agent     → create evals for existing agent
+/aw:adk agent delete my-agent    → remove agent + evals + clean references
+```
+
+## Arguments
+
+| Position | Values | Default |
+|---|---|---|
+| type | `command` · `agent` · `skill` · `rule` · `eval` | interactive (ask) |
+| mode | `create` · `improve` · `fix` · `delete` · `score` · `comply` · `audit` · `health` | interactive (ask) |
+| target | artifact name or `all` (for audit/health) | interactive (ask) |
+
+## Execution
+
+**Step 1: Read the skill file.** Open and read `~/.aw-ecc/skills/aw-adk/SKILL.md` before doing anything else. Do not skip this — the skill contains the full flow, templates, rubrics, and scripts. All reference files are relative to that skill directory.
+
+**Step 2: Follow the create flow steps in order.** Every type (command, agent, skill, rule, eval) goes through the same pipeline. Here are the steps you must not skip:
+
+1. CLASSIFY → 2. INTERVIEW → 3. RESOLVE PATH → 4. SCAFFOLD → 5. CHECKPOINT (output remaining steps to user) → 6. LINT → 7. SCORE → 8. EVAL GATE (2+ evals) → 9. TEST RUNS → 10. ITERATE → 11. DESCRIPTION OPT → 12. CROSS-IDE → 13. REGISTRY UPDATES → 14. SYNC
+
+If you find yourself writing the artifact and then jumping to "done" — you skipped steps 5-14. Go back.
+
+## When No Arguments
+
+If invoked without arguments, ask the user:
+1. What type of artifact? (with the quick classifier table from the skill)
+2. What mode? (with brief descriptions of each)
+3. What target? (name or path)
+
+Then proceed with the skill's flow for that combination.

package/commands/build.md

@@ -42,6 +42,16 @@ Implement approved work in thin, reversible slices, continue until the approved
 - tests or validation changes where applicable
 - `.aw_docs/features/<feature_slug>/execution.md`
 - updated `.aw_docs/features/<feature_slug>/state.json`
+- `.aw_docs/features/<feature_slug>/execution.html` when docs output mode is `dual` or `html`
+
+## Human HTML Companion
+
+Markdown `execution.md` remains canonical for agents.
+When `/aw:build` writes or materially updates execution evidence, delegate to the `aw:echo` subagent with the `implementation-plan` profile. Markdown-only is allowed only when the user explicitly requests it for this run.
+Subagent authorization: invoking `/aw:build` in `dual` or `html` output mode is an explicit user request to delegate the human-facing HTML companion to exactly one background `aw:echo` subagent. This authorization is scoped only to HTML companion generation; do not spawn unrelated subagents.
+HTML sidecars are required before the final handoff. Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn, record `generated_fallback` with the blocker, and keep Markdown canonical.
+
+Record `html_companion_artifacts` in `state.json` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
 
 ## Execution Rules
 
@@ -51,15 +61,17 @@ Implement approved work in thin, reversible slices, continue until the approved
 4. Default to sequential execution unless the approved plan marks disjoint `parallel_candidate` slices with explicit write scopes.
 5. If parallel fan-out is approved, respect the plan’s `max_parallel_subagents` cap, defaulting to `3` when no stricter or larger value is justified.
 6. Break non-trivial work into thin, rollback-friendly slices or bounded parallel waves.
-7. Validate each slice or completed wave before expanding scope.
-8. Keep moving through approved slices until the current build scope is complete or explicitly blocked.
-9. For bug work, require a failing signal or reproduction before broad fixes.
-10. For frontend work, inherit HighRise, accessibility, responsive, and runtime-verification expectations.
-11. Record what changed, what remains, whether execution stayed sequential or ran in bounded parallel waves, and what was intentionally not touched.
-12. If the approved tasks are phased, record each completed phase and name the next phase before handoff.
-13. Create save-point commits for meaningful completed slices.
-14. If a proposed slice cannot support a clean save-point commit, treat that as a slicing problem instead of normalizing a no-commit checkpoint.
-15. Hand off to `/aw:test` or `/aw:review` with the exact next command instead of claiming readiness without evidence.
+7. For each slice that changes observable behavior, load `tdd-workflow` and follow RED-GREEN-REFACTOR; use the `tdd` companion skill when deeper behavior-test, mocking, or tracer-bullet guidance is needed.
+8. Validate each slice or completed wave before expanding scope.
+9. Keep moving through approved slices until the current build scope is complete or explicitly blocked.
+10. For bug work, require a failing signal or reproduction before broad fixes.
+11. For frontend work, inherit HighRise, accessibility, responsive, and runtime-verification expectations.
+12. Record what changed, what remains, whether execution stayed sequential or ran in bounded parallel waves, and what was intentionally not touched.
+13. If the approved tasks are phased, record each completed phase and name the next phase before handoff.
+14. Create save-point commits for meaningful completed slices.
+15. If a proposed slice cannot support a clean save-point commit, treat that as a slicing problem instead of normalizing a no-commit checkpoint.
+16. Hand off to `/aw:test` or `/aw:review` with the exact next command instead of claiming readiness without evidence.
+17. Generate or explicitly record the HTML companion status before handoff.
 
 ## Must Not Do
 
@@ -87,5 +99,6 @@ Always end with:
 - `Changes`
 - `Validation`
 - `Save Points`
+- `HTML Companion`
 - `Blockers`
 - `Next`