@itz4blitz/agentful 0.1.10 → 0.2.0

package/.claude/commands/agentful.md

@@ -1,11 +1,220 @@
 ---
 name: agentful
-description: Quick reference for agentful autonomous development kit
+description: Natural language interface for agentful human-in-the-loop development. Processes user intent and routes to appropriate handlers.
 ---
 
 # agentful
 
-Autonomous product development with Claude Code.
+Natural language interface for human-in-the-loop product development with Claude Code.
+
+## Implementation
+
+When this command is invoked:
+
+1. **Check if user provided input**: If arguments are provided, this is a natural language request
+2. **If NO input**: Show the Quick Reference section below
+3. **If input provided**: Use the Task tool to delegate to the conversation skill
+
+```bash
+# User runs: /agentful build authentication
+# You should execute:
+Task("conversation", "User said: 'build authentication'. Process this using the conversation skill workflow.")
+```
+
+The conversation skill will:
+- Load conversation state and history
+- Classify intent and extract entities
+- Detect ambiguity and ask clarifying questions if needed
+- Route to appropriate handler (orchestrator, status, validate, etc.)
+- Update conversation state and history
+
+## Command Behavior
+
+### Without Arguments
+
+```bash
+/agentful
+```
+
+Shows quick reference and available commands.
+
+### With Natural Language Input
+
+```bash
+/agentful <your request>
+```
+
+**Examples:**
+- `/agentful build the authentication system`
+- `/agentful fix the memory leak in checkout`
+- `/agentful what's the status?`
+- `/agentful validate the tests`
+
+This invokes the **conversation skill** which:
+1. Classifies your intent
+2. Resolves references (pronouns like "it", "that")
+3. Detects ambiguity and asks clarifying questions
+4. Routes to appropriate handler (orchestrator, status, validate, etc.)
+
+### Processing Flow
+
+When user provides natural language input:
+
+```typescript
+// 1. Load conversation state and history
+const state = load_conversation_state('.agentful/conversation-state.json');
+const history = read_conversation_history('.agentful/conversation-history.json');
+const productSpec = load_product_spec('.claude/product/');
+
+// 2. Check for context loss (>24h gaps)
+const contextRecovery = detect_context_loss(history.messages, state);
+if (contextRecovery.is_stale) {
+  return {
+    message: contextRecovery.message,
+    confirmation: contextRecovery.suggested_confirmation
+  };
+}
+
+// 3. Detect mind changes ("actually", "wait", "never mind")
+const mindChange = detect_mind_change(userMessage, state);
+if (mindChange.detected && mindChange.reset_context) {
+  reset_conversation_context(state);
+}
+
+// 4. Resolve references ("it", "that", "this" → actual feature names)
+const resolved = resolve_references(userMessage, history.messages, state);
+
+// 5. Classify intent
+const intent = classify_intent(resolved.resolved, history.messages, productSpec);
+// Possible intents: feature_request, bug_report, question, status_update,
+//                   clarification, approval, rejection, pause, continue
+
+// 6. Extract entities (features, domains, subtasks)
+const entities = extract_feature_mention(resolved.resolved, productSpec);
+
+// 7. Detect ambiguity
+const ambiguity = detect_ambiguity(resolved.resolved);
+if (ambiguity.is_ambiguous && ambiguity.confidence > 0.6) {
+  const clarification = suggest_clarification(resolved.resolved, productSpec);
+  return {
+    message: clarification.primary_question,
+    suggestions: clarification.suggested_responses
+  };
+}
+
+// 8. Route to appropriate handler
+const routing = route_to_handler(intent, entities);
+switch (routing.handler) {
+  case 'orchestrator':
+    Task('orchestrator', routing.context);
+    break;
+  case 'status':
+    Task('product-tracking', 'show_status');
+    break;
+  case 'validate':
+    Task('validation', 'run_quality_gates');
+    break;
+  case 'decide':
+    Task('decision-handler', 'list_pending_decisions');
+    break;
+  case 'product':
+    Task('product-planning', routing.context);
+    break;
+  default:
+    // Handle inline with conversation skill
+    return generate_response(intent, entities, state);
+}
+
+// 9. Add to conversation history
+add_message_to_history({
+  role: 'user',
+  content: userMessage,
+  intent: intent.intent,
+  entities: entities,
+  references_resolved: resolved.references
+});
+
+// 10. Update conversation state
+update_conversation_state(state, routing.result);
+```
+
+### Intent to Handler Mapping
+
+| Intent | Handler | Notes |
+|--------|---------|-------|
+| `feature_request` | orchestrator | Delegates to FEATURE_DEVELOPMENT workflow |
+| `bug_report` | orchestrator | Delegates to BUGFIX workflow |
+| `status_update` | product-tracking | Shows completion percentage and current work |
+| `validation` | validation skill | Runs quality gates |
+| `decision` | decision handler | Lists/resolves pending decisions |
+| `question` | inline | Answers using conversation history |
+| `clarification` | inline | Provides more detail on previous response |
+| `approval` | orchestrator | Continues current work |
+| `rejection` | orchestrator | Stops current work |
+| `pause` | state update | Marks work as paused |
+| `continue` | orchestrator | Resumes paused work |
+
+### Example Scenarios
+
+**Scenario 1: Clear Feature Request**
+```
+User: /agentful build the authentication system
+→ Intent: feature_request (confidence: 0.9)
+→ Entities: feature "authentication system"
+→ Route: orchestrator (FEATURE_DEVELOPMENT workflow)
+→ No ambiguity, proceed immediately
+```
+
+**Scenario 2: Ambiguous Reference**
+```
+User: /agentful fix it
+→ Intent: bug_report (confidence: 0.7)
+→ Entities: none (pronoun "it" without referent)
+→ Ambiguity: HIGH (pronoun_without_antecedent)
+→ Response: "I want to make sure I understand correctly. What specifically would you like me to fix?"
+```
+
+**Scenario 3: Reference Resolution**
+```
+User: /agentful update it to use OAuth
+Context: Currently working on "login feature"
+→ Resolve: "it" → "login feature"
+→ Intent: feature_request (confidence: 0.85)
+→ Entities: feature "login", action "update to use OAuth"
+→ Route: orchestrator (FEATURE_DEVELOPMENT workflow)
+```
+
+**Scenario 4: Status Check**
+```
+User: /agentful what's the status?
+→ Intent: status_update (confidence: 0.95)
+→ Route: product-tracking skill
+→ Shows completion percentage, current work, blocked items
+```
+
+**Scenario 5: Mind Change**
+```
+User: /agentful actually never mind, let's do the dashboard instead
+→ Mind change detected: HIGH confidence
+→ Reset context: clear current feature
+→ Intent: feature_request (confidence: 0.9)
+→ Entities: feature "dashboard"
+→ Route: orchestrator (FEATURE_DEVELOPMENT workflow)
+```
+
+**Scenario 6: Context Loss**
+```
+User: /agentful continue with that
+Last message: 48 hours ago
+→ Context loss detected: STALE
+→ Response: "It's been 48 hours since our last conversation. We were working on the login feature. Would you like to continue with that, or would you prefer to start something new?"
+```
+
+---
+
+## Quick Reference
+
+Human-in-the-loop product development with Claude Code.
 
 ## What It Does
 
@@ -13,7 +222,7 @@ agentful transforms product specifications into working software by:
 
 1. **Understanding your stack** - Auto-detects languages, frameworks, patterns
 2. **Planning the work** - Organizes features into domains and priorities
-3. **Building autonomously** - Specialized agents implement, test, validate
+3. **Building with guidance** - Specialized agents implement, test, validate with human checkpoints
 4. **Ensuring quality** - Automatic code review, testing, security checks
 5. **Tracking progress** - Real-time completion metrics and state
 
@@ -25,7 +234,7 @@ agentful transforms product specifications into working software by:
 # Install in your project
 npx @itz4blitz/agentful init
 
-# Start autonomous development
+# Start structured development
 /agentful-start
 
 # Monitor progress
@@ -36,7 +245,7 @@ npx @itz4blitz/agentful init
 
 | Command | What It Does |
 |---------|--------------|
-| `/agentful-start` | Start autonomous development loop |
+| `/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 |
@@ -250,15 +459,15 @@ When agentful needs input:
 
 | Type | Trigger | Workflow |
 |------|---------|----------|
-| **Feature** | "Build X", "Add Y feature" | Autonomous loop until complete |
+| **Feature** | "Build X", "Add Y feature" | Iterative loop with human checkpoints until complete |
 | **Bugfix** | "Fix X bug", "Y is broken" | Quick fix → test → validate → stop |
 | **Enhancement** | "Add X to Y", "Enhance Z" | Enhance → test → validate → stop |
 | **Refactor** | "Refactor X", "Improve Y code" | Refactor → test → validate → stop |
 | **Maintenance** | "Update deps", "Security scan" | Update → test → validate → stop |
 
-## Continuous Development
+## Extended Development Sessions
 
-For 24/7 autonomous development, use the **Ralph Wiggum plugin** (requires separate installation):
+For longer development sessions with fewer interruptions, use the **Ralph Wiggum plugin** (requires separate installation):
 
 ```bash
 /ralph-loop "/agentful-start" \
@@ -268,10 +477,10 @@ For 24/7 autonomous development, use the **Ralph Wiggum plugin** (requires separ
 
 > **Note**: `/ralph-loop` is an external plugin command from the Ralph Wiggum plugin. Install separately from the Claude Code plugin registry.
 
-Stops when:
+Pauses when:
+- Human decisions are needed
 - All features complete (100%)
-- Decision needed (pauses for input)
-- Quality gates fail (pauses for review)
+- Quality gates fail (requires review)
 
 ## Best Practices
 
@@ -281,7 +490,7 @@ Stops when:
 - Group related features into domains (for complex projects)
 
 **2. Answer Decisions Promptly**
-- Decisions block the autonomous loop
+- Decisions block the development loop
 - Use `/agentful-decide` to resolve multiple at once
 
 **3. Review Commits**
@@ -319,6 +528,7 @@ It learns **your project's patterns** and generates agents that match your conve
 │  └─ Template creation                       │
 ├─────────────────────────────────────────────┤
 │  Slash Commands (Claude Code)               │
+│  ├─ /agentful-product (requirements)        │
 │  ├─ /agentful-start  (orchestrator)        │
 │  ├─ /agentful-status (progress)             │
 │  ├─ /agentful-validate (quality gates)      │
@@ -340,4 +550,4 @@ It learns **your project's patterns** and generates agents that match your conve
 - **Documentation**: https://agentful.app
 - **GitHub**: https://github.com/itz4blitz/agentful
 - **Issues**: https://github.com/itz4blitz/agentful/issues
-- **Version**: 0.1.7 (check updates: `npm outdated @itz4blitz/agentful`)
+- **Version**: 0.1.11 (check updates: `npm outdated @itz4blitz/agentful`)

package/.claude/settings.json

@@ -1,6 +1,18 @@
 {
   "includeCoAuthoredBy": false,
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash bin/hooks/health-check.sh",
+            "timeout": 5,
+            "description": "Quick agentful health check"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Write|Edit",
@@ -13,6 +25,17 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash bin/hooks/analyze-trigger.sh",
+            "timeout": 3,
+            "description": "Check if file changes warrant analysis"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [
@@ -37,7 +60,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -f .agentful/state.json ]; then jq -r '.current_phase // \"idle\"' .agentful/state.json 2>/dev/null || echo 'idle'; else echo 'idle'; fi"
+            "command": "if [ -f .agentful/state.json ]; then jq -r '.current_phase // \"idle\"' .agentful/state.json 2>/dev/null || echo 'idle'; else echo 'idle'; fi",
+            "description": "Track current agentful phase"
           }
         ]
       }

package/.claude/skills/conversation/SKILL.md

@@ -9,6 +9,26 @@ tools: Read, Write, Edit, Glob, Grep
 
 This skill provides natural language processing capabilities for understanding user intent, managing conversation context, resolving references, and maintaining conversation history.
 
+## When to Use
+
+This skill is invoked when:
+- User runs `/agentful <text>` with natural language input
+- Any command receives ambiguous or unclear input
+- Need to resolve pronouns or references from conversation history
+- Need to classify user intent before routing to handlers
+
+**Entry Point**: The `/agentful` command delegates to this skill for all natural language processing.
+
+## Responsibilities
+
+1. **Intent Classification** - Determine what the user wants (feature, bug fix, status, etc.)
+2. **Reference Resolution** - Resolve "it", "that", "this" to actual feature names
+3. **Entity Extraction** - Extract features, domains, subtasks mentioned
+4. **Ambiguity Detection** - Identify unclear requests and ask clarifying questions
+5. **Context Management** - Track conversation state, detect context loss
+6. **Routing** - Route to appropriate handler (orchestrator, status, validate, etc.)
+7. **History Tracking** - Maintain conversation history for context
+
 ## Core Functions
 
 ### 1. Intent Classification
@@ -796,6 +816,221 @@ function get_recent_context(
 }
 ```
 
+## Routing Logic
+
+### Route to Handler
+
+```typescript
+/**
+ * Determine which handler should process the classified intent
+ * @param intent - Classified intent from user message
+ * @param entities - Extracted entities (features, domains, etc.)
+ * @param state - Current conversation state
+ * @returns Routing decision with handler and context
+ */
+function route_to_handler(
+  intent: IntentClassification,
+  entities: FeatureMention,
+  state: ConversationState
+): RoutingDecision {
+  const intentName = intent.intent;
+
+  // Feature development or bug fixes → orchestrator
+  if (intentName === 'feature_request' || intentName === 'bug_report') {
+    return {
+      handler: 'orchestrator',
+      skill: null,
+      context: {
+        intent: intentName,
+        message: entities.feature_name
+          ? `User wants to ${intentName === 'feature_request' ? 'build' : 'fix'} ${entities.feature_name}`
+          : 'User has a request that needs classification',
+        feature_id: entities.feature_id,
+        domain_id: entities.domain_id,
+        work_type: intentName === 'feature_request' ? 'FEATURE_DEVELOPMENT' : 'BUGFIX'
+      }
+    };
+  }
+
+  // Status inquiries → product-tracking skill
+  if (intentName === 'status_update') {
+    return {
+      handler: 'product-tracking',
+      skill: 'product-tracking',
+      context: {
+        intent: intentName,
+        feature_filter: entities.feature_id || null,
+        domain_filter: entities.domain_id || null
+      }
+    };
+  }
+
+  // Validation requests → validation skill
+  if (/test|validate|check/i.test(intentName)) {
+    return {
+      handler: 'validation',
+      skill: 'validation',
+      context: {
+        intent: intentName,
+        scope: entities.feature_id ? 'feature' : 'all'
+      }
+    };
+  }
+
+  // Decision handling → decision-handler
+  if (intentName === 'decision' || /decide|choice|option/i.test(intentName)) {
+    return {
+      handler: 'decision-handler',
+      skill: null,
+      context: {
+        intent: intentName
+      }
+    };
+  }
+
+  // Product planning → product-planning skill
+  if (/plan|requirements|spec|analyze/i.test(intentName)) {
+    return {
+      handler: 'product-planning',
+      skill: 'product-planning',
+      context: {
+        intent: intentName
+      }
+    };
+  }
+
+  // Approval/continue → orchestrator (resume current work)
+  if (intentName === 'approval' || intentName === 'continue') {
+    return {
+      handler: 'orchestrator',
+      skill: null,
+      context: {
+        intent: 'continue',
+        message: 'User approved or wants to continue current work',
+        resume_feature: state.current_feature
+      }
+    };
+  }
+
+  // Rejection/stop → update state, don't delegate
+  if (intentName === 'rejection' || intentName === 'pause') {
+    return {
+      handler: 'inline',
+      skill: null,
+      context: {
+        intent: intentName,
+        action: 'pause_work'
+      }
+    };
+  }
+
+  // Questions/clarifications → handle inline
+  if (intentName === 'question' || intentName === 'clarification') {
+    return {
+      handler: 'inline',
+      skill: null,
+      context: {
+        intent: intentName,
+        answer_from: ['conversation_history', 'product_spec', 'completion_status']
+      }
+    };
+  }
+
+  // Default: handle inline or ask for clarification
+  return {
+    handler: 'inline',
+    skill: null,
+    context: {
+      intent: intentName,
+      needs_clarification: true
+    }
+  };
+}
+
+interface RoutingDecision {
+  handler: 'orchestrator' | 'product-tracking' | 'validation' | 'decision-handler' | 'product-planning' | 'inline';
+  skill: string | null; // Skill name for Task delegation
+  context: {
+    intent: string;
+    message?: string;
+    feature_id?: string;
+    domain_id?: string;
+    work_type?: string;
+    [key: string]: any;
+  };
+}
+```
+
+### Execute Routing
+
+```typescript
+/**
+ * Execute the routing decision
+ * @param routing - Routing decision from route_to_handler
+ * @param userMessage - Original user message
+ * @param resolved - Resolved message with references expanded
+ */
+function execute_routing(
+  routing: RoutingDecision,
+  userMessage: string,
+  resolved: ResolvedMessage
+): void {
+  switch (routing.handler) {
+    case 'orchestrator':
+      // Delegate to orchestrator agent
+      Task('orchestrator',
+        `${routing.context.message || userMessage}
+
+        Work Type: ${routing.context.work_type || 'FEATURE_DEVELOPMENT'}
+        ${routing.context.feature_id ? `Feature: ${routing.context.feature_id}` : ''}
+        ${routing.context.domain_id ? `Domain: ${routing.context.domain_id}` : ''}
+
+        Classify and execute appropriate workflow.`
+      );
+      break;
+
+    case 'product-tracking':
+      // Delegate to product-tracking skill
+      Task('product-tracking',
+        `Show status and progress.
+        ${routing.context.feature_filter ? `Filter: feature ${routing.context.feature_filter}` : ''}
+        ${routing.context.domain_filter ? `Filter: domain ${routing.context.domain_filter}` : ''}`
+      );
+      break;
+
+    case 'validation':
+      // Delegate to validation skill
+      Task('validation',
+        `Run quality gates.
+        Scope: ${routing.context.scope || 'all'}`
+      );
+      break;
+
+    case 'decision-handler':
+      // For now, show how to use /agentful-decide
+      return `You have pending decisions. Run \`/agentful-decide\` to review and resolve them.`;
+      break;
+
+    case 'product-planning':
+      // Delegate to product-planning skill
+      Task('product-planning', userMessage);
+      break;
+
+    case 'inline':
+      // Handle inline (no delegation needed)
+      if (routing.context.needs_clarification) {
+        return generate_clarification_response(userMessage, routing.context);
+      } else if (routing.context.action === 'pause_work') {
+        pause_current_work();
+        return 'Work paused. Run `/agentful` with your next request when ready to continue.';
+      } else if (routing.context.intent === 'question') {
+        return answer_question(userMessage, routing.context);
+      }
+      break;
+  }
+}
+```
+
 ## Integration with Orchestrator
 
 ### Delegation Interface
@@ -1037,9 +1272,9 @@ interface StaleContextResponse {
 // Complete conversation processing flow
 async function process_conversation(userMessage: string): Promise<ConversationResponse> {
   // 1. Load conversation state and history
-  const state = load_conversation_state();
-  const history = read_conversation_history();
-  const productSpec = load_product_spec();
+  const state = load_conversation_state('.agentful/conversation-state.json');
+  const history = read_conversation_history('.agentful/conversation-history.json');
+  const productSpec = load_product_spec('.claude/product/');
 
   // 2. Check for context loss
   const contextRecovery = detect_context_loss(history.messages, state);
@@ -1079,8 +1314,8 @@ async function process_conversation(userMessage: string): Promise<ConversationRe
     };
   }
 
-  // 8. Determine delegation
-  const delegation = determine_delegation(intent, entities);
+  // 8. Route to appropriate handler
+  const routing = route_to_handler(intent, entities, state);
 
   // 9. Add user message to history
   add_message_to_history({
@@ -1089,24 +1324,66 @@ async function process_conversation(userMessage: string): Promise<ConversationRe
     intent: intent.intent,
     entities: entities,
     references_resolved: resolved.references
-  });
-
-  // 10. Return delegation decision or response
-  if (delegation.should_delegate) {
-    return {
-      type: 'delegate',
-      target_skill: delegation.target_skill,
-      context: delegation.context
+  }, '.agentful/conversation-history.json');
+
+  // 10. Execute routing
+  execute_routing(routing, userMessage, resolved);
+
+  // 11. Update conversation state
+  state.last_message_time = new Date().toISOString();
+  state.message_count++;
+  if (entities.feature_id) {
+    state.current_feature = {
+      feature_id: entities.feature_id,
+      feature_name: entities.feature_name,
+      domain_id: entities.domain_id
     };
   }
+  save_conversation_state(state);
 
   return {
-    type: 'response',
-    message: generate_response(intent, entities, state)
+    type: 'routed',
+    handler: routing.handler,
+    context: routing.context
   };
 }
 ```
 
+### Complete Flow Diagram
+
+```
+User Input
+    ↓
+Load State & History
+    ↓
+Context Loss Check ──→ [STALE] ──→ Confirm & Resume
+    ↓ [FRESH]
+Mind Change Detection ──→ [DETECTED] ──→ Reset Context
+    ↓ [CONTINUE]
+Reference Resolution
+    ↓
+Intent Classification
+    ↓
+Entity Extraction
+    ↓
+Ambiguity Detection ──→ [AMBIGUOUS] ──→ Ask Clarifying Question
+    ↓ [CLEAR]
+Route to Handler
+    ↓
+    ├─→ [orchestrator] ──→ Task('orchestrator', context)
+    ├─→ [product-tracking] ──→ Task('product-tracking', context)
+    ├─→ [validation] ──→ Task('validation', context)
+    ├─→ [decision-handler] ──→ Show /agentful-decide
+    ├─→ [product-planning] ──→ Task('product-planning', context)
+    └─→ [inline] ──→ Generate Response Directly
+    ↓
+Add to History
+    ↓
+Update State
+    ↓
+Done
+```
+
 ## File Locations
 
 ```