@itz4blitz/agentful 0.1.7 → 0.1.9

package/.claude/agents/architect.md

@@ -13,12 +13,173 @@ You are the **Architect Agent**. Your job is to understand the project's pattern
 
 ### 1. Analyze the Project
 
-**For NEW projects** (just ran `npx @itz4blitz/agentful init`):
-1. Read `product/index.md` to understand what they want to build
-2. Ask user: "What tech stack are you using?" (add to decisions.json if needed)
-3. Once tech stack is known, generate agents
+**Step 1: Detect Project State**
+
+First, determine if this is a new or existing project:
+
+```bash
+# Check for existing source code
+has_code = Glob("**/*.{ts,tsx,js,jsx,py,go,rs,java,cs,rb,php,ex}")
+           excluding: node_modules, .git, dist, build, target, __pycache__
+
+if has_code.count < 3:
+  project_state = "NEW"
+  # Empty or nearly empty project
+else:
+  project_state = "EXISTING"
+  # Has existing codebase to learn from
+```
+
+**For NEW Projects** (empty or minimal code):
+
+When there's no code to analyze, use declarative approach:
+
+1. **Read product specification**:
+   ```bash
+   Read(".claude/product/index.md")
+   # OR hierarchical:
+   Glob(".claude/product/domains/*/index.md")
+   Glob(".claude/product/domains/*/features/*.md")
+   ```
+
+2. **Check for tech stack declaration**:
+   Look in product spec for tech stack hints:
+   - "Build a Next.js app..."
+   - "Using Django and PostgreSQL..."
+   - "React frontend with Express backend..."
+
+3. **Ask user directly if not specified**:
+   ```
+   📋 Tech Stack Selection
+
+   I need to understand your tech stack to generate appropriate specialized agents.
+
+   **What you're building:**
+   - [Summary from product spec]
+
+   **Please specify your stack:**
+
+   Frontend:
+   - [ ] React (Next.js / Vite / CRA)
+   - [ ] Vue (Nuxt / Vite)
+   - [ ] Angular
+   - [ ] Svelte (SvelteKit)
+   - [ ] Other: __________
+
+   Backend:
+   - [ ] Node.js (Express / Fastify / NestJS)
+   - [ ] Python (Django / Flask / FastAPI)
+   - [ ] Go (Gin / Echo / Chi)
+   - [ ] .NET (ASP.NET Core)
+   - [ ] Java (Spring Boot)
+   - [ ] Ruby (Rails / Sinatra)
+   - [ ] Other: __________
+
+   Database:
+   - [ ] PostgreSQL
+   - [ ] MySQL
+   - [ ] MongoDB
+   - [ ] SQLite
+   - [ ] Other: __________
+
+   Additional tools:
+   - ORM: __________
+   - Testing: __________
+   - Styling: __________
+   ```
+
+4. **Generate agents from declared stack**:
+
+   Based on user's declared stack, create specialized agents using **best practices and common patterns** for that technology.
+
+   **Key difference from existing projects:**
+   - EXISTING: Sample real code → extract actual patterns
+   - NEW: Use framework best practices → will be refined later
+
+   **Agent Generation Guidelines:**
+
+   a. **Use official framework patterns**:
+      - Next.js → App Router, Server Components, Route Handlers
+      - Django → Class-based views, ORM, Django REST Framework
+      - Express → Middleware, async/await, error handling
+      - Spring Boot → Annotations, Dependency Injection, JPA
+
+   b. **Include canonical examples** (not placeholder code):
+      ```markdown
+      ## Example from Next.js documentation
+
+      ```typescript
+      // app/api/users/route.ts
+      import { NextResponse } from 'next/server';
+
+      export async function GET() {
+        const users = await db.user.findMany();
+        return NextResponse.json(users);
+      }
+      ```
+
+      Use this pattern when creating API routes.
+      ```
+
+   c. **Reference official documentation**:
+      - "See: https://nextjs.org/docs/app/building-your-application/routing/route-handlers"
+      - "Pattern based on Django documentation best practices"
+
+   d. **Mark as template-based**:
+      ```markdown
+      ---
+      name: nextjs-specialist
+      description: Handles Next.js implementation using best practices (will be updated with project patterns)
+      template: true
+      confidence: 0.4
+      ---
+
+      # Next.js Specialist (Template)
+
+      ⚠️ **This agent was generated from framework best practices.**
+      It will be updated with YOUR project's specific patterns after the first feature is implemented.
+
+      ## Best Practice Patterns
+
+      Based on Next.js 14 documentation and common conventions:
+      ...
+      ```
+
+   e. **Common stack combinations**:
+
+      **Next.js + Prisma:**
+      - `nextjs-specialist.md` - App Router, Server Components, API routes
+      - `prisma-specialist.md` - Schema design, migrations, queries
+
+      **Django + PostgreSQL:**
+      - `django-specialist.md` - Views, models, URL routing
+      - `postgres-specialist.md` - Schema design, indexing, queries
+
+      **Express + MongoDB:**
+      - `express-specialist.md` - Routes, middleware, async patterns
+      - `mongodb-specialist.md` - Collections, queries, aggregations
+
+      **Spring Boot + MySQL:**
+      - `spring-specialist.md` - Controllers, services, repositories
+      - `jpa-specialist.md` - Entities, relationships, JPQL
+
+   f. **Always generate these core agents** (framework-agnostic):
+      - Use existing `backend.md` and `frontend.md` as fallbacks
+      - Don't duplicate - only create specialized agents when needed
+
+5. **Mark for re-analysis**:
+   Set flag in architecture.json:
+   ```json
+   {
+     "project_type": "new",
+     "declared_stack": { /* user's choices */ },
+     "needs_reanalysis_after_first_code": true,
+     "confidence": 0.4
+   }
+   ```
+
+**For EXISTING Projects** (has code to analyze):
 
-**For EXISTING projects**:
 1. Sample 3-5 files from `src/` or equivalent (or `app/`, `lib/`, `Controllers/`, etc.)
 2. Identify the patterns:
    - **Language**: Python? C#? JavaScript? Go? Rust? Java?
@@ -494,10 +655,82 @@ When you create an agent, ALWAYS include:
 
 Create/update `.agentful/architecture.json`:
 
+**For NEW projects (declarative stack):**
+```json
+{
+  "analysis_date": "2026-01-18T00:00:00Z",
+  "project_type": "new",
+  "analysis_source": "declared",
+  "declared_stack": {
+    "frontend": "Next.js 14",
+    "backend": "Node.js",
+    "database": "PostgreSQL",
+    "orm": "Prisma",
+    "testing": "Vitest",
+    "styling": "Tailwind CSS"
+  },
+  "detected_patterns": {
+    "framework": "Next.js 14 (App Router)",
+    "language": "TypeScript",
+    "primary_language": "TypeScript",
+    "structure": "to-be-determined",
+    "build_system": "npm",
+    "package_manager": "npm"
+  },
+  "tech_stack": {
+    "language": "TypeScript",
+    "primaryLanguage": "TypeScript",
+    "languages": ["TypeScript"],
+    "frameworks": ["Next.js", "React"],
+    "databases": ["PostgreSQL"],
+    "testingFrameworks": ["Vitest"],
+    "styling": ["Tailwind CSS"],
+    "buildSystem": "npm",
+    "packageManager": "npm",
+    "dependencies": [],
+    "devDependencies": [],
+    "confidence": 0.4
+  },
+  "domains": [],
+  "patterns": {
+    "imports": [],
+    "exports": [],
+    "styling": [],
+    "stateManagement": [],
+    "apiPatterns": [],
+    "testingFrameworks": []
+  },
+  "conventions": {
+    "naming": {},
+    "fileOrganization": "to-be-determined",
+    "importStyle": [],
+    "codeStyle": []
+  },
+  "generated_agents": [
+    "nextjs-specialist",
+    "prisma-specialist"
+  ],
+  "key_conventions_discovered": [],
+  "needs_reanalysis_after_first_code": true,
+  "confidence": 0.4,
+  "warnings": [
+    "Project has no code yet - using declared tech stack",
+    "Agents generated from best practices, not project patterns",
+    "Will re-analyze after first code is written"
+  ],
+  "recommendations": [
+    "Implement first feature to establish code patterns",
+    "Re-run architect after initial implementation"
+  ]
+}
+```
+
+**For EXISTING projects (detected patterns):**
 ```json
 {
   "analysis_date": "2026-01-18T00:00:00Z",
   "project_type": "existing",
+  "analysis_source": "detected",
   "detected_patterns": {
     "framework": "Next.js 14 (App Router)",
     "language": "TypeScript",
@@ -511,6 +744,20 @@ Create/update `.agentful/architecture.json`:
     "authentication": "NextAuth.js v5",
     "testing": "Vitest + React Testing Library + Playwright"
   },
+  "tech_stack": {
+    "language": "TypeScript",
+    "primaryLanguage": "TypeScript",
+    "languages": ["TypeScript", "JavaScript"],
+    "frameworks": ["Next.js", "React"],
+    "databases": ["PostgreSQL"],
+    "testingFrameworks": ["Vitest", "Playwright"],
+    "styling": ["Tailwind CSS"],
+    "buildSystem": "npm",
+    "packageManager": "npm",
+    "dependencies": ["next", "react", "prisma", "zustand"],
+    "devDependencies": ["vitest", "playwright"],
+    "confidence": 0.9
+  },
   "generated_agents": [
     "nextjs-specialist",
     "prisma-specialist",
@@ -526,16 +773,72 @@ Create/update `.agentful/architecture.json`:
     "Error responses use NextResponse.json()",
     "Database queries use Prisma Client",
     "Auth session checks on server components"
-  ]
+  ],
+  "needs_reanalysis_after_first_code": false,
+  "confidence": 0.9
 }
 ```
 
 ## When to Run
 
 You are invoked by the orchestrator when:
-1. agentful is first initialized on an existing project
-2. product/index.md tech stack changes significantly
-3. Orchestrator notices patterns don't match current agents
+
+1. **Initial setup** - agentful is first initialized (new or existing project)
+2. **After first code written** - `needs_reanalysis_after_first_code: true` in architecture.json
+3. **Tech stack changes** - product/index.md tech stack declaration changes significantly
+4. **Pattern drift detected** - Orchestrator notices existing code doesn't match current agents
+5. **Manual request** - User explicitly asks to re-analyze or regenerate agents
+6. **Low confidence warning** - confidence < 0.5 and code exists to analyze
+
+## Re-Analysis Workflow
+
+When `needs_reanalysis_after_first_code: true`:
+
+1. **Triggered by orchestrator** after first feature completes:
+   ```
+   architecture.json shows:
+   - needs_reanalysis_after_first_code: true
+   - Some code now exists (wasn't there initially)
+
+   → Orchestrator delegates: Task("architect", "Re-analyze project now that code exists")
+   ```
+
+2. **You run full analysis** on actual code:
+   - Glob for source files (should find some now)
+   - Sample and analyze actual patterns
+   - Compare with declared stack (did they actually use what they said?)
+   - Update agents with real examples from the codebase
+   - Increase confidence score (0.4 → 0.8+)
+
+3. **Update architecture.json**:
+   ```json
+   {
+     "project_type": "existing",
+     "analysis_source": "detected",
+     "original_declared_stack": { /* what user said */ },
+     "detected_patterns": { /* what we found */ },
+     "needs_reanalysis_after_first_code": false,
+     "confidence": 0.85,
+     "notes": "Re-analyzed after initial implementation. Patterns match declared stack."
+   }
+   ```
+
+4. **Report findings**:
+   ```
+   ✅ Re-analysis complete!
+
+   Initial (declared): Next.js + PostgreSQL + Prisma
+   Actual (detected):  Next.js 14 App Router + PostgreSQL + Prisma
+
+   Patterns discovered:
+   - Using Server Components by default
+   - API routes in src/app/api/
+   - Tailwind for styling
+   - TypeScript strict mode
+
+   Agents updated with real examples from your code.
+   Confidence: 40% → 85%
+   ```
 
 ## Integration
 

package/.claude/agents/orchestrator.md

@@ -729,6 +729,105 @@ Update `.agentful/completion.json` after validated work.
 }
 ```
 
+## Architecture Re-Analysis
+
+After updating `completion.json`, **ALWAYS check** if architecture needs re-analysis:
+
+### Check Architecture State
+
+```bash
+Read(".agentful/architecture.json")
+
+# Check for re-analysis flag
+if architecture.needs_reanalysis_after_first_code == true:
+  # Check if any code has been written since initial analysis
+  source_files = Glob("src/**/*.{ts,tsx,js,jsx,py,go,rs,java,cs,rb,php,ex}")
+                 excluding: node_modules, .git, dist, build
+
+  if source_files.count >= 3:
+    # Trigger re-analysis
+    trigger_reanalysis = true
+```
+
+### When to Trigger Re-Analysis
+
+Invoke architect agent when:
+
+1. **First code written in new project**:
+   ```json
+   {
+     "needs_reanalysis_after_first_code": true,
+     "confidence": 0.4,
+     "project_type": "new"
+   }
+   ```
+   AND source files now exist (wasn't true initially)
+
+2. **Low confidence with existing code**:
+   ```json
+   {
+     "confidence": < 0.5,
+     "project_type": "existing"
+   }
+   ```
+   AND source files exist to analyze
+
+3. **Manual trigger**:
+   User explicitly asks to "re-analyze" or "regenerate agents"
+
+### Re-Analysis Workflow
+
+```bash
+# After first feature completes in new project
+if architecture.needs_reanalysis_after_first_code == true:
+  "🔄 Re-analyzing project architecture..."
+  "Initial analysis was based on declared tech stack."
+  "Now analyzing actual code patterns..."
+
+  Task("architect", "Re-analyze project now that code exists. Update agents with real patterns discovered in the codebase.")
+
+  # Architect will:
+  # 1. Sample actual source files
+  # 2. Detect patterns (how components written, how DB accessed, etc.)
+  # 3. Update specialized agents with REAL examples
+  # 4. Set needs_reanalysis_after_first_code = false
+  # 5. Increase confidence score (0.4 → 0.8+)
+
+  "✅ Architecture re-analyzed. Agents updated with your project's patterns."
+```
+
+### Example Scenario
+
+```
+New Project Flow:
+
+1. User runs: npx @itz4blitz/agentful init
+2. Architect asks: "What tech stack?" → User: "Next.js + Prisma"
+3. Architect generates agents from best practices (confidence: 0.4)
+4. Sets: needs_reanalysis_after_first_code = true
+
+5. User runs: /agentful-start
+6. Orchestrator picks first feature: "authentication/login"
+7. Delegates to @nextjs-specialist (using template patterns)
+8. Code is written, validated, committed
+9. Updates completion.json: authentication/login = 100%
+
+10. ⚡ TRIGGER: Check architecture.json
+11. Sees: needs_reanalysis_after_first_code = true
+12. Sees: Source files now exist (src/app/, src/components/)
+13. Delegates: Task("architect", "Re-analyze...")
+14. Architect samples REAL code, updates agents with actual patterns
+15. Sets: needs_reanalysis_after_first_code = false, confidence = 0.85
+
+16. Continue with next feature using IMPROVED agents
+```
+
+**Benefits:**
+- Start fast with declared stack (no blocking on empty project)
+- Learn real patterns after first implementation
+- Continuously improve agent quality
+- Higher confidence for remaining features
+
 ## Work Selection Priority
 
 When selecting next work, use this order:

package/.claude/commands/agentful-status.md

@@ -98,5 +98,5 @@ At the end, suggest next actions:
 Next Actions:
   • /agentful-start    - Continue development
   • /agentful-decide  - Answer pending decisions
-  • /agentful-validate- Run quality checks
+  • /agentful-validate - Run quality checks
 ```

package/.claude/commands/agentful.md

@@ -165,15 +165,16 @@ Orchestrator:
 
 ## Quality Gates
 
-Every change automatically passes through:
+Every change automatically passes through **6 core automated quality gates**:
 
-- **Type checking** - No type errors
-- **Linting** - Consistent code style
-- **Tests** - All tests passing
-- **Coverage** - Minimum 80% code coverage
-- **Security** - No vulnerabilities, hardcoded secrets
-- **Dead code** - No unused exports, imports, files
-- **Performance** - Benchmarks (if configured)
+1. **Type checking** - No type errors
+2. **Linting** - Consistent code style
+3. **Tests** - All tests passing
+4. **Coverage** - Minimum 80% code coverage
+5. **Security** - No vulnerabilities, hardcoded secrets
+6. **Dead code** - No unused exports, imports, files
+
+> **Note**: The reviewer agent may run additional context-specific checks beyond these 6 core gates based on project needs (e.g., performance benchmarks, accessibility audits).
 
 **If gates fail** → @fixer automatically resolves issues → re-validates
 
@@ -207,7 +208,7 @@ Progress lives in `.agentful/`:
     "no_type_errors": true,
     "coverage_80": false
   },
-  "overall": 65
+  "overall_progress": 65
 }
 ```
 
@@ -246,7 +247,7 @@ When agentful needs input:
 
 ## Continuous Development
 
-For 24/7 autonomous development:
+For 24/7 autonomous development, use the **Ralph Wiggum plugin** (requires separate installation):
 
 ```bash
 /ralph-loop "/agentful-start" \
@@ -254,6 +255,8 @@ For 24/7 autonomous development:
   --completion-promise "AGENTFUL_COMPLETE"
 ```
 
+> **Note**: `/ralph-loop` is an external plugin command from the Ralph Wiggum plugin. Install separately from the Claude Code plugin registry.
+
 Stops when:
 - All features complete (100%)
 - Decision needed (pauses for input)
@@ -326,4 +329,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.1 (check updates: `npm outdated @itz4blitz/agentful`)
+- **Version**: 0.1.7 (check updates: `npm outdated @itz4blitz/agentful`)

package/README.md

@@ -1,670 +1,190 @@
-<div align="center">
-
 # agentful
 
-### The Autonomous Product Development Kit for Claude Code
-
-Transform any project into an intelligent, self-building product with specialized AI agents that work 24/7 to write, test, and validate your code.
-
-**[📚 Full Documentation →](https://agentful.app)**
+Autonomous product 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)
-[![Claude Code](https://img.shields.io/badge/Claude_Code-Compatible-blue)](https://code.anthropic.com)
-
-</div>
-
----
-
-## What is agentful?
-
-**agentful** is an opinionated setup for Claude Code that transforms it into a powerful autonomous development system. It's not just another AI coding assistant—it's a complete product development framework that coordinates specialized agents to build your entire application autonomously.
-
-Think of it as having a team of expert developers available 24/7, each with their own specialty, working together to build your product while you sleep.
-
-### What Makes agentful Different?
-
-Unlike single-purpose AI tools, agentful provides:
-
-- **7 Specialized Agents** working in concert (Orchestrator, Architect, Backend, Frontend, Tester, Reviewer, Fixer)
-- **Intelligent Init** that automatically detects your project structure (flat vs hierarchical)
-- **Natural Conversation Interface**—just talk to agentful like a senior developer
-- **24/7 Autonomous Development** that works while you sleep
-- **Built-in Quality Gates** ensuring production-ready code
-- **Tech Stack Auto-Detection** generating agents for your specific stack
-- **Progress Tracking** showing exactly what's done and what's next
-
----
-
-## How agentful Works
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                        1. DEFINE YOUR PRODUCT                               │
-│  Edit PRODUCT.md with your requirements, tech stack, and features           │
-└─────────────────────────────────────────────────────────────────────────────┘
-                                    ↓
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                     2. INTELLIGENT INIT (Automatic)                         │
-│  • Analyzes your project structure                                         │
-│  • Detects tech stack (Next.js, React, Prisma, etc.)                       │
-│  • Creates optimal product structure (flat or hierarchical)                │
-│  • Generates specialized agents for your stack                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-                                    ↓
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                     3. AUTONOMOUS DEVELOPMENT                               │
-│  • Orchestrator coordinates work                                           │
-│  • Specialized agents implement features                                   │
-│  • Tester writes and runs tests                                            │
-│  • Reviewer validates quality gates                                        │
-│  • Fixer resolves any issues                                               │
-└─────────────────────────────────────────────────────────────────────────────┘
-                                    ↓
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                        4. 24/7 ITERATION                                    │
-│  Loop continues until all features complete and quality gates pass         │
-└─────────────────────────────────────────────────────────────────────────────┘
-                                    ↓
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                      ✅ PRODUCTION-READY CODE                                │
-│  All tests passing • No type errors • Coverage ≥80% • Secure               │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Quick Start (30 seconds)
-
-### Step 1: Initialize in Your Project
 
-```bash
-npx @itz4blitz/agentful init
-```
-
-**Intelligent Structure Detection:**
-
-agentful automatically analyzes your project and creates the optimal product structure:
-
-- **Simple Projects** → Creates `PRODUCT.md` at root (flat, single-file)
-- **Large/Complex Projects** → Creates `.claude/product/` with domain directories (hierarchical)
-
-**Detection Logic:**
-- ≥3 detected domains → Hierarchical structure
-- ≥2 frameworks detected → Hierarchical structure
-- Monorepo detected → Hierarchical structure
-- Otherwise → Flat structure (recommended for beginners)
-
-### Step 2: Edit Your Product Specification
-
-**For Simple Projects (Flat Structure)** - Edit `PRODUCT.md`:
-
-```markdown
 ## Overview
-A task management app for remote teams with real-time collaboration.
-
-## Tech Stack
-- Frontend: Next.js 14 + TypeScript + Tailwind CSS
-- Backend: Next.js API Routes
-- Database: Prisma + PostgreSQL
-- Testing: Vitest + Playwright
-
-## Features
-
-### Domain: Authentication
-
-#### User Registration - CRITICAL
-**Description**: Allow new users to create accounts
 
-**Subtasks**:
-1. Create registration form UI - CRITICAL
-   - [ ] Email validation with regex
-   - [ ] Password minimum 8 characters
-   - [ ] Responsive design
+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.
 
-2. Implement registration API endpoint - CRITICAL
-   - [ ] POST /api/auth/register
-   - [ ] Hash passwords with bcrypt
-   - [ ] Rate limiting
-
-#### User Login - CRITICAL
-[... more features]
-```
-
-**For Large Projects (Hierarchical Structure)** - Edit `.claude/product/index.md`:
-
-```markdown
-## Overview
-E-commerce platform with multi-vendor support.
-
-## Domains
-1. **Authentication** - See `.claude/product/domains/auth/` for details
-2. **Product Catalog** - See `.claude/product/domains/products/` for details
-3. **Order Processing** - See `.claude/product/domains/orders/` for details
-4. **Vendor Management** - See `.claude/product/domains/vendors/` for details
-```
-
-Then edit domain-specific files in `.claude/product/domains/{domain-name}/`.
-
-### Step 3: Start Autonomous Development
-
-```bash
-claude
-```
-
-Then inside Claude Code:
-
-```
-/agentful-start
-```
-
-That's it! agentful will:
-
-1. **Analyze** your product specification
-2. **Detect** your tech stack from `package.json` and code
-3. **Generate** specialized agents for your stack
-4. **Begin** autonomous development immediately
-
----
-
-## Key Features
-
-### 🧠 Intelligent Init
-
-Smart initialization that adapts to your project:
-
-- **Automatic Structure Detection** - Chooses flat vs hierarchical based on project complexity
-- **Tech Stack Detection** - Analyzes dependencies, frameworks, and code patterns
-- **Dynamic Agent Generation** - Creates specialized agents for your specific stack
-- **Zero Configuration** - Works out of the box, no setup needed
-
-**Example:**
-
-```bash
-$ npx @itz4blitz/agentful init
-
-✓ Detected project type: Next.js App Router
-✓ Detected tech stack: Next.js 14, TypeScript, Prisma, Tailwind CSS
-✓ Analyzing project structure...
-✓ Detected 5 domains → Using hierarchical structure
-✓ Created .claude/product/domains/ with 5 domain directories
-✓ Generated specialized agents: nextjs-agent, prisma-agent, tailwind-agent
-
-Next: Edit .claude/product/index.md to define your product, then run 'claude' and '/agentful-start'
-```
-
-### 💬 Natural Conversation Interface
-
-Talk to agentful like a senior developer:
+## Installation
 
 ```bash
-/agentful
-
-You: I need to add user authentication
-agentful: I'll help you add authentication. I can see you have Next.js set up.
-        Would you like to use NextAuth.js or implement custom JWT?
-
-You: Let's use NextAuth.js with Google provider
-agentful: Perfect. I'll:
-        1. Install next-auth
-        2. Configure Google OAuth
-        3. Create login/logout pages
-        4. Add session management
-        5. Write tests
-        Ready to proceed?
-
-You: Yes, go ahead
-agentful: Starting implementation...
-```
-
-### 🤖 Specialized Agents
-
-Seven AI agents working together:
-
-| Agent | Role | Expertise |
-|-------|------|-----------|
-| **@orchestrator** | Project Manager | Coordinates all work, manages decisions, tracks progress |
-| **@architect** | System Architect | Analyzes tech stack, generates specialized agents |
-| **@backend** | Backend Developer | Services, repositories, controllers, APIs |
-| **@frontend** | Frontend Developer | Components, pages, hooks, styling |
-| **@tester** | QA Engineer | Unit, integration, E2E tests |
-| **@reviewer** | Code Reviewer | Code review, dead code detection, quality validation |
-| **@fixer** | DevOps Engineer | Auto-fixes validation failures |
-
-### 🌙 24/7 Autonomous Development
-
-Use the Ralph Wiggum plugin for overnight autonomous development:
-
-```bash
-# Inside Claude Code
-/plugin install ralph-wiggum@anthropics
-
-# Run autonomous development loop
-/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"
+npx @itz4blitz/agentful init
 ```
 
-**What happens overnight:**
-- agentful works while you sleep
-- Continues until all features complete (100%)
-- Stops when all quality gates pass
-- Or reaches max iterations
-
-Wake up to a working product!
+This command creates the necessary directory structure and configuration files in your project.
 
-### 📊 Quality Gates
+## Usage
 
-Code must pass ALL gates before completion:
+### 1. Define Product Specification
 
-- ✅ **All tests passing** - Unit, integration, and E2E
-- ✅ **Type checking** - Adapts to your stack (TypeScript, Flow, etc.)
-- ✅ **Linting** - Zero lint errors
-- ✅ **Dead code elimination** - No unused exports, files, or dependencies
-- ✅ **Test coverage** - Minimum 80% coverage
-- ✅ **Security** - No vulnerabilities or security issues
+After initialization, edit your product specification file with features and requirements.
 
-Quality gates automatically adapt to your tech stack. Using JavaScript instead of TypeScript? No type checking. Using ESLint instead of Biome? Linting adapts accordingly.
+**Flat structure** (single file at project root):
+- `PRODUCT.md` - All features in one file
 
-### 📈 Progress Tracking
+**Hierarchical structure** (organized by domain):
+- `.claude/product/index.md` - Product overview
+- `.claude/product/domains/*/features/` - Feature definitions organized by domain
 
-Real-time visibility into development:
+### 2. Start Development
 
 ```bash
-/agentful-status
-```
-
-**Output:**
-```
-🔧 Working on: User authentication feature
-   Phase: implementation
-   Iterations: 12
-   Current task: Implementing JWT service
-
-Progress:
-   ████████░░░░░░░░░░░ 40%
-
-Quality Gates:
-   ✅ Tests Passing (47/47)
-   ❌ Type Checking (3 errors found)
-   ⚠️  Coverage (76% - target: 80%)
-   ✅ Linting (0 errors)
-   ✅ Dead Code (0 issues)
-   ✅ Security (0 vulnerabilities)
-
-Pending Decisions (2):
-   1. ⚠️  Which auth library? (NextAuth.js or custom JWT?)
-   2. ⚠️  Session duration? (7 days or 30 days?)
-
-Completed:
-   ✅ User registration (100%)
-   ✅ Password reset (100%)
-   🔄 User authentication (40%)
-   ⏳ User profile (0%)
+claude  # Start Claude Code
 ```
 
-### 🎯 Smart Decision Handling
+Then use the `/agentful-start` command to begin autonomous development.
 
-agentful asks when it needs clarification:
+#### New Projects (No Existing Code)
 
-1. **Question added** to `decisions.json`
-2. **Continues work** on unblocked features
-3. **You answer** when convenient via `/agentful-decide`
-4. **Resumes** blocked work automatically
+For brand new projects with no code yet:
 
-Never interrupt flow—agentful keeps working on what it can.
-
----
-
-## Example Flow
-
-Here's a real example of agentful building authentication:
-
-```bash
-# You: Initialize agentful
-$ npx @itz4blitz/agentful init
-✓ Detected project type: Next.js App Router
-✓ Detected tech stack: Next.js 14, TypeScript, Prisma, Tailwind CSS
-✓ Created PRODUCT.md (flat structure)
+1. **Tech Stack Selection**: On first run, the architect agent will ask about your tech stack:
+   - Frontend framework (React, Vue, Next.js, etc.)
+   - Backend framework (Express, Django, Spring Boot, etc.)
+   - Database (PostgreSQL, MongoDB, MySQL, etc.)
+   - Additional tools (ORM, testing framework, styling)
 
-# You: Edit PRODUCT.md with authentication requirements
+2. **Initial Agent Generation**: Specialized agents are generated using **best practices** for your chosen stack:
+   - Based on official framework documentation
+   - Using common patterns and conventions
+   - Marked with `confidence: 0.4` (template-based)
 
-# You: Start Claude Code
-$ claude
+3. **First Feature Implementation**: The system builds your first feature using these template agents
 
-# You: Start autonomous development
-> /agentful-start
+4. **Automatic Re-Analysis**: After the first feature is complete:
+   - Architect re-analyzes your **actual code**
+   - Updates agents with **your project's specific patterns**
+   - Confidence increases (`0.4 → 0.8+`)
+   - Remaining features use refined, project-specific agents
 
-# agentful responds:
-🔍 Analyzing PRODUCT.md...
-📋 Detected domains: Authentication, User Management
-🛠️  Detected tech stack: Next.js 14, TypeScript, Prisma, Tailwind CSS, Vitest
-🤖 Generating specialized agents: nextjs-agent, typescript-agent, prisma-agent, tailwind-agent
+**Benefits**:
+- ✅ Start immediately without existing code
+- ✅ No blocking on pattern detection
+- ✅ Learns and adapts after first implementation
+- ✅ Continuously improving agent quality
 
-🚀 Starting autonomous development...
+#### Existing Projects (With Code)
 
-📌 Feature: User Registration (CRITICAL)
-   → @backend implementing JWT service
-   → @backend creating user schema in Prisma
-   → @backend implementing registration API route
-   → @frontend creating registration form
-   → @tester writing unit tests
-   → @tester writing integration tests
+For projects with existing code:
 
-✅ User Registration complete (100%)
-   Tests: ✅ 12/12 passing
-   Type check: ✅ 0 errors
-   Coverage: ✅ 87%
+1. **Pattern Detection**: Architect samples your codebase to detect:
+   - Language and framework
+   - File organization patterns
+   - Coding conventions
+   - Import/export styles
+   - Error handling patterns
 
-📌 Feature: User Login (CRITICAL)
-   → @backend implementing login API
-   → @frontend creating login page
-   → @tester writing auth tests
+2. **Agent Generation**: Creates specialized agents matching **your exact conventions**
+   - Real code examples from your project
+   - Your specific patterns and styles
+   - High confidence (`0.8-1.0`)
 
-⚠️  Decision needed: Which session duration?
-   Options: 7 days, 30 days, or custom
-   → @orchestrator continuing with unblocked features...
+### 3. Monitor Progress
 
-📌 Feature: Password Reset (HIGH)
-   → @backend implementing reset token flow
-   → @backend creating email service
-   → @frontend creating reset form
+- `/agentful-status` - View completion percentage and current work
+- `/agentful-validate` - Run quality checks
+- `/agentful-decide` - Answer blocking questions
 
-> /agentful-decide
-
-📝 Pending Decisions:
-1. Which session duration for JWT tokens?
-   a) 7 days (recommended for better security)
-   b) 30 days (more convenient)
-   c) Custom duration
-
-   Your choice: a
-
-✅ Decision resolved: Using 7-day session duration
-🔄 @orchestrator resuming login feature...
-
-📌 Feature: User Login (resuming)
-   → @backend implementing 7-day session duration
-   → @frontend adding session persistence
-
-✅ User Login complete (100%)
-   Tests: ✅ 18/18 passing
-   Type check: ✅ 0 errors
-   Coverage: ✅ 91%
-
-📊 Progress Update:
-   ████████░░░░░░░░░░░ 33% (3/9 features complete)
-
-🔄 Continuing with next feature: User Profile...
-
-[Continues 24/7 until complete]
-```
-
----
-
-## Why Use agentful?
-
-### vs. Manual Development
-
-| Manual Development | agentful |
-|-------------------|----------|
-| Write every line yourself | AI agents write code autonomously |
-| Forget to write tests | Tests written automatically |
-| Debug for hours | Issues caught and fixed automatically |
-| Works only when you work | Works 24/7 |
-| Inconsistent code quality | Enforced quality standards |
-| Context switching overhead | Specialized agents maintain focus |
-
-### vs. Other AI Tools
-
-| Other AI Coding Assistants | agentful |
-|---------------------------|----------|
-| Single-purpose (code completion) | Complete product development system |
-| No coordination between agents | 7 specialized agents working together |
-| Requires constant supervision | Autonomous 24/7 operation |
-| No quality enforcement | Built-in quality gates |
-| Generic code | Tech stack-specific agents |
-| No progress tracking | Real-time progress visibility |
-| Manual testing | Automatic test generation |
-
-### Key Differentiators
-
-1. **Agent Coordination** - Unlike single AI tools, agentful orchestrates 7 specialized agents working together
-2. **Intelligent Init** - Automatically detects optimal project structure (flat vs hierarchical)
-3. **Natural Conversation** - Talk to agentful like a senior developer, not a tool
-4. **Quality Built-In** - Every feature includes tests, type checking, linting, coverage, security
-5. **24/7 Development** - Works while you sleep via Ralph Wiggum loops
-6. **Tech Stack Adaptation** - Dynamically generates agents for your specific stack
-7. **Progress Visibility** - Always know what's done, what's next, and what's blocked
-
----
-
-## Product Structures
+## Architecture
 
-agentful supports two product structure formats:
+### Agent System
 
-### Flat Structure (Recommended for Beginners)
+agentful uses seven specialized agents:
 
-**Best for:** Simple projects, MVPs, prototypes
+| Agent | Responsibility |
+|-------|---------------|
+| orchestrator | Coordinates work, routes tasks, tracks state |
+| architect | Analyzes project structure and generates specialized agents<br/>• New projects: Prompts for tech stack, generates template agents<br/>• Existing projects: Detects patterns from code<br/>• Re-analyzes after first implementation in new projects |
+| backend | Implements server-side logic, APIs, database schemas |
+| frontend | Implements UI components, pages, state management |
+| tester | Writes unit, integration, and end-to-end tests |
+| reviewer | Validates code quality, security, and standards |
+| fixer | Resolves validation failures and test errors |
 
-```
-your-project/
-├── PRODUCT.md          # Single file with all features
-├── .claude/            # agentful configuration
-└── src/                # Your code
-```
+### Quality Gates
 
-**Advantages:**
-- Simple to get started
-- Everything in one file
-- Easy to understand
-- Great for small teams
+Code changes are validated against:
 
-### Hierarchical Structure (For Large Projects)
+- Type checking (TypeScript, Flow, etc.)
+- Linting (ESLint, Biome, etc.)
+- Test execution (all tests must pass)
+- Code coverage (minimum 80%)
+- Security scanning
+- Dead code detection
 
-**Best for:** Complex projects, multiple domains, large teams
+### State Tracking
 
-```
-your-project/
-├── .claude/
-│   └── product/
-│       ├── index.md           # Product overview
-│       └── domains/
-│           ├── authentication/
-│           │   ├── index.md   # Domain overview
-│           │   └── features/
-│           │       ├── login.md
-│           │       └── register.md
-│           ├── user-management/
-│           │   └── features/
-│           └── payments/
-│               └── features/
-└── src/
-```
+Runtime state is stored in `.agentful/`:
 
-**Advantages:**
-- Organized by domain
-- Multiple team members can edit simultaneously
-- Easier to navigate large specs
-- Better for complex products
-
-### Automatic Detection
-
-agentful automatically detects which structure you're using. No configuration needed!
-
-**Start with flat, migrate to hierarchical as you grow.** Both formats work identically.
-
----
+- `state.json` - Current task and phase
+- `completion.json` - Feature completion status
+- `decisions.json` - Pending and resolved decisions
+- `architecture.json` - Technology stack (declared or detected)
+  - 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
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `/agentful` | **Natural conversation** - Just talk to agentful |
-| `/agentful-start` | Begin or resume autonomous development |
-| `/agentful-status` | Check current progress and what's being worked on |
-| `/agentful-decide` | Answer pending decisions that block development |
-| `/agentful-validate` | Run all quality checks (tests, type check, lint, coverage, security) |
-
----
-
-## Tech Stack Support
-
-agentful automatically detects and supports:
-
-### Frontend Frameworks
-- Next.js (App Router & Pages Router)
-- React + Vite
-- Vue + Nuxt
-- SvelteKit
-- Solid.js
-- Astro
-
-### Backend Frameworks
-- Next.js API Routes
-- Express
-- Fastify
-- NestJS
-- Hono
-- tRPC
-
-### Databases & ORMs
-- PostgreSQL, MySQL, SQLite, MongoDB
-- Prisma, Drizzle, TypeORM, Mongoose
-
-### Styling
-- Tailwind CSS, CSS Modules, styled-components, shadcn/ui
-
-### Testing
-- Vitest, Jest, Playwright, Cypress
-
-### Authentication
-- NextAuth.js, Clerk, Auth0, Lucia, custom JWT
-
-**And many more!** agentful generates specialized agents for whatever stack you're using.
-
----
-
-## Use Cases
-
-### Perfect For:
-
-- **MVP Development** - Ship your minimum viable product in days, not weeks
-- **Prototyping** - Quickly test ideas with working code
-- **Full-Stack Projects** - Build complete applications from scratch
-- **Legacy Migration** - Modernize old codebases with test coverage
-- **SaaS Products** - Build complete SaaS applications autonomously
-- **Internal Tools** - Create tools for your team automatically
-- **Learning Projects** - Learn best practices from autonomously written code
-- **Open Source** - Generate boilerplate and scaffolding automatically
+| `/agentful-start` | Start or resume autonomous development |
+| `/agentful-status` | Display progress and current state |
+| `/agentful-validate` | Run all quality checks |
+| `/agentful-decide` | Answer pending decisions |
 
-### Not Ideal For:
+## Technology Support
 
-- Highly experimental research projects
-- Projects requiring proprietary algorithms
-- Applications needing human creative direction
-- Simple one-off scripts (overkill)
+agentful detects and adapts to your technology stack automatically:
 
----
+- **Languages**: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, Elixir
+- **Frontend**: React, Vue, Angular, Svelte, Next.js, Astro, SolidJS
+- **Backend**: Express, Fastify, NestJS, Hono, Next.js API Routes
+- **Databases**: PostgreSQL, MySQL, SQLite, MongoDB
+- **ORMs**: Prisma, Drizzle, TypeORM, Mongoose
+- **Testing**: Jest, Vitest, Playwright, Cypress, Pytest, JUnit
 
 ## Requirements
 
-- **Claude Code** - [Install here](https://code.anthropic.com)
-- **Node.js 22+** - For CLI tool
-- **Git** - For version control
-
----
+- Claude Code ([code.anthropic.com](https://code.anthropic.com))
+- Node.js 22 or higher
+- Git
 
 ## Documentation
 
-Full documentation at **[agentful.app](https://agentful.app)**
-
-### Getting Started
-- **[Quick Start Guide](https://agentful.app/getting-started/quick-start)** - 5-minute walkthrough
-- **[Your First Project](https://agentful.app/getting-started/first-project)** - Build your first project
-- **[Product Specification](https://agentful.app/getting-started/product-specification)** - How to write effective specs
-
-### Core Concepts
-- **[Agents](https://agentful.app/agents)** - Specialized agents and their roles
-- **[Commands](https://agentful.app/core-concepts/commands)** - All available commands
-- **[Quality Gates](https://agentful.app/autonomous-development/quality-gates)** - Quality checks explained
-- **[Progress Tracking](https://agentful.app/core-concepts/progress-tracking)** - State management
-- **[Decision Handling](https://agentful.app/core-concepts/decisions)** - How agentful handles decisions
+Full documentation: [agentful.app](https://agentful.app)
 
-### Advanced
-- **[24/7 Development](https://agentful.app/autonomous-development/24-7-development)** - Overnight autonomous loops
-- **[Product Structures](https://agentful.app/core-concepts/product-structures)** - Flat vs hierarchical
-- **[Tech Stack Detection](https://agentful.app/core-concepts/tech-stack-detection)** - How it works
-- **[Customization](https://agentful.app/advanced/customization)** - Customize agents and commands
-
----
-
-## Architecture
+## Project Structure
 
 ```
 your-project/
-├── PRODUCT.md              # Your product spec (flat structure)
-├── CLAUDE.md               # Project-specific Claude instructions
-├── .claude/                # agentful configuration
-│   ├── product/            # Product spec (hierarchical structure)
-│   │   ├── index.md        # Product overview
-│   │   └── domains/        # Domain-specific specs
-│   ├── agents/             # Specialized agents
-│   │   ├── orchestrator.md
-│   │   ├── architect.md
-│   │   ├── backend.md
-│   │   ├── frontend.md
-│   │   ├── tester.md
-│   │   ├── reviewer.md
-│   │   └── fixer.md
-│   ├── commands/           # Slash commands
-│   │   ├── agentful.md
-│   │   ├── agentful-start.md
-│   │   ├── agentful-status.md
-│   │   ├── agentful-decide.md
-│   │   └── agentful-validate.md
-│   ├── skills/             # Domain-specific skills
-│   │   ├── conversation/
-│   │   ├── product-tracking/
-│   │   └── validation/
-│   └── settings.json       # Hooks and permissions
-├── .agentful/              # Runtime state (gitignored)
-│   ├── state.json          # Current work state
-│   ├── completion.json     # Feature completion percentages
-│   ├── decisions.json      # Pending and resolved decisions
-│   ├── architecture.json   # Detected tech stack
-│   └── last-validation.json # Most recent validation report
-└── src/                    # Your code (generated by agentful)
+├── PRODUCT.md                      # Product specification (flat)
+├── CLAUDE.md                       # Project instructions
+├── .claude/
+│   ├── product/                    # Product specification (hierarchical)
+│   ├── agents/                     # Agent definitions
+│   ├── commands/                   # Slash commands
+│   ├── skills/                     # Reusable skills
+│   └── settings.json               # Configuration
+├── .agentful/                      # Runtime state
+│   ├── state.json
+│   ├── completion.json
+│   ├── decisions.json
+│   └── architecture.json
+└── src/                            # Source code
 ```
 
----
-
-## Links
-
-- **GitHub**: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
-- **Issues**: [github.com/itz4blitz/agentful/issues](https://github.com/itz4blitz/agentful/issues)
-- **Website**: [agentful.app](https://agentful.app)
-- **Documentation**: [agentful.app](https://agentful.app)
-- **NPM**: [npmjs.com/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)
-- **Claude Code**: [code.anthropic.com](https://code.anthropic.com)
-
----
-
 ## License
 
 MIT
 
----
-
 ## Links
 
-- **GitHub**: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
-- **Issues**: [github.com/itz4blitz/agentful/issues](https://github.com/itz4blitz/agentful/issues)
-- **Website**: [agentful.app](https://agentful.app)
-- **Documentation**: [agentful.app](https://agentful.app)
-- **NPM**: [npmjs.com/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)
-- **Claude Code**: [code.anthropic.com](https://code.anthropic.com)
-
----
-
-## License
-
-MIT
+- GitHub: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
+- Issues: [github.com/itz4blitz/agentful/issues](https://github.com/itz4blitz/agentful/issues)
+- Documentation: [agentful.app](https://agentful.app)
+- NPM: [npmjs.com/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Autonomous product development kit for Claude Code with smart product analysis and natural conversation",
   "type": "module",
   "bin": {
-    "agentful": "./bin/cli.js"
+    "agentful": "bin/cli.js"
   },
   "scripts": {
     "init": "node bin/cli.js init",
@@ -33,7 +33,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/itz4blitz/agentful"
+    "url": "git+https://github.com/itz4blitz/agentful.git"
   },
   "homepage": "https://agentful.app",
   "engines": {

package/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.6"
+  "version": "0.1.9"
 }