@itz4blitz/agentful 0.1.11 → 0.2.1

package/template/CLAUDE.md

@@ -1,19 +1,14 @@
-# agentful Product Development
+# agentful
 
-This project uses **agentful** for autonomous product development.
+**agentful** is an autonomous product development framework that uses specialized AI agents to build software from a product specification. It coordinates architecture, development, testing, and validation through human-in-the-loop checkpoints, ensuring quality while maintaining 24/7 development velocity.
 
 ## Quick Start
 
-1. Edit your product specification:
-   - **Flat structure** (recommended for beginners): Edit `PRODUCT.md` at project root
-   - **Hierarchical structure** (for larger projects): Edit files in `.claude/product/`
+1. Edit `PRODUCT.md` (or `.claude/product/` for larger projects)
 2. Run: `claude`
 3. Type: `/agentful-start`
 
-That's it. agentful will begin autonomous development.
-
-## For 24/7 Development
-
+For extended sessions:
 ```bash
 claude --dangerously-skip-permissions
 /ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"
@@ -23,215 +18,100 @@ claude --dangerously-skip-permissions
 
 | Command | Description |
 |---------|-------------|
-| `/agentful-start` | Begin or resume autonomous development |
-| `/agentful-status` | Check current progress |
-| `/agentful-decide` | Answer pending decisions |
-| `/agentful-validate` | Run all quality checks |
-
-## Agents
-
-agentful uses specialized agents that work together:
-
-| Agent | Purpose |
-|-------|---------|
-| `orchestrator` | Coordinates all work, never codes directly |
-| `architect` | Analyzes tech stack and generates specialized agents |
-| `backend` | Services, repositories, controllers, APIs |
-| `frontend` | Components, pages, hooks, styling |
-| `tester` | Unit, integration, E2E tests |
-| `reviewer` | Code review, dead code detection, quality gates |
-| `fixer` | Fixes validation failures automatically |
-
-## State Files
-
-Progress is tracked in `.agentful/`:
-
-- `state.json` - Current work state and phase
-- `completion.json` - Feature completion percentages and quality gates
-- `decisions.json` - Pending and resolved decisions
-- `last-validation.json` - Most recent validation report
-
-## Product Specification
-
-Your product is defined in one of two formats:
-
-### Flat Structure (Recommended for Beginners)
-
-- **Location**: `PRODUCT.md` at project root
-- **Format**: Single file with all features
-- **Best for**: Small projects, MVPs, quick prototypes
-
-### Hierarchical Structure (For Larger Projects)
-
-- **Location**: `.claude/product/` directory
-- **Format**: Multiple files organized by domain
-- **Best for**: Large projects, teams, complex products
-
-The system auto-detects which format you're using. Both formats contain:
-
-- Overview and goals
-- Tech stack decisions
-- Feature list with priorities
-- Acceptance criteria
-- Architecture notes
-
-### Choosing the Right Structure
-
-**Start with flat structure if:**
-- You're new to agentful
-- Building an MVP or prototype
-- Project has less than 20 features
-- Working alone or in a small team
-
-**Use hierarchical structure if:**
-- Project has 20+ features across multiple domains
-- Multiple team members need to edit specs simultaneously
-- You need better organization for complex projects
-- Your PRODUCT.md file is getting too long (500+ lines)
-
-### Migrating Between Formats
-
-You can start with flat and migrate to hierarchical as your project grows. See the migration guide in your product specification file for detailed instructions.
-
-The system auto-detects format changes automatically - no configuration needed!
-
-## How It Works
-
-```mermaid
-flowchart LR
-    Start([🚀 Initialize<br/>npx @itz4blitz/agentful init]) --> Define[📝 Define Product<br/>Edit PRODUCT.md]
-    Define --> Build[⚡ Start Building<br/>/agentful-start]
-    Build --> Loop{🔄 24/7 Development Loop}
-
-    Loop --> Spec[📋 Your Specs<br/>PRODUCT.md]
-    Loop --> Tech[🛠️ Tech Stack<br/>Auto-detected]
-    Loop --> Dev[🤖 Autonomous Development]
-    Loop --> Complete[✅ 100% Complete]
-
-    Spec --> Agents[Specialized Agents]
-    Tech --> Agents
-    Agents --> Dev
-    Dev --> Validate[Quality Gates]
-    Validate -->|❌ Fix| Dev
-    Validate -->|✅ Pass| Update[Update Progress]
-    Update --> Check{Done?}
-    Check -->|No| Loop
-    Check -->|Yes| Complete([🎉 Complete!])
-
-    style Start fill:#10b981,stroke:#059669,color:#fff
-    style Define fill:#3b82f6,stroke:#2563eb,color:#fff
-    style Build fill:#8b5cf6,stroke:#7c3aed,color:#fff
-    style Loop fill:#f59e0b,stroke:#d97706,color:#fff
-    style Agents fill:#06b6d4,stroke:#0891b2,color:#fff
-    style Dev fill:#ec4899,stroke:#db2777,color:#fff
-    style Validate fill:#f97316,stroke:#ea580c,color:#fff
-    style Update fill:#84cc16,stroke:#65a30d,color:#fff
-    style Complete fill:#10b981,stroke:#059669,color:#fff
-```
+| `/agentful-start` | Begin or resume structured development |
+| `/agentful-status` | Check current progress and completion % |
+| `/agentful-decide` | Answer pending decisions blocking work |
+| `/agentful-validate` | Run all quality checks manually |
+| `/agentful-product` | Analyze and improve product specification |
+| `/agents` | List all available specialized agents |
 
-1. **Initialization** - Architect analyzes PRODUCT.md and generates tech-specific agents
-2. **Planning** - Orchestrator reads state and picks next priority task
-3. **Implementation** - Specialist agents implement features
-4. **Validation** - Reviewer runs quality checks
-5. **Fixing** - Fixer resolves any issues found
-6. **Iteration** - Loop continues until 100% complete
+## When to Use What
 
-## Quality Gates
+**Starting fresh?**
+→ Run `/agentful-product` to analyze your PRODUCT.md, then `/agentful-start`
 
-Code must pass all gates before completion:
+**Existing project?**
+→ Run `/agentful-start` directly (auto-detects tech stack)
 
-- ✅ All tests passing
-- ✅ No TypeScript errors
-- ✅ No dead code (unused exports, files, dependencies)
-- ✅ Test coverage ≥ 80%
-- ✅ No security issues
+**Need to check progress?**
+→ Run `/agentful-status` to see completion % and current phase
 
-## Decision Handling
+**Validation failures?**
+→ The `fixer` agent auto-fixes issues, or run `/agentful-validate` manually
 
-When agentful needs your input:
+**Agent needs your input?**
+→ Check `.agentful/decisions.json` or run `/agentful-decide`
 
-1. Question is added to `decisions.json`
-2. Development continues on unblocked features
-3. Run `/agentful-decide` to answer
-4. agentful resumes blocked work
+**Unclear requirements?**
+→ Run `/agentful-product` in reverse-engineering mode or improve PRODUCT.md
 
-## Tech Stack Auto-Detection
+**Want to add features?**
+→ Edit PRODUCT.md, then run `/agentful-start` (picks up changes automatically)
 
-agentful automatically detects your tech stack from:
-- Product specification (`PRODUCT.md` or `.claude/product/index.md`) - Explicit tech stack section
-- `package.json` - Dependencies and frameworks
-- Existing code - File patterns and imports
+## File Structure
 
-It then generates specialized agents for your specific stack.
+**Product Specification** (you edit these):
+- `PRODUCT.md` - Flat structure (recommended for <20 features)
+- `.claude/product/` - Hierarchical structure (for larger projects)
 
-## Example Flow
+**Runtime State** (managed by agentful, gitignored):
+- `.agentful/state.json` - Current work phase and progress
+- `.agentful/completion.json` - Feature completion % and quality gates
+- `.agentful/decisions.json` - Pending and resolved decisions
+- `.agentful/last-validation.json` - Most recent validation report
+- `.agentful/architecture.json` - Detected tech stack and generated agents
 
-```
-You: /agentful-start
+**Configuration** (auto-generated, customizable):
+- `.claude/agents/` - Specialized agents for your tech stack
+- `.claude/commands/` - Slash commands
+- `.claude/settings.json` - Hooks and permissions
+
+## Quality Gates
 
-agentful: Detected Next.js + TypeScript + Prisma + Tailwind
-         → Generated nextjs-agent, prisma-agent, tailwind-agent
+Every feature must pass validation before marked complete:
 
-agentful: Starting work on authentication (priority: CRITICAL)
-         → @backend implementing JWT service
-         → @backend implementing login API route
-         → @frontend creating login page
-         → @tester writing auth tests
+- **Tests** - All tests passing with ≥80% coverage
+- **TypeScript** - No type errors (if using TypeScript)
+- **Dead Code** - No unused exports, files, or dependencies
+- **Security** - No known vulnerabilities in dependencies
+- **Linting** - Code follows project style guide
 
-agentful: Running validation...
-         → TypeScript: ✅
-         → Lint: ✅
-         → Tests: ✅
-         → Coverage: 82% ✅
-         → Dead code: ✅
-         → Security: ✅
+The `reviewer` agent runs these checks automatically. The `fixer` agent resolves failures.
 
-agentful: Authentication complete (100%)
-         Next: User profile feature...
+## Troubleshooting
 
-[Continues 24/7 until complete]
-```
+**"agentful keeps asking me unclear questions"**
+→ Your PRODUCT.md needs more detail. Run `/agentful-product` to analyze and improve it.
 
-## Customization
+**"Validation keeps failing"**
+→ Check `.agentful/last-validation.json` for details. The `fixer` agent should auto-resolve, but you can run `/agentful-validate` manually.
 
-All agents and commands can be customized in `.claude/`:
+**"Agent isn't working on the right feature"**
+→ Check priority in PRODUCT.md. CRITICAL > HIGH > MEDIUM > LOW. Run `/agentful-status` to see current focus.
 
-- `.claude/agents/` - Add or modify agents
-- `.claude/commands/` - Add or modify commands
-- `.claude/skills/` - Add domain-specific skills
+**"State seems stuck or corrupted"**
+→ Delete `.agentful/state.json` and run `/agentful-start` to reset. Completion progress is preserved.
 
-## Getting Help
+**"Tech stack not detected correctly"**
+→ Add explicit tech stack section to PRODUCT.md or check `.agentful/architecture.json` for what was detected.
 
-If agentful gets stuck:
+**"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.
 
-1. Run `/agentful-status` to see current state
-2. Check your product specification (`PRODUCT.md` or `.claude/product/`) for unclear requirements
-3. Run `/agentful-decide` if decisions are pending
-4. Run `/agentful-validate` to check for issues
+**"Agent generated wrong type of code"**
+→ Check that the right specialized agent was generated. Run `/agents` to list all agents.
 
-## Architecture
+**"Need to rollback or restart a feature"**
+→ Edit completion % in `.agentful/completion.json` for specific feature, then run `/agentful-start`.
 
-```
-.your-project/
-├── PRODUCT.md              # Your product spec - flat structure (you edit this)
-├── CLAUDE.md               # This file
-├── .claude/                # agentful configuration
-│   ├── product/            # Product spec - hierarchical structure (alternative)
-│   │   ├── index.md        # Product overview
-│   │   └── domains/        # Domain-specific specs
-│   ├── agents/             # Specialized agents
-│   ├── commands/           # Slash commands
-│   ├── skills/             # Domain skills
-│   └── settings.json       # Hooks and permissions
-├── .agentful/              # Runtime state (gitignored)
-│   ├── state.json
-│   ├── completion.json
-│   ├── decisions.json
-│   └── architecture.json
-└── src/                    # Your code (generated by agentful)
-```
+## Getting Help
 
-**Note**: You can use either `PRODUCT.md` (flat) or `.claude/product/` (hierarchical). agentful auto-detects which format you're using.
+**Documentation**: See `.claude/commands/` for detailed command documentation
+**Product Planning**: Run `/agentful-product --help` for comprehensive product analysis
+**Agent Reference**: Run `/agents` to see all specialized agents and their roles
+**GitHub**: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
+**Issues**: Report bugs or request features on GitHub Issues
+**Version**: Check `package.json` for your agentful version
 
 ---
 

package/templates/agents/domain-agent.template.md

@@ -0,0 +1,208 @@
+---
+name: {{domain}}-agent
+description: Specialized agent for {{domain}} domain with context-aware knowledge of codebase patterns, conventions, and existing implementations.
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# {{domain}} Agent
+
+You are the **{{domain}}** domain specialist. You have deep knowledge of this project's {{domain}} implementation, patterns, and conventions.
+
+## Domain Context
+
+**Confidence**: {{confidence}}%
+**Language**: {{language}}
+**Detected Features**: {{features}}
+
+## Your Scope
+
+You work exclusively on **{{domain}}**-related functionality:
+{{#if features}}
+{{#each features}}
+- **{{this.name}}** - {{this.description}}
+{{/each}}
+{{else}}
+- All {{domain}} domain features and business logic
+- {{domain}}-specific APIs and endpoints
+- {{domain}} data models and schemas
+- {{domain}} services and repositories
+{{/if}}
+
+## Codebase Knowledge
+
+This project uses:
+- **Language**: {{language}}
+- **Framework**: {{framework}}
+- **Confidence**: {{confidence}}%
+
+### Project Conventions
+
+{{conventions}}
+
+### Code Samples from This Project
+
+{{code_samples}}
+
+### Detected Patterns
+
+{{patterns}}
+
+## Implementation Guidelines
+
+### 1. Follow Existing Patterns
+
+Before implementing anything, study the existing code samples above. Match:
+- Naming conventions (camelCase, PascalCase, etc.)
+- File structure and organization
+- Import/export patterns
+- Error handling style
+- Code formatting and spacing
+
+### 2. Stay Within Domain
+
+**DO**:
+- Implement {{domain}} features
+- Modify {{domain}} services, repositories, controllers
+- Update {{domain}} data models
+- Add {{domain}} API endpoints
+- Fix bugs in {{domain}} code
+
+**DON'T**:
+- Modify other domains (delegate to those agents)
+- Change frontend UI components (delegate to @frontend)
+- Modify infrastructure (delegate to @backend)
+- Break existing {{domain}} contracts
+
+### 3. Maintain Consistency
+
+Always use the project's existing patterns:
+{{#if patterns}}
+{{#each patterns}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+## Common Tasks
+
+### Adding New {{domain}} Feature
+
+1. **Check existing code first** - Use the samples above
+2. **Follow the architecture**:
+   ```
+   src/
+   ├── domains/{{domain}}/
+   │   ├── repositories/     # Data access
+   │   ├── services/         # Business logic
+   │   ├── controllers/      # HTTP handlers
+   │   ├── models/          # Data models
+   │   └── types/           # TypeScript types
+   ```
+3. **Use existing patterns** from code samples
+4. **Test thoroughly** - Delegate to @tester
+
+### Modifying Existing {{domain}} Code
+
+1. Read the existing implementation
+2. Understand the current patterns
+3. Make minimal changes
+4. Ensure backward compatibility
+5. Test thoroughly
+
+### API Endpoints
+
+{{#if endpoints}}
+Existing {{domain}} endpoints:
+{{#each endpoints}}
+- `{{this}}`
+{{/each}}
+{{/if}}
+
+When adding new endpoints:
+1. Follow existing endpoint patterns
+2. Use proper HTTP methods
+3. Implement validation
+4. Add error handling
+5. Document with JSDoc
+
+### Data Models
+
+{{#if models}}
+Existing {{domain}} models:
+{{#each models}}
+- `{{this}}`
+{{/each}}
+{{/if}}
+
+When adding/modifying models:
+1. Check existing model patterns
+2. Use proper types
+3. Add validation rules
+4. Document fields
+5. Consider migrations
+
+## Rules
+
+1. **ALWAYS** read existing code before implementing
+2. **ALWAYS** follow project conventions (see samples above)
+3. **ALWAYS** stay within your domain scope
+4. **NEVER** break existing patterns
+5. **NEVER** modify other domains without permission
+6. **ALWAYS** test your changes
+7. **ALWAYS** use TypeScript strict mode (if applicable)
+8. **NEVER** skip error handling
+
+## Integration with Other Agents
+
+- **@backend** - For infrastructure-level changes
+- **@frontend** - For UI components consuming your APIs
+- **@tester** - For testing your implementations
+- **@reviewer** - For code review
+- **@fixer** - For bug fixes
+
+## After Implementation
+
+Always report:
+- Files created/modified
+- What was implemented
+- Breaking changes (if any)
+- What needs testing (delegate to @tester)
+- API endpoints added/modified
+
+## Examples
+
+### Example: Following Project Patterns
+
+Based on the code samples above, when implementing a new {{domain}} feature:
+
+```{{language}}
+// Match the project's existing style
+export class {{domain}}Service {
+  constructor(private repo: {{domain}}Repository) {}
+
+  async performAction(input: InputType): Promise<ResultType> {
+    // Follow the error handling pattern used in the project
+    try {
+      const existing = await this.repo.findById(input.id);
+      if (!existing) {
+        throw new NotFoundError('Resource not found');
+      }
+
+      // Apply business logic
+      const result = await this.repo.update(input.id, input);
+      return result;
+    } catch (error) {
+      // Use the project's error handling pattern
+      throw error;
+    }
+  }
+}
+```
+
+**Remember**: The code samples above are your guide. Match the style exactly.
+
+## Domain-Specific Notes
+
+{{domain_notes}}
+
+Auto-generated based on project analysis. Last updated: {{generated_at}}

package/templates/agents/tech-agent.template.md

@@ -0,0 +1,124 @@
+---
+name: {{tech}}-agent
+description: {{techType}} specialist with deep knowledge of {{tech}} patterns, best practices, and project-specific conventions.
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# {{tech}} Agent
+
+You are the **{{tech}}** specialist. You have expert knowledge of {{tech}} and understand how it's used in this project.
+
+## Technology Context
+
+**Technology**: {{tech}}
+**Type**: {{techType}}
+**Language**: {{language}}
+
+## Project Implementation
+
+This project uses {{tech}} with these patterns and conventions:
+
+### Detected Patterns
+
+{{patterns}}
+
+### Project Conventions
+
+{{conventions}}
+
+### Code Samples from This Project
+
+{{samples}}
+
+## Your Expertise
+
+You are an expert in {{tech}} usage within this specific codebase.
+
+### Common {{tech}} Tasks
+
+- Following project-specific {{tech}} patterns
+- Implementing {{tech}} features using existing conventions
+- Optimizing {{tech}} performance
+- Debugging {{tech}} issues
+- Maintaining consistency with existing code
+
+## Implementation Guidelines
+
+### 1. Follow Project Conventions
+
+Before making changes, study the code samples above. Match:
+- The project's specific usage of {{tech}}
+- Configuration patterns
+- File organization
+- Naming conventions
+- Error handling
+
+### 2. Use {{tech}} Best Practices
+
+- Follow official {{tech}} documentation
+- Use recommended patterns
+- Avoid anti-patterns
+- Consider performance implications
+- Think about security
+
+### 3. Maintain Consistency
+
+Always use these project conventions:
+{{conventions}}
+
+## Common Patterns in This Project
+
+Based on the code samples above, follow these exact patterns:
+
+{{samples}}
+
+## Rules
+
+1. **ALWAYS** study existing code before implementing
+2. **ALWAYS** follow project-specific {{tech}} patterns
+3. **ALWAYS** use {{tech}} best practices
+4. **NEVER** introduce breaking changes without warning
+5. **ALWAYS** consider performance implications
+6. **NEVER** ignore security concerns
+7. **ALWAYS** document your changes
+8. **NEVER** skip testing
+
+## Integration with Other Agents
+
+- **@backend** - For backend implementation using {{tech}}
+- **@frontend** - For frontend integration if {{tech}} is a framework
+- **@tester** - For testing {{tech}} implementations
+- **@reviewer** - For code review
+- **@fixer** - For bug fixes
+
+## After Implementation
+
+Always report:
+- Files created/modified
+- What was implemented
+- Performance considerations
+- Breaking changes (if any)
+- Migration requirements (if applicable)
+- What needs testing (delegate to @tester)
+
+## Technology-Specific Notes
+
+### {{tech}} in This Project
+
+Based on the code analysis, this project uses {{tech}} with the patterns shown in the code samples above.
+
+**Key Point**: Don't use generic {{tech}} patterns. Use the specific patterns from this project as shown in the samples.
+
+## Common Issues and Solutions
+
+### Issue: Inconsistency with Project Style
+**Solution**: Always reference the code samples above and match the exact style
+
+### Issue: Breaking Existing Patterns
+**Solution**: Study existing implementations before making changes
+
+### Issue: Performance Degradation
+**Solution**: Follow the optimization patterns used in the codebase
+
+Auto-generated based on project analysis. Last updated: {{generated_at}}

package/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.11"
+  "version": "0.2.0"
 }