@itz4blitz/agentful 0.2.1 → 0.4.0

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-generate.md

@@ -0,0 +1,206 @@
+---
+name: agentful-generate
+description: Analyze codebase and generate domain agents + tech skills based on your stack
+---
+
+# /agentful-generate
+
+Analyze codebase, detect tech stack, discover business domains, generate domain agents and tech skills.
+
+## Key Concepts
+
+**Agents** = Actors that DO work. They have tools, write code, make decisions.
+- Core agents: backend, frontend, tester, reviewer, fixer (already included)
+- Domain agents: books, auth, billing, orders (generated based on your code)
+
+**Skills** = Knowledge that agents REFERENCE. Documentation and patterns.
+- Tech skills: react, express, prisma, nextjs (generated based on your stack)
+
+## Workflow
+
+### Step 1: Detect Tech Stack
+
+**Read**: package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, prisma/schema.prisma
+
+**Detect**:
+- Language: TypeScript, JavaScript, Python, Go, Rust
+- Framework: Next.js, React, Vue, Express, NestJS, Django, Flask, FastAPI
+- ORM: Prisma, Drizzle, TypeORM, Mongoose, SQLAlchemy
+- Database: PostgreSQL, MySQL, MongoDB, SQLite
+- Testing: Vitest, Jest, Playwright, pytest
+
+### Step 2: Discover Business Domains
+
+**Scan**: src/**/*, API routes, services, models, components
+
+**Evidence scoring**:
+- Directory named after domain: +10 (src/auth/, src/billing/)
+- API routes for domain: +15 (api/auth/*, routes/books.ts)
+- Service/controller files: +8 (authService.ts, bookController.ts)
+- Database models: +5 (User, Book, Order)
+- Frontend pages/components: +5 (Books.tsx, AuthorCard.tsx)
+
+**Confidence** = score / 50 * 100 (max 100%)
+
+**Threshold**: Only generate domain agent if confidence >= 75%
+
+### Step 3: Plan Generation
+
+**Show plan to user**:
+
+```
+Tech Stack Detected:
+  - TypeScript
+  - React 18 + Vite
+  - Express 4
+  - Prisma + SQLite
+
+Domains Discovered:
+  - books (95% confidence) ✓ Will generate agent
+  - authors (95% confidence) ✓ Will generate agent
+  - stats (85% confidence) ✓ Will generate agent
+  - payments (40% confidence) ✗ Below threshold
+
+Will Generate:
+
+  Domain Agents (3):
+    .claude/agents/books.md
+    .claude/agents/authors.md
+    .claude/agents/stats.md
+
+  Tech Skills (4):
+    .claude/skills/react/SKILL.md
+    .claude/skills/express/SKILL.md
+    .claude/skills/prisma/SKILL.md
+    .claude/skills/typescript/SKILL.md
+
+Proceed? (y/n)
+```
+
+**Wait for confirmation before generating.**
+
+### Step 4: Generate Domain Agents
+
+Create `.claude/agents/<domain>.md` for each domain with confidence >= 75%:
+
+```markdown
+---
+name: <domain>
+description: <Domain> domain - <brief description based on evidence>
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# <Domain> Agent
+
+## Your Scope
+[List responsibilities based on discovered files]
+
+## Domain Structure
+[List actual files discovered - services, controllers, routes, components]
+
+## Implementation Guidelines
+[Patterns specific to this domain, derived from existing code]
+
+## Boundaries
+- Handles: [what this agent owns]
+- Delegates to @backend: [general backend patterns]
+- Delegates to @frontend: [general frontend patterns]
+- Delegates to @tester: [testing]
+
+## Rules
+1. Stay within domain boundaries
+2. Follow existing patterns in this domain
+3. Coordinate with related domains via clear interfaces
+```
+
+### Step 5: Generate Tech Skills
+
+Create `.claude/skills/<tech>/SKILL.md` for each detected technology:
+
+```markdown
+---
+name: <tech>
+description: <Tech> patterns and best practices for this project
+---
+
+# <Tech> Skill
+
+## Overview
+[Brief intro - what this tech does in this project]
+
+## Project Configuration
+[Detected version, settings from package.json/config files]
+
+## Common Patterns
+[3-5 patterns with code examples from THIS project's style]
+
+## Best Practices
+[Numbered list specific to this project's usage]
+
+## Common Pitfalls
+[What to avoid]
+
+## References
+[Official docs links]
+```
+
+### Step 6: Create architecture.json
+
+Write to `.agentful/architecture.json`:
+
+```json
+{
+  "techStack": {
+    "languages": ["TypeScript"],
+    "frontend": { "framework": "React", "version": "18.x" },
+    "backend": { "framework": "Express", "version": "4.x" },
+    "database": { "type": "SQLite", "orm": "Prisma" },
+    "testing": ["Vitest", "Jest"]
+  },
+  "domains": [
+    { "name": "books", "confidence": 95 },
+    { "name": "authors", "confidence": 95 }
+  ],
+  "generatedAgents": ["books", "authors"],
+  "generatedSkills": ["react", "express", "prisma", "typescript"],
+  "analyzedAt": "2026-01-20T00:00:00Z"
+}
+```
+
+### Step 7: Report Results
+
+```
+✅ Generation Complete
+
+Domain Agents (2):
+  ✓ .claude/agents/books.md (95%)
+  ✓ .claude/agents/authors.md (95%)
+
+Tech Skills (4):
+  ✓ .claude/skills/react/SKILL.md
+  ✓ .claude/skills/express/SKILL.md
+  ✓ .claude/skills/prisma/SKILL.md
+  ✓ .claude/skills/typescript/SKILL.md
+
+Architecture saved to .agentful/architecture.json
+
+Usage:
+  @books add new field to book model
+  @authors implement author search
+  @backend (uses express, prisma skills automatically)
+  @frontend (uses react skill automatically)
+
+Rerun /agentful-generate when codebase structure changes.
+```
+
+## Rules
+
+1. **Agents are ACTORS** - Only create agents for business domains (books, auth, billing)
+2. **Skills are KNOWLEDGE** - Create skills for technologies (react, express, prisma)
+3. **Never create tech agents** - No react.md agent, no express.md agent
+4. **Domain threshold is 75%** - Don't create agents for low-confidence domains
+5. **Always show plan first** - Wait for user confirmation before generating
+6. **Use real code examples** - Sample actual project files for patterns
+7. **Don't duplicate core agents** - backend, frontend, tester already exist
+8. **Create architecture.json** - Track what was generated for health checks

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!