@itz4blitz/agentful 1.2.0 → 1.3.0

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

@@ -9,7 +9,105 @@ This command initiates the structured product development loop with human checkp
 
 ## Startup Sequence
 
-### 0. State File Validation
+### 0. First-Run Detection
+
+Check if this is the user's first time running agentful:
+
+```javascript
+const isFirstRun = !exists('.agentful/state.json') &&
+                  !exists('.agentful/architecture.json');
+
+if (isFirstRun) {
+  const hasProductSpec = exists('.claude/product/index.md') &&
+                        Read('.claude/product/index.md').length > 200;
+
+  if (!hasProductSpec) {
+    // No product spec - guide user to setup
+    const response = AskUserQuestion({
+      question: `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Welcome to agentful!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This is your first time running agentful in this project.
+
+To get started, I need to understand what you're building.
+
+Would you like to:
+`,
+      options: [
+        'Use guided setup (/agentful-init) - 5 minutes',
+        'Manually edit .claude/product/index.md first',
+        'Skip setup and explore agentful commands'
+      ]
+    });
+
+    if (response.includes('guided setup')) {
+      console.log(`
+Launching guided setup...
+
+This will ask 7 quick questions to understand your product,
+then automatically generate specialized agents for your stack.
+`);
+      // User should run /agentful-init
+      // SlashCommand('/agentful-init');
+      return;
+    } else if (response.includes('Manually edit')) {
+      console.log(`
+Please edit .claude/product/index.md with:
+- Product description
+- Key features
+- Business domains
+- Priority levels
+
+Template: https://github.com/itz4blitz/agentful#product-spec
+
+When done, run /agentful-start again.
+`);
+      return;
+    } else {
+      // Skip setup - show help
+      console.log(`
+agentful commands:
+  /agentful-init     - Guided setup (recommended for first-time)
+  /agentful-product  - Analyze product requirements
+  /agentful-status   - Show progress
+  /agentful          - Quick reference
+
+Edit .claude/product/index.md when ready to start development.
+`);
+      return;
+    }
+  } else {
+    // Has product spec but no agents - generate them
+    console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   First Run Detected
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I found your product specification at .claude/product/index.md
+
+Before starting development, let me generate specialized agents
+for your tech stack and domains.
+
+This takes about 30-60 seconds...
+`);
+
+    // Auto-trigger /agentful-generate
+    // SlashCommand('/agentful-generate');
+
+    console.log(`
+After agent generation completes, run /agentful-start again
+to begin development.
+`);
+    return;
+  }
+}
+
+// Not first run - continue with normal startup
+```
+
+### 1. State File Validation
 
 Before processing any state files, validate their existence and structure. This prevents corrupted or missing state from causing failures.
 

package/template/.claude/product/EXAMPLES.md

@@ -18,7 +18,7 @@ agentful supports two product specification formats.
 
 ## Tech Stack
 
-- **Frontend**: Next.js 14, TypeScript, Tailwind
+- **Frontend**: Next.js 15, TypeScript, Tailwind
 - **Backend**: Node.js, Prisma, PostgreSQL
 - **Testing**: Vitest, Playwright
 
@@ -98,7 +98,7 @@ agentful supports two product specification formats.
 
 ## Tech Stack
 
-- **Frontend**: Next.js 14, TypeScript, Tailwind
+- **Frontend**: Next.js 15, TypeScript, Tailwind
 - **Backend**: Node.js, Prisma, PostgreSQL
 
 ## Domains

package/template/.claude/product/index.md

@@ -22,7 +22,7 @@ Example:
 ## Tech Stack
 
 ### Frontend
-- **Framework**: [Next.js 14 / React + Vite / Vue + Nuxt / SvelteKit]
+- **Framework**: [Next.js 15 / React + Vite / Vue + Nuxt / SvelteKit]
 - **Language**: [TypeScript / JavaScript]
 - **Styling**: [Tailwind CSS / CSS Modules / styled-components / shadcn/ui]
 - **State Management**: [Zustand / Context API / Redux / Jotai]

package/template/.claude/settings.json

@@ -30,6 +30,17 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node bin/hooks/product-spec-watcher.js",
+            "timeout": 3,
+            "description": "Watch for product spec changes and auto-trigger generation"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [
@@ -41,6 +52,17 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node bin/hooks/architect-drift-detector.js",
+            "timeout": 3,
+            "description": "Detect when architect needs to re-analyze project"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [

package/template/.claude/skills/research/SKILL.md

@@ -0,0 +1,432 @@
+---
+name: research
+description: Research best practices for tech stacks and product domains using Context7 or WebSearch
+---
+
+# Research Skill
+
+Enables agents to research current best practices, design patterns, and implementation approaches for technologies and product domains.
+
+## When to Use
+
+- **Tech Stack Analysis**: Learning current best practices for detected frameworks/languages
+- **Domain Patterns**: Understanding implementation approaches for specific business domains
+- **Agent Generation**: Informing specialized agent creation with research findings
+- **Architecture Decisions**: Comparing approaches before implementation
+- **Trend Analysis**: Understanding what's current vs deprecated
+
+## Available Research Methods
+
+### 1. Context7 MCP (Preferred)
+
+Context7 provides curated, high-quality technical documentation and best practices.
+
+**Advantages**:
+- ✅ Curated, accurate results
+- ✅ Up-to-date framework documentation
+- ✅ Language-specific patterns
+- ✅ Faster than web search
+- ✅ No noise or outdated content
+
+**Check Availability**:
+```javascript
+function hasContext7() {
+  // Check if Context7 MCP is connected
+  // Claude Code automatically exposes MCP tools
+  return typeof mcp__context7__search !== 'undefined';
+}
+```
+
+**Usage**:
+```javascript
+// Example: Research Next.js 15 patterns
+const results = await mcp__context7__search({
+  query: 'Next.js 15 app router best practices',
+  limit: 5
+});
+
+// Results include:
+// - Official documentation
+// - Verified patterns
+// - Current recommendations
+```
+
+### 2. WebSearch (Fallback)
+
+When Context7 is unavailable, use WebSearch for broader coverage.
+
+**Advantages**:
+- ✅ Always available
+- ✅ Broader coverage (blogs, forums, etc.)
+- ✅ Real-world examples
+- ✅ Community insights
+
+**Limitations**:
+- ⚠️ May include outdated content
+- ⚠️ Requires filtering and verification
+- ⚠️ More noise
+
+**Usage**:
+```javascript
+const results = await WebSearch({
+  query: 'Next.js 15 app router best practices 2026',
+  limit: 5
+});
+
+// Always include current year in query for freshness
+```
+
+## Research Workflow
+
+### Step 1: Determine Research Method
+
+```javascript
+const researchMethod = hasContext7() ? 'context7' : 'websearch';
+
+console.log(`Research method: ${researchMethod}`);
+```
+
+### Step 2: Formulate Queries
+
+Create specific, targeted queries:
+
+**Good queries**:
+- "Next.js 15 server components best practices"
+- "React 19 concurrent rendering patterns"
+- "PostgreSQL connection pooling with Prisma"
+- "Authentication implementation patterns 2026"
+
+**Bad queries**:
+- "Next.js" (too broad)
+- "How to code" (too generic)
+- "Best JavaScript framework" (subjective, not actionable)
+
+**Query Template**:
+```
+[Technology/Framework] + [Specific Topic] + [Year]
+```
+
+### Step 3: Execute Research
+
+```javascript
+async function researchTopic(topic, context = {}) {
+  const queries = generateQueries(topic, context);
+  const findings = [];
+
+  for (const query of queries) {
+    let result;
+
+    if (hasContext7()) {
+      result = await mcp__context7__search({
+        query,
+        limit: 3
+      });
+    } else {
+      result = await WebSearch({
+        query: `${query} ${new Date().getFullYear()}`,
+        limit: 3
+      });
+    }
+
+    findings.push({
+      query,
+      results: result,
+      source: hasContext7() ? 'context7' : 'websearch'
+    });
+  }
+
+  return findings;
+}
+```
+
+### Step 4: Synthesize Findings
+
+Extract actionable insights from research results:
+
+```javascript
+function synthesizeResearch(findings, context) {
+  // Aggregate findings by category
+  const synthesis = {
+    techStackPatterns: {},
+    domainPatterns: {},
+    bestPractices: [],
+    commonPitfalls: [],
+    references: []
+  };
+
+  for (const finding of findings) {
+    // Extract tech stack patterns
+    if (finding.query.includes(context.techStack.framework)) {
+      synthesis.techStackPatterns[context.techStack.framework] = extractPatterns(finding.results);
+    }
+
+    // Extract domain-specific patterns
+    for (const domain of context.domains || []) {
+      if (finding.query.includes(domain)) {
+        synthesis.domainPatterns[domain] = extractPatterns(finding.results);
+      }
+    }
+
+    // Collect best practices
+    synthesis.bestPractices.push(...extractBestPractices(finding.results));
+
+    // Collect common pitfalls
+    synthesis.commonPitfalls.push(...extractPitfalls(finding.results));
+
+    // Store references
+    synthesis.references.push({
+      query: finding.query,
+      source: finding.source,
+      url: extractURL(finding.results)
+    });
+  }
+
+  // Deduplicate and rank
+  synthesis.bestPractices = deduplicateAndRank(synthesis.bestPractices);
+  synthesis.commonPitfalls = deduplicateAndRank(synthesis.commonPitfalls);
+
+  return synthesis;
+}
+```
+
+## Research Use Cases
+
+### Use Case 1: Tech Stack Research
+
+Research current best practices for detected technologies:
+
+```javascript
+// Called by /agentful-generate after tech stack detection
+const techStack = {
+  framework: 'Next.js',
+  version: '15.1.0',
+  language: 'TypeScript',
+  database: 'PostgreSQL',
+  orm: 'Prisma'
+};
+
+const queries = [
+  `${techStack.framework} ${techStack.version} best practices`,
+  `${techStack.framework} project structure patterns`,
+  `${techStack.orm} with ${techStack.database} optimization`,
+  `TypeScript configuration for ${techStack.framework}`
+];
+
+const findings = await researchTopic('tech-stack', { techStack, queries });
+const synthesis = synthesizeResearch(findings, { techStack });
+
+// Use synthesis to inform:
+// - Agent generation (what agents should know)
+// - Skill creation (patterns to document)
+// - Architecture decisions
+```
+
+### Use Case 2: Domain Research
+
+Research implementation patterns for product domains:
+
+```javascript
+// Called by /agentful-generate after domain discovery
+const product = {
+  type: 'task management app',
+  domains: ['authentication', 'tasks', 'collaboration']
+};
+
+const queries = [
+  `${product.type} architecture patterns`,
+  `authentication implementation best practices ${techStack.framework}`,
+  `task management data model design`,
+  `real-time collaboration implementation`
+];
+
+const findings = await researchTopic('domains', { product, queries });
+const synthesis = synthesizeResearch(findings, { domains: product.domains });
+
+// Use synthesis to inform:
+// - Domain agent specialization
+// - Database schema design
+// - API design patterns
+```
+
+### Use Case 3: Pre-Implementation Research
+
+Research before implementing a complex feature:
+
+```javascript
+// Called by orchestrator before delegating complex work
+const feature = {
+  name: 'Real-time notifications',
+  complexity: 'high',
+  technologies: ['WebSockets', 'Redis', 'React']
+};
+
+const queries = [
+  `WebSocket implementation ${techStack.framework}`,
+  `Redis pub/sub patterns for notifications`,
+  `React real-time updates best practices`,
+  `scaling WebSocket connections`
+];
+
+const findings = await researchTopic('feature', { feature, queries });
+const synthesis = synthesizeResearch(findings, { feature });
+
+// Share findings with specialist agent before implementation
+```
+
+## Quality Criteria
+
+When evaluating research findings:
+
+1. **Recency**: Prefer results from current year
+2. **Authority**: Official docs > verified blogs > forums
+3. **Specificity**: Specific patterns > general advice
+4. **Actionability**: Code examples > theory
+5. **Relevance**: Exact version match > general version
+
+## Integration Points
+
+### /agentful-generate
+
+Research is integrated into agent generation:
+
+```javascript
+// Step 3 of /agentful-generate workflow
+console.log('Researching best practices...');
+
+const research = await researchTopic('generation', {
+  techStack,
+  domains,
+  productType
+});
+
+const synthesis = synthesizeResearch(research, { techStack, domains });
+
+// Use synthesis when generating:
+// - Domain agent responsibilities
+// - Tech skill documentation
+// - Best practices sections
+```
+
+### Orchestrator
+
+Research can inform architectural decisions:
+
+```javascript
+// Before implementing complex features
+if (feature.complexity === 'high') {
+  console.log(`Researching implementation approaches for ${feature.name}...`);
+
+  const research = await researchTopic('feature-planning', {
+    feature,
+    techStack
+  });
+
+  const synthesis = synthesizeResearch(research, { feature });
+
+  // Present findings to user for decision
+  AskUserQuestion({
+    question: `
+Research findings for ${feature.name}:
+
+Recommended approach:
+${synthesis.bestPractices[0]}
+
+Alternatives:
+${synthesis.bestPractices.slice(1, 3).join('\n')}
+
+Which approach should we use?
+`,
+    options: synthesis.bestPractices.map(p => p.summary)
+  });
+}
+```
+
+## Example: Full Research Flow
+
+```javascript
+// 1. Detect tech stack
+const techStack = detectTechStack();
+
+// 2. Read product requirements
+const product = Read('.claude/product/index.md');
+const productType = extractProductType(product);
+const domains = extractDomains(product);
+
+// 3. Research
+console.log('Researching best practices...');
+
+const method = hasContext7() ? 'Context7' : 'WebSearch';
+console.log(`Method: ${method}`);
+
+// Tech stack research
+const techResearch = await researchTopic('tech-stack', {
+  techStack,
+  queries: [
+    `${techStack.framework} ${techStack.version} best practices`,
+    `${techStack.framework} project structure`,
+    `${techStack.orm} patterns`
+  ]
+});
+
+// Domain research
+const domainResearch = await researchTopic('domains', {
+  domains,
+  queries: domains.map(d => `${d} domain implementation patterns`)
+});
+
+// Product type research
+const productResearch = await researchTopic('product-type', {
+  productType,
+  queries: [`${productType} application architecture`]
+});
+
+// 4. Synthesize
+const synthesis = synthesizeResearch(
+  [...techResearch, ...domainResearch, ...productResearch],
+  { techStack, domains, productType }
+);
+
+// 5. Apply findings
+console.log('Research complete. Applying findings to agent generation...');
+
+// Generate agents with research-informed patterns
+generateAgentsWithResearch(synthesis);
+```
+
+## Error Handling
+
+```javascript
+async function safeResearch(query, context = {}) {
+  try {
+    if (hasContext7()) {
+      return await mcp__context7__search({ query, limit: 3 });
+    } else {
+      return await WebSearch({ query: `${query} ${new Date().getFullYear()}`, limit: 3 });
+    }
+  } catch (error) {
+    console.warn(`Research failed for query "${query}": ${error.message}`);
+    return {
+      query,
+      results: [],
+      error: error.message,
+      fallback: true
+    };
+  }
+}
+```
+
+## Best Practices
+
+1. **Always check Context7 availability first** - More accurate results
+2. **Include year in WebSearch queries** - Ensure freshness
+3. **Limit queries to 5-10** - Balance coverage vs speed
+4. **Synthesize findings** - Don't just dump raw results
+5. **Cache research results** - Avoid redundant queries
+6. **Provide references** - Link to source material
+7. **Time-box research** - Don't spend hours researching
+
+## References
+
+- Context7 MCP Documentation
+- Claude Code WebSearch API
+- Research methodology best practices

package/template/CLAUDE.md

@@ -26,7 +26,7 @@ npx @itz4blitz/agentful presets
 
 1. Edit `.claude/product/index.md` to define your product requirements
 2. Run: `claude`
-3. Type: `/agentful-start`
+3. Type: `/agentful-generate`
 
 For extended sessions:
 ```bash
@@ -68,9 +68,6 @@ claude --dangerously-skip-permissions
 **Want to add features?**
 → Edit `.claude/product/index.md`, then run `/agentful-start` (picks up changes automatically)
 
-**Need remote execution?**
-→ Run `agentful serve` on a VPS, then use `agentful remote` CLI to trigger agents from anywhere
-
 ## File Structure
 
 **Product Specification** (you edit these):
@@ -81,7 +78,9 @@ claude --dangerously-skip-permissions
 - `.agentful/state.json` - Current work phase and progress
 - `.agentful/completion.json` - Feature completion % and quality gates
 - `.agentful/decisions.json` - Pending and resolved decisions
-- `.agentful/last-validation.json` - Most recent validation report
+- `.agentful/conversation-state.json` - Natural language conversation context
+- `.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
 
 **Configuration** (auto-generated, customizable):
@@ -129,7 +128,7 @@ The `reviewer` agent runs these checks automatically. The `fixer` agent resolves
 → Edit completion % in `.agentful/completion.json` for specific feature, then run `/agentful-start`.
 
 **"Want to work on multiple features in parallel?"**
-→ Use git worktrees for branch-based parallel development, or `agentful serve` for coordinated remote execution.
+→ Use git worktrees for branch-based parallel development.
 
 ## Getting Help