@polymorphism-tech/morph-spec 2.4.0 → 3.0.1

package/content/.morph/hooks/README.md

@@ -187,4 +187,162 @@ bash -x content/.morph/hooks/pre-commit-costs.sh
 
 ---
 
+## Agent Teams Hooks (Claude Code)
+
+**New in MORPH 3.0:** Hooks for Claude Code's experimental Agent Teams feature.
+
+### Available Agent Teams Hooks
+
+| Hook | Event | Description | Action |
+|------|-------|-------------|--------|
+| `teammate-idle.js` | TeammateIdle | Validates teammate's work before proceeding | ❌ Blocks if errors |
+| `task-completed.js` | TaskCompleted | Validates task deliverables on completion | ❌ Blocks if errors |
+
+### teammate-idle.js
+
+**Triggered:** When a teammate in Agent Teams is idle and waiting for instructions
+**Purpose:** Quality gate to validate recent work before allowing teammate to proceed
+**Validates:** Security, code quality, standards compliance
+
+**Usage:**
+```bash
+node content/.morph/hooks/teammate-idle.js <feature-name> [--dry-run] [--verbose]
+```
+
+**Example:**
+```bash
+node content/.morph/hooks/teammate-idle.js user-authentication --verbose
+```
+
+**Output:**
+```
+🔔 TeammateIdle Hook Triggered
+   Feature: user-authentication
+   Event: Teammate is idle, validating recent work...
+
+🎯 Executing TeammateIdle hook for feature: user-authentication
+   Validators: security-expert
+
+🔍 Running security-expert validators...
+
+✅ TeammateIdle hook: All validators passed
+```
+
+**Configuration:**
+
+Validators are configured in `agents.json` for Tier 4 agents:
+
+```json
+{
+  "security-expert": {
+    "tier": 4,
+    "role": "validator",
+    "relationships": {
+      "runs_in": "hooks",
+      "hook_triggers": ["TeammateIdle", "TaskCompleted"]
+    },
+    "hook_behavior": {
+      "validates": [
+        "SQL injection (string concatenation in queries)",
+        "Hardcoded secrets (API keys, passwords, connection strings)",
+        "XSS (@Html.Raw usage in Razor/Blazor)"
+      ],
+      "severity": "error",
+      "blocks_on_fail": true
+    }
+  }
+}
+```
+
+### task-completed.js
+
+**Triggered:** When a task is marked as completed
+**Purpose:** Quality gate to validate task deliverables before marking done
+**Validates:** All active validators for the feature
+
+**Usage:**
+```bash
+node content/.morph/hooks/task-completed.js <feature-name> <task-id> [--dry-run] [--verbose]
+```
+
+**Example:**
+```bash
+node content/.morph/hooks/task-completed.js user-authentication T003 --verbose
+```
+
+**Output:**
+```
+🔔 TaskCompleted Hook Triggered
+   Feature: user-authentication
+   Task: T003
+   Event: Task marked complete, validating deliverables...
+
+🎯 Executing TaskCompleted hook for feature: user-authentication
+   Validators: security-expert
+
+🔍 Running security-expert validators...
+
+❌ TaskCompleted hook: Validation FAILED
+
+🚫 ERRORS (blocking):
+   security-expert → security
+      • Hardcoded secret detected: API key in appsettings.json (appsettings.json:15)
+      • SQL injection risk: String concatenation in UserService.cs (UserService.cs:42)
+
+⛔ Hook execution BLOCKED - fix errors before proceeding
+
+💡 TIP: Fix the errors above before the task can be marked complete.
+```
+
+### Integration with Claude Code
+
+When Agent Teams is enabled (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`), these hooks run automatically:
+
+1. **TeammateIdle**: When a teammate finishes work and waits
+2. **TaskCompleted**: When `morph-spec task done` is called
+
+**Claude Code Settings:**
+```json
+{
+  "hooks": {
+    "TeammateIdle": "node content/.morph/hooks/teammate-idle.js {feature}",
+    "TaskCompleted": "node content/.morph/hooks/task-completed.js {feature} {taskId}"
+  }
+}
+```
+
+### Dry Run Mode
+
+Test hooks without blocking:
+
+```bash
+# See what would run without executing
+node content/.morph/hooks/teammate-idle.js my-feature --dry-run
+
+# Output:
+# 🔍 DRY RUN - Would execute:
+#    - security-expert (severity: error)
+#      • SQL injection (string concatenation in queries)
+#      • Hardcoded secrets (API keys, passwords, connection strings)
+#      • XSS (@Html.Raw usage in Razor/Blazor)
+```
+
+### Hook Behavior Configuration
+
+| Field | Description | Values |
+|-------|-------------|--------|
+| `validates` | Array of validation checks | Descriptive strings |
+| `severity` | Error level | `"error"` (blocks) \| `"warning"` (warns only) |
+| `blocks_on_fail` | Block on failure | `true` (default) \| `false` |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All validators passed |
+| 1 | Validation failed and blocked |
+| 2 | Configuration error (missing feature, etc.) |
+
+---
+
 *MORPH-SPEC Framework - Git Hooks*

package/content/.morph/hooks/task-completed.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * TaskCompleted Hook - Claude Code Agent Teams
+ *
+ * Triggered when a task is marked as completed.
+ * Validates the task deliverables before allowing the task to be marked done.
+ *
+ * Usage (from Claude Code hooks):
+ *   task-completed.js <feature-name> <task-id> [--dry-run] [--verbose]
+ *
+ * Exit codes:
+ *   0 - All validators passed
+ *   1 - Validation failed and blocked
+ *   2 - Configuration error
+ */
+
+import { executeHook, formatHookResults } from '../../../src/lib/hook-executor.js';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Get project root (3 levels up from hooks dir)
+const projectPath = join(__dirname, '../../..');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.error('Usage: task-completed.js <feature-name> <task-id> [--dry-run] [--verbose]');
+    process.exit(2);
+  }
+
+  const featureName = args[0];
+  const taskId = args[1];
+  const dryRun = args.includes('--dry-run');
+  const verbose = args.includes('--verbose');
+
+  console.log('🔔 TaskCompleted Hook Triggered');
+  console.log(`   Feature: ${featureName}`);
+  console.log(`   Task: ${taskId}`);
+  console.log(`   Event: Task marked complete, validating deliverables...\n`);
+
+  try {
+    const results = await executeHook(projectPath, featureName, 'TaskCompleted', {
+      dryRun,
+      verbose
+    });
+
+    const output = formatHookResults(results, 'TaskCompleted');
+    console.log(output);
+
+    if (results.blocked) {
+      console.log('\n💡 TIP: Fix the errors above before the task can be marked complete.');
+      console.log(`   Run: morph-spec task done ${featureName} ${taskId} --skip-validation`);
+      console.log('   (Not recommended - only use if you know what you\'re doing)');
+      process.exit(1);
+    }
+
+    console.log('\n✅ Task deliverables validated successfully.');
+    process.exit(0);
+  } catch (err) {
+    console.error(`\n❌ Hook execution error: ${err.message}`);
+    if (verbose) {
+      console.error(err.stack);
+    }
+    process.exit(2);
+  }
+}
+
+main();

package/content/.morph/hooks/teammate-idle.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * TeammateIdle Hook - Claude Code Agent Teams
+ *
+ * Triggered when a teammate is idle and waiting for next instructions.
+ * Validates the teammate's recent work before allowing them to proceed.
+ *
+ * Usage (from Claude Code hooks):
+ *   teammate-idle.js <feature-name> [--dry-run] [--verbose]
+ *
+ * Exit codes:
+ *   0 - All validators passed
+ *   1 - Validation failed and blocked
+ *   2 - Configuration error
+ */
+
+import { executeHook, formatHookResults } from '../../../src/lib/hook-executor.js';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Get project root (3 levels up from hooks dir)
+const projectPath = join(__dirname, '../../..');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: teammate-idle.js <feature-name> [--dry-run] [--verbose]');
+    process.exit(2);
+  }
+
+  const featureName = args[0];
+  const dryRun = args.includes('--dry-run');
+  const verbose = args.includes('--verbose');
+
+  console.log('🔔 TeammateIdle Hook Triggered');
+  console.log(`   Feature: ${featureName}`);
+  console.log(`   Event: Teammate is idle, validating recent work...\n`);
+
+  try {
+    const results = await executeHook(projectPath, featureName, 'TeammateIdle', {
+      dryRun,
+      verbose
+    });
+
+    const output = formatHookResults(results, 'TeammateIdle');
+    console.log(output);
+
+    if (results.blocked) {
+      console.log('\n💡 TIP: Fix the errors above before the teammate can proceed.');
+      process.exit(1);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    console.error(`\n❌ Hook execution error: ${err.message}`);
+    if (verbose) {
+      console.error(err.stack);
+    }
+    process.exit(2);
+  }
+}
+
+main();