@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

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

@@ -1,239 +1,348 @@
-# MORPH-SPEC Git Hooks
-
-Pre-commit hooks for automatic validation before committing.
-
-## Available Hooks
-
-| Hook | Description | Action |
-|------|-------------|--------|
-| `pre-commit-agents.sh` | Validates agents.json with JSON Schema | ❌ Blocks commit |
-| `pre-commit-costs.sh` | Validates Azure costs don't exceed limits | ❌ Blocks commit |
-| `pre-commit-specs.sh` | Validates spec.md has required sections | ❌ Blocks commit |
-| `pre-commit-tests.sh` | Checks if new code has tests | ⚠️ Warns only |
-| `pre-commit-all.sh` | Runs all hooks in sequence | ❌ Blocks if any fail |
-
-## Installation
-
-### Option 1: Install Individual Hooks
-
-```bash
-# Install cost validation
-ln -s ../../content/.morph/hooks/pre-commit-costs.sh .git/hooks/pre-commit
-
-# Or symlink all at once
-ln -s ../../content/.morph/hooks/pre-commit-all.sh .git/hooks/pre-commit
-```
-
-### Option 2: Copy Hooks
-
-```bash
-# Copy master hook
-cp content/.morph/hooks/pre-commit-all.sh .git/hooks/pre-commit
-chmod +x .git/hooks/pre-commit
-```
-
-### Option 3: Use Existing Hooks
-
-If you already have `.git/hooks/pre-commit`, add this to the end:
-
-```bash
-# Run MORPH-SPEC validations
-bash content/.morph/hooks/pre-commit-all.sh || exit 1
-```
-
-## What Each Hook Does
-
-### pre-commit-agents.sh
-
-**Validates:** `agents.json` configuration
-
-**Checks:**
-- JSON Schema compliance
-- Required fields (id, name, emoji, type, etc.)
-- Keyword patterns (alphanumeric + hyphens/underscores)
-- No duplicate keywords
-- autoActivation for specialist agents
-
-**Example Output:**
-```
-🤖 Validating agent configuration...
-Detected changes to agents.json
-
-=== MORPH-SPEC Agent Validator ===
-
-Version: 1.0.0
-Core Agents: 6
-Specialist Agents: 4
-
-✓ Validation PASSED
-```
-
-### pre-commit-costs.sh
-
-**Validates:** Bicep files for Azure costs
-
-**Checks:**
-- Parses modified `.bicep` files
-- Calculates monthly costs
-- Blocks if > `requiresADR` limit (default: $10)
-- Checks if ADR exists in decisions.md
-
-**Example Output:**
-```
-💰 Calculating Azure costs...
-
-╔════════════════════════════════════════════════╗
-║ sqlDatabase (Basic)              $4.99/mo     ║
-║ containerApp (Consumption)       $0.00/mo     ║
-╠════════════════════════════════════════════════╣
-║ Total: $4.99                                   ║
-║ Requires ADR: NO                               ║
-╚════════════════════════════════════════════════╝
-
-✓ Cost validation passed
-```
-
-### pre-commit-specs.sh
-
-**Validates:** `spec.md` files have required sections
-
-**Checks:**
-- `## 📋 Metadata`
-- `## 🎯 Overview`
-- `## 🏗️ Technical Design`
-- `## ✅ Acceptance Criteria`
-- Warns if no user stories found
-
-**Example Output:**
-```
-🔍 Validating spec files...
-Checking: .morph/outputs/my-feature/spec.md
-  ✓ All required sections found
-✓ All spec files are valid
-```
-
-### pre-commit-tests.sh
-
-**Validates:** New C# code has corresponding tests
-
-**Checks:**
-- Finds modified `.cs` files (excluding tests)
-- Looks for `*Tests.cs` or `Test*.cs`
-- Skips trivial files (DTOs, records, models)
-- **Warns only, doesn't block**
-
-**Example Output:**
-```
-🧪 Checking test coverage...
-  ✓ Test found for: Services/UserService.cs
-  ⚠️  No test found for: Services/PaymentService.cs
-
-⚠️  WARNING: Some files don't have tests
-   Override with: git commit --no-verify
-```
-
-### pre-commit-all.sh (Master Hook)
-
-**Runs:** All hooks in sequence
-
-**Output:**
-```
-╔════════════════════════════════════════════════╗
-║     MORPH-SPEC PRE-COMMIT VALIDATION           ║
-╚════════════════════════════════════════════════╝
-
-─────────────────────────────────────────────────
-🤖 Validating agent configuration...
-✓ No changes to agents.json
-
-─────────────────────────────────────────────────
-💰 Calculating Azure costs...
-✓ No Bicep files modified
-
-─────────────────────────────────────────────────
-🔍 Validating spec files...
-✓ No spec files modified
-
-─────────────────────────────────────────────────
-🧪 Checking test coverage...
-  ✓ Test found for: Services/UserService.cs
-
-═════════════════════════════════════════════════
-✅ ALL PRE-COMMIT VALIDATIONS PASSED
-```
-
-## Bypassing Hooks
-
-If you need to commit without validation (e.g., WIP commit):
-
-```bash
-git commit --no-verify -m "WIP: work in progress"
-```
-
-**⚠️ Use sparingly** - hooks exist to prevent errors.
-
-## Customizing Hooks
-
-### Adjust Cost Limits
-
-Edit `content/.morph/config/config.json`:
-
-```json
-{
-  "costs": {
-    "limits": {
-      "requiresADR": 15  // Change from $10 to $15
-    }
-  }
-}
-```
-
-### Disable Specific Hooks
-
-Edit `.git/hooks/pre-commit` and comment out unwanted hooks:
-
-```bash
-HOOKS=(
-  "pre-commit-agents.sh"
-  # "pre-commit-costs.sh"  # Disabled
-  "pre-commit-specs.sh"
-  "pre-commit-tests.sh"
-)
-```
-
-## Troubleshooting
-
-### Hook Not Running
-
-```bash
-# Check if hook exists
-ls -la .git/hooks/pre-commit
-
-# Check if executable
-chmod +x .git/hooks/pre-commit
-
-# Test manually
-bash .git/hooks/pre-commit
-```
-
-### Hook Fails Unexpectedly
-
-```bash
-# Run individual hook for debugging
-bash content/.morph/hooks/pre-commit-costs.sh
-
-# Check hook output
-bash -x content/.morph/hooks/pre-commit-costs.sh
-```
-
-## Benefits
-
-- ✅ **Prevents Errors:** Catches issues before commit
-- ✅ **Enforces Quality:** Requires tests, specs, ADRs
-- ✅ **Cost Control:** Blocks expensive infrastructure
-- ✅ **Fast Feedback:** Fails early in dev workflow
-- ✅ **Consistent:** Same validation for entire team
-
----
-
-*MORPH-SPEC Framework - Git Hooks*
+# MORPH-SPEC Git Hooks
+
+Pre-commit hooks for automatic validation before committing.
+
+## Available Hooks
+
+| Hook | Description | Action |
+|------|-------------|--------|
+| `pre-commit-agents.sh` | Validates agents.json with JSON Schema | ❌ Blocks commit |
+| `pre-commit-specs.sh` | Validates spec.md has required sections | ❌ Blocks commit |
+| `pre-commit-tests.sh` | Checks if new code has tests | ⚠️ Warns only |
+| `pre-commit-all.sh` | Runs all hooks in sequence | ❌ Blocks if any fail |
+
+## Installation
+
+### Option 1: Install Individual Hooks
+
+```bash
+# Symlink all hooks at once
+ln -s ../../content/.morph/hooks/pre-commit-all.sh .git/hooks/pre-commit
+```
+
+### Option 2: Copy Hooks
+
+```bash
+# Copy master hook
+cp content/.morph/hooks/pre-commit-all.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+### Option 3: Use Existing Hooks
+
+If you already have `.git/hooks/pre-commit`, add this to the end:
+
+```bash
+# Run MORPH-SPEC validations
+bash content/.morph/hooks/pre-commit-all.sh || exit 1
+```
+
+## What Each Hook Does
+
+### pre-commit-agents.sh
+
+**Validates:** `agents.json` configuration
+
+**Checks:**
+- JSON Schema compliance
+- Required fields (id, name, emoji, type, etc.)
+- Keyword patterns (alphanumeric + hyphens/underscores)
+- No duplicate keywords
+- autoActivation for specialist agents
+
+**Example Output:**
+```
+🤖 Validating agent configuration...
+Detected changes to agents.json
+
+=== MORPH-SPEC Agent Validator ===
+
+Version: 1.0.0
+Core Agents: 6
+Specialist Agents: 4
+
+✓ Validation PASSED
+```
+
+### pre-commit-specs.sh
+
+**Validates:** `spec.md` files have required sections
+
+**Checks:**
+- `## 📋 Metadata`
+- `## 🎯 Overview`
+- `## 🏗️ Technical Design`
+- `## ✅ Acceptance Criteria`
+- Warns if no user stories found
+
+**Example Output:**
+```
+🔍 Validating spec files...
+Checking: .morph/outputs/my-feature/spec.md
+  ✓ All required sections found
+✓ All spec files are valid
+```
+
+### pre-commit-tests.sh
+
+**Validates:** New C# code has corresponding tests
+
+**Checks:**
+- Finds modified `.cs` files (excluding tests)
+- Looks for `*Tests.cs` or `Test*.cs`
+- Skips trivial files (DTOs, records, models)
+- **Warns only, doesn't block**
+
+**Example Output:**
+```
+🧪 Checking test coverage...
+  ✓ Test found for: Services/UserService.cs
+  ⚠️  No test found for: Services/PaymentService.cs
+
+⚠️  WARNING: Some files don't have tests
+   Override with: git commit --no-verify
+```
+
+### pre-commit-all.sh (Master Hook)
+
+**Runs:** All hooks in sequence
+
+**Output:**
+```
+╔════════════════════════════════════════════════╗
+║     MORPH-SPEC PRE-COMMIT VALIDATION           ║
+╚════════════════════════════════════════════════╝
+
+─────────────────────────────────────────────────
+🤖 Validating agent configuration...
+✓ No changes to agents.json
+
+─────────────────────────────────────────────────
+🔍 Validating spec files...
+✓ No spec files modified
+
+─────────────────────────────────────────────────
+🧪 Checking test coverage...
+  ✓ Test found for: Services/UserService.cs
+
+═════════════════════════════════════════════════
+✅ ALL PRE-COMMIT VALIDATIONS PASSED
+```
+
+## Bypassing Hooks
+
+If you need to commit without validation (e.g., WIP commit):
+
+```bash
+git commit --no-verify -m "WIP: work in progress"
+```
+
+**⚠️ Use sparingly** - hooks exist to prevent errors.
+
+## Customizing Hooks
+
+### Disable Specific Hooks
+
+Edit `.git/hooks/pre-commit` and comment out unwanted hooks:
+
+```bash
+HOOKS=(
+  "pre-commit-agents.sh"
+  "pre-commit-specs.sh"
+  "pre-commit-tests.sh"
+)
+```
+
+## Troubleshooting
+
+### Hook Not Running
+
+```bash
+# Check if hook exists
+ls -la .git/hooks/pre-commit
+
+# Check if executable
+chmod +x .git/hooks/pre-commit
+
+# Test manually
+bash .git/hooks/pre-commit
+```
+
+### Hook Fails Unexpectedly
+
+```bash
+# Run individual hook for debugging
+bash content/.morph/hooks/pre-commit-costs.sh
+
+# Check hook output
+bash -x content/.morph/hooks/pre-commit-costs.sh
+```
+
+## Benefits
+
+- ✅ **Prevents Errors:** Catches issues before commit
+- ✅ **Enforces Quality:** Requires tests, specs, ADRs
+- ✅ **Fast Feedback:** Fails early in dev workflow
+- ✅ **Consistent:** Same validation for entire team
+
+---
+
+## 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/pre-commit-agents.sh

@@ -1,24 +1,24 @@
-#!/bin/bash
-# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
-# Uses validate-agents.js to check agents.json
-
-echo "🤖 Validating agent configuration..."
-
-# Check if agents.json is being modified
-if git diff --cached --name-only | grep -q 'agents\.json$'; then
-  echo "Detected changes to agents.json"
-
-  # Run validator
-  if ! node bin/validate-agents.js; then
-    echo ""
-    echo "❌ COMMIT BLOCKED: agents.json validation failed"
-    echo "   Fix errors above before committing"
-    exit 1
-  fi
-
-  echo "✓ agents.json is valid"
-else
-  echo "✓ No changes to agents.json"
-fi
-
-exit 0
+#!/bin/bash
+# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
+# Uses validate-agents.js to check agents.json
+
+echo "🤖 Validating agent configuration..."
+
+# Check if agents.json is being modified
+if git diff --cached --name-only | grep -q 'agents\.json$'; then
+  echo "Detected changes to agents.json"
+
+  # Run validator
+  if ! npx morph-spec validate-agents-skills; then
+    echo ""
+    echo "❌ COMMIT BLOCKED: agents.json validation failed"
+    echo "   Fix errors above before committing"
+    exit 1
+  fi
+
+  echo "✓ agents.json is valid"
+else
+  echo "✓ No changes to agents.json"
+fi
+
+exit 0