@itz4blitz/agentful 1.7.0 → 1.8.1

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

@@ -330,8 +330,9 @@ TodoWrite([
 6. Run @reviewer for quality gates
 7. If issues → @fixer → re-validate
 8. Update completion.json
-9. Check if architecture needs re-analysis
-10. LOOP until 100% complete
+9. COMPOUND: Store learnings and patterns
+10. Check if architecture needs re-analysis
+11. LOOP until 100% complete
 ```
 
 ### BUGFIX / ENHANCEMENT / REFACTOR
@@ -455,6 +456,188 @@ else:
 }
 ```
 
+## Worktree Management
+
+Git worktrees provide isolated environments for parallel agent development. Each task can work in its own worktree without polluting the main repository.
+
+### Why Worktrees?
+
+- **Isolation**: Changes are isolated until merged
+- **Parallel Development**: Multiple agents can work simultaneously
+- **Safety**: Experimental changes don't affect main branch
+- **Clean History**: Each worktree has its own git history
+
+### Worktree Modes
+
+Controlled via `AGENTFUL_WORKTREE_MODE` environment variable:
+
+| Mode | Behavior | When to Use |
+|-------|-----------|--------------|
+| `auto` | Create worktrees automatically | Default, recommended |
+| `block` | Require existing worktree | Strict environments |
+| `off` | Allow direct edits | Legacy, manual control |
+
+### Before Delegation: Worktree Setup
+
+Before delegating to any specialist agent:
+
+```bash
+# Check worktree mode
+if AGENTFUL_WORKTREE_MODE != "off":
+    # Check if we need a worktree
+    current_worktree = get_current_worktree()
+
+    if not current_worktree:
+        # Determine purpose from task type
+        purpose = determine_worktree_purpose(task_type)
+
+        # Create worktree via worktree-service
+        worktree = execute("node bin/hooks/worktree-service.js create " + purpose)
+
+        # Set environment for delegated agents
+        # They inherit AGENTFUL_WORKTREE_DIR
+        current_worktree = worktree
+
+    # Track in state.json
+    state.current_worktree = {
+        name: worktree.name,
+        path: worktree.path,
+        branch: worktree.branch,
+        purpose: worktree.purpose,
+        created_at: worktree.created_at
+    }
+```
+
+### Worktree Naming Convention
+
+Worktrees are automatically named:
+
+```
+agentful-<purpose>-<branch-slug>-<timestamp>
+```
+
+Examples:
+- `agentful-feature-auth-1739297120` - Feature development
+- `agentful-fix-coverage-1739297150` - Fixer adding coverage
+- `agentful-review-1739297180` - Reviewer validating
+- `agentful-hotfix-login-bug-1739297210` - Hotfix work
+
+### State Schema Extension
+
+Track worktrees in `.agentful/state.json`:
+
+```json
+{
+  "current_task": "feature/auth",
+  "current_phase": "implementation",
+  "current_worktree": {
+    "name": "agentful-feature-auth-1739297120",
+    "path": "/Users/dev/project/.git/worktrees/agentful-feature-auth-1739297120",
+    "branch": "feature/auth",
+    "purpose": "feature",
+    "created_at": "2025-02-11T15:30:00Z"
+  },
+  "worktrees": {
+    "active": [
+      {
+        "name": "agentful-feature-auth-1739297120",
+        "branch": "feature/auth",
+        "purpose": "feature",
+        "agent": "orchestrator",
+        "created_at": "2025-02-11T15:30:00Z",
+        "last_activity": "2025-02-11T16:45:00Z"
+      }
+    ]
+  }
+}
+```
+
+### After Task Completion: Worktree Cleanup
+
+When a feature passes all quality gates:
+
+```bash
+if task_completed and AGENTFUL_WORKTREE_AUTO_CLEANUP != "false":
+    # Commit changes in worktree
+    git -C $WORKTREE_PATH add .
+    git -C $WORKTREE_PATH commit -m "feat: complete ${feature_name}"
+
+    # Ask user what to do next
+    response = AskUserQuestion(
+        "Feature complete! What would you like to do?",
+        options: [
+            "Create PR",
+            "Merge to main",
+            "Keep worktree for review",
+            "Clean up worktree"
+        ]
+    )
+
+    if response == "Create PR" or response == "Merge to main":
+        # Push and create PR/merge
+        git -C $WORKTREE_PATH push
+        # ... PR creation logic ...
+
+    # Remove worktree
+    execute("node bin/hooks/worktree-service.js remove " + worktree.name)
+
+    # Update state.json
+    state.current_worktree = null
+```
+
+### Handling Interruptions
+
+If user interrupts during worktree operation:
+
+```bash
+on SIGINT:
+    if active_worktree:
+        # Mark for review instead of deleting
+        state.interrupted_worktree = {
+            name: active_worktree.name,
+            path: active_worktree.path,
+            interrupted_at: new Date().toISOString()
+        }
+
+        console.log("Worktree preserved: " + active_worktree.name)
+        console.log("Run /agentful-worktree --resume to continue")
+        console.log("Run /agentful-worktree --cleanup to remove")
+```
+
+### Worktree Service API
+
+The `worktree-service.js` provides these operations:
+
+```bash
+node bin/hooks/worktree-service.js create <purpose> [branch]  # Create worktree
+node bin/hooks/worktree-service.js list                    # List all worktrees
+node bin/hooks/worktree-service.js status                  # Show current status
+node bin/hooks/worktree-service.js cleanup                # Remove stale worktrees
+node bin/hooks/worktree-service.js prune                 # Run git prune
+node bin/hooks/worktree-service.js remove <name>         # Remove specific worktree
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|-----------|----------|-------------|
+| `AGENTFUL_WORKTREE_MODE` | `auto` | Worktree enforcement mode |
+| `AGENTFUL_WORKTREE_DIR` | (auto-set) | Current worktree path |
+| `AGENTFUL_WORKTREE_LOCATION` | `../` | Where to create worktrees |
+| `AGENTFUL_WORKTREE_AUTO_CLEANUP` | `true` | Auto-remove after completion |
+| `AGENTFUL_WORKTREE_RETENTION_DAYS` | `7` | Days before stale cleanup |
+| `AGENTFUL_WORKTREE_MAX_ACTIVE` | `5` | Maximum active worktrees |
+
+### CI/CD Detection
+
+Worktree mode auto-disables in CI environments:
+
+```bash
+if process.env.CI == "true" or process.env.GITHUB_ACTIONS == "true":
+    # Skip worktree creation
+    # CI already provides isolated environments
+```
+
 ## Delegation Pattern
 
 **NEVER implement yourself.** Always use Task tool.
@@ -502,6 +685,48 @@ Task("reviewer agent", "Review all changes in src/auth/")
 - ❌ Fixer needs reviewer results before fixing issues
 - ❌ Quality gates (must validate sequentially)
 
+### COMPOUND Phase
+
+After a feature passes all quality gates in FEATURE_DEVELOPMENT, run the compound phase:
+
+1. **Store successful patterns to MCP** (if available):
+   ```
+   Try MCP tool: store_pattern
+   - code: <key implementation pattern 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 unavailable: skip silently
+
+2. **Append retrospective to `.agentful/learnings.json`** (create if missing):
+   ```json
+   {
+     "learnings": [
+       {
+         "feature": "<feature name>",
+         "timestamp": "<ISO 8601>",
+         "review_fix_cycles": <number of review→fix→re-validate cycles>,
+         "gates_failed_initially": ["<gate names that failed on first review>"],
+         "key_learning": "<1-sentence summary of what was learned>"
+       }
+     ]
+   }
+   ```
+
+3. **Track iteration metrics** in `state.json`:
+   ```json
+   {
+     "last_feature_metrics": {
+       "feature": "<feature name>",
+       "cycles": <review/fix cycle count>,
+       "gates_passed_first_try": <boolean>
+     }
+   }
+   ```
+
+**Skip COMPOUND for**: BUGFIX, ENHANCEMENT, REFACTOR workflows and blocked/skipped features.
+
 ## Decision Handling
 
 When you need user input:

package/template/.claude/agents/reviewer.md

@@ -2,7 +2,7 @@
 name: reviewer
 description: Reviews code quality, finds dead code, validates production readiness. Runs all checks and reports issues.
 model: sonnet
-tools: Read, Write, Edit, Glob, Grep, Bash
+tools: Read, Write, Edit, Glob, Grep, Bash, mcp__agentful__store_pattern
 ---
 
 # Reviewer Agent
@@ -38,6 +38,24 @@ Fall back to manual Grep if none available
 
 **Reference the validation skill** (`.claude/skills/validation/SKILL.md`) for comprehensive validation strategies.
 
+## Step 1.5: Worktree Check
+
+Before running checks, verify your working environment:
+
+```bash
+# Check if AGENTFUL_WORKTREE_DIR is set
+if exists("$AGENTFUL_WORKTREE_DIR"):
+    worktree_path = "$AGENTFUL_WORKTREE_DIR"
+    echo "✅ Reviewing in worktree: $worktree_path"
+else:
+    echo "📍 Reviewing in root repository"
+    echo "⚠️  Validation reports will be saved to main .agentful/"
+```
+
+**Report worktree status**: In your validation report, always include:
+- Worktree path (if applicable)
+- Branch being validated
+
 ## Your Scope
 
 - **Type Checking** - Run type checker (tsc, mypy, etc.)
@@ -221,9 +239,21 @@ When validation tools are unavailable:
 
 ## After Implementation
 
-Report:
-- Overall validation status (passed/failed)
-- Which gates passed/failed
-- List of issues requiring fixes
-- List of warnings that can be ignored
-- Recommendation: delegate to @fixer if issues found
+1. **Store error patterns to MCP** (if available):
+   For each failed gate with specific error messages:
+   ```
+   Try MCP tool: store_pattern
+   - code: <error pattern and context>
+   - tech_stack: <detected tech stack>
+   - error: <specific error message from failed gate>
+   ```
+   - Focus on recurring or non-obvious errors
+   - Include enough context for the fixer to match against
+   - If tool unavailable: skip silently
+
+2. **Report**:
+   - Overall validation status (passed/failed)
+   - Which gates passed/failed
+   - List of issues requiring fixes
+   - List of warnings that can be ignored
+   - Recommendation: delegate to @fixer if issues found

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, mcp__agentful-mcp-server__find_patterns, mcp__agentful-mcp-server__store_pattern, mcp__agentful-mcp-server__add_feedback
+tools: Read, Write, Edit, Glob, Grep, Bash, mcp__agentful__find_patterns, mcp__agentful__store_pattern, mcp__agentful__add_feedback
 ---
 
 # Tester Agent

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

@@ -0,0 +1,106 @@
+---
+name: agentful-worktree
+description: Manage git worktrees for parallel agent development. List, create, and cleanup worktrees.
+---
+
+# /agentful-worktree
+
+Manage git worktrees for parallel agentful development.
+
+## Usage
+
+```bash
+/agentful-worktree                    # List all active worktrees
+/agentful-worktree --status           # Show current session worktree
+/agentful-worktree --create feature/x  # Create new worktree for branch
+/agentful-worktree --cleanup          # Remove stale worktrees
+/agentful-worktree --prune           # Run git worktree prune
+/agentful-worktree --remove <name>    # Remove specific worktree
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|-----------|----------|-------------|
+| `AGENTFUL_WORKTREE_MODE` | `auto` | `auto` (create), `block` (require), `off` (disabled) |
+| `AGENTFUL_WORKTREE_LOCATION` | `../` | Where to create worktrees (relative to repo) |
+| `AGENTFUL_WORKTREE_AUTO_CLEANUP` | `true` | Auto-remove worktrees after task completion |
+| `AGENTFUL_WORKTREE_RETENTION_DAYS` | `7` | Days before worktrees are marked stale |
+| `AGENTFUL_WORKTREE_MAX_ACTIVE` | `5` | Maximum active worktrees before cleanup forced |
+
+## Examples
+
+### List Worktrees
+
+```
+/agentful-worktree
+```
+
+Output:
+```
+📋 Active Worktrees:
+
+┌─────────────────────────────────────────────────────────────┐
+│ agentful-feature-auth-1739297120                │
+│ ├─ Branch: feature/auth                             │
+│ ├─ Purpose: feature                                │
+│ ├─ Path: ../agentful-feature-auth-1739297120       │
+│ ├─ Status: 🟢 Active (15 min ago)                │
+│ └─ Created: 2025-02-11T15:30:00.000Z            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Show Current Status
+
+```
+/agentful-worktree --status
+```
+
+### Create Worktree
+
+```
+/agentful-worktree --create feature/dashboard
+```
+
+Creates a worktree named `agentful-feature-dashboard-<timestamp>` on the `feature/dashboard` branch.
+
+### Cleanup Stale Worktrees
+
+```
+/agentful-worktree --cleanup
+```
+
+Removes worktrees older than `AGENTFUL_WORKTREE_RETENTION_DAYS` (default: 7 days).
+
+## Worktree Naming Convention
+
+Worktrees are automatically named using this pattern:
+
+```
+agentful-<purpose>-<branch-slug>-<timestamp>
+```
+
+Examples:
+- `agentful-feature-auth-1739297120` - Feature development
+- `agentful-fix-coverage-1739297150` - Fixer adding coverage
+- `agentful-review-1739297180` - Reviewer validating
+- `agentful-hotfix-login-bug-1739297210` - Hotfix work
+
+## When to Use Worktrees
+
+**Use worktrees when**:
+- Working on multiple features simultaneously
+- Running quality gates while developing other features
+- Reviewing PRs without interrupting active work
+- Testing experimental approaches safely
+
+**Don't need worktrees when**:
+- Quick fixes in a single feature branch
+- Documentation-only changes
+- Set `AGENTFUL_WORKTREE_MODE=off` to disable
+
+## See Also
+
+- [Git Worktrees Concept](/concepts/git-worktrees) - Deep dive on worktree usage
+- [/agentful-start](/commands/agentful-start) - Main development loop
+- [/agentful-status](/commands/agentful-status) - Check completion progress

package/template/.claude/settings.json

@@ -1,7 +1,8 @@
 {
   "includeCoAuthoredBy": false,
   "env": {
-    "ENABLE_TOOL_SEARCH": "true"
+    "ENABLE_TOOL_SEARCH": "true",
+    "AGENTFUL_WORKTREE_MODE": "auto"
   },
   "hooks": {
     "SessionStart": [
@@ -23,6 +24,17 @@
       }
     ],
     "PreToolUse": [
+      {
+        "tools": ["Write", "Edit"],
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node bin/hooks/ensure-worktree.js",
+            "timeout": 10,
+            "description": "Ensure agents work in git worktrees (disable with AGENTFUL_WORKTREE_MODE=off)"
+          }
+        ]
+      },
       {
         "tools": ["Write", "Edit"],
         "hooks": [

package/template/CLAUDE.md

@@ -61,6 +61,23 @@ When you start a Claude Code session, agentful automatically:
 
 No need to remember commands - just pick a numbered action!
 
+## Pattern Learning (MCP Server)
+
+Enable cross-session pattern learning so agents compound knowledge over time:
+
+```bash
+claude mcp add agentful -- npx -y @itz4blitz/agentful-mcp-server
+```
+
+**What this enables:**
+- **Reviewer** stores error patterns so the fixer can look up known fixes instantly
+- **Fixer** queries known fixes before attempting manual repairs, then stores successful fixes
+- **Orchestrator** stores successful implementation patterns after features pass all quality gates
+
+Without MCP: agents start from scratch every session. With MCP: agents compound across sessions.
+
+See [Hooks System](#hooks-system) below for manual setup or other editors.
+
 ## Commands
 
 | Command | Description | When to Use |
@@ -119,6 +136,8 @@ These appear only when relevant:
 - `.agentful/conversation-history.json` - Message history for context tracking
 - `.agentful/agent-metrics.json` - Agent lifecycle hooks and metrics
 - `.agentful/architecture.json` - Detected tech stack and generated agents
+- `.agentful/learnings.json` - Compound engineering retrospectives
+- `.agentful/last-validation.json` - Latest validation report from reviewer
 
 **Configuration** (auto-generated, customizable):
 - `.claude/agents/` - Specialized agents for your tech stack
@@ -180,6 +199,33 @@ The `reviewer` agent runs these checks automatically. The `fixer` agent resolves
 - Estimated remaining work
 → If no progress for 2+ minutes, the task may be stuck. Check `.agentful/state.json` for circuit breaker status.
 
+### Git Worktree Mode
+
+agentful supports automatic git worktree management for safer parallel development.
+
+**Modes**:
+| Mode | Behavior |
+|-------|-----------|
+| `auto` | Create worktrees automatically when agents make changes (recommended) |
+| `block` | Require agents to work in existing worktrees |
+| `off` | Allow direct edits to root repository (legacy) |
+
+**Enable via environment**:
+```bash
+export AGENTFUL_WORKTREE_MODE=auto
+```
+
+**Or in `.claude/settings.json`**:
+```json
+{
+  "env": {
+    "AGENTFUL_WORKTREE_MODE": "auto"
+  }
+}
+```
+
+**More configuration**: See [/agentful-worktree](/commands/agentful-worktree) command and [Git Worktrees concept](/concepts/git-worktrees) for full details.
+
 ## Getting Help
 
 **Documentation**: See `.claude/commands/` for detailed command documentation

package/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.6.0"
+  "version": "1.8.0"
 }