@itz4blitz/agentful 0.1.0 → 0.1.4

package/lib/template-engine.js

@@ -0,0 +1,153 @@
+/**
+ * Template Engine
+ *
+ * Simple template engine for variable interpolation in agent templates.
+ * Supports nested objects, arrays, and conditional rendering.
+ */
+
+class TemplateEngine {
+  /**
+   * Render template with data
+   */
+  static render(template, data) {
+    let content = template;
+
+    // Handle arrays and objects with special formatting FIRST
+    content = this.formatComplexTypes(content, data);
+
+    // Replace simple variables: {{variable}}
+    content = this.replaceVariables(content, data);
+
+    // Add timestamp if needed
+    if (content.includes('{{generated_at}}')) {
+      content = content.replace(/\{\{generated_at\}\}/g, new Date().toISOString());
+    }
+
+    return content;
+  }
+
+  /**
+   * Replace simple variables
+   */
+  static replaceVariables(content, data) {
+    for (const [key, value] of Object.entries(data)) {
+      const placeholder = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+      content = content.replace(placeholder, this.formatValue(value));
+    }
+    return content;
+  }
+
+  /**
+   * Format complex types (arrays, objects)
+   */
+  static formatComplexTypes(content, data) {
+    // Handle code_samples first (before generic samples check)
+    if (data.codeSamples && Array.isArray(data.codeSamples)) {
+      const placeholder = new RegExp('\\{\\{code_samples\\}\\}', 'g');
+      const formatted = this.formatSamples(data.codeSamples);
+      content = content.replace(placeholder, formatted);
+    }
+
+    // Handle samples array
+    if (data.samples && Array.isArray(data.samples)) {
+      const placeholder = new RegExp('\\{\\{samples\\}\\}', 'g');
+      const formatted = this.formatSamples(data.samples);
+      content = content.replace(placeholder, formatted);
+    }
+    // Handle patterns array - format as bullet points
+    if (data.patterns && Array.isArray(data.patterns)) {
+      const placeholder = new RegExp('\\{\\{patterns\\}\\}', 'g');
+      const formatted = data.patterns
+        .map(p => {
+          if (typeof p === 'string') return `- ${p}`;
+          if (p.keyword && p.context) {
+            return `- **${p.keyword}**: Found in codebase`;
+          }
+          return JSON.stringify(p);
+        })
+        .join('\n');
+      content = content.replace(placeholder, formatted);
+    }
+
+    // Handle conventions array
+    if (data.conventions && Array.isArray(data.conventions)) {
+      const placeholder = new RegExp('\\{\\{conventions\\}\\}', 'g');
+      const formatted = data.conventions
+        .filter(c => c && c.trim())
+        .map(c => `- ${c}`)
+        .join('\n');
+      content = content.replace(placeholder, formatted || 'No specific conventions detected');
+    }
+
+    // Handle features array
+    if (data.features && Array.isArray(data.features)) {
+      const placeholder = new RegExp('\\{\\{features\\}\\}', 'g');
+      const formatted = data.features
+        .map(f => `- **${f.name}**: ${f.description || 'No description'}`)
+        .join('\n');
+      content = content.replace(placeholder, formatted || 'No features detected');
+    }
+
+    // Handle endpoints array
+    if (data.endpoints && Array.isArray(data.endpoints)) {
+      const placeholder = new RegExp('\\{\\{endpoints\\}\\}', 'g');
+      const formatted = data.endpoints
+        .map(e => `- \`${e.code || e}\``)
+        .join('\n');
+      content = content.replace(placeholder, formatted || 'No endpoints detected');
+    }
+
+    // Handle models array
+    if (data.models && Array.isArray(data.models)) {
+      const placeholder = new RegExp('\\{\\{models\\}\\}', 'g');
+      const formatted = data.models
+        .map(m => `- \`${m.code || m}\``)
+        .join('\n');
+      content = content.replace(placeholder, formatted || 'No models detected');
+    }
+
+    return content;
+  }
+
+  /**
+   * Format code samples for display
+   */
+  static formatSamples(samples) {
+    if (!samples || samples.length === 0) {
+      return 'No code samples available yet.';
+    }
+
+    return samples
+      .slice(0, 5) // Limit to 5 samples
+      .map(sample => {
+        if (typeof sample === 'string') return sample;
+
+        const path = sample.path || 'unknown';
+        const content = sample.content || '';
+
+        return `#### ${path}\n\`\`\`\n${content.substring(0, 800)}${content.length > 800 ? '\n...' : ''}\n\`\`\``;
+      })
+      .join('\n\n');
+  }
+
+  /**
+   * Format value for template
+   */
+  static formatValue(value) {
+    if (value === null || value === undefined) {
+      return '';
+    }
+
+    if (Array.isArray(value)) {
+      return value.join(', ');
+    }
+
+    if (typeof value === 'object') {
+      return JSON.stringify(value, null, 2);
+    }
+
+    return String(value);
+  }
+}
+
+export default TemplateEngine;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "0.1.0",
-  "description": "One-click autonomous product development kit for Claude Code (Alpha - Unstable)",
+  "version": "0.1.4",
+  "description": "Autonomous product development kit for Claude Code with smart product analysis and natural conversation",
   "type": "module",
   "bin": {
     "agentful": "./bin/cli.js"
@@ -10,12 +10,14 @@
     "init": "node bin/cli.js init",
     "release": "semantic-release",
     "release:dry-run": "semantic-release --dry-run",
+    "version": "node -e \"const pkg=require('./package.json'); const v=require('./version.json'); v.version=pkg.version; require('fs').writeFileSync('version.json', JSON.stringify(v, null, 2));\"",
     "docs:dev": "vocs dev",
     "docs:build": "vocs build",
     "docs:preview": "vocs preview"
   },
   "files": [
     "bin/",
+    "lib/",
     "template/",
     ".claude/"
   ],
@@ -26,17 +28,24 @@
     "agent",
     "productivity"
   ],
-  "author": "Agentful",
+  "author": "agentful",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/itz4blitz/agentful.git"
+    "url": "https://github.com/itz4blitz/agentful"
   },
   "homepage": "https://agentful.app",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "semantic-release": "^24.2.0",
     "vocs": "^1.4.1"
   }
 }

package/template/CLAUDE.md

@@ -1,14 +1,16 @@
-# Agentful Product Development
+# agentful Product Development
 
-This project uses **Agentful** for autonomous product development.
+This project uses **agentful** for autonomous product development.
 
 ## Quick Start
 
-1. Edit `PRODUCT.md` with your product requirements
+1. Edit your product specification:
+   - **Flat structure** (recommended for beginners): Edit `PRODUCT.md` at project root
+   - **Hierarchical structure** (for larger projects): Edit files in `.claude/product/`
 2. Run: `claude`
 3. Type: `/agentful-start`
 
-That's it. Agentful will begin autonomous development.
+That's it. agentful will begin autonomous development.
 
 ## For 24/7 Development
 
@@ -28,7 +30,7 @@ claude --dangerously-skip-permissions
 
 ## Agents
 
-Agentful uses specialized agents that work together:
+agentful uses specialized agents that work together:
 
 | Agent | Purpose |
 |-------|---------|
@@ -51,7 +53,21 @@ Progress is tracked in `.agentful/`:
 
 ## Product Specification
 
-Your product is defined in `PRODUCT.md`. This file contains:
+Your product is defined in one of two formats:
+
+### Flat Structure (Recommended for Beginners)
+
+- **Location**: `PRODUCT.md` at project root
+- **Format**: Single file with all features
+- **Best for**: Small projects, MVPs, quick prototypes
+
+### Hierarchical Structure (For Larger Projects)
+
+- **Location**: `.claude/product/` directory
+- **Format**: Multiple files organized by domain
+- **Best for**: Large projects, teams, complex products
+
+The system auto-detects which format you're using. Both formats contain:
 
 - Overview and goals
 - Tech stack decisions
@@ -59,11 +75,31 @@ Your product is defined in `PRODUCT.md`. This file contains:
 - Acceptance criteria
 - Architecture notes
 
+### Choosing the Right Structure
+
+**Start with flat structure if:**
+- You're new to agentful
+- Building an MVP or prototype
+- Project has less than 20 features
+- Working alone or in a small team
+
+**Use hierarchical structure if:**
+- Project has 20+ features across multiple domains
+- Multiple team members need to edit specs simultaneously
+- You need better organization for complex projects
+- Your PRODUCT.md file is getting too long (500+ lines)
+
+### Migrating Between Formats
+
+You can start with flat and migrate to hierarchical as your project grows. See the migration guide in your product specification file for detailed instructions.
+
+The system auto-detects format changes automatically - no configuration needed!
+
 ## How It Works
 
 ```mermaid
 flowchart LR
-    Start([🚀 Initialize<br/>npx agentful init]) --> Define[📝 Define Product<br/>Edit PRODUCT.md]
+    Start([🚀 Initialize<br/>npx @itz4blitz/agentful init]) --> Define[📝 Define Product<br/>Edit PRODUCT.md]
     Define --> Build[⚡ Start Building<br/>/agentful-start]
     Build --> Loop{🔄 24/7 Development Loop}
 
@@ -112,17 +148,17 @@ Code must pass all gates before completion:
 
 ## Decision Handling
 
-When Agentful needs your input:
+When agentful needs your input:
 
 1. Question is added to `decisions.json`
 2. Development continues on unblocked features
 3. Run `/agentful-decide` to answer
-4. Agentful resumes blocked work
+4. agentful resumes blocked work
 
 ## Tech Stack Auto-Detection
 
-Agentful automatically detects your tech stack from:
-- `PRODUCT.md` - Explicit tech stack section
+agentful automatically detects your tech stack from:
+- Product specification (`PRODUCT.md` or `.claude/product/index.md`) - Explicit tech stack section
 - `package.json` - Dependencies and frameworks
 - Existing code - File patterns and imports
 
@@ -133,16 +169,16 @@ It then generates specialized agents for your specific stack.
 ```
 You: /agentful-start
 
-Agentful: Detected Next.js + TypeScript + Prisma + Tailwind
+agentful: Detected Next.js + TypeScript + Prisma + Tailwind
          → Generated nextjs-agent, prisma-agent, tailwind-agent
 
-Agentful: Starting work on authentication (priority: CRITICAL)
+agentful: Starting work on authentication (priority: CRITICAL)
          → @backend implementing JWT service
          → @backend implementing login API route
          → @frontend creating login page
          → @tester writing auth tests
 
-Agentful: Running validation...
+agentful: Running validation...
          → TypeScript: ✅
          → Lint: ✅
          → Tests: ✅
@@ -150,7 +186,7 @@ Agentful: Running validation...
          → Dead code: ✅
          → Security: ✅
 
-Agentful: Authentication complete (100%)
+agentful: Authentication complete (100%)
          Next: User profile feature...
 
 [Continues 24/7 until complete]
@@ -166,10 +202,10 @@ All agents and commands can be customized in `.claude/`:
 
 ## Getting Help
 
-If Agentful gets stuck:
+If agentful gets stuck:
 
 1. Run `/agentful-status` to see current state
-2. Check `PRODUCT.md` for unclear requirements
+2. Check your product specification (`PRODUCT.md` or `.claude/product/`) for unclear requirements
 3. Run `/agentful-decide` if decisions are pending
 4. Run `/agentful-validate` to check for issues
 
@@ -177,9 +213,12 @@ If Agentful gets stuck:
 
 ```
 .your-project/
-├── PRODUCT.md              # Your product spec (you edit this)
+├── PRODUCT.md              # Your product spec - flat structure (you edit this)
 ├── CLAUDE.md               # This file
-├── .claude/                # Agentful configuration
+├── .claude/                # agentful configuration
+│   ├── product/            # Product spec - hierarchical structure (alternative)
+│   │   ├── index.md        # Product overview
+│   │   └── domains/        # Domain-specific specs
 │   ├── agents/             # Specialized agents
 │   ├── commands/           # Slash commands
 │   ├── skills/             # Domain skills
@@ -189,9 +228,11 @@ If Agentful gets stuck:
 │   ├── completion.json
 │   ├── decisions.json
 │   └── architecture.json
-└── src/                    # Your code (generated by Agentful)
+└── src/                    # Your code (generated by agentful)
 ```
 
+**Note**: You can use either `PRODUCT.md` (flat) or `.claude/product/` (hierarchical). agentful auto-detects which format you're using.
+
 ---
 
-**Agentful** - Autonomous product development with Claude Code
+**agentful** - Autonomous product development with Claude Code

package/template/PRODUCT.md

@@ -1,5 +1,12 @@
 # Product Specification
 
+> **Note**: agentful supports **both** flat and hierarchical product structures.
+>
+> - **Flat Structure** (Recommended for beginners): Single file at project root (this file)
+> - **Hierarchical Structure** (For larger projects): `.claude/product/` with separate domain files
+>
+> This template shows the **flat structure** format. To convert to hierarchical structure, see [Migration Guide](#migration-to-hierarchical-structure) below.
+
 ## Overview
 
 [Describe what you're building in 2-3 sentences]
@@ -489,8 +496,89 @@ Each subtask should have:
 - **Priorities** ensure MVP features are built first
 - **Status tracking** enables autonomous development loops
 
-**Tip**: The more detailed your PRODUCT.md, the better Agentful can understand what to build. Include:
+**Tip**: The more detailed your PRODUCT.md, the better agentful can understand what to build. Include:
 - Clear acceptance criteria with checkboxes
 - User stories for context
 - Technical constraints and notes
 - Examples when helpful
+
+---
+
+## Migration to Hierarchical Structure
+
+When your project grows too large for a single file, you can migrate to the hierarchical structure:
+
+### When to Migrate
+
+Consider migrating when:
+- Your PRODUCT.md exceeds 500 lines
+- You have 20+ features across multiple domains
+- Multiple team members need to edit product specs simultaneously
+- You want better organization for complex projects
+
+### How to Migrate
+
+1. **Create the hierarchical structure:**
+   ```bash
+   mkdir -p .claude/product/domains
+   ```
+
+2. **Split your PRODUCT.md into domain files:**
+   - Move each domain section to `.claude/product/domains/{domain-name}/index.md`
+   - Move each feature to `.claude/product/domains/{domain-name}/features/{feature-name}.md`
+   - Create `.claude/product/index.md` with product overview only
+
+3. **System auto-detects the change:**
+   - agentful will automatically detect the hierarchical structure
+   - No configuration changes needed
+
+4. **Delete or archive the old PRODUCT.md:**
+   - You can keep it as a backup
+   - Or delete it once migration is complete
+
+### Example Migration
+
+**Before (Flat - this file):**
+```markdown
+# Product Spec
+
+## Domain: Authentication
+### Feature: Login
+[Details...]
+
+## Domain: User Management
+### Feature: Profile
+[Details...]
+```
+
+**After (Hierarchical):**
+```
+.claude/product/
+├── index.md                    # Product overview only
+└── domains/
+    ├── authentication/
+    │   ├── index.md           # Domain overview
+    │   └── features/
+    │       └── login.md       # Feature details
+    └── user-management/
+        ├── index.md
+        └── features/
+            └── profile.md
+```
+
+### Detailed Migration Guide
+
+For step-by-step instructions, examples, and best practices, see:
+`.claude/product/README.md` in your project (after running `npx @itz4blitz/agentful init`)
+
+### Key Differences
+
+| Aspect | Flat Structure | Hierarchical Structure |
+|--------|---------------|----------------------|
+| **File location** | `PRODUCT.md` at root | `.claude/product/` directory |
+| **Organization** | Single file with all features | Multiple files split by domain |
+| **Best for** | Small projects, MVPs, beginners | Large projects, teams, complex products |
+| **Tracking** | Feature-level completion | Subtask → Feature → Domain completion |
+| **Collaboration** | One editor at a time | Multiple editors can work on different domains |
+
+Both structures work identically - agentful auto-detects which format you're using!