@itz4blitz/agentful 0.1.11 → 0.2.0

package/README.md

@@ -1,13 +1,13 @@
 # agentful
 
-Autonomous product development framework for Claude Code.
+Human-in-the-loop development framework for Claude Code.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40itz4blitz%2Fagentful.svg)](https://www.npmjs.com/package/@itz4blitz/agentful)
 
 ## Overview
 
-agentful is a Claude Code configuration that provides structured autonomous development through specialized AI agents. It coordinates multiple agents to implement features, write tests, and validate code quality according to a defined product specification.
+agentful is a Claude Code configuration that provides structured development through specialized AI agents. It coordinates multiple agents to implement features, write tests, and validate code quality according to a defined product specification, with human checkpoints for key decisions.
 
 ## Installation
 
@@ -53,7 +53,7 @@ Create your specification manually:
 claude  # Start Claude Code
 ```
 
-Then use the `/agentful-start` command to begin autonomous development.
+Then use the `/agentful-start` command to begin structured development.
 
 #### New Projects (No Existing Code)
 
@@ -135,7 +135,7 @@ Code changes are validated against:
 
 ### State Tracking
 
-Runtime state is stored in `.agentful/`:
+Runtime state is stored in `.agentful/` (gitignored, managed by npm package):
 
 - `state.json` - Current task and phase
 - `completion.json` - Feature completion status
@@ -144,13 +144,28 @@ Runtime state is stored in `.agentful/`:
   - New projects: Starts with declared stack (`confidence: 0.4`)
   - Existing projects: Detected from code (`confidence: 0.8-1.0`)
   - Re-analyzed after first implementation in new projects
+- `last-validation.json` - Latest test/lint results
+- `conversation-history.json` - Session tracking
+
+User configuration is stored in `.claude/` (version controlled):
+
+- `agents/` - Agent definitions (core + custom + ephemeral)
+- `commands/` - Slash commands
+- `product/` - Product specifications
+  - `index.md` - Main product spec (user editable)
+  - `product-analysis.json` - Readiness analysis (generated by `/agentful-product`)
+  - `domains/` - Optional hierarchical structure
+- `skills/` - Reusable skill modules
+- `settings.json` - Project configuration
+
+**See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed explanation of file organization.**
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
 | `/agentful-product` | Smart product planning: create, analyze, and refine requirements |
-| `/agentful-start` | Start or resume autonomous development |
+| `/agentful-start` | Start or resume structured development |
 | `/agentful-status` | Display progress and current state |
 | `/agentful-validate` | Run all quality checks |
 | `/agentful-decide` | Answer pending decisions |
@@ -188,11 +203,13 @@ your-project/
 │   ├── commands/                   # Slash commands
 │   ├── skills/                     # Reusable skills
 │   └── settings.json               # Configuration
-├── .agentful/                      # Runtime state
+├── .agentful/                      # Runtime state (gitignored)
 │   ├── state.json
 │   ├── completion.json
 │   ├── decisions.json
-│   └── architecture.json
+│   ├── architecture.json
+│   ├── last-validation.json
+│   └── conversation-history.json
 └── src/                            # Source code
 ```
 

package/bin/cli.js

@@ -2,7 +2,7 @@
 
 /**
  * agentful CLI
- * An opinionated autonomous product development kit for Claude Code
+ * An opinionated human-in-the-loop product development kit for Claude Code
  */
 
 import fs from 'fs';
@@ -74,9 +74,9 @@ function showHelp() {
   console.log(`     ${colors.dim}(Detection based on: # of domains, frameworks, monorepo status)${colors.reset}`);
   console.log(`  2. ${colors.bright}Edit your product specification${colors.reset}`);
   console.log(`  3. Run ${colors.bright}claude${colors.reset} to start Claude Code`);
-  console.log(`  4. Type ${colors.bright}/agentful${colors.reset} for natural conversation or ${colors.bright}/agentful-start${colors.reset} for autonomous development`);
+  console.log(`  4. Type ${colors.bright}/agentful${colors.reset} for natural conversation or ${colors.bright}/agentful-start${colors.reset} for structured development`);
   console.log('');
-  console.log('FOR 24/7 DEVELOPMENT:');
+  console.log('FOR EXTENDED DEVELOPMENT SESSIONS:');
   console.log(`  ${colors.cyan}/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"${colors.reset}`);
   console.log('');
 }
@@ -442,7 +442,7 @@ ${analysis && analysis.domains.length > 0 ? analysis.domains.map((d, i) => `${i
   }
 
   console.log(`  2. ${colors.cyan}Run: claude${colors.reset}`);
-  console.log(`  3. ${colors.cyan}Type: /agentful${colors.reset} (natural) or ${colors.cyan}/agentful-start${colors.reset} (autonomous)`);
+  console.log(`  3. ${colors.cyan}Type: /agentful${colors.reset} (natural) or ${colors.cyan}/agentful-start${colors.reset} (structured)`);
   console.log('');
 
   if (usingHierarchical) {
@@ -453,7 +453,7 @@ ${analysis && analysis.domains.length > 0 ? analysis.domains.map((d, i) => `${i
     console.log('');
   }
 
-  log(colors.dim, 'For autonomous 24/7 development:');
+  log(colors.dim, 'For extended development sessions with fewer interruptions:');
   log(colors.cyan, `  /ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"`);
   console.log('');
 }

package/bin/hooks/README.md

@@ -0,0 +1,120 @@
+# Agentful Hooks
+
+This directory contains hook scripts that enhance Claude Code's behavior with agentful.
+
+## Scripts
+
+### `analyze-trigger.sh`
+
+**Purpose**: Suggests running `/agentful-analyze` when key configuration files change.
+
+**Triggers on**:
+- `package.json` (root only, excludes node_modules)
+- `architecture.json`
+- `tsconfig.json` / `jsconfig.json`
+- Build configs: `vite.config.*`, `webpack.config.*`, `rollup.config.*`, `next.config.*`
+- Environment templates: `.env.example`, `.env.sample`
+- Docker files: `docker-compose.yml`, `Dockerfile`
+
+**Behavior**:
+- Runs on PostToolUse for Write/Edit operations
+- Exits silently for non-matching files
+- Outputs suggestion message for matching files
+- Timeout: 3 seconds
+
+**Usage**: Automatically triggered by hooks. Can be tested manually:
+```bash
+FILE="package.json" bash bin/hooks/analyze-trigger.sh
+```
+
+### `health-check.sh`
+
+**Purpose**: Performs lightweight startup checks for agentful configuration.
+
+**Checks**:
+- `.agentful/` directory exists
+- `architecture.json` exists
+- Project has a package manager config (package.json, pyproject.toml, go.mod, or Cargo.toml)
+
+**Behavior**:
+- Runs on SessionStart
+- Outputs "Agentful ready." if all checks pass
+- Lists warnings for missing components
+- Always exits with code 0 (non-blocking)
+- Timeout: 5 seconds
+
+**Usage**: Automatically triggered on session start. Can be tested manually:
+```bash
+bash bin/hooks/health-check.sh
+```
+
+## Hook Configuration
+
+Hooks are configured in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash bin/hooks/health-check.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash bin/hooks/analyze-trigger.sh",
+            "timeout": 3
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Design Principles
+
+1. **Fast**: All hooks complete in under 5 seconds
+2. **Non-blocking**: Always exit with code 0 to avoid interrupting workflow
+3. **Helpful**: Provide actionable suggestions, not errors
+4. **Smart**: Only trigger on relevant files (exclude node_modules, etc.)
+5. **Lightweight**: No heavy analysis, just quick checks and suggestions
+
+## Adding New Hooks
+
+When adding new hooks:
+
+1. Keep execution time under 10 seconds
+2. Use `set -e` and proper error handling
+3. Exit with code 0 for success (non-blocking)
+4. Output clear, actionable messages
+5. Test edge cases (missing files, node_modules, etc.)
+6. Document the hook in this README
+7. Update `.claude/settings.json` with appropriate timeout
+
+## Testing
+
+Test hooks manually before committing:
+
+```bash
+# Test analyze-trigger with different files
+FILE="package.json" bash bin/hooks/analyze-trigger.sh
+FILE="node_modules/pkg/package.json" bash bin/hooks/analyze-trigger.sh
+FILE="src/index.ts" bash bin/hooks/analyze-trigger.sh
+
+# Test health-check
+bash bin/hooks/health-check.sh
+
+# Validate JSON
+jq empty .claude/settings.json
+```

package/bin/hooks/analyze-trigger.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# analyze-trigger.sh
+# Checks if changed files warrant an /agentful-analyze suggestion
+
+FILE="${FILE:-}"
+
+# Exit silently if no file specified
+if [ -z "$FILE" ]; then
+  exit 0
+fi
+
+# Normalize the file path to get just the filename
+FILENAME=$(basename "$FILE")
+FILEPATH="$FILE"
+
+# Check for key files that should trigger analysis suggestions
+case "$FILENAME" in
+  package.json)
+    # Only trigger for root package.json, not node_modules
+    if echo "$FILEPATH" | grep -q "node_modules"; then
+      exit 0
+    fi
+    echo "Dependencies changed in package.json. Consider running /agentful-analyze to update architecture understanding."
+    exit 0
+    ;;
+
+  architecture.json)
+    echo "Architecture configuration updated. Run /agentful-analyze to refresh tech stack analysis."
+    exit 0
+    ;;
+
+  tsconfig.json|jsconfig.json)
+    echo "TypeScript/JavaScript configuration changed. Consider running /agentful-analyze to update build settings."
+    exit 0
+    ;;
+
+  vite.config.*|webpack.config.*|rollup.config.*|next.config.*)
+    echo "Build configuration changed. Consider running /agentful-analyze to update bundler settings."
+    exit 0
+    ;;
+
+  .env.example|.env.sample)
+    echo "Environment template changed. Consider running /agentful-analyze to update configuration understanding."
+    exit 0
+    ;;
+
+  docker-compose.yml|Dockerfile)
+    echo "Docker configuration changed. Consider running /agentful-analyze to update deployment setup."
+    exit 0
+    ;;
+
+  *)
+    # No suggestion needed for other files
+    exit 0
+    ;;
+esac

package/bin/hooks/health-check.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# health-check.sh
+# Lightweight startup health check for agentful
+
+# Exit early on any error
+set -e
+
+# Check if .agentful directory exists
+if [ ! -d ".agentful" ]; then
+  echo "Agentful not initialized. Run /agentful-start to set up."
+  exit 0
+fi
+
+# Check for critical files
+WARNINGS=()
+
+if [ ! -f ".agentful/architecture.json" ]; then
+  WARNINGS+=("Architecture config missing. Run /agentful-analyze to detect tech stack.")
+fi
+
+if [ ! -f "package.json" ] && [ ! -f "pyproject.toml" ] && [ ! -f "go.mod" ] && [ ! -f "Cargo.toml" ]; then
+  WARNINGS+=("No package manager config found. Project structure unclear.")
+fi
+
+# Output any warnings
+if [ ${#WARNINGS[@]} -gt 0 ]; then
+  echo "Agentful Health Check:"
+  for warning in "${WARNINGS[@]}"; do
+    echo "  - $warning"
+  done
+else
+  echo "Agentful ready."
+fi
+
+exit 0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "0.1.11",
-  "description": "Autonomous product development kit for Claude Code with smart product analysis and natural conversation",
+  "version": "0.2.0",
+  "description": "Human-in-the-loop development kit for Claude Code with smart product analysis and natural conversation",
   "type": "module",
   "bin": {
     "agentful": "bin/cli.js"
@@ -24,7 +24,7 @@
   ],
   "keywords": [
     "claude-code",
-    "autonomous",
+    "human-in-the-loop",
     "ai-development",
     "agent",
     "productivity"
@@ -36,17 +36,22 @@
     "url": "git+https://github.com/itz4blitz/agentful.git"
   },
   "homepage": "https://agentful.app",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "engines": {
     "node": ">=22.0.0"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/exec": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^11.0.1",
-    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/npm": "^13.1.3",
     "@semantic-release/release-notes-generator": "^14.0.1",
-    "semantic-release": "^24.2.0",
+    "semantic-release": "^25.0.2",
     "vocs": "^1.4.1"
   }
 }