@itz4blitz/agentful 0.4.0 → 1.0.0

package/bin/hooks/health-check.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// health-check.js
+// Comprehensive startup health check for agentful
+
+import fs from 'fs';
+import { execSync } from 'child_process';
+
+let errors = 0;
+let warnings = 0;
+
+// === CRITICAL CHECKS (must pass) ===
+
+// Check 1: .agentful directory
+if (!fs.existsSync('.agentful')) {
+  console.log('❌ Agentful not initialized.');
+  console.log('   Run: npx @itz4blitz/agentful init');
+  process.exit(0);
+}
+
+// Check 2: Core state files
+const stateFiles = ['state.json', 'completion.json', 'decisions.json'];
+for (const file of stateFiles) {
+  const filePath = `.agentful/${file}`;
+  if (!fs.existsSync(filePath)) {
+    console.log(`❌ Missing .agentful/${file}`);
+    errors++;
+  }
+}
+
+// Check 3: .claude directory structure
+const claudeDirs = ['agents', 'commands', 'product', 'skills'];
+for (const dir of claudeDirs) {
+  const dirPath = `.claude/${dir}`;
+  if (!fs.existsSync(dirPath)) {
+    console.log(`❌ Missing .claude/${dir}/`);
+    errors++;
+  }
+}
+
+// Check 4: Core agents
+const coreAgents = [
+  'orchestrator',
+  'backend',
+  'frontend',
+  'tester',
+  'reviewer',
+  'fixer',
+  'architect',
+  'product-analyzer'
+];
+for (const agent of coreAgents) {
+  const agentPath = `.claude/agents/${agent}.md`;
+  if (!fs.existsSync(agentPath)) {
+    console.log(`❌ Missing core agent: ${agentPath}`);
+    errors++;
+  }
+}
+
+// Check 5: Product specification
+if (!fs.existsSync('.claude/product/index.md')) {
+  // Check for hierarchical structure
+  let hasHierarchicalSpec = false;
+  if (fs.existsSync('.claude/product/domains')) {
+    try {
+      const domains = fs.readdirSync('.claude/product/domains');
+      for (const domain of domains) {
+        if (fs.existsSync(`.claude/product/domains/${domain}/index.md`)) {
+          hasHierarchicalSpec = true;
+          break;
+        }
+      }
+    } catch (err) {
+      // Ignore errors
+    }
+  }
+
+  if (!hasHierarchicalSpec) {
+    console.log('⚠️  No product specification found');
+    console.log('   Create .claude/product/index.md or run /agentful-product');
+    warnings++;
+  }
+}
+
+// Check 6: Settings file
+const settingsPath = '.claude/settings.json';
+if (!fs.existsSync(settingsPath)) {
+  console.log('❌ Missing .claude/settings.json');
+  errors++;
+} else {
+  try {
+    const settingsContent = fs.readFileSync(settingsPath, 'utf8');
+    JSON.parse(settingsContent);
+  } catch (err) {
+    console.log('❌ Invalid JSON in .claude/settings.json');
+    errors++;
+  }
+}
+
+// === WARNING CHECKS (nice to have) ===
+
+// Check: Architecture analysis
+const architecturePath = '.agentful/architecture.json';
+if (!fs.existsSync(architecturePath)) {
+  console.log('⚠️  Tech stack not analyzed. Run /agentful-generate to:');
+  console.log('   - Detect your tech stack');
+  console.log('   - Discover business domains');
+  console.log('   - Generate specialized agents');
+  warnings++;
+} else {
+  try {
+    const archContent = fs.readFileSync(architecturePath, 'utf8');
+    const arch = JSON.parse(archContent);
+    if (!arch.techStack || !arch.domains) {
+      console.log('⚠️  .agentful/architecture.json is malformed');
+      console.log('   Run /agentful-generate to regenerate');
+      warnings++;
+    }
+  } catch (err) {
+    console.log('⚠️  .agentful/architecture.json is malformed');
+    console.log('   Run /agentful-generate to regenerate');
+    warnings++;
+  }
+}
+
+// Check: Node version
+try {
+  const nodeVersion = process.version.replace('v', '');
+  const majorVersion = parseInt(nodeVersion.split('.')[0], 10);
+  if (majorVersion < 22) {
+    console.log(`⚠️  Node.js ${nodeVersion} detected. Requires >=22.0.0`);
+    warnings++;
+  }
+} catch (err) {
+  // Ignore errors
+}
+
+// === SUMMARY ===
+
+if (errors > 0) {
+  console.log('');
+  console.log(`❌ Found ${errors} critical issue(s)`);
+  console.log('   Run: npx @itz4blitz/agentful init');
+  process.exit(0);
+}
+
+if (warnings > 0) {
+  console.log('');
+  console.log(`⚠️  Agentful ready with ${warnings} warning(s)`);
+} else {
+  console.log('✅ Agentful ready');
+}
+
+process.exit(0);

package/bin/hooks/post-agent.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// post-agent.js
+// Tracks agent execution metrics
+
+import fs from 'fs';
+
+const METRICS_FILE = '.agentful/agent-metrics.json';
+
+/**
+ * Track agent execution metrics
+ * @param {Object} options - Tracking options
+ * @param {string} options.agentName - Name of the agent
+ * @param {string} [options.feature] - Feature being worked on
+ * @param {string} [options.domain] - Domain context
+ * @param {string} [options.timestamp] - ISO timestamp (defaults to current time)
+ * @returns {Object} - Result with success flag and optional error
+ */
+export function trackAgentMetrics({ agentName, feature = '', domain = '', timestamp = new Date().toISOString() }) {
+  // Exit successfully if no agent specified
+  if (!agentName) {
+    return { success: true };
+  }
+
+  // Ensure .agentful directory exists
+  const metricsDir = METRICS_FILE.substring(0, METRICS_FILE.lastIndexOf('/'));
+  if (!fs.existsSync(metricsDir)) {
+    fs.mkdirSync(metricsDir, { recursive: true });
+  }
+
+  // Create metrics file if it doesn't exist
+  if (!fs.existsSync(METRICS_FILE)) {
+    const initialMetrics = {
+      invocations: {},
+      last_invocation: null,
+      feature_hooks: []
+    };
+    fs.writeFileSync(METRICS_FILE, JSON.stringify(initialMetrics, null, 2));
+  }
+
+  // Validate and read existing metrics file
+  let metrics;
+  if (!fs.existsSync(METRICS_FILE)) {
+    // File doesn't exist, create new structure
+    metrics = {
+      invocations: {},
+      last_invocation: null,
+      feature_hooks: []
+    };
+  } else {
+    try {
+      const metricsContent = fs.readFileSync(METRICS_FILE, 'utf8');
+      metrics = JSON.parse(metricsContent);
+    } catch (err) {
+      console.log('WARNING: agent-metrics.json is corrupted, recreating');
+      metrics = {
+        invocations: {},
+        last_invocation: null,
+        feature_hooks: []
+      };
+    }
+  }
+
+  // Update invocation count for this agent
+  const currentCount = metrics.invocations[agentName] || 0;
+  const newCount = currentCount + 1;
+
+  // Update metrics
+  metrics.invocations[agentName] = newCount;
+  metrics.last_invocation = {
+    agent: agentName,
+    timestamp: timestamp,
+    feature: feature,
+    domain: domain
+  };
+
+  // Write updated metrics
+  try {
+    fs.writeFileSync(METRICS_FILE, JSON.stringify(metrics, null, 2));
+    return { success: true };
+  } catch (err) {
+    console.error('WARNING: Failed to write agent-metrics.json');
+    return { success: true, error: err.message };
+  }
+}
+
+// CLI entrypoint
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const AGENT_NAME = process.env.AGENTFUL_AGENT || '';
+  const FEATURE = process.env.AGENTFUL_FEATURE || '';
+  const DOMAIN = process.env.AGENTFUL_DOMAIN || '';
+  const TIMESTAMP = new Date().toISOString();
+
+  trackAgentMetrics({
+    agentName: AGENT_NAME,
+    feature: FEATURE,
+    domain: DOMAIN,
+    timestamp: TIMESTAMP
+  });
+
+  process.exit(0);
+}

package/bin/hooks/post-feature.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// post-feature.js
+// Feature completion validation and tracking
+
+import fs from 'fs';
+import { execSync } from 'child_process';
+
+// Helper function to run command and capture output
+function runCommand(command, description) {
+  try {
+    const output = execSync(command, {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: 60000 // 60 second timeout
+    });
+    return { success: true, output };
+  } catch (err) {
+    return { success: false, output: err.stdout || err.stderr || '' };
+  }
+}
+
+/**
+ * Validate feature completion with automated checks
+ * @param {string} feature - Feature name
+ * @param {string} domain - Domain name (optional)
+ * @returns {object} - { errors, validationResults, exitCode }
+ */
+export function validateFeatureCompletion(feature, domain = '') {
+  // Exit successfully if no feature specified
+  if (!feature) {
+    return { errors: 0, validationResults: [], exitCode: 0 };
+  }
+
+  const TIMESTAMP = new Date().toISOString();
+  let errors = 0;
+  const validationResults = [];
+
+  console.log(`=== Post-Feature Validation: ${feature} ===`);
+  console.log('');
+
+  // Detect stack
+  const hasPackageJson = fs.existsSync('package.json');
+  const hasPyProject = fs.existsSync('pyproject.toml') || fs.existsSync('requirements.txt');
+  const hasGoMod = fs.existsSync('go.mod');
+  const hasPomXml = fs.existsSync('pom.xml');
+  const hasCargoToml = fs.existsSync('Cargo.toml');
+
+  // Check 1: Run tests
+  console.log('[1/4] Running tests...');
+  let testCmd = null;
+  if (hasPackageJson) testCmd = 'npm test 2>&1';
+  else if (hasPyProject) testCmd = 'pytest 2>&1';
+  else if (hasGoMod) testCmd = 'go test ./... 2>&1';
+  else if (hasPomXml) testCmd = 'mvn test 2>&1';
+  else if (hasCargoToml) testCmd = 'cargo test 2>&1';
+
+  if (testCmd) {
+    const testResult = runCommand(testCmd, 'tests');
+    if (testResult.success) {
+      console.log('  Tests: PASS');
+      validationResults.push('tests:pass');
+    } else {
+      console.log('  Tests: FAIL');
+      validationResults.push('tests:fail');
+      errors++;
+    }
+  } else {
+    console.log('  Tests: SKIP (no test framework detected)');
+    validationResults.push('tests:skip');
+  }
+  console.log('');
+
+  // Check 2: Type checking
+  console.log('[2/4] Running type check...');
+  let typeCmd = null;
+  if (fs.existsSync('tsconfig.json')) typeCmd = 'npx tsc --noEmit 2>&1';
+  else if (hasPyProject) typeCmd = 'mypy . --ignore-missing-imports 2>&1';
+  else if (hasGoMod) typeCmd = 'go vet ./... 2>&1';
+  else if (hasCargoToml) typeCmd = 'cargo check 2>&1';
+
+  if (typeCmd) {
+    const tscResult = runCommand(typeCmd, 'type-check');
+    if (tscResult.success) {
+      console.log('  Type Check: PASS');
+      validationResults.push('types:pass');
+    } else {
+      console.log('  Type Check: FAIL');
+      validationResults.push('types:fail');
+      errors++;
+    }
+  } else {
+    console.log('  Type Check: SKIP (no type checker detected)');
+    validationResults.push('types:skip');
+  }
+  console.log('');
+
+  // Check 3: Linting
+  console.log('[3/4] Running linter...');
+  let lintCmd = null;
+  if (hasPackageJson) lintCmd = 'npm run lint 2>&1';
+  else if (hasPyProject) lintCmd = 'ruff check . 2>&1 || pylint **/*.py 2>&1';
+  else if (hasGoMod) lintCmd = 'golangci-lint run 2>&1';
+  else if (hasCargoToml) lintCmd = 'cargo clippy -- -D warnings 2>&1';
+
+  if (lintCmd) {
+    const lintResult = runCommand(lintCmd, 'lint');
+    if (lintResult.success) {
+      console.log('  Lint: PASS');
+      validationResults.push('lint:pass');
+    } else {
+      console.log('  Lint: FAIL');
+      validationResults.push('lint:fail');
+      errors++;
+    }
+  } else {
+    console.log('  Lint: SKIP (no linter detected)');
+    validationResults.push('lint:skip');
+  }
+  console.log('');
+
+  // Check 4: Coverage check
+  console.log('[4/4] Checking test coverage...');
+  console.log('  Coverage: SKIP (run /agentful-validate for full coverage report)');
+  validationResults.push('coverage:skip');
+  console.log('');
+
+  // Update completion.json with validation results
+  const completionJsonPath = '.agentful/completion.json';
+  if (fs.existsSync(completionJsonPath)) {
+    try {
+      const completionContent = fs.readFileSync(completionJsonPath, 'utf8');
+      const completion = JSON.parse(completionContent);
+
+      const validationStatus = errors > 0 ? 'failed' : 'passed';
+      const validationObject = {
+        status: validationStatus,
+        timestamp: TIMESTAMP,
+        errors: errors,
+        results: validationResults
+      };
+
+      if (domain) {
+        // Hierarchical structure
+        if (!completion.domains) completion.domains = {};
+        if (!completion.domains[domain]) completion.domains[domain] = {};
+        if (!completion.domains[domain].features) completion.domains[domain].features = {};
+        if (!completion.domains[domain].features[feature]) completion.domains[domain].features[feature] = {};
+        completion.domains[domain].features[feature].validation = validationObject;
+      } else {
+        // Flat structure
+        if (!completion.features) completion.features = {};
+        if (!completion.features[feature]) completion.features[feature] = {};
+        completion.features[feature].validation = validationObject;
+      }
+
+      fs.writeFileSync(completionJsonPath, JSON.stringify(completion, null, 2));
+    } catch (err) {
+      console.error('WARNING: Failed to update completion.json');
+    }
+  }
+
+  // Log to metrics
+  const metricsPath = '.agentful/agent-metrics.json';
+  if (fs.existsSync(metricsPath)) {
+    try {
+      const metricsContent = fs.readFileSync(metricsPath, 'utf8');
+      const metrics = JSON.parse(metricsContent);
+
+      if (!metrics.feature_hooks) metrics.feature_hooks = [];
+      metrics.feature_hooks.push({
+        hook: 'PostFeature',
+        feature: feature,
+        domain: domain,
+        timestamp: TIMESTAMP,
+        result: errors > 0 ? 'failed' : 'passed'
+      });
+
+      fs.writeFileSync(metricsPath, JSON.stringify(metrics, null, 2));
+    } catch (err) {
+      console.error('WARNING: Failed to update agent-metrics.json');
+    }
+  }
+
+  // Create git commit if all validations pass
+  if (errors === 0) {
+    console.log('=== All Validations Passed ===');
+    console.log('');
+
+    // Check if there are changes to commit
+    try {
+      execSync('git diff --quiet 2>/dev/null', { stdio: 'pipe' });
+      execSync('git diff --cached --quiet 2>/dev/null', { stdio: 'pipe' });
+      console.log('No changes to commit');
+    } catch (err) {
+      // There are changes
+      const commitMsg = domain
+        ? `feat(${domain}): complete ${feature} feature`
+        : `feat: complete ${feature} feature`;
+
+      console.log('Creating git commit...');
+      try {
+        execSync('git add -A', { stdio: 'pipe' });
+        execSync(`git commit -m "${commitMsg}"`, { stdio: 'pipe' });
+        console.log(`  Commit created: ${commitMsg}`);
+      } catch (err) {
+        console.log('WARNING: Git commit failed (this is non-blocking)');
+      }
+    }
+
+    return { errors: 0, validationResults, exitCode: 0 };
+  } else {
+    console.log(`=== Validation Failed (${errors} error(s)) ===`);
+    console.log('');
+    console.log('Fix validation errors before completing feature.');
+    console.log('Run /agentful-validate for detailed output');
+    return { errors, validationResults, exitCode: 1 };
+  }
+}
+
+// CLI entrypoint
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const FEATURE = process.env.AGENTFUL_FEATURE || '';
+  const DOMAIN = process.env.AGENTFUL_DOMAIN || '';
+
+  const result = validateFeatureCompletion(FEATURE, DOMAIN);
+  process.exit(result.exitCode);
+}

package/bin/hooks/pre-agent.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// pre-agent.js
+// Validates agent preconditions before invocation
+
+import fs from 'fs';
+
+/**
+ * Validate agent preconditions
+ * @param {string} agentName - Agent name
+ * @param {string} feature - Feature name (optional)
+ * @param {string} domain - Domain name (optional)
+ * @returns {object} - { errors, exitCode }
+ */
+export function validateAgentPreconditions(agentName, feature = '', domain = '') {
+  // Exit successfully if no agent specified
+  if (!agentName) {
+    return { errors: 0, exitCode: 0 };
+  }
+
+  let errors = 0;
+
+  // Check 1: Agent file exists
+  const agentFile = `.claude/agents/${agentName}.md`;
+  if (!fs.existsSync(agentFile)) {
+    console.error(`ERROR: Agent file not found: ${agentFile}`);
+    errors++;
+  }
+
+  // Check 2: Required state files exist
+  const stateFiles = ['state.json', 'completion.json', 'decisions.json'];
+  for (const file of stateFiles) {
+    const filePath = `.agentful/${file}`;
+    if (!fs.existsSync(filePath)) {
+      console.error(`ERROR: Missing state file: ${filePath}`);
+      errors++;
+    }
+  }
+
+  // Check 3: Validate state.json structure
+  const stateJsonPath = '.agentful/state.json';
+  if (fs.existsSync(stateJsonPath)) {
+    try {
+      const stateContent = fs.readFileSync(stateJsonPath, 'utf8');
+      const state = JSON.parse(stateContent);
+      if (!state.current_phase) {
+        console.error('ERROR: .agentful/state.json is malformed (missing current_phase)');
+        errors++;
+      }
+    } catch (err) {
+      console.error('ERROR: .agentful/state.json is invalid JSON');
+      errors++;
+    }
+  }
+
+  // Check 4: If feature specified, verify it exists in product spec
+  if (feature) {
+    let featureFound = false;
+
+    // Check hierarchical structure
+    if (domain) {
+      const featureFile = `.claude/product/domains/${domain}/features/${feature}.md`;
+      if (fs.existsSync(featureFile)) {
+        featureFound = true;
+      }
+    }
+
+    // Check flat structure
+    if (!featureFound) {
+      const featureFile = `.claude/product/features/${feature}.md`;
+      if (fs.existsSync(featureFile)) {
+        featureFound = true;
+      }
+    }
+
+    if (!featureFound) {
+      console.log(`WARNING: Feature '${feature}' not found in product specification`);
+      // Warning only, don't block
+    }
+  }
+
+  // Check 5: Verify orchestrator isn't blocked
+  if (fs.existsSync(stateJsonPath)) {
+    try {
+      const stateContent = fs.readFileSync(stateJsonPath, 'utf8');
+      const state = JSON.parse(stateContent);
+      const blockedOn = state.blocked_on || [];
+      if (Array.isArray(blockedOn) && blockedOn.length > 0) {
+        console.log(`WARNING: Orchestrator is blocked on decisions: ${JSON.stringify(blockedOn)}`);
+        // Warning only, don't block
+      }
+    } catch (err) {
+      // Already handled in Check 3
+    }
+  }
+
+  // Exit with error if critical checks failed
+  if (errors > 0) {
+    console.log('');
+    console.log(`Pre-agent validation failed with ${errors} error(s)`);
+    console.log(`Agent: ${agentName}`);
+    if (feature) console.log(`Feature: ${feature}`);
+    if (domain) console.log(`Domain: ${domain}`);
+    return { errors, exitCode: 1 };
+  }
+
+  // All checks passed
+  return { errors: 0, exitCode: 0 };
+}
+
+// CLI entrypoint
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const AGENT_NAME = process.env.AGENTFUL_AGENT || '';
+  const FEATURE = process.env.AGENTFUL_FEATURE || '';
+  const DOMAIN = process.env.AGENTFUL_DOMAIN || '';
+
+  const result = validateAgentPreconditions(AGENT_NAME, FEATURE, DOMAIN);
+  process.exit(result.exitCode);
+}