@itz4blitz/agentful 0.3.0 → 0.5.1

package/bin/hooks/README.md

@@ -1,120 +1,376 @@
-# Agentful Hooks
+# agentful Lifecycle Hooks
 
-This directory contains hook scripts that enhance Claude Code's behavior with agentful.
+Comprehensive lifecycle hooks for validation and metrics tracking throughout the development workflow. All hooks are Node.js scripts for cross-platform compatibility (Windows, macOS, Linux).
 
-## Scripts
+## Why Node.js?
 
-### `analyze-trigger.sh`
+- ✅ **Cross-platform** - Works on Windows, macOS, Linux without modifications
+- ✅ **No extra dependencies** - Node.js already required for Claude Code (>=22.0.0)
+- ✅ **Zero external packages** - Uses only built-in modules (`fs`, `path`, `child_process`)
+- ✅ **Maintainable** - JavaScript is more familiar to most developers than Bash
+- ✅ **Consistent behavior** - Same execution across all platforms
 
-**Purpose**: Suggests running `/agentful-analyze` when key configuration files change.
+## Available Hooks
 
-**Triggers on**:
-- `package.json` (root only, excludes node_modules)
-- `architecture.json`
-- `tsconfig.json` / `jsconfig.json`
-- Build configs: `vite.config.*`, `webpack.config.*`, `rollup.config.*`, `next.config.*`
-- Environment templates: `.env.example`, `.env.sample`
-- Docker files: `docker-compose.yml`, `Dockerfile`
+### 1. Pre-Agent Hook (`pre-agent.js`)
 
-**Behavior**:
-- Runs on PostToolUse for Write/Edit operations
-- Exits silently for non-matching files
-- Outputs suggestion message for matching files
-- Timeout: 3 seconds
+**Purpose**: Validates agent preconditions before invocation
 
-**Usage**: Automatically triggered by hooks. Can be tested manually:
+**When to invoke**: Before calling `Task()` to delegate to any agent
+
+**Environment Variables**:
+- `AGENTFUL_AGENT` - Name of the agent being invoked (e.g., "backend", "frontend")
+- `AGENTFUL_FEATURE` - Feature being worked on (optional)
+- `AGENTFUL_DOMAIN` - Domain containing the feature (optional)
+
+**Checks**:
+- Agent file exists in `.claude/agents/`
+- Required state files exist (state.json, completion.json, decisions.json)
+- State files are valid JSON
+- Feature exists in product specification (if specified)
+- Orchestrator is not blocked on decisions
+
+**Return Codes**:
+- `0` - All validations passed, proceed with agent invocation
+- `1` - Validation failed, block agent invocation
+
+**Example Usage**:
+```bash
+export AGENTFUL_AGENT="backend"
+export AGENTFUL_FEATURE="user-login"
+export AGENTFUL_DOMAIN="authentication"
+
+node bin/hooks/pre-agent.js
+# or make executable
+./bin/hooks/pre-agent.js
+```
+
+### 2. Post-Agent Hook (`post-agent.js`)
+
+**Purpose**: Tracks agent execution metrics and invocation history
+
+**When to invoke**: After an agent completes its work (success or failure)
+
+**Environment Variables**: Same as pre-agent
+
+**Actions**:
+- Increments invocation counter for the agent
+- Records last invocation timestamp
+- Updates `.agentful/agent-metrics.json`
+
+**Return Codes**:
+- `0` - Always succeeds (non-blocking)
+
+**Example Usage**:
+```bash
+export AGENTFUL_AGENT="frontend"
+node bin/hooks/post-agent.js
+```
+
+### 3. Pre-Feature Hook (`pre-feature.js`)
+
+**Purpose**: Validates feature readiness before implementation
+
+**When to invoke**: Before starting feature implementation
+
+**Environment Variables**:
+- `AGENTFUL_FEATURE` - Feature name (required)
+- `AGENTFUL_DOMAIN` - Domain name (optional for hierarchical structure)
+
+**Checks**:
+- Feature file exists in product specification
+- Completion tracking exists
+- Feature dependencies are met
+- Domain is not blocked (for hierarchical structure)
+- No blocking decisions exist for this feature
+- Tech stack has been analyzed
+- Required agents exist
+
+**Return Codes**:
+- `0` - All validations passed (may have warnings)
+- `1` - Validation failed, block feature implementation
+
+**Example Usage**:
+```bash
+export AGENTFUL_FEATURE="checkout-flow"
+export AGENTFUL_DOMAIN="ecommerce"
+node bin/hooks/pre-feature.js
+```
+
+### 4. Post-Feature Hook (`post-feature.js`)
+
+**Purpose**: Feature completion validation and automated testing
+
+**When to invoke**: After feature implementation is complete
+
+**Environment Variables**: Same as pre-feature
+
+**Actions**:
+1. Runs test suite (`npm test`)
+2. Runs type checking (`npx tsc --noEmit` if TypeScript exists)
+3. Runs linter (`npm run lint`)
+4. Checks test coverage (if available)
+5. Updates `.agentful/completion.json` with validation results
+6. Creates git commit if all validations pass
+
+**Return Codes**:
+- `0` - All validations passed, feature complete
+- `1` - Validation failed, needs fixes
+
+**Example Usage**:
 ```bash
-FILE="package.json" bash bin/hooks/analyze-trigger.sh
+export AGENTFUL_FEATURE="search-api"
+node bin/hooks/post-feature.js
 ```
 
-### `health-check.sh`
+### 5. Health Check Hook (`health-check.js`)
+
+**Purpose**: Comprehensive startup health check for agentful
 
-**Purpose**: Performs lightweight startup checks for agentful configuration.
+**When to invoke**: On system startup, before any agent invocation
+
+**Environment Variables**: None
 
 **Checks**:
 - `.agentful/` directory exists
-- `architecture.json` exists
-- Project has a package manager config (package.json, pyproject.toml, go.mod, or Cargo.toml)
+- Core state files exist and are valid JSON
+- `.claude/` directory structure is complete
+- All core agents exist
+- Product specification exists
+- Settings file is valid
+- Architecture has been analyzed
+- Node.js version meets requirements (>=22.0.0)
+
+**Return Codes**:
+- `0` - System ready (may have warnings)
+
+**Example Usage**:
+```bash
+node bin/hooks/health-check.js
+```
 
-**Behavior**:
-- Runs on SessionStart
-- Outputs "Agentful ready." if all checks pass
-- Lists warnings for missing components
-- Always exits with code 0 (non-blocking)
-- Timeout: 5 seconds
+### 6. Analyze Trigger Hook (`analyze-trigger.js`)
 
-**Usage**: Automatically triggered on session start. Can be tested manually:
+**Purpose**: Suggests running `/agentful-analyze` when critical files change
+
+**When to invoke**: After file modifications (via git hooks or file watchers)
+
+**Environment Variables**:
+- `FILE` - Path to the changed file
+
+**Triggers suggestions for**:
+- `package.json` - Dependency changes
+- `architecture.json` - Architecture updates
+- `tsconfig.json` / `jsconfig.json` - TypeScript/JavaScript config
+- Build configs (vite, webpack, rollup, next)
+- Environment templates (`.env.example`, `.env.sample`)
+- Docker configs (`Dockerfile`, `docker-compose.yml`)
+
+**Return Codes**:
+- `0` - Always succeeds (informational only)
+
+**Example Usage**:
 ```bash
-bash bin/hooks/health-check.sh
+export FILE="package.json"
+node bin/hooks/analyze-trigger.js
+```
+
+## Implementation Details
+
+### Technical Architecture
+
+The Node.js hooks use:
+- **ES Modules** - Leverages `"type": "module"` from package.json
+- **Built-in modules only** - `fs`, `path`, `child_process` (no external dependencies)
+- **Cross-platform paths** - Uses `path` module for proper path handling
+- **Environment variables** - `process.env` for configuration
+- **Exit codes** - `process.exit(0/1)` for proper shell integration
+- **JSON parsing** - Native `JSON.parse()` for validation and querying
+- **Command execution** - `execSync` for running npm scripts and git commands
+
+### File Structure
+
+```
+bin/hooks/
+├── pre-agent.js          # Agent precondition validation
+├── post-agent.js         # Agent metrics tracking
+├── pre-feature.js        # Feature readiness validation
+├── post-feature.js       # Feature completion validation
+├── health-check.js       # System health check
+├── analyze-trigger.js    # Analysis suggestion trigger
+└── README.md             # This file
 ```
 
-## Hook Configuration
+All hooks are executable (`chmod +x`) and can be invoked directly or via `node`.
 
-Hooks are configured in `.claude/settings.json`:
+## Metrics Structure
 
+`.agentful/agent-metrics.json`:
 ```json
 {
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash bin/hooks/health-check.sh",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash bin/hooks/analyze-trigger.sh",
-            "timeout": 3
-          }
-        ]
-      }
-    ]
-  }
+  "invocations": {
+    "backend": 15,
+    "frontend": 12,
+    "tester": 8
+  },
+  "last_invocation": {
+    "agent": "backend",
+    "timestamp": "2026-01-20T10:30:00Z",
+    "feature": "login",
+    "domain": "authentication"
+  },
+  "feature_hooks": [
+    {
+      "hook": "PreFeature",
+      "feature": "login",
+      "domain": "auth",
+      "timestamp": "2026-01-20T10:25:00Z",
+      "result": "passed"
+    },
+    {
+      "hook": "PostFeature",
+      "feature": "login",
+      "domain": "auth",
+      "timestamp": "2026-01-20T10:35:00Z",
+      "result": "passed"
+    }
+  ]
+}
+```
+
+## Integration Examples
+
+### From Orchestrator Agent
+
+```javascript
+// Before delegating to an agent
+const preAgentCheck = await Bash({
+  command: `AGENTFUL_AGENT="${agentName}" AGENTFUL_FEATURE="${featureName}" node bin/hooks/pre-agent.js`,
+  description: "Validate agent preconditions"
+});
+
+if (preAgentCheck.exit_code !== 0) {
+  // Handle validation failure
+  return "Pre-agent validation failed. Cannot proceed.";
 }
+
+// Delegate to agent
+await Task({
+  agent: agentName,
+  task: "Implement feature..."
+});
+
+// After agent completes
+await Bash({
+  command: `AGENTFUL_AGENT="${agentName}" AGENTFUL_FEATURE="${featureName}" node bin/hooks/post-agent.js`,
+  description: "Track agent metrics"
+});
 ```
 
-## Design Principles
+### From CLI Commands
 
-1. **Fast**: All hooks complete in under 5 seconds
-2. **Non-blocking**: Always exit with code 0 to avoid interrupting workflow
-3. **Helpful**: Provide actionable suggestions, not errors
-4. **Smart**: Only trigger on relevant files (exclude node_modules, etc.)
-5. **Lightweight**: No heavy analysis, just quick checks and suggestions
+```javascript
+// In /agentful-start command
+await Bash({
+  command: 'node bin/hooks/health-check.js',
+  description: "System health check"
+});
+```
+
+### From Git Hooks
+
+```bash
+# .git/hooks/post-checkout
+#!/bin/bash
+FILE="package.json"
+if git diff --name-only HEAD@{1} HEAD | grep -q "$FILE"; then
+  export FILE="$FILE"
+  node bin/hooks/analyze-trigger.js
+fi
+```
 
-## Adding New Hooks
+### From CI/CD Pipelines
 
-When adding new hooks:
+```yaml
+# GitHub Actions example
+steps:
+  - name: Pre-feature validation
+    run: |
+      export AGENTFUL_FEATURE="api-auth"
+      export AGENTFUL_DOMAIN="backend"
+      node bin/hooks/pre-feature.js
 
-1. Keep execution time under 10 seconds
-2. Use `set -e` and proper error handling
-3. Exit with code 0 for success (non-blocking)
-4. Output clear, actionable messages
-5. Test edge cases (missing files, node_modules, etc.)
-6. Document the hook in this README
-7. Update `.claude/settings.json` with appropriate timeout
+  - name: Run feature implementation
+    run: |
+      # Your implementation steps
+
+  - name: Post-feature validation
+    run: |
+      export AGENTFUL_FEATURE="api-auth"
+      export AGENTFUL_DOMAIN="backend"
+      node bin/hooks/post-feature.js
+```
 
 ## Testing
 
-Test hooks manually before committing:
+To test a hook manually:
 
 ```bash
-# Test analyze-trigger with different files
-FILE="package.json" bash bin/hooks/analyze-trigger.sh
-FILE="node_modules/pkg/package.json" bash bin/hooks/analyze-trigger.sh
-FILE="src/index.ts" bash bin/hooks/analyze-trigger.sh
+# Test pre-agent validation
+export AGENTFUL_AGENT="backend"
+export AGENTFUL_FEATURE="test-feature"
+node bin/hooks/pre-agent.js
+echo "Exit code: $?"
+
+# Test health check
+node bin/hooks/health-check.js
+
+# Test with invalid state (should fail)
+mv .agentful/state.json .agentful/state.json.bak
+export AGENTFUL_AGENT="backend"
+node bin/hooks/pre-agent.js
+echo "Exit code: $?" # Should be 1
+mv .agentful/state.json.bak .agentful/state.json
+
+# Test post-agent metrics
+export AGENTFUL_AGENT="tester"
+export AGENTFUL_FEATURE="unit-tests"
+node bin/hooks/post-agent.js
+cat .agentful/agent-metrics.json # Verify metrics updated
+```
+
+## Troubleshooting
+
+### Hook Not Executing
+
+If a hook doesn't execute:
+1. Verify Node.js version: `node --version` (must be >=22.0.0)
+2. Check file permissions: `ls -la bin/hooks/` (should be executable)
+3. Make executable: `chmod +x bin/hooks/*.js`
+4. Verify environment variables are set: `echo $AGENTFUL_AGENT`
+
+### Exit Code Issues
 
-# Test health-check
-bash bin/hooks/health-check.sh
+Hooks use standard exit codes:
+- `0` = Success (proceed)
+- `1` = Failure (block)
 
-# Validate JSON
-jq empty .claude/settings.json
+Check exit code in shell:
+```bash
+node bin/hooks/pre-agent.js
+echo $? # Shows exit code
 ```
+
+### JSON Parse Errors
+
+If you see JSON parse errors:
+1. Validate JSON files: `node -e "JSON.parse(require('fs').readFileSync('.agentful/state.json'))"`
+2. Check file encoding (must be UTF-8)
+3. Look for trailing commas or syntax errors
+
+## See Documentation
+
+For complete documentation, usage examples, and integration guide, see:
+- Orchestrator integration instructions in `.claude/agents/orchestrator.md`
+- Individual hook script headers for detailed behavior
+- Main documentation at `docs/`

package/bin/hooks/analyze-trigger.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// analyze-trigger.js
+// Checks if changed files warrant an /agentful-analyze suggestion
+
+import path from 'path';
+
+/**
+ * Check if a file change should trigger an /agentful-analyze suggestion
+ * @param {string} filepath - The file path to check
+ * @returns {string|null} - Suggestion message or null if no suggestion needed
+ */
+export function checkAnalyzeTrigger(filepath) {
+  // Exit silently if no file specified
+  if (!filepath) {
+    return null;
+  }
+
+  // Normalize the file path to get just the filename
+  const filename = path.basename(filepath);
+
+  // Check for key files that should trigger analysis suggestions
+  switch (filename) {
+    case 'package.json':
+      // Only trigger for root package.json, not node_modules
+      if (filepath.includes('node_modules')) {
+        return null;
+      }
+      return 'Dependencies changed in package.json. Consider running /agentful-analyze to update architecture understanding.';
+
+    case 'architecture.json':
+      return 'Architecture configuration updated. Run /agentful-analyze to refresh tech stack analysis.';
+
+    case 'tsconfig.json':
+    case 'jsconfig.json':
+      return 'TypeScript/JavaScript configuration changed. Consider running /agentful-analyze to update build settings.';
+
+    case '.env.example':
+    case '.env.sample':
+      return 'Environment template changed. Consider running /agentful-analyze to update configuration understanding.';
+
+    case 'docker-compose.yml':
+    case 'Dockerfile':
+      return 'Docker configuration changed. Consider running /agentful-analyze to update deployment setup.';
+
+    default:
+      // Check for build config files with patterns
+      if (filename.startsWith('vite.config.') ||
+          filename.startsWith('webpack.config.') ||
+          filename.startsWith('rollup.config.') ||
+          filename.startsWith('next.config.')) {
+        return 'Build configuration changed. Consider running /agentful-analyze to update bundler settings.';
+      }
+
+      // No suggestion needed for other files
+      return null;
+  }
+}
+
+// CLI entrypoint
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const FILE = process.env.FILE || '';
+  const message = checkAnalyzeTrigger(FILE);
+
+  if (message) {
+    console.log(message);
+  }
+
+  process.exit(0);
+}

package/bin/hooks/block-random-docs.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+/**
+ * Block Random Documentation Hook
+ *
+ * Prevents creation of random markdown files outside of allowed directories.
+ *
+ * Allowed markdown locations:
+ * - docs/pages/*.mdx (Vocs documentation)
+ * - README.md, CONTRIBUTING.md, CHANGELOG.md (root project docs)
+ * - .claude/agents/*.md (agent definitions)
+ * - .claude/skills/*\/SKILL.md (skill documentation)
+ * - .claude/product/**\/*.md (product specifications)
+ * - template/**\/*.md (template files)
+ * - examples/**\/*.md (example documentation)
+ *
+ * Blocked:
+ * - Random *.md files in project root
+ * - Documentation in lib/, src/, test/ directories
+ * - Any ad-hoc "summary", "guide", "notes" files
+ */
+
+import path from 'path';
+import fs from 'fs';
+
+// Get file path from environment (set by Claude Code hooks)
+const filePath = process.env.FILE || '';
+
+// Only check markdown files
+if (!filePath.endsWith('.md') && !filePath.endsWith('.mdx')) {
+  process.exit(0);
+}
+
+// Normalize path
+const normalizedPath = path.normalize(filePath);
+
+// Allowed patterns (regex)
+const ALLOWED_PATTERNS = [
+  /^docs\/pages\/.*\.mdx$/,                    // Vocs docs
+  /^(README|CONTRIBUTING|CHANGELOG)\.md$/,     // Root project docs
+  /^\.claude\/agents\/[^\/]+\.md$/,            // Agent definitions
+  /^\.claude\/skills\/[^\/]+\/SKILL\.md$/,     // Skill docs
+  /^\.claude\/product\/.*\.md$/,               // Product specs
+  /^template\/.*\.md$/,                        // Template files
+  /^examples\/.*\.md$/,                        // Examples
+  /^\.agentful\/.*\.md$/                       // Internal agentful state docs (rare)
+];
+
+// Check if file matches any allowed pattern
+const isAllowed = ALLOWED_PATTERNS.some(pattern => pattern.test(normalizedPath));
+
+if (!isAllowed) {
+  console.error(`
+❌ BLOCKED: Random markdown file creation
+
+File: ${filePath}
+
+Allowed locations:
+  - docs/pages/*.mdx (user-facing documentation)
+  - README.md, CONTRIBUTING.md, CHANGELOG.md (root project docs)
+  - .claude/agents/*.md (agent definitions)
+  - .claude/skills/*/SKILL.md (skill documentation)
+  - .claude/product/**/*.md (product specifications)
+
+Instead of creating random markdown files:
+  1. Update CLAUDE.md for instructions
+  2. Update skills for implementation patterns
+  3. Update docs/pages/*.mdx for user docs
+  4. Update agents for role definitions
+
+Do NOT litter the codebase with ad-hoc documentation files.
+`);
+  process.exit(1);
+}
+
+// File is allowed
+process.exit(0);