@itz4blitz/agentful 1.8.0 → 1.8.2

package/lib/presets.js

@@ -19,7 +19,7 @@ export const presets = {
     description: 'Complete agentful installation (recommended)',
     agents: ['orchestrator', 'architect', 'backend', 'frontend', 'tester', 'reviewer', 'fixer', 'product-analyzer'],
     skills: ['product-tracking', 'validation', 'testing', 'conversation', 'product-planning', 'deployment', 'research'],
-    hooks: ['session-start', 'health-check', 'block-random-docs', 'block-file-creation', 'product-spec-watcher', 'architect-drift-detector', 'analyze-trigger'],
+    hooks: ['session-start', 'health-check', 'mcp-health-check', 'block-random-docs', 'block-file-creation', 'product-spec-watcher', 'architect-drift-detector', 'analyze-trigger', 'package-metadata-guard'],
     gates: ['types', 'tests', 'coverage', 'lint', 'security', 'dead-code']
   },
 
@@ -47,6 +47,16 @@ export const hookConfigurations = {
     }
   },
 
+  'mcp-health-check': {
+    event: 'SessionStart',
+    config: {
+      type: 'command',
+      command: 'node bin/hooks/mcp-health-check.js',
+      timeout: 3,
+      description: 'Verify agentful MCP server is configured'
+    }
+  },
+
   'block-random-docs': {
     event: 'PreToolUse',
     matcher: 'Write',
@@ -151,6 +161,17 @@ export const hookConfigurations = {
       timeout: 3,
       description: 'Watch for product spec changes and auto-trigger generation'
     }
+  },
+
+  'package-metadata-guard': {
+    event: 'PostToolUse',
+    matcher: 'Write|Edit',
+    config: {
+      type: 'command',
+      command: 'node bin/hooks/package-metadata-guard.js',
+      timeout: 3,
+      description: 'Protect package.json ownership metadata from accidental corruption'
+    }
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Pre-configured AI toolkit with self-hosted execution - works with any LLM, any tech stack, any platform.",
   "type": "module",
   "bin": {
@@ -16,16 +16,14 @@
     "lint": "eslint .",
     "release": "semantic-release",
     "release:dry-run": "semantic-release --dry-run",
-    "docs:dev": "vocs dev",
+    "docs:dev": "vocs dev --host 127.0.0.1 --port 8080",
     "docs:build": "vocs build",
     "docs:preview": "vocs preview",
-    "build:all": "npm run build:cli && npm run build:studio && npm run build:mcp",
-    "build:cli": "cd packages/cli && npm run build",
-    "build:studio": "cd packages/studio && npm run build",
+    "build:all": "npm run build:mcp",
     "build:mcp": "cd packages/mcp-server && npm run build",
-    "dev:studio": "cd packages/studio && npm run dev",
-    "watch:studio": "cd packages/studio && npm run watch",
-    "install:all": "npm install && cd packages/cli && npm install && cd ../studio && npm install && cd ../mcp-server && npm install && cd ../shared && npm install"
+    "test:mcp": "cd packages/mcp-server && npm run test",
+    "dev:mcp": "cd packages/mcp-server && npm run dev",
+    "install:all": "npm install && cd packages/mcp-server && npm install"
   },
   "exports": {
     ".": {
@@ -79,6 +77,7 @@
     "@vitest/coverage-v8": "^1.2.0",
     "eslint": "^9.39.2",
     "semantic-release": "^25.0.2",
+    "vite-plugin-pagefind": "^1.0.7",
     "vitest": "^1.2.0",
     "vocs": "^1.4.1"
   },

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

@@ -48,6 +48,25 @@ You are the **Backend Agent**. You implement server-side code using clean archit
 
 **Reference skills for tech-specific guidance:**
 - Look in `.claude/skills/` for framework-specific patterns
+
+## Step 1.5: Worktree Check
+
+Before implementing, verify your working environment:
+
+```bash
+# Check if AGENTFUL_WORKTREE_DIR is set
+if exists("$AGENTFUL_WORKTREE_DIR"):
+    worktree_path = "$AGENTFUL_WORKTREE_DIR"
+    echo "✅ Implementing backend in worktree: $worktree_path"
+else:
+    echo "📍 Implementing backend in root repository"
+    echo "⚠️  Changes will affect main branch directly"
+```
+
+**Report worktree status**: In your final report, always include:
+- Worktree path (if applicable)
+- Branch being worked on
+- Any commits created
 - Skills contain project-specific conventions, not generic framework docs
 
 **Sample existing code to understand conventions:**

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

@@ -53,6 +53,25 @@ You are the **Frontend Agent**. You implement user interfaces and client-side co
 
 **Reference skills for tech-specific guidance:**
 - Look in `.claude/skills/` for framework-specific patterns
+
+## Step 1.5: Worktree Check
+
+Before implementing, verify your working environment:
+
+```bash
+# Check if AGENTFUL_WORKTREE_DIR is set
+if exists("$AGENTFUL_WORKTREE_DIR"):
+    worktree_path = "$AGENTFUL_WORKTREE_DIR"
+    echo "✅ Implementing frontend in worktree: $worktree_path"
+else:
+    echo "📍 Implementing frontend in root repository"
+    echo "⚠️  Changes will affect main branch directly"
+```
+
+**Report worktree status**: In your final report, always include:
+- Worktree path (if applicable)
+- Branch being worked on
+- Any commits created
 - Skills contain project-specific conventions (styling, state management, forms)
 
 **Sample existing code to understand conventions:**

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

@@ -456,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.

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

@@ -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.)

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": [
@@ -24,7 +25,18 @@
     ],
     "PreToolUse": [
       {
-        "tools": ["Write", "Edit"],
+        "matcher": "Write|Edit|NotebookEdit",
+        "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)"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -35,7 +47,7 @@
         ]
       },
       {
-        "tools": ["Write"],
+        "matcher": "Write",
         "hooks": [
           {
             "type": "command",
@@ -48,7 +60,7 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -59,7 +71,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -70,7 +82,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -81,7 +93,18 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node bin/hooks/package-metadata-guard.js",
+            "timeout": 3,
+            "description": "Protect package.json ownership metadata from accidental corruption"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -90,7 +113,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -120,4 +143,4 @@
       "Bash(mkfs:*)"
     ]
   }
-}
+}

package/template/CLAUDE.md

@@ -20,7 +20,7 @@ npx @itz4blitz/agentful init --agents=orchestrator,backend --skills=validation
 npx @itz4blitz/agentful presets
 ```
 
-**[agentful.app/configure](https://agentful.app/configure)** - Interactive web configurator for shareable configurations
+Use `npx @itz4blitz/agentful presets` to see local installation options.
 
 ## Quick Start
 
@@ -78,6 +78,15 @@ Without MCP: agents start from scratch every session. With MCP: agents compound
 
 See [Hooks System](#hooks-system) below for manual setup or other editors.
 
+## Metadata Safety (Critical)
+
+When editing `package.json` (or other repo metadata files), preserve project ownership:
+
+- Never change `repository.url`, `homepage`, `bugs.url`, `name` scope, or `author` to agentful maintainer values unless the project explicitly asks.
+- Keep `repository.type` as `"git"` when a `repository` object exists.
+- Do not infer repo owner from agentful package names/docs (`@itz4blitz/agentful`); derive owner from the current repository remote instead.
+- Prefer structured JSON edits (JSON path / `jq` / `npm pkg`) instead of broad text replace on `"type"` or `"url"`.
+
 ## Commands
 
 | Command | Description | When to Use |
@@ -199,6 +208,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
@@ -259,7 +295,6 @@ Agentful uses Claude Code hooks for automation, protection, and intelligent cont
   - ✅ `.claude/skills/*/SKILL.md` - Skill documentation
   - ✅ `.claude/product/**/*.md` - Product specifications
   - ✅ `template/**/*.md` - Template files
-  - ✅ `examples/**/*.md` - Example documentation
 - **Allowed if parent directory exists**:
   - 📁 `docs/*.md`, `docs/pages/*.mdx` - Requires `docs/` directory
   - 📁 `documentation/*.md` - Requires `documentation/` directory

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

@@ -16,7 +16,6 @@
  * - .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

package/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.7.0"
+  "version": "1.8.1"
 }