@itz4blitz/agentful 0.3.0 → 0.4.0

package/.claude/agents/orchestrator.md

@@ -130,7 +130,7 @@ if task_successful:
 ### Read These Files First
 
 ```bash
-1. PRODUCT.md OR .claude/product/index.md           # Product overview
+1. .claude/product/index.md                         # Product overview
 2. .claude/product/domains/*/index.md               # Domains (if hierarchical)
 3. .claude/product/domains/*/features/*.md          # Features (if hierarchical)
 4. .agentful/state.json                             # Current work state
@@ -146,7 +146,7 @@ if task_successful:
 if exists(".claude/product/domains/*/index.md"):
     structure = "hierarchical"  # Organized: domains → features
     use_completion.domains
-else if exists("PRODUCT.md") OR exists(".claude/product/index.md"):
+else if exists(".claude/product/index.md"):
     structure = "flat"  # Simple: flat feature list
     use_completion.features
 else:

package/.claude/agents/product-analyzer.md

@@ -36,7 +36,6 @@ First, detect which product structure format is being used:
 domains_found = Glob(".claude/product/domains/*/index.md")
 
 # Step 2: Check for flat structure
-product_md_exists = exists("PRODUCT.md")
 product_index_exists = exists(".claude/product/index.md")
 
 if domains_found:
@@ -50,11 +49,6 @@ if domains_found:
         for feature_file in Glob(".claude/product/domains/{domain}/features/*.md"):
             Read(feature_file)
 
-elif product_md_exists:
-    format = "flat"
-    product_root = "."
-    Read("PRODUCT.md")
-
 elif product_index_exists:
     format = "flat"
     product_root = ".claude/product"
@@ -325,7 +319,7 @@ if structure == "hierarchical":
             domain.features.append(feature)
         domains.append(domain)
 else:
-    product_spec = Read("PRODUCT.md" OR ".claude/product/index.md")
+    product_spec = Read(".claude/product/index.md")
 ```
 
 ### Step 2: Analyze Each Dimension
@@ -735,9 +729,8 @@ Analysis saved to: .claude/product/product-analysis.json
       "recommendation": {
         "action": "Create product specification",
         "options": [
-          "Use PRODUCT.md for simple projects",
-          "Use .claude/product/index.md for organized flat structure",
-          "Use .claude/product/domains/* for complex projects"
+          "Use .claude/product/index.md for simple flat structure",
+          "Use .claude/product/domains/* for complex projects with hierarchical organization"
         ]
       }
     }

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

@@ -28,7 +28,7 @@ if user_text:
   goto DISCUSSION_MODE
 
 # Step 2: Check if product spec exists
-product_spec_exists = exists(".claude/product/index.md") OR exists("PRODUCT.md")
+product_spec_exists = exists(".claude/product/index.md")
 
 if !product_spec_exists:
   has_substantial_codebase = check_codebase_exists()
@@ -169,7 +169,7 @@ Task("product-analyzer", "Analyze .claude/product/index.md and generate product-
 
 The product analyzer should:
 
-1. **Read product specification**: `.claude/product/index.md` or `PRODUCT.md`
+1. **Read product specification**: `.claude/product/index.md`
 
 2. **Analyze for completeness and clarity**:
    - Tech stack: All stack choices specified (not placeholders)
@@ -425,7 +425,7 @@ Task("product-analyzer", "Analyze .claude/product/index.md and generate product-
 
 ## File Locations
 
-- **Product spec**: `.claude/product/index.md` (or `PRODUCT.md` for legacy)
+- **Product spec**: `.claude/product/index.md`
 - **Analysis results**: `.claude/product/product-analysis.json`
 - **Domain structure**: `.claude/product/domains/*/index.md` (optional hierarchical)
 

package/.claude/commands/agentful.md

@@ -268,18 +268,7 @@ This is optional but recommended for complex projects. Run `/agentful-product` t
 
 Create a product specification (choose one):
 
-**Flat structure** (simple projects):
-```markdown
-# PRODUCT.md
-
-## Features
-
-- [CRITICAL] User authentication (login, register, password reset)
-- [HIGH] User profiles (edit, avatar, preferences)
-- [MEDIUM] Dashboard (analytics, activity feed)
-```
-
-**Hierarchical structure** (complex projects):
+**Hierarchical structure** (recommended):
 ```
 .claude/product/
 ├── index.md                 # Product overview

package/.claude/product/EXAMPLES.md

@@ -4,7 +4,7 @@ This file shows concrete examples of both flat and hierarchical product structur
 
 ## Example 1: Flat Structure (Simple Project)
 
-### File: PRODUCT.md
+### File: .claude/product/index.md
 
 ```markdown
 # TaskFlow - Task Management App
@@ -600,7 +600,7 @@ POST /api/auth/login
 
 | Aspect | Flat Structure | Hierarchical Structure |
 |--------|---------------|----------------------|
-| **Files** | 1 file (PRODUCT.md) | 10+ files (domains/features) |
+| **Files** | 1 file (.claude/product/index.md) | 10+ files (domains/features) |
 | **Organization** | Feature list | Domains → Features → Subtasks |
 | **Tracking** | Feature-level (6 items) | Subtask-level (20+ items) |
 | **Scalability** | Good for < 20 features | Good for 20+ features |

package/.claude/product/README.md

@@ -6,16 +6,7 @@ agentful supports **both** flat and hierarchical product structures with automat
 
 ### Simple Projects (Flat Structure)
 
-Just create a single `PRODUCT.md` file at your project root:
-
-```bash
-your-project/
-├── PRODUCT.md          # All features in one file
-├── src/
-└── package.json
-```
-
-Or use `.claude/product/index.md`:
+Create `.claude/product/index.md` with all your features:
 
 ```bash
 your-project/
@@ -54,8 +45,7 @@ your-project/
 The system automatically detects which format you're using:
 
 1. **Hierarchical**: If `.claude/product/domains/*/index.md` exists
-2. **Flat (legacy)**: If `PRODUCT.md` exists at root
-3. **Flat (new)**: If `.claude/product/index.md` exists (without domains)
+2. **Flat**: If `.claude/product/index.md` exists (without domains)
 
 ### Detection Algorithm
 
@@ -63,11 +53,8 @@ The system automatically detects which format you're using:
 if exists(".claude/product/domains/*/index.md"):
     → Use hierarchical structure
     → Track at subtask → feature → domain levels
-else if exists("PRODUCT.md"):
-    → Use flat structure (legacy)
-    → Track at feature level
 else if exists(".claude/product/index.md"):
-    → Use flat structure (new)
+    → Use flat structure
     → Track at feature level
 else:
     → Error: No product specification found
@@ -83,7 +70,7 @@ else:
 - Single developer or small team
 - Simple feature list without dependencies
 
-**Example `PRODUCT.md`:**
+**Example `.claude/product/index.md`:**
 
 ```markdown
 # My App
@@ -209,16 +196,13 @@ Priority: CRITICAL
 
 ## Migration Path
 
-You can start flat and migrate to hierarchical as your project grows:
+You can start flat and expand to hierarchical as your project grows:
 
 ```
 Phase 1: Quick Start
-└── PRODUCT.md (all features in one file)
-
-Phase 2: Organize (optional)
-└── .claude/product/index.md (move to .claude directory)
+└── .claude/product/index.md (all features in one file)
 
-Phase 3: Scale Up (when needed)
+Phase 2: Scale Up (when needed)
 └── .claude/product/domains/ (split by domain)
     ├── authentication/
     ├── user-management/
@@ -285,7 +269,6 @@ For hierarchical structure examples, check:
 ### "No product specification found"
 
 **Solution**: Create one of:
-- `PRODUCT.md` at root
 - `.claude/product/index.md`
 - `.claude/product/domains/*/index.md`
 
@@ -294,7 +277,7 @@ For hierarchical structure examples, check:
 **Cause**: completion.json structure doesn't match product files
 
 **Solution**: Don't mix formats. Choose one:
-- All flat: `PRODUCT.md` + `completion.json` with `features` object
+- All flat: `.claude/product/index.md` + `completion.json` with `features` object
 - All hierarchical: `.claude/product/domains/` + `completion.json` with `domains` object
 
 ### Can I use both formats?
@@ -337,8 +320,7 @@ After running `/agentful-product`, a `product-analysis.json` file is generated:
 
 | Format | Best For | Tracking | File Structure |
 |--------|----------|----------|----------------|
-| Flat (PRODUCT.md) | Small projects, MVPs | Feature level | Single file |
-| Flat (.claude/product/index.md) | Small projects, organized | Feature level | Single file in .claude |
+| Flat (.claude/product/index.md) | Small projects, MVPs | Feature level | Single file |
 | Hierarchical | Large projects, teams | Subtask/feature/domain level | Multiple files, domain folders |
 
 Choose the format that matches your project needs. The system will auto-detect and adapt!

package/.claude/skills/product-tracking/SKILL.md

@@ -16,10 +16,8 @@ This skill tracks the completion progress of product development with support fo
 The system supports **both** flat and hierarchical product structures with automatic detection:
 
 ```
-Option 1: Flat Structure (Legacy/Quick Start)
-├── PRODUCT.md                    # Single file with all features
-    OR
-├── .claude/product/
+Option 1: Flat Structure (Simple)
+└── .claude/product/
     └── index.md                  # Single file with all features
 
 Option 2: Hierarchical Structure (Organized)
@@ -53,11 +51,7 @@ if exists(".claude/product/domains/*/index.md"):
     use_domains = true
 else:
     # Step 2: Fall back to flat structure
-    if exists("PRODUCT.md"):
-        structure_type = "flat"
-        product_root = "."
-        use_domains = false
-    elif exists(".claude/product/index.md"):
+    if exists(".claude/product/index.md"):
         structure_type = "flat"
         product_root = ".claude/product"
         use_domains = false
@@ -67,8 +61,7 @@ else:
 
 **Priority Order:**
 1. Hierarchical (`.claude/product/domains/*/index.md`) - preferred for organized projects
-2. Flat (`PRODUCT.md`) - legacy quick-start format at root
-3. Flat (`.claude/product/index.md`) - new flat format in .claude directory
+2. Flat (`.claude/product/index.md`) - simple flat format for projects without domains
 
 ### Parsing Product Structure
 
@@ -105,9 +98,7 @@ if domain_files.length > 0:
 
 ```bash
 # 1. Detect structure
-if exists("PRODUCT.md"):
-    product_file = "PRODUCT.md"
-elif exists(".claude/product/index.md"):
+if exists(".claude/product/index.md"):
     product_file = ".claude/product/index.md"
 else:
     error("No product specification found")
@@ -549,7 +540,7 @@ Map to completion.json:
 
 ### Parsing Flat Product Structure
 
-Parse `PRODUCT.md` (or `.claude/product/index.md`) to extract feature list:
+Parse `.claude/product/index.md` to extract feature list:
 
 ```markdown
 ## Features
@@ -591,12 +582,11 @@ Always detect structure type before any operation:
 ```bash
 # Detect structure
 domains_found = Glob(".claude/product/domains/*/index.md")
-product_md_exists = exists("PRODUCT.md")
 product_index_exists = exists(".claude/product/index.md")
 
 if domains_found:
     use_hierarchical_tracking()
-else if product_md_exists or product_index_exists:
+else if product_index_exists:
     use_flat_tracking()
 else:
     error("No product specification found")
@@ -629,8 +619,8 @@ When subtask work completes:
 
 When orchestrator asks for progress update:
 
-1. Detect structure type (no domains, PRODUCT.md exists → flat)
-2. Determine product file: `PRODUCT.md` or `.claude/product/index.md`
+1. Detect structure type (no domains, `.claude/product/index.md` exists → flat)
+2. Read `.claude/product/index.md` for product specification
 3. Read completion.json
 4. Calculate overall percentage
 5. Identify next priority feature
@@ -650,5 +640,4 @@ When feature work completes:
 | Structure Type | Detection | Product File | Completion Schema | Tracking Method |
 |---------------|-----------|--------------|-------------------|-----------------|
 | Hierarchical | `.claude/product/domains/*/index.md` exists | `.claude/product/index.md` | Nested `domains` object | Track at subtask → feature → domain levels |
-| Flat (legacy) | `PRODUCT.md` exists | `PRODUCT.md` | Flat `features` object | Track at feature level |
-| Flat (new) | `.claude/product/index.md` exists | `.claude/product/index.md` | Flat `features` object | Track at feature level |
+| Flat | `.claude/product/index.md` exists | `.claude/product/index.md` | Flat `features` object | Track at feature level |

package/README.md

@@ -38,10 +38,10 @@ Use `/agentful-product` for guided product planning:
 
 #### Option B: Manual Creation
 
-Create your specification manually:
+Create your specification manually in `.claude/product/`:
 
-**Flat structure** (single file at project root):
-- `PRODUCT.md` - All features in one file
+**Flat structure** (single file):
+- `.claude/product/index.md` - All features in one file
 
 **Hierarchical structure** (organized by domain):
 - `.claude/product/index.md` - Product overview
@@ -195,10 +195,11 @@ Full documentation: [agentful.app](https://agentful.app)
 
 ```
 your-project/
-├── PRODUCT.md                      # Product specification (flat)
 ├── CLAUDE.md                       # Project instructions
 ├── .claude/
-│   ├── product/                    # Product specification (hierarchical)
+│   ├── product/                    # Product specification
+│   │   ├── index.md                # Product spec (flat or hierarchical)
+│   │   └── domains/                # Optional: hierarchical structure
 │   ├── agents/                     # Agent definitions
 │   ├── commands/                   # Slash commands
 │   ├── skills/                     # Reusable skills

package/bin/cli.js

@@ -131,7 +131,7 @@ async function init() {
   // Initialize using lib/init.js
   log(colors.dim, 'Copying templates...');
   try {
-    const result = await initProject(targetDir, { includeProduct: true });
+    const result = await initProject(targetDir);
 
     console.log('');
     log(colors.green, 'Initialized agentful successfully!');
@@ -161,7 +161,7 @@ async function init() {
   log(colors.dim, '  - Domain-specific agents (auth, billing, etc.)');
   log(colors.dim, '  - Skills for frameworks you use');
   console.log('');
-  log(colors.dim, 'Optional: Edit CLAUDE.md and PRODUCT.md first to customize.');
+  log(colors.dim, 'Optional: Edit CLAUDE.md and .claude/product/index.md first to customize.');
   console.log('');
 }
 

package/lib/init.js

@@ -9,12 +9,9 @@ const CLAUDE_DIR = path.join(__dirname, '..', '.claude');
 /**
  * Initialize agentful in a target project directory
  * @param {string} targetDir - Target project directory
- * @param {Object} options - Initialization options
- * @param {boolean} options.includeProduct - Whether to include PRODUCT.md template
  * @returns {Promise<{success: boolean, files: string[]}>}
  */
-export async function initProject(targetDir, options = {}) {
-  const { includeProduct = false } = options;
+export async function initProject(targetDir) {
   const createdFiles = [];
 
   try {
@@ -79,19 +76,271 @@ export async function initProject(targetDir, options = {}) {
     await fs.writeFile(decisionsFile, JSON.stringify(initialDecisions, null, 2));
     createdFiles.push('.agentful/decisions.json');
 
-    // 4. Optionally copy PRODUCT.md template
-    if (includeProduct) {
-      const productMdSource = path.join(TEMPLATE_DIR, 'PRODUCT.md');
-      const productMdTarget = path.join(targetDir, 'PRODUCT.md');
-
-      try {
-        await fs.access(productMdSource);
-        await fs.copyFile(productMdSource, productMdTarget);
-        createdFiles.push('PRODUCT.md');
-      } catch (err) {
-        // PRODUCT.md template doesn't exist, skip
-      }
-    }
+    // 4. Create .claude/product/ hierarchical structure
+    const productDir = path.join(targetDir, '.claude', 'product');
+    await fs.mkdir(productDir, { recursive: true });
+
+    // Create basic index.md template
+    const indexMdContent = `# Product Specification
+
+## Overview
+
+[Describe what you're building in 2-3 sentences]
+
+Example:
+> A task management application that helps teams collaborate on projects. Users can create projects, add tasks with deadlines, assign team members, and track progress with real-time updates.
+
+## Goals
+
+- [ ] [Primary goal 1]
+- [ ] [Primary goal 2]
+- [ ] [Primary goal 3]
+
+## Tech Stack
+
+### Frontend
+- **Framework**: [Next.js 14 / React + Vite / Vue + Nuxt / SvelteKit]
+- **Language**: [TypeScript / JavaScript]
+- **Styling**: [Tailwind CSS / CSS Modules / styled-components / shadcn/ui]
+- **State Management**: [Zustand / Context API / Redux / Jotai]
+
+### Backend
+- **Runtime**: [Node.js / Bun / Deno]
+- **Framework**: [Next.js API Routes / Express / Fastify / NestJS / Hono]
+- **Language**: [TypeScript / JavaScript]
+
+### Database
+- **Database**: [PostgreSQL / MySQL / SQLite / MongoDB / PlanetScale]
+- **ORM**: [Prisma / Drizzle / TypeORM / Mongoose]
+
+### Authentication
+- **Method**: [JWT / NextAuth / Clerk / Auth0 / Lucia]
+
+### Testing
+- **Unit**: [Vitest / Jest]
+- **E2E**: [Playwright / Cypress]
+
+### Deployment
+- **Hosting**: [Vercel / Netlify / Railway / Fly.io]
+
+## Domains
+
+Create domain-specific subdirectories under \`.claude/product/domains/\` to organize your features:
+
+\`\`\`
+.claude/product/
+├── index.md (this file)
+├── README.md
+└── domains/
+    ├── authentication/
+    │   ├── index.md
+    │   └── features/
+    │       ├── login.md
+    │       └── register.md
+    └── user-management/
+        ├── index.md
+        └── features/
+            └── profile.md
+\`\`\`
+
+See \`.claude/product/README.md\` for detailed structure guidance.
+
+## Architecture Notes
+
+### Design Patterns
+
+- [Any specific patterns to use]
+- [Any patterns to avoid]
+
+### Constraints
+
+- [Performance requirements]
+- [Accessibility requirements]
+- [Browser support requirements]
+
+## Third-Party Integrations (Optional)
+
+- [API 1]: [Purpose]
+- [API 2]: [Purpose]
+
+## Out of Scope (for MVP)
+
+List what you're explicitly NOT building:
+
+- [Feature X] - Will add in v2
+- [Feature Y] - Out of scope
+- [Feature Z] - Not needed
+
+## Success Criteria
+
+The product is complete when:
+
+1. [All critical features implemented and tested]
+2. [All tests passing with 80%+ coverage]
+3. [No TypeScript errors]
+4. [No security vulnerabilities]
+5. [Deployed to production]
+
+## Notes
+
+[Any additional context, links, or documentation]
+
+---
+
+**Tip**: The more detailed your product specification, the better agentful can understand what to build. Include:
+- Clear acceptance criteria
+- User stories for context
+- Technical constraints
+- Examples when helpful
+`;
+
+    const indexMdPath = path.join(productDir, 'index.md');
+    await fs.writeFile(indexMdPath, indexMdContent);
+    createdFiles.push('.claude/product/index.md');
+
+    // Create README.md explaining the structure
+    const readmeMdContent = `# Product Structure Guide
+
+agentful uses a hierarchical product structure to organize features by domain.
+
+## Structure
+
+\`\`\`
+.claude/product/
+├── index.md              # Product overview (name, description, tech stack)
+├── README.md             # This file - documentation about the structure
+└── domains/              # Business domains (create as needed)
+    ├── authentication/
+    │   ├── index.md      # Domain overview
+    │   └── features/
+    │       ├── login.md
+    │       └── register.md
+    └── user-management/
+        ├── index.md
+        └── features/
+            └── profile.md
+\`\`\`
+
+## Files Explained
+
+### \`index.md\` (Product Level)
+- Product name and description
+- Tech stack
+- High-level goals
+- List of domains
+- Architecture notes
+- Success criteria
+
+### \`domains/{domain-name}/index.md\` (Domain Level)
+- Domain description and purpose
+- List of features in this domain
+- Domain-specific constraints
+- Dependencies on other domains
+
+### \`domains/{domain-name}/features/{feature-name}.md\` (Feature Level)
+- Feature description
+- Priority (CRITICAL, HIGH, MEDIUM, LOW)
+- Acceptance criteria (checkboxes)
+- User stories
+- Technical notes
+- Subtasks breakdown
+
+## When to Create a Domain
+
+Create a new domain when you have:
+- A distinct business area (e.g., authentication, billing, analytics)
+- Multiple related features (e.g., login, register, password reset)
+- Shared logic or data models
+- Clear boundaries from other domains
+
+**Example domains:**
+- \`authentication\` - Login, registration, password reset
+- \`user-management\` - Profile, settings, preferences
+- \`purchasing\` - Cart, checkout, orders, payments
+- \`analytics\` - Dashboards, reports, metrics
+- \`content\` - Posts, comments, media uploads
+
+## Example Feature File
+
+\`\`\`markdown
+<!-- .claude/product/domains/authentication/features/login.md -->
+
+# Feature: User Login
+
+**Priority**: CRITICAL
+
+**Description**: Allow existing users to authenticate with email and password.
+
+## Acceptance Criteria
+
+- [ ] Login form with email and password fields
+- [ ] Client-side validation before submission
+- [ ] API endpoint POST /api/auth/login
+- [ ] Returns JWT token on success
+- [ ] Sets httpOnly cookie with token
+- [ ] Returns 401 for invalid credentials
+- [ ] Rate limited to 10 requests per minute
+- [ ] Account lockout after 5 failed attempts
+
+## User Stories
+
+- As a returning user, I want to log in with my credentials so that I can access my account
+
+## Subtasks
+
+### 1. Create login form UI
+**Status**: pending
+
+- [ ] Email and password input fields
+- [ ] "Remember me" checkbox
+- [ ] "Forgot password" link
+- [ ] Loading state during authentication
+- [ ] Error message display
+
+### 2. Implement login API endpoint
+**Status**: pending
+
+- [ ] Verify email exists in database
+- [ ] Compare hashed password using bcrypt
+- [ ] Generate JWT token with 7-day expiration
+- [ ] Set secure httpOnly cookie
+- [ ] Implement rate limiting
+- [ ] Track failed login attempts
+
+## Technical Notes
+
+- Use jose or jsonwebtoken for JWT
+- Store failed attempts in Redis
+- Set cookie flags: httpOnly, secure, sameSite=strict
+\`\`\`
+
+## Priority Levels
+
+- **CRITICAL** - Must have for MVP, blocks other features
+- **HIGH** - Important for MVP, should include
+- **MEDIUM** - Nice to have if time permits
+- **LOW** - Future enhancement, not for MVP
+
+## Status Tracking
+
+- \`pending\` - Not started
+- \`in-progress\` - Currently being worked on
+- \`complete\` - Done and tested
+- \`blocked\` - Waiting for decision or dependency
+
+## Getting Started
+
+1. Edit \`index.md\` to describe your product
+2. Create domains under \`domains/\` for major functional areas
+3. Add features under each domain's \`features/\` directory
+4. Run \`/agentful-start\` in Claude Code to begin development
+
+For more information, see the agentful documentation.
+`;
+
+    const readmeMdPath = path.join(productDir, 'README.md');
+    await fs.writeFile(readmeMdPath, readmeMdContent);
+    createdFiles.push('.claude/product/README.md');
 
     return {
       success: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Human-in-the-loop development kit for Claude Code with smart product analysis and natural conversation",
   "type": "module",
   "bin": {

package/template/CLAUDE.md

@@ -4,7 +4,7 @@
 
 ## Quick Start
 
-1. Edit `PRODUCT.md` (or `.claude/product/` for larger projects)
+1. Edit `.claude/product/index.md` to define your product requirements
 2. Run: `claude`
 3. Type: `/agentful-start`
 
@@ -28,7 +28,7 @@ claude --dangerously-skip-permissions
 ## When to Use What
 
 **Starting fresh?**
-→ Run `/agentful-product` to analyze your PRODUCT.md, then `/agentful-start`
+→ Run `/agentful-product` to analyze your product spec, then `/agentful-start`
 
 **Existing project?**
 → Run `/agentful-start` directly (auto-detects tech stack)
@@ -43,16 +43,16 @@ claude --dangerously-skip-permissions
 → Check `.agentful/decisions.json` or run `/agentful-decide`
 
 **Unclear requirements?**
-→ Run `/agentful-product` in reverse-engineering mode or improve PRODUCT.md
+→ Run `/agentful-product` in reverse-engineering mode or improve `.claude/product/index.md`
 
 **Want to add features?**
-→ Edit PRODUCT.md, then run `/agentful-start` (picks up changes automatically)
+→ Edit `.claude/product/index.md`, then run `/agentful-start` (picks up changes automatically)
 
 ## File Structure
 
 **Product Specification** (you edit these):
-- `PRODUCT.md` - Flat structure (recommended for <20 features)
-- `.claude/product/` - Hierarchical structure (for larger projects)
+- `.claude/product/index.md` - Flat structure (all features in one file)
+- `.claude/product/domains/` - Hierarchical structure (organized by domain)
 
 **Runtime State** (managed by agentful, gitignored):
 - `.agentful/state.json` - Current work phase and progress
@@ -81,22 +81,22 @@ The `reviewer` agent runs these checks automatically. The `fixer` agent resolves
 ## Troubleshooting
 
 **"agentful keeps asking me unclear questions"**
-→ Your PRODUCT.md needs more detail. Run `/agentful-product` to analyze and improve it.
+→ Your product spec needs more detail. Run `/agentful-product` to analyze and improve it.
 
 **"Validation keeps failing"**
 → Check `.agentful/last-validation.json` for details. The `fixer` agent should auto-resolve, but you can run `/agentful-validate` manually.
 
 **"Agent isn't working on the right feature"**
-→ Check priority in PRODUCT.md. CRITICAL > HIGH > MEDIUM > LOW. Run `/agentful-status` to see current focus.
+→ Check priority in `.claude/product/index.md`. CRITICAL > HIGH > MEDIUM > LOW. Run `/agentful-status` to see current focus.
 
 **"State seems stuck or corrupted"**
 → Delete `.agentful/state.json` and run `/agentful-start` to reset. Completion progress is preserved.
 
 **"Tech stack not detected correctly"**
-→ Add explicit tech stack section to PRODUCT.md or check `.agentful/architecture.json` for what was detected.
+→ Add explicit tech stack section to `.claude/product/index.md` or check `.agentful/architecture.json` for what was detected.
 
-**"How do I switch from flat to hierarchical product structure?"**
-→ Run `/agentful-product migrate` or manually create `.claude/product/index.md` and move content. Auto-detected.
+**"How do I expand to hierarchical product structure?"**
+→ Create `.claude/product/domains/` directories and organize features by domain. Auto-detected.
 
 **"Agent generated wrong type of code"**
 → Check that the right specialized agent was generated. Run `/agents` to list all agents.

package/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.2.1"
+  "version": "0.3.0"
 }

package/template/PRODUCT.md

@@ -1,584 +0,0 @@
-# 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]
-
-Example:
-> A task management application that helps teams collaborate on projects. Users can create projects, add tasks with deadlines, assign team members, and track progress with real-time updates.
-
-## Goals
-
-- [ ] [Primary goal 1]
-- [ ] [Primary goal 2]
-- [ ] [Primary goal 3]
-
-## Tech Stack
-
-### Frontend
-- **Framework**: [Next.js 14 / React + Vite / Vue + Nuxt / SvelteKit]
-- **Language**: [TypeScript / JavaScript]
-- **Styling**: [Tailwind CSS / CSS Modules / styled-components / shadcn/ui]
-- **State Management**: [Zustand / Context API / Redux / Jotai]
-
-### Backend
-- **Runtime**: [Node.js / Bun / Deno]
-- **Framework**: [Next.js API Routes / Express / Fastify / NestJS / Hono]
-- **Language**: [TypeScript / JavaScript]
-
-### Database
-- **Database**: [PostgreSQL / MySQL / SQLite / MongoDB / PlanetScale]
-- **ORM**: [Prisma / Drizzle / TypeORM / Mongoose]
-
-### Authentication
-- **Method**: [JWT / NextAuth / Clerk / Auth0 / Lucia]
-
-### Testing
-- **Unit**: [Vitest / Jest]
-- **E2E**: [Playwright / Cypress]
-
-### Deployment
-- **Hosting**: [Vercel / Netlify / Railway / Fly.io]
-
-## Product Structure
-
-This product is organized into **domains**, which contain **features**, which break down into **subtasks**.
-
-### Hierarchical Structure
-
-```
-Product
-└── Domain (e.g., authentication)
-    └── Feature (e.g., login)
-        └── Subtask (e.g., create login form)
-```
-
-**Definitions**:
-- **Domain**: A major functional area (e.g., authentication, purchasing, user-management)
-- **Feature**: A specific capability within a domain (e.g., login, registration, password-reset)
-- **Subtask**: An implementable unit of work (e.g., create UI form, implement API endpoint)
-
-**Priority Levels**:
-- `CRITICAL` - Must have for MVP, blocks other features
-- `HIGH` - Important for MVP, should include
-- `MEDIUM` - Nice to have if time permits
-- `LOW` - Future enhancement, not for MVP
-
-**Status Tracking**:
-- `pending` - Not started
-- `in-progress` - Currently being worked on
-- `complete` - Done and tested
-- `blocked` - Waiting for decision or dependency
-
----
-
-## Domain: Authentication
-
-### Feature: User Registration - CRITICAL
-**Description**: Allow new users to create accounts
-
-**Subtasks**:
-
-#### 1. Create registration form UI - CRITICAL
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Form includes email, password, and confirm password fields
-- [ ] Email validation with regex pattern
-- [ ] Password minimum 8 characters with requirements shown
-- [ ] Password match validation
-- [ ] Submit button disabled until all valid
-- [ ] Loading state during submission
-- [ ] Error messages display inline
-- [ ] Responsive design (mobile and desktop)
-
-**User Stories**:
-- As a new user, I want to create an account with email and password so that I can access the application
-
-**Technical Notes**:
-- Use React Hook Form or similar
-- Zod validation schema
-- Tailwind CSS for styling
-
----
-
-#### 2. Implement registration API endpoint - CRITICAL
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] POST /api/auth/register endpoint created
-- [ ] Validates email format and uniqueness
-- [ ] Hashes password using bcrypt (cost factor 10)
-- [ ] Creates user in database
-- [ ] Returns 201 on success with user object (excluding password)
-- [ ] Returns 400 for validation errors with specific messages
-- [ ] Returns 409 if email already exists
-- [ ] Rate limited to 5 requests per minute per IP
-
-**Technical Notes**:
-- Use Prisma/Drizzle for database operations
-- Implement rate limiting middleware
-- Log registration attempts for monitoring
-
----
-
-### Feature: User Login - CRITICAL
-**Description**: Allow existing users to authenticate
-
-**Subtasks**:
-
-#### 1. Create login form UI - CRITICAL
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Form includes email and password fields
-- [ ] "Remember me" checkbox
-- [ ] "Forgot password" link
-- [ ] Link to registration page
-- [ ] Client-side validation before submission
-- [ ] Loading state during authentication
-- [ ] Clear error messages (invalid credentials, account locked, etc.)
-
-**User Stories**:
-- As a returning user, I want to log in with my credentials so that I can access my account
-
----
-
-#### 2. Implement login API endpoint - CRITICAL
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] POST /api/auth/login endpoint created
-- [ ] Verifies email exists in database
-- [ ] Compares hashed password using bcrypt
-- [ ] Generates JWT token with 7-day expiration
-- [ ] Sets httpOnly cookie with token
-- [ ] Returns 200 with user object on success
-- [ ] Returns 401 for invalid credentials
-- [ ] Implements account lockout after 5 failed attempts
-- [ ] Rate limited to 10 requests per minute
-
-**Technical Notes**:
-- Use jose or jsonwebtoken for JWT
-- Store failed attempts in Redis or database
-- Set secure cookie flags: httpOnly, secure, sameSite
-
----
-
-### Feature: Password Reset - HIGH
-**Description**: Allow users to reset forgotten passwords
-
-**Subtasks**:
-
-#### 1. Create forgot password form - HIGH
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Single email input field
-- [ ] Submit button to send reset link
-- [ ] Success message: "If email exists, reset link sent"
-- [ ] Rate limited to 3 requests per hour
-
-**User Stories**:
-- As a user, I want to request a password reset email so that I can regain access to my account
-
----
-
-#### 2. Implement password reset email flow - HIGH
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Generates secure reset token (UUID, expires in 1 hour)
-- [ ] Stores token in database with expiration
-- [ ] Sends email with reset link containing token
-- [ ] Validates token on reset attempt
-- [ ] Updates password after validation
-- [ ] Invalidates token after use
-- [ ] Uses transaction for database updates
-
-**Technical Notes**:
-- Use Resend, SendGrid, or AWS SES for emails
-- Store hashed token in database
-- Background job for email sending
-
----
-
-## Domain: Purchasing
-
-### Feature: Product Catalog - CRITICAL
-**Description**: Display and browse available products
-
-**Subtasks**:
-
-#### 1. Create product listing page - CRITICAL
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Grid layout showing product cards
-- [ ] Each card displays: image, name, price, short description
-- [ ] Pagination or infinite scroll (20 items per page)
-- [ ] Loading skeleton while fetching
-- [ ] Empty state message when no products
-- [ ] Clicking card navigates to product detail page
-- [ ] Mobile-responsive (1 column) and desktop (3-4 columns)
-
-**User Stories**:
-- As a customer, I want to browse products so that I can see what's available
-
-**Technical Notes**:
-- Use virtual scrolling for performance
-- Cache product list for 5 minutes
-- Lazy load images
-
----
-
-#### 2. Implement product API endpoints - CRITICAL
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] GET /api/products endpoint with pagination (page, limit)
-- [ ] Supports filtering by category, price range
-- [ ] Supports sorting by name, price, date
-- [ ] Returns 200 with products array and metadata
-- [ ] Returns 400 for invalid query parameters
-- [ ] Response time < 200ms p95
-
-**Technical Notes**:
-- Use database indexes on category and price
-- Implement query validation schema
-- Cache popular queries
-
----
-
-### Feature: Shopping Cart - HIGH
-**Description**: Allow users to manage cart items
-
-**Subtasks**:
-
-#### 1. Create cart UI components - HIGH
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Cart icon in header showing item count badge
-- [ ] Cart drawer/modal for quick access
-- [ ] Full cart page with item list
-- [ ] Each item shows: image, name, price, quantity controls
-- [ ] Remove item button with confirmation
-- [ ] Subtotal calculation
-- [ ] "Checkout" button
-- [ ] Empty cart state with call-to-action
-
-**User Stories**:
-- As a customer, I want to view and edit my cart so that I can review items before purchase
-
----
-
-#### 2. Implement cart state management - HIGH
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Cart persisted in localStorage
-- [ ] Sync cart state across tabs (storage event listener)
-- [ ] Add to cart action (with quantity)
-- [ ] Remove from cart action
-- [ ] Update quantity action
-- [ ] Clear cart action
-- [ ] Calculate totals (subtotal, tax, shipping)
-- [ ] Merge guest cart with user cart on login
-
-**Technical Notes**:
-- Use Zustand or Redux for state
-- Debounce localStorage writes
-- Validate cart integrity on load
-
----
-
-## Domain: User Management
-
-### Feature: User Profile - HIGH
-**Description**: Allow users to view and edit their profile
-
-**Subtasks**:
-
-#### 1. Create profile page UI - HIGH
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Display user information: name, email, avatar
-- [ ] Editable fields: name, bio, location
-- [ ] Avatar upload with preview
-- [ ] Save button with loading state
-- [ ] Success notification on save
-- [ ] "Change password" section
-- [ ] "Delete account" danger zone
-
-**User Stories**:
-- As a user, I want to edit my profile so that I can keep my information up to date
-
-**Technical Notes**:
-- Use file upload API for avatar (max 2MB, images only)
-- Client-side image optimization before upload
-- Confirmation modal for account deletion
-
----
-
-#### 2. Implement profile API endpoints - HIGH
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] GET /api/user/profile - Returns current user profile
-- [ ] PATCH /api/user/profile - Updates profile fields
-- [ ] POST /api/user/avatar - Uploads avatar image
-- [ ] DELETE /api/user/account - Deletes account (requires confirmation)
-- [ ] All endpoints require authentication
-- [ ] Returns 401 if not authenticated
-- [ ] Validates file type and size for avatar
-
-**Technical Notes**:
-- Use S3 or Cloudflare R2 for image storage
-- Generate unique filename for avatars
-- Soft delete for user accounts
-- Log all profile changes
-
----
-
-### Feature: User Roles - MEDIUM
-**Description**: Implement role-based access control
-
-**Subtasks**:
-
-#### 1. Define role system - MEDIUM
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Database schema for roles (user, admin, moderator)
-- [ ] User-role many-to-many relationship
-- [ ] Seed default roles in database
-- [ ] Utility function to check user role
-- [ ] Middleware to protect routes by role
-- [ ] Type definitions for role-based permissions
-
-**User Stories**:
-- As an admin, I want to have elevated permissions so that I can manage the application
-- As a developer, I want role-based access control so that I can secure sensitive features
-
-**Technical Notes**:
-- Use enum for role names
-- Cache user roles in JWT for fast access
-- Create RBAC policy definitions
-
----
-
-#### 2. Implement role-based UI - MEDIUM
-**Status**: pending
-
-**Acceptance Criteria**:
-- [ ] Admin dashboard visible only to admins
-- [ ] User management page for admins
-- [ ] Role assignment interface
-- [ ] Permission checks on client side (UI only)
-- [ ] Graceful fallback for unauthorized access
-
-**User Stories**:
-- As an admin, I want to manage user roles so that I can control access
-
-**Technical Notes**:
-- Server-side validation is the source of truth
-- Client-side checks only for UI/UX
-- Log all role changes
-
----
-
-## Architecture Notes
-
-### Folder Structure (Optional)
-
-If you have a preferred structure:
-
-```
-src/
-├── app/              # Next.js app router
-├── components/       # React components
-│   ├── auth/         # Authentication components
-│   ├── product/      # Product components
-│   └── cart/         # Cart components
-├── lib/              # Utilities
-├── hooks/            # Custom hooks
-└── styles/           # Global styles
-```
-
-### Design Patterns
-
-- [Any specific patterns to use]
-- [Any patterns to avoid]
-
-### Constraints
-
-- [Performance requirements]
-- [Accessibility requirements]
-- [Browser support requirements]
-
-## Third-Party Integrations (Optional)
-
-- [API 1]: [Purpose]
-- [API 2]: [Purpose]
-
-## Out of Scope (for MVP)
-
-List what you're explicitly NOT building:
-
-- [Feature X] - Will add in v2
-- [Feature Y] - Out of scope
-- [Feature Z] - Not needed
-
-## Success Criteria
-
-The product is complete when:
-
-1. [All CRITICAL features implemented and tested]
-2. [All HIGH priority features implemented or documented]
-3. [All tests passing with 80%+ coverage]
-4. [No TypeScript errors]
-5. [No security vulnerabilities]
-6. [Deployed to production]
-
-## Notes
-
-[Any additional context, links, or documentation]
-
----
-
-## Template Guide
-
-### How to Use This Template
-
-1. **Keep the structure**: Maintain the domains → features → subtasks hierarchy
-2. **Be specific**: Write detailed acceptance criteria for each subtask
-3. **Think sequentially**: Order subtasks in implementation order
-4. **Set priorities**: Use CRITICAL/HIGH/MEDIUM/LOW to guide development
-5. **Track progress**: Update status as features are complete
-
-### Example Domain Breakdown
-
-```
-Authentication (Domain)
-├── User Registration (Feature)
-│   ├── Create registration form UI (Subtask) - CRITICAL
-│   └── Implement registration API endpoint (Subtask) - CRITICAL
-├── User Login (Feature)
-│   ├── Create login form UI (Subtask) - CRITICAL
-│   └── Implement login API endpoint (Subtask) - CRITICAL
-└── Password Reset (Feature)
-    ├── Create forgot password form (Subtask) - HIGH
-    └── Implement password reset email flow (Subtask) - HIGH
-```
-
-### Acceptance Criteria Format
-
-Each subtask should have:
-- **Status**: pending → in-progress → complete (or blocked)
-- **Checkbox list**: [ ] Specific, testable requirements
-- **User stories**: As a [role], I want [feature] so that [benefit]
-- **Technical notes**: Implementation details and constraints
-
-### Why This Structure Works
-
-- **Domains** organize work by functional area
-- **Features** break domains into user-facing capabilities
-- **Subtasks** create implementable units that can be completed in one session
-- **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:
-- 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!