@itz4blitz/agentful 1.3.0 → 1.4.0

package/README.md

@@ -14,22 +14,22 @@
 [![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289da)](https://discord.gg/SMDvJXUe)
 [![Documentation](https://img.shields.io/badge/docs-agentful.app-blue)](https://agentful.app)
 
-**AI agent toolkit for autonomous product development with Claude Code**
+**Pre-configured development toolkit for Claude Code**
+
+Orchestrates specialized agents in parallel with inter-agent communication to build features from product specs.
 
 [Quick Start](#quick-start) • [Documentation](https://agentful.app) • [Discord](https://discord.gg/SMDvJXUe)
 
 </div>
 
-**The Swiss Army Knife of AI Agents** - Works with any LLM (Claude, GLM, DeepSeek, Ollama), any tech stack, any platform. Self-hosted or cloud.
-
 ## Features
 
-- **8 specialized agents** - orchestrator, architect, backend, frontend, tester, reviewer, fixer, product-analyzer
-- **6 quality gates** - types, tests, coverage, lint, security, dead code
-- **Auto-generated domain agents** - learns your codebase patterns and conventions
-- **Self-hosted execution** - run agents on your infrastructure (optional)
-- **Multi-platform CI/CD** - GitHub Actions, GitLab, Jenkins, or any HTTP client
-- **Product-driven workflow** - define specs, agents build features
+- **Parallel execution** - Multiple agents work simultaneously in git worktrees (frontend + backend + tests running concurrently)
+- **Three-tier architecture** - Core agents (pre-built), domain agents (generated for your stack), ephemeral agents (task-specific)
+- **Shared skills** - Reusable capabilities like validation, testing, and research across all agents
+- **Quality gates** - Automated validation for every change (types, lint, tests, coverage, security, dead code)
+- **Tech stack agnostic** - Works with any language/framework
+- **Human checkpoints** - You decide, agents execute
 
 ## Quick Start
 
@@ -40,13 +40,12 @@ npx @itz4blitz/agentful init
 # 2. Start Claude Code
 claude
 
-# 3. Define product spec (interactive)
-/agentful-product
-
-# 4. Generate specialized agents
-/agentful-generate
+# 3. Define product spec (choose one):
+/agentful-init       # Interactive 7-question wizard (recommended for new users)
+# OR
+/agentful-product    # Manual spec creation/analysis
 
-# 5. Start development
+# 4. Start development (auto-generates agents on first run)
 /agentful-start
 ```
 
@@ -70,71 +69,24 @@ https://agentful.app/configure
 
 | Command | Description |
 |---------|-------------|
+| `/agentful-init` | Interactive onboarding - 7 guided questions |
 | `/agentful-product` | Create and analyze product specifications |
+| `/agentful-generate` | Generate domain-specific agents for your stack |
 | `/agentful-start` | Start autonomous development |
 | `/agentful-status` | View completion % and current work |
 | `/agentful-validate` | Run quality checks |
 | `/agentful-decide` | Answer blocking decisions |
-| `/agentful-analyze` | Generate domain-specific agents |
-
-## Self-Hosted Remote Execution
-
-Run agents on your infrastructure:
-
-```bash
-# Deploy to Oracle Cloud free tier ($0/month)
-agentful serve --auth=tailscale
-
-# Or use SSH tunnel for local dev
-ssh -L 3000:localhost:3000 your-server
-agentful serve
-```
-
-See [deployment docs](https://agentful.app/remote-execution) for Tailscale, HMAC auth, and Oracle Cloud setup.
-
-## MCP Server
-
-Use agentful with any MCP-compatible AI tool (Claude Code, Kiro, Aider):
-
-```json
-{
-  "mcpServers": {
-    "agentful": {
-      "command": "npx",
-      "args": ["-y", "@itz4blitz/agentful-mcp"]
-    }
-  }
-}
-```
-
-**Features**:
-- Cross-tool compatibility (works with any MCP client)
-- Launch specialized agents via MCP tools
-- Access product specs and state via MCP resources
-- Real-time execution status updates
-
-See [MCP Integration Guide](./docs/mcp-integration.md) for setup with different AI tools.
-
-## CI/CD Integration
-
-Works with any platform via HTTP API or templates:
-
-- [GitHub Actions](https://agentful.app/ci-integration#github-actions)
-- [GitLab CI](https://agentful.app/ci-integration#gitlab-ci)
-- [Jenkins](https://agentful.app/ci-integration#jenkins)
-- [HTTP API](https://agentful.app/ci-integration#http-api) (CircleCI, Bitbucket, Travis, etc.)
 
 ## Documentation
 
 - **Full docs**: [agentful.app](https://agentful.app)
-- **MCP Integration**: [MCP Server Guide](./mcp/README.md) | [Integration Guide](./docs/mcp-integration.md)
-- **Architecture**: [Agent system](https://agentful.app/concepts/architecture)
-- **Agents**: [Orchestrator](https://agentful.app/agents/orchestrator), [Backend](https://agentful.app/agents/backend), [Frontend](https://agentful.app/agents/frontend), etc.
-- **Skills**: [Product tracking](https://agentful.app/skills/product-tracking), [Validation](https://agentful.app/skills/validation), etc.
+- **Architecture**: [Three-tier system](https://agentful.app/concepts/architecture) | [Background agents](https://agentful.app/concepts/background-agents)
+- **Agents**: [Orchestrator](https://agentful.app/agents/orchestrator), [Backend](https://agentful.app/agents/backend), [Frontend](https://agentful.app/agents/frontend), [Reviewer](https://agentful.app/agents/reviewer), [Fixer](https://agentful.app/agents/fixer)
+- **Skills**: [Validation](https://agentful.app/skills/validation), [Testing](https://agentful.app/skills/testing), [Research](https://agentful.app/skills/research), [Product Planning](https://agentful.app/skills/product-planning)
 
 ## Requirements
 
-- Claude Code ([code.anthropic.com](https://code.anthropic.com))
+- [Claude Code](https://claude.ai/download)
 - Node.js 22+
 - Git
 

package/bin/cli.js

@@ -29,6 +29,7 @@ import {
   mergePresetWithFlags,
   validateConfiguration
 } from '../lib/presets.js';
+import {  detectTeammateTool, enableTeammateTool } from '../lib/parallel-execution.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -122,7 +123,7 @@ function showPresets() {
   log(colors.cyan, 'DEFAULT (Recommended)');
   log(colors.dim, '  Install all components - agentful works best with everything enabled');
   log(colors.dim, '  Command: agentful init');
-  log(colors.dim, '  Includes: 8 agents, 6 skills, all hooks, all gates');
+  log(colors.dim, '  Includes: 8 agents, 7 skills, all hooks, all gates');
   console.log('');
 
   log(colors.cyan, 'MINIMAL');
@@ -354,6 +355,34 @@ async function init(args) {
       log(colors.green, `  ${file}`);
     });
     console.log('');
+
+    // Enable parallel execution
+    log(colors.dim, 'Checking parallel execution support...');
+    const detection = detectTeammateTool();
+
+    if (detection.available) {
+      if (detection.autoEnabled) {
+        log(colors.green, '✓ Parallel execution enabled (TeammateTool auto-patched)');
+      } else {
+        log(colors.green, '✓ Parallel execution available');
+      }
+    } else if (detection.canEnable) {
+      log(colors.yellow, '⚡ Enabling parallel execution...');
+      const result = enableTeammateTool();
+      if (result.success) {
+        log(colors.green, '✓ Parallel execution enabled successfully');
+        log(colors.dim, `  Backup created: ${result.backupPath}`);
+      } else {
+        log(colors.yellow, '⚠ Could not enable parallel execution');
+        log(colors.dim, `  Reason: ${result.error}`);
+        log(colors.dim, '  Agents will run sequentially (still works, just slower)');
+      }
+    } else {
+      log(colors.yellow, '⚠ Parallel execution not available');
+      log(colors.dim, `  Reason: ${detection.reason}`);
+      log(colors.dim, '  Agents will run sequentially (still works, just slower)');
+    }
+    console.log('');
   } catch (error) {
     log(colors.red, `Failed to initialize: ${error.message}`);
     process.exit(1);

package/bin/hooks/architect-drift-detector.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+
+/**
+ * Architect Drift Detector Hook
+ *
+ * Detects when project changes require architect to re-analyze and update skills/agents.
+ *
+ * Triggers re-analysis when:
+ * - New dependencies added (package.json, requirements.txt, go.mod, etc.)
+ * - Tech stack changes (switched frameworks)
+ * - New patterns emerge (5+ files violating existing conventions)
+ * - Skills are stale (last analysis > 7 days old)
+ *
+ * Run: After any Write/Edit operation by agents
+ * Action: Updates .agentful/architecture.json with needs_reanalysis: true
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+const ARCHITECTURE_FILE = '.agentful/architecture.json';
+const STALE_THRESHOLD_DAYS = 7;
+
+/**
+ * Detect if architect needs to re-run
+ */
+function detectArchitectDrift() {
+  try {
+    // Load current architecture analysis
+    const arch = loadArchitecture();
+
+    // Check various drift indicators
+    const driftReasons = [];
+
+    // 1. Check if dependency files changed
+    if (dependenciesChanged(arch)) {
+      driftReasons.push('dependencies_changed');
+    }
+
+    // 2. Check if tech stack files modified
+    if (techStackFilesModified(arch)) {
+      driftReasons.push('tech_stack_modified');
+    }
+
+    // 3. Check if analysis is stale
+    if (analysisIsStale(arch)) {
+      driftReasons.push('analysis_stale');
+    }
+
+    // 4. Check if new patterns emerged (heuristic: lots of new files)
+    if (newPatternsDetected(arch)) {
+      driftReasons.push('new_patterns_detected');
+    }
+
+    // If drift detected, mark for re-analysis
+    if (driftReasons.length > 0) {
+      markForReanalysis(arch, driftReasons);
+      console.log(`⚠️  Architect drift detected: ${driftReasons.join(', ')}`);
+      console.log('   Run /agentful-generate to update skills and agents');
+      return true;
+    }
+
+    return false;
+  } catch (error) {
+    // Fail silently - don't block operations if architecture.json missing
+    return false;
+  }
+}
+
+/**
+ * Load architecture.json
+ */
+function loadArchitecture() {
+  if (!fs.existsSync(ARCHITECTURE_FILE)) {
+    // First run - architect hasn't analyzed yet
+    return {
+      last_analysis: null,
+      dependency_hashes: {},
+      file_count: 0,
+      needs_reanalysis: true
+    };
+  }
+
+  return JSON.parse(fs.readFileSync(ARCHITECTURE_FILE, 'utf8'));
+}
+
+/**
+ * Check if dependency files changed
+ */
+function dependenciesChanged(arch) {
+  const depFiles = [
+    'package.json',
+    'package-lock.json',
+    'requirements.txt',
+    'pyproject.toml',
+    'Pipfile',
+    'go.mod',
+    'go.sum',
+    'Gemfile',
+    'Gemfile.lock',
+    'composer.json',
+    'pom.xml',
+    'build.gradle',
+    'Cargo.toml'
+  ];
+
+  for (const file of depFiles) {
+    if (!fs.existsSync(file)) continue;
+
+    const currentHash = hashFile(file);
+    const previousHash = arch.dependency_hashes?.[file];
+
+    if (previousHash && currentHash !== previousHash) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if tech stack config files modified
+ */
+function techStackFilesModified(arch) {
+  const configFiles = [
+    'tsconfig.json',
+    'next.config.js',
+    'vite.config.js',
+    'webpack.config.js',
+    'django/settings.py',
+    'config/application.rb',
+    'nest-cli.json'
+  ];
+
+  for (const file of configFiles) {
+    if (!fs.existsSync(file)) continue;
+
+    const currentHash = hashFile(file);
+    const previousHash = arch.dependency_hashes?.[file];
+
+    if (previousHash && currentHash !== previousHash) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if analysis is stale (>7 days old)
+ */
+function analysisIsStale(arch) {
+  if (!arch.last_analysis) return true;
+
+  const lastAnalysis = new Date(arch.last_analysis);
+  const daysSinceAnalysis = (Date.now() - lastAnalysis.getTime()) / (1000 * 60 * 60 * 24);
+
+  return daysSinceAnalysis > STALE_THRESHOLD_DAYS;
+}
+
+/**
+ * Heuristic: Check if significant new code added (potential new patterns)
+ */
+function newPatternsDetected(arch) {
+  // Count current files in src/
+  const currentFileCount = countSourceFiles();
+  const previousFileCount = arch.file_count || 0;
+
+  // If 20% more files added, might have new patterns
+  const growthRatio = (currentFileCount - previousFileCount) / Math.max(previousFileCount, 1);
+
+  return growthRatio > 0.2;
+}
+
+/**
+ * Count source files
+ */
+function countSourceFiles() {
+  const srcDirs = ['src', 'app', 'lib', 'pages', 'components'];
+  let count = 0;
+
+  for (const dir of srcDirs) {
+    if (fs.existsSync(dir)) {
+      count += countFilesRecursive(dir);
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Count files recursively
+ */
+function countFilesRecursive(dir) {
+  let count = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (entry.name === 'node_modules') continue;
+
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      count += countFilesRecursive(fullPath);
+    } else if (entry.isFile()) {
+      count++;
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Hash a file
+ */
+function hashFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+/**
+ * Mark architecture.json for re-analysis
+ */
+function markForReanalysis(arch, reasons) {
+  arch.needs_reanalysis = true;
+  arch.drift_reasons = reasons;
+  arch.drift_detected_at = new Date().toISOString();
+
+  // Ensure directory exists
+  const dir = path.dirname(ARCHITECTURE_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  fs.writeFileSync(ARCHITECTURE_FILE, JSON.stringify(arch, null, 2));
+}
+
+// Run detection
+const driftDetected = detectArchitectDrift();
+process.exit(driftDetected ? 1 : 0);