@itz4blitz/agentful 0.1.11 → 0.2.1

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
 
 ```

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';
@@ -11,6 +11,7 @@ import { fileURLToPath } from 'url';
 import { analyzeProject, exportToArchitectureJson } from '../lib/project-analyzer.js';
 import AgentGenerator from '../lib/agent-generator.js';
 import DomainStructureGenerator from '../lib/domain-structure-generator.js';
+import { detectTechStack } from '../lib/tech-stack-detector.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -74,9 +75,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 +443,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 +454,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('');
 }
@@ -582,87 +583,13 @@ function showStatus() {
   console.log('');
 }
 
-function detectTechStack() {
-  const targetDir = process.cwd();
-  const detected = {
-    language: null,
-    framework: null,
-    dependencies: [],
-    devDependencies: []
-  };
-
-  // Check for package.json (Node.js/JavaScript/TypeScript)
-  const packageJsonPath = path.join(targetDir, 'package.json');
-  if (fs.existsSync(packageJsonPath)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-      detected.dependencies = Object.keys(pkg.dependencies || {});
-      detected.devDependencies = Object.keys(pkg.devDependencies || {});
-      detected.language = pkg.type === 'module' ? 'TypeScript/ESM' : 'JavaScript/TypeScript';
-
-      // Detect framework
-      if (detected.dependencies.includes('next')) {
-        detected.framework = 'Next.js';
-      } else if (detected.dependencies.includes('react')) {
-        detected.framework = 'React';
-      } else if (detected.dependencies.includes('vue')) {
-        detected.framework = 'Vue';
-      } else if (detected.dependencies.includes('express')) {
-        detected.framework = 'Express';
-      } else if (detected.dependencies.includes('nestjs')) {
-        detected.framework = 'NestJS';
-      }
-    } catch (err) {
-      log(colors.yellow, '⚠️  Could not parse package.json');
-    }
-  }
-
-  // Check for requirements.txt or pyproject.toml (Python)
-  const requirementsPath = path.join(targetDir, 'requirements.txt');
-  const pyprojectPath = path.join(targetDir, 'pyproject.toml');
-  if (fs.existsSync(requirementsPath) || fs.existsSync(pyprojectPath)) {
-    detected.language = 'Python';
-    const requirements = fs.existsSync(requirementsPath)
-      ? fs.readFileSync(requirementsPath, 'utf-8')
-      : '';
-    if (requirements.includes('django')) detected.framework = 'Django';
-    else if (requirements.includes('flask')) detected.framework = 'Flask';
-    else if (requirements.includes('fastapi')) detected.framework = 'FastAPI';
-  }
-
-  // Check for go.mod (Go)
-  if (fs.existsSync(path.join(targetDir, 'go.mod'))) {
-    detected.language = 'Go';
-    detected.framework = 'Standard Library';
-  }
-
-  // Check for Cargo.toml (Rust)
-  if (fs.existsSync(path.join(targetDir, 'Cargo.toml'))) {
-    detected.language = 'Rust';
-  }
-
-  // Check for .csproj or .fsproj (C#/.NET)
-  const csprojFiles = fs.readdirSync(targetDir).filter(f => f.endsWith('.csproj'));
-  if (csprojFiles.length > 0) {
-    detected.language = 'C#';
-    detected.framework = 'ASP.NET';
-  }
-
-  // Check for pom.xml (Java)
-  if (fs.existsSync(path.join(targetDir, 'pom.xml'))) {
-    detected.language = 'Java';
-    detected.framework = 'Maven';
-  }
-
-  return detected;
-}
-
 function generateAgentPrompt(stack) {
   let prompt = `# Tech Stack Analysis\n\n`;
   prompt += `**Language**: ${stack.language || 'Unknown'}\n`;
-  prompt += `**Framework**: ${stack.framework || 'None'}\n\n`;
+  const primaryFramework = stack.frameworks && stack.frameworks.length > 0 ? stack.frameworks[0] : null;
+  prompt += `**Framework**: ${primaryFramework || 'None'}\n\n`;
 
-  if (stack.dependencies.length > 0) {
+  if (stack.dependencies && stack.dependencies.length > 0) {
     prompt += `**Key Dependencies**:\n`;
     stack.dependencies.slice(0, 10).forEach(dep => {
       prompt += `- ${dep}\n`;
@@ -724,11 +651,11 @@ async function generateAgents() {
     process.exit(1);
   }
 
-  // Detect tech stack
+  // Detect tech stack using library function
   log(colors.dim, 'Analyzing tech stack...');
-  const stack = detectTechStack();
+  const stack = await detectTechStack(process.cwd());
 
-  if (!stack.language) {
+  if (!stack.language || stack.language === 'unknown') {
     log(colors.yellow, '⚠️  Could not detect language/framework');
     log(colors.dim, 'Supported: Node.js, Python, Go, Rust, C#, Java');
     console.log('');
@@ -739,7 +666,8 @@ async function generateAgents() {
     return;
   }
 
-  log(colors.green, `✓ Detected: ${stack.language} ${stack.framework ? `(${stack.framework})` : ''}`);
+  const primaryFramework = stack.frameworks.length > 0 ? stack.frameworks[0] : null;
+  log(colors.green, `✓ Detected: ${stack.language} ${primaryFramework ? `(${primaryFramework})` : ''}`);
   log(colors.dim, `   Dependencies: ${stack.dependencies.length} packages`);
 
   // Update architecture.json
@@ -762,7 +690,7 @@ async function generateAgents() {
 
   log(colors.bright, 'Detected Stack:');
   if (stack.language) log(colors.cyan, `  Language:    ${stack.language}`);
-  if (stack.framework) log(colors.cyan, `  Framework:   ${stack.framework}`);
+  if (primaryFramework) log(colors.cyan, `  Framework:   ${primaryFramework}`);
   if (stack.dependencies.length > 0) {
     log(colors.cyan, `  Dependencies: ${stack.dependencies.length} packages`);
   }