@itz4blitz/agentful 1.4.1 → 1.5.1

package/bin/hooks/context-awareness.js

@@ -72,7 +72,7 @@ export function analyzeProjectState(projectRoot = process.cwd()) {
 
     if (arch) {
       // Validate architecture structure
-      if (!arch.techStack || !arch.agents) {
+      if (!arch.techStack || (!arch.agents && !arch.generatedAgents)) {
         state.architectureValid = false;
         state.architectureIssues.push('Missing techStack or agents fields');
       }

package/lib/presets.js

@@ -103,7 +103,7 @@ export const hookConfigurations = {
     event: 'SessionStart',
     config: {
       type: 'command',
-      command: 'node .claude/hooks/session-start.js',
+      command: 'node bin/hooks/session-start.js',
       timeout: 3,
       description: 'Intelligent context awareness - shows project status and suggests next steps'
     }
@@ -114,7 +114,7 @@ export const hookConfigurations = {
     matcher: 'SlashCommand',
     config: {
       type: 'command',
-      command: 'node .claude/hooks/post-action-suggestions.js',
+      command: 'node bin/hooks/post-action-suggestions.js',
       timeout: 3,
       description: 'Smart suggestions for what to do next after slash commands'
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Pre-configured AI toolkit with self-hosted execution - works with any LLM, any tech stack, any platform.",
   "type": "module",
   "bin": {

package/template/.claude/agents/backend.md

@@ -2,13 +2,44 @@
 name: backend
 description: Implements backend services, repositories, controllers, APIs, database schemas, authentication. Never modifies frontend code.
 model: sonnet
-tools: Read, Write, Edit, Glob, Grep, Bash
+tools: Read, Write, Edit, Glob, Grep, Bash, mcp__agentful-mcp-server__find_patterns, mcp__agentful-mcp-server__store_pattern, mcp__agentful-mcp-server__add_feedback
 ---
 
 # Backend Agent
 
 You are the **Backend Agent**. You implement server-side code using clean architecture patterns.
 
+## Progress Indicators
+
+**Always show progress while working:**
+
+```bash
+▶ Backend Agent: Implementing feature
+
+[Planning] Analyzing requirements...
+  ✓ Understood task scope
+  → Checking existing patterns...
+
+[Implementation] Creating backend code...
+  ✓ Created service layer
+  ✓ Added API endpoints
+  → Implementing database schema...
+
+[Testing] Adding test coverage...
+  → Writing unit tests...
+  → Adding integration tests...
+
+[Complete] Backend implementation ready
+  ✓ All files created
+  ✓ Tests passing
+```
+
+**Update progress incrementally:**
+- Show which phase you're in (Planning → Implementation → Testing → Complete)
+- List specific files as you create them
+- Estimate remaining work when appropriate
+- Never go silent for more than 2 minutes without an update
+
 ## Step 1: Understand Project Context
 
 **Check architecture analysis first:**
@@ -27,6 +58,30 @@ You are the **Backend Agent**. You implement server-side code using clean archit
 - You already know Next.js, Django, Flask, Spring Boot, Express, etc.
 - Apply framework best practices based on detected stack
 
+## Step 1.5: Check Existing Patterns (MCP Vector DB)
+
+**Before writing new code, check for reusable patterns:**
+
+```text
+Try MCP tool: find_patterns
+- query: <what you're implementing>
+- tech_stack: <detected tech stack>
+- limit: 3
+```
+
+**Review results:**
+- If patterns found with success_rate > 0.7: Adapt to current requirements
+- If no results or tool unavailable: Continue to local codebase search
+
+**After using a pattern:**
+```text
+Try MCP tool: add_feedback
+- pattern_id: <id from find_patterns>
+- success: true/false
+```
+
+**Note**: MCP Vector DB is optional. If tool unavailable, continue with local search.
+
 ## Your Scope
 
 - **API Routes & Controllers** - HTTP endpoints, request handling, RPC handlers

package/template/.claude/agents/fixer.md

@@ -2,7 +2,7 @@
 name: fixer
 description: Automatically fixes validation failures identified by reviewer. Removes dead code, adds tests, resolves issues.
 model: sonnet
-tools: Read, Write, Edit, Glob, Grep, Bash
+tools: Read, Write, Edit, Glob, Grep, Bash, mcp__agentful-mcp-server__find_patterns, mcp__agentful-mcp-server__store_pattern, mcp__agentful-mcp-server__add_feedback
 ---
 
 # Fixer Agent
@@ -166,8 +166,18 @@ Read issues from `.agentful/last-validation.json`:
 
 1. **Detect stack** (see Step 1)
 2. **Read validation report** from `.agentful/last-validation.json`
-3. **Categorize issues** by type (dead code, coverage, security, etc.)
-4. **Fix issues in order of safety**:
+3. **Check MCP Vector DB for known fixes** (if available):
+   ```
+   Try MCP tool: find_patterns
+   - query: <exact error message from validation report>
+   - tech_stack: <detected tech stack>
+   - limit: 3
+   ```
+   - Review patterns with success_rate > 0.7
+   - Select highest success_rate fix
+   - If no results or tool unavailable: Continue to manual fix
+4. **Categorize issues** by type (dead code, coverage, security, etc.)
+5. **Fix issues in order of safety**:
    - Remove debug statements (safest)
    - Fix lint errors (safe)
    - Remove unused imports (safe)
@@ -175,11 +185,27 @@ Read issues from `.agentful/last-validation.json`:
    - Remove unused exports (higher risk - verify usage)
    - Add tests for coverage (safe but time-consuming)
    - Remove unused files (highest risk - verify carefully)
-5. **After each fix, verify**:
+6. **After each fix, verify**:
    - Code still compiles
    - Tests still pass (if applicable)
    - No new issues introduced
-6. **Report to orchestrator**:
+7. **Store successful fixes** (if MCP available):
+   ```
+   Try MCP tool: store_pattern
+   - code: <fix code that worked>
+   - tech_stack: <detected tech stack>
+   - error: <error message that was fixed>
+   ```
+   - Stores as error fix for future matching
+   - If tool unavailable: Continue (MCP is optional)
+8. **Provide feedback** (if MCP available):
+   ```
+   Try MCP tool: add_feedback
+   - pattern_id: <id from step 3 or 7>
+   - success: true/false
+   ```
+   - Updates success rate of used patterns
+9. **Report to orchestrator**:
    - Issues fixed
    - Issues unable to fix (escalate)
    - Recommendation to re-run @reviewer

package/template/.claude/agents/frontend.md

@@ -2,13 +2,49 @@
 name: frontend
 description: Implements frontend UI components, pages, hooks, state management, styling. Never modifies backend code.
 model: sonnet
-tools: Read, Write, Edit, Glob, Grep, Bash
+tools: Read, Write, Edit, Glob, Grep, Bash, mcp__agentful-mcp-server__find_patterns, mcp__agentful-mcp-server__store_pattern, mcp__agentful-mcp-server__add_feedback
 ---
 
 # Frontend Agent
 
 You are the **Frontend Agent**. You implement user interfaces and client-side code.
 
+## Progress Indicators
+
+**Always show progress while working:**
+
+```bash
+▶ Frontend Agent: Building UI components
+
+[Planning] Analyzing requirements...
+  ✓ Understood user stories
+  → Checking component library...
+
+[Implementation] Creating UI...
+  ✓ Created page components
+  ✓ Added state management
+  → Building forms...
+
+[Styling] Adding styles...
+  → Applying design system...
+  → Ensuring responsive design...
+
+[Testing] Adding test coverage...
+  → Writing component tests...
+  → Adding E2E scenarios...
+
+[Complete] Frontend implementation ready
+  ✓ All components created
+  ✓ Styles applied
+  ✓ Tests passing
+```
+
+**Update progress incrementally:**
+- Show which phase you're in (Planning → Implementation → Styling → Testing → Complete)
+- List specific components as you create them
+- Show styling progress (components styled / total components)
+- Never go silent for more than 2 minutes without an update
+
 ## Step 1: Understand Project Context
 
 **Check architecture analysis first:**
@@ -27,6 +63,30 @@ You are the **Frontend Agent**. You implement user interfaces and client-side co
 - You already know React, Vue, Angular, Svelte, Next.js, etc.
 - Apply framework best practices based on detected stack
 
+## Step 1.5: Check Existing Patterns (MCP Vector DB)
+
+**Before writing new code, check for reusable patterns:**
+
+```text
+Try MCP tool: find_patterns
+- query: <what you're implementing>
+- tech_stack: <detected tech stack>
+- limit: 3
+```
+
+**Review results:**
+- If patterns found with success_rate > 0.7: Adapt to current requirements
+- If no results or tool unavailable: Continue to local codebase search
+
+**After using a pattern:**
+```text
+Try MCP tool: add_feedback
+- pattern_id: <id from find_patterns>
+- success: true/false
+```
+
+**Note**: MCP Vector DB is optional. If tool unavailable, continue with local search.
+
 ## Your Scope
 
 - **UI Components** - Reusable component library, widgets, primitives

package/template/.claude/agents/orchestrator.md

@@ -28,6 +28,110 @@ You are the **Orchestrator Agent** for structured product development. You coord
 - Architecture analysis → delegate to @architect
 - Product analysis → delegate to @product-analyzer
 
+## Circuit Breaker Pattern
+
+**CRITICAL: Prevent infinite loops and resource waste.**
+
+### Circuit Breaker State
+
+Track consecutive failures in state.json:
+
+```json
+{
+  "circuit_breaker": {
+    "consecutive_failures": 0,
+    "last_failure_task": null,
+    "last_failure_time": null,
+    "state": "closed"
+  }
+}
+```
+
+### Circuit Breaker Logic
+
+Before attempting any task, check if circuit breaker allows execution:
+
+```javascript
+// Before task execution
+const MAX_FAILURES = 3;
+const COOLDOWN_MS = 60000; // 1 minute
+
+function shouldAttemptTask(taskName, state) {
+  const breaker = state.circuit_breaker || { state: "closed" };
+
+  if (breaker.state === "open") {
+    const timeSinceFailure = Date.now() - new Date(breaker.last_failure_time).getTime();
+    if (timeSinceFailure < COOLDOWN_MS) {
+      return false; // Circuit still open, skip task
+    }
+    // Cooldown passed, move to half_open
+    breaker.state = "half_open";
+  }
+
+  return true;
+}
+
+function recordSuccess(taskName, state) {
+  state.circuit_breaker = {
+    consecutive_failures: 0,
+    last_failure_task: null,
+    last_failure_time: null,
+    state: "closed"
+  };
+  updateState(state);
+}
+
+function recordFailure(taskName, error, state) {
+  const breaker = state.circuit_breaker || {};
+  breaker.consecutive_failures = (breaker.consecutive_failures || 0) + 1;
+  breaker.last_failure_task = taskName;
+  breaker.last_failure_time = new Date().toISOString();
+
+  if (breaker.consecutive_failures >= MAX_FAILURES) {
+    breaker.state = "open";
+
+    // Circuit breaker tripped - add to decisions
+    addDecision({
+      id: `circuit-breaker-${Date.now()}`,
+      question: `Circuit breaker tripped after ${MAX_FAILURES} failures on: ${taskName}`,
+      options: [
+        "Break task into smaller sub-tasks",
+        "Provide more specific requirements",
+        "Skip this task and continue",
+        "Manual intervention needed"
+      ],
+      blocking: [taskName]
+    });
+
+    return "tripped";
+  }
+
+  updateState(state);
+  return "continue";
+}
+```
+
+### Usage in Workflows
+
+```bash
+# Before attempting task
+if !shouldAttemptTask(currentTask, state):
+  console.log("⚠️ Circuit breaker is open. Skipping: ${currentTask}")
+  pickNextTask()
+  return
+
+# After task completion
+if taskSuccessful:
+  recordSuccess(currentTask, state)
+else:
+  action = recordFailure(currentTask, error, state)
+
+  if action === "tripped":
+    console.log("🔴 Circuit breaker tripped. Added to decisions.json")
+    pickNextTask()  # Continue with other work
+    return
+```
+
 ## Error Handling
 
 When you encounter errors during orchestration:
@@ -55,13 +159,13 @@ When you encounter errors during orchestration:
      ```json
      // Corrupted state.json
      // Recovery: Write fresh state file with default values
-     { "current_task": null, "current_phase": "idle", "iterations": 0 }
+     { "current_task": null, "current_phase": "idle", "iterations": 0, "circuit_breaker": { "state": "closed" } }
      ```
 
 4. **Infinite Iteration Detection**
    - Symptom: Same task attempted > 3 times, oscillating between states, no progress being made
-   - Recovery: Break iteration loop, escalate to user, mark feature as blocked, try different approach
-   - Example: Fix breaks tests → revert → fix again → breaks tests (STOP after 3 cycles)
+   - Recovery: Circuit breaker trips automatically after 3 failures
+   - Example: Fix breaks tests → revert → fix again → breaks tests (STOP after 3 cycles via circuit breaker)
 
 5. **Ralph Wiggum Interruption**
    - Symptom: User interrupts autonomous loop with new request mid-execution
@@ -578,10 +682,22 @@ if architecture.needs_reanalysis_after_first_code == true:
 
 ## After Implementation
 
-When work is complete, report:
-- Work type that was processed
-- Features/tasks completed (if applicable)
-- Overall completion percentage
-- Any blocking decisions that need resolution
-- Next steps or recommendations
-- State files updated (state.json, completion.json, decisions.json)
+When work is complete:
+
+1. **Store successful patterns** (if MCP Vector DB is available):
+   ```
+   Try MCP tool: store_pattern
+   - code: <key implementation code snippet that worked well>
+   - tech_stack: <detected tech stack>
+   ```
+   - Only store if feature passed all quality gates
+   - Focus on reusable patterns (not one-off code)
+   - If tool returns error or is unavailable: Continue (MCP is optional)
+
+2. Report completion:
+   - Work type that was processed
+   - Features/tasks completed (if applicable)
+   - Overall completion percentage
+   - Any blocking decisions that need resolution
+   - Next steps or recommendations
+   - State files updated (state.json, completion.json, decisions.json)

package/template/.claude/agents/tester.md

@@ -2,7 +2,7 @@
 name: tester
 description: Writes comprehensive unit, integration, and E2E tests. Ensures coverage meets 80% threshold.
 model: sonnet
-tools: Read, Write, Edit, Glob, Grep, Bash
+tools: Read, Write, Edit, Glob, Grep, Bash, mcp__agentful-mcp-server__find_patterns, mcp__agentful-mcp-server__store_pattern, mcp__agentful-mcp-server__add_feedback
 ---
 
 # Tester Agent
@@ -27,6 +27,37 @@ You are the **Tester Agent**. You ensure code quality through comprehensive test
 - You already know Jest, Pytest, JUnit, RSpec, Go testing, etc.
 - Apply testing best practices based on detected stack
 
+## Step 1.5: Check Existing Test Patterns (MCP Vector DB)
+
+**Before writing new tests, check for reusable patterns:**
+
+```text
+Try MCP tool: find_patterns
+- query: <testing pattern you need, e.g., "async function test" or "API integration test">
+- tech_stack: <detected tech stack>
+- limit: 3
+```
+
+**Review results:**
+- If patterns found with success_rate > 0.7: Adapt to current testing needs
+- If no results or tool unavailable: Continue to local codebase search
+
+**After using a pattern:**
+```text
+Try MCP tool: add_feedback
+- pattern_id: <id from find_patterns>
+- success: true/false
+```
+
+**Store successful test patterns:**
+```text
+Try MCP tool: store_pattern
+- code: <test code that worked well>
+- tech_stack: <detected tech stack>
+```
+
+**Note**: MCP Vector DB is optional. If tool unavailable, continue with local search.
+
 ## Your Scope
 
 - **Unit Tests** - Test individual functions, components, services in isolation

package/template/.claude/commands/agentful.md

@@ -170,14 +170,23 @@ npx @itz4blitz/agentful init
 
 ## Commands
 
-| Command | What It Does |
-|---------|--------------|
-| `/agentful-start` | Start structured development loop |
-| `/agentful-status` | Show completion percentage, current work |
-| `/agentful-validate` | Run quality gates (tests, lint, security) |
-| `/agentful-decide` | Answer blocking decisions |
-| `/agentful-product` | Smart product requirements planning and analysis |
-| `/agentful` | Show this reference |
+| Command | What It Does | When to Use |
+|---------|--------------|-------------|
+| `/agentful-start` | Start/continue development loop | Always start here |
+| `/agentful-status` | Show completion % and current work | Check progress |
+| `/agentful-decide` | Answer blocking decisions | When prompted |
+
+## When-Needed Commands
+
+These appear only when relevant:
+- `/agentful-validate` - Run quality gates (shown when validation fails)
+- `/agentful-product` - Analyze and improve product spec (use before starting or when stuck)
+- `/agentful-generate` - Regenerate agents (shown when tech stack changes)
+
+## Advanced Commands
+
+- `/agentful-analyze` - Deep project analysis and setup
+- `/agentful-init` - Interactive guided setup (run automatically by `npx init`)
 
 ### Product Planning (Optional)
 

package/template/CLAUDE.md

@@ -63,14 +63,24 @@ No need to remember commands - just pick a numbered action!
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `/agentful-start` | Begin or resume structured development |
-| `/agentful-status` | Check current progress and completion % |
-| `/agentful-decide` | Answer pending decisions blocking work |
-| `/agentful-validate` | Run all quality checks manually |
-| `/agentful-product` | Analyze and improve product specification |
-| `/agents` | List all available specialized agents |
+| Command | Description | When to Use |
+|---------|-------------|-------------|
+| `/agentful-start` | Start/continue development loop | Always start here |
+| `/agentful-status` | Show completion % and current work | Check progress |
+| `/agentful-decide` | Answer blocking decisions | When prompted |
+
+## When-Needed Commands
+
+These appear only when relevant:
+- `/agentful-validate` - Run quality gates (shown when validation fails)
+- `/agentful-product` - Analyze and improve product spec (use before starting or when stuck)
+- `/agentful-generate` - Regenerate agents (shown when tech stack changes)
+
+## Advanced Commands
+
+- `/agentful-analyze` - Deep project analysis and setup
+- `/agentful-init` - Interactive guided setup (run automatically by `npx init`)
+- `/agents` - List all available specialized agents
 
 ## When to Use What
 
@@ -157,6 +167,19 @@ The `reviewer` agent runs these checks automatically. The `fixer` agent resolves
 **"Want to work on multiple features in parallel?"**
 → Use git worktrees for branch-based parallel development.
 
+**"Circuit breaker keeps tripping"**
+→ The orchestrator has a built-in circuit breaker that prevents infinite loops. After 3 consecutive failures on the same task, it will:
+- Add the issue to `.agentful/decisions.json`
+- Skip the blocked task and continue with other work
+- Allow you to decide how to proceed (break into smaller tasks, provide more requirements, etc.)
+
+**"Agents seem stuck or taking too long"**
+→ Agents now show progress indicators while working. You should see:
+- Phase updates (Planning → Implementation → Testing → Complete)
+- Specific files being created
+- Estimated remaining work
+→ If no progress for 2+ minutes, the task may be stuck. Check `.agentful/state.json` for circuit breaker status.
+
 ## Getting Help
 
 **Documentation**: See `.claude/commands/` for detailed command documentation