@itz4blitz/agentful 0.1.0

package/.claude/product/README.md

@@ -0,0 +1,312 @@
+# Product Structure Guide
+
+Agentful supports **both** flat and hierarchical product structures with automatic detection. This guide explains how to use each format.
+
+## Quick Start
+
+### 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`:
+
+```bash
+your-project/
+├── .claude/
+│   └── product/
+│       └── index.md    # All features in one file
+├── src/
+└── package.json
+```
+
+### Organized Projects (Hierarchical Structure)
+
+Create a hierarchical structure under `.claude/product/domains/`:
+
+```bash
+your-project/
+├── .claude/
+│   └── product/
+│       ├── index.md              # Product overview
+│       └── domains/
+│           ├── authentication/
+│           │   ├── index.md      # Domain overview
+│           │   └── features/
+│           │       ├── login.md
+│           │       └── register.md
+│           └── user-management/
+│               ├── index.md
+│               └── features/
+│                   └── profile.md
+├── src/
+└── package.json
+```
+
+## Auto-Detection
+
+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)
+
+### Detection Algorithm
+
+```bash
+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)
+    → Track at feature level
+else:
+    → Error: No product specification found
+```
+
+## When to Use Each Format
+
+### Flat Structure
+
+**Use when:**
+- Quick prototype or MVP
+- Small project with 5-10 features
+- Single developer or small team
+- Simple feature list without dependencies
+
+**Example `PRODUCT.md`:**
+
+```markdown
+# My App
+
+## Features
+
+### 1. User Authentication - CRITICAL
+- Login with email/password
+- JWT token handling
+- Password reset
+
+### 2. User Profile - HIGH
+- Edit profile information
+- Upload avatar
+
+### 3. Dashboard - MEDIUM
+- Display user stats
+- Recent activity
+```
+
+### Hierarchical Structure
+
+**Use when:**
+- Large project with 20+ features
+- Multiple team members working in parallel
+- Complex feature dependencies
+- Need domain-driven organization
+
+**Example structure:**
+
+```markdown
+<!-- .claude/product/index.md -->
+# My App
+
+## Domains
+- Authentication (CRITICAL)
+- User Management (HIGH)
+- Dashboard (MEDIUM)
+
+<!-- .claude/product/domains/authentication/index.md -->
+# Authentication Domain
+
+Handles user identity and access control.
+
+## Features
+- Login
+- Register
+- Password Reset
+
+<!-- .claude/product/domains/authentication/features/login.md -->
+# Feature: Login
+
+Priority: CRITICAL
+
+## Subtasks
+1. Create login UI
+2. Implement login API
+3. Add JWT handling
+4. Write tests
+```
+
+## Completion Tracking
+
+### Flat Structure Tracking
+
+```json
+{
+  "features": {
+    "authentication": {
+      "status": "complete",
+      "score": 100
+    },
+    "user-profile": {
+      "status": "in_progress",
+      "score": 60
+    }
+  },
+  "gates": {
+    "tests_passing": true,
+    "no_type_errors": true
+  },
+  "overall": 72
+}
+```
+
+### Hierarchical Structure Tracking
+
+```json
+{
+  "domains": {
+    "authentication": {
+      "status": "complete",
+      "score": 100,
+      "features": {
+        "login": {
+          "status": "complete",
+          "score": 100,
+          "subtasks": {
+            "login-ui": { "status": "complete" },
+            "login-api": { "status": "complete" }
+          }
+        }
+      }
+    },
+    "user-management": {
+      "status": "in_progress",
+      "score": 60,
+      "features": {
+        "profile": {
+          "status": "in_progress",
+          "score": 60
+        }
+      }
+    }
+  },
+  "gates": {
+    "tests_passing": true,
+    "no_type_errors": true
+  },
+  "overall": 72
+}
+```
+
+## Migration Path
+
+You can start flat and migrate 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)
+
+Phase 3: Scale Up (when needed)
+└── .claude/product/domains/ (split by domain)
+    ├── authentication/
+    ├── user-management/
+    └── dashboard/
+```
+
+### How to Migrate
+
+1. **Create domain directories:**
+   ```bash
+   mkdir -p .claude/product/domains/authentication/features
+   mkdir -p .claude/product/domains/user-management/features
+   ```
+
+2. **Split features into domain files:**
+   ```bash
+   # Move authentication features
+   # .claude/product/domains/authentication/features/login.md
+   # .claude/product/domains/authentication/features/register.md
+   ```
+
+3. **Create domain index files:**
+   ```bash
+   # .claude/product/domains/authentication/index.md
+   # List overview, goals, and feature summaries
+   ```
+
+4. **Update .claude/product/index.md:**
+   ```bash
+   # Keep only product overview and domain list
+   # Remove detailed feature specs (now in domain files)
+   ```
+
+5. **System auto-detects the change:**
+   - Next agent run will detect hierarchical structure
+   - No configuration changes needed
+
+## Best Practices
+
+### Flat Structure
+
+1. **Keep features focused**: Each feature should be independently testable
+2. **Use priorities**: CRITICAL, HIGH, MEDIUM, LOW
+3. **Clear acceptance criteria**: Specific requirements for each feature
+4. **Track progress**: Update completion.json after validated work
+
+### Hierarchical Structure
+
+1. **Domain boundaries**: Group related features (e.g., authentication, billing)
+2. **Feature independence**: Each feature should be completable independently
+3. **Subtask granularity**: Break features into small, testable subtasks
+4. **Cross-domain dependencies**: Document in feature files, minimize where possible
+
+## Examples
+
+See `.claude/product/index.md` template for a complete flat structure example.
+
+For hierarchical structure examples, check:
+- `.claude/agents/orchestrator.md` - Product structure reading algorithm
+- `.claude/skills/product-tracking/SKILL.md` - Progress tracking for both formats
+
+## Troubleshooting
+
+### "No product specification found"
+
+**Solution**: Create one of:
+- `PRODUCT.md` at root
+- `.claude/product/index.md`
+- `.claude/product/domains/*/index.md`
+
+### "Format mismatch" error
+
+**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 hierarchical: `.claude/product/domains/` + `completion.json` with `domains` object
+
+### Can I use both formats?
+
+**No**: The system auto-detects ONE format. Choose the format that best fits your project size and complexity.
+
+## Summary
+
+| 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 |
+| 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/product/index.md

@@ -0,0 +1,152 @@
+# Product Specification
+
+> **Note**: This template supports **both** flat and hierarchical product structures. The system will auto-detect which format you're using:
+> - **Flat (this file)**: Add all features here for simple projects
+> - **Hierarchical**: Create `.claude/product/domains/*/` directories for organized projects
+>
+> See `.claude/agents/orchestrator.md` for details on product structure detection.
+
+## 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]
+
+## Features (Priority Order)
+
+### 1. [Feature Name] - CRITICAL
+**Description**: [What this feature does]
+
+**Acceptance Criteria**:
+- [ ] [Specific requirement 1]
+- [ ] [Specific requirement 2]
+- [ ] [Specific requirement 3]
+
+**User Stories**:
+- As a [user type], I want [feature] so that [benefit]
+
+**Technical Notes**:
+- [Any technical details or constraints]
+
+---
+
+### 2. [Feature Name] - HIGH
+**Description**: [What this feature does]
+
+**Acceptance Criteria**:
+- [ ] [Specific requirement 1]
+- [ ] [Specific requirement 2]
+
+---
+
+### 3. [Feature Name] - MEDIUM
+**Description**: [What this feature does]
+
+**Acceptance Criteria**:
+- [ ] [Specific requirement 1]
+- [ ] [Specific requirement 2]
+
+---
+
+### 4. [Feature Name] - LOW
+**Description**: [What this feature does]
+
+**Acceptance Criteria**:
+- [ ] [Specific requirement 1]
+
+---
+
+## Architecture Notes
+
+### Folder Structure (Optional)
+
+If you have a preferred structure:
+
+```
+src/
+├── app/              # Next.js app router
+├── components/       # React 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 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

package/.claude/settings.json

@@ -0,0 +1,63 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$FILE\"\" = \"*.md\" ] && grep -q 'Deployment Guide\\|Publishing Guide\\|Setup Guide' \"$FILE\" 2>/dev/null; then echo \"WARNING: Similar documentation may exist. Check for: docs/pages/deployment.mdx, PUBLISHING.md\"; fi"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx tsc --noEmit 2>&1 | head -5 || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$FILE\"\" = \"*.md\" ]; then existing=$(find . -name '*.md' -not -path './node_modules/*' -not -path './.git/*' | xargs grep -l \"$(basename '$FILE' | sed 's/_/ /g' | sed 's/.md$//' | head -c 30)\" 2>/dev/null | grep -v \"$FILE\" | head -1); if [ -n \"$existing\"\" ]; then echo \"⚠️  Similar doc exists: $existing - consider updating instead\"; fi; fi || true"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .agentful/state.json ]; then jq -r '.current_phase // \"idle\"' .agentful/state.json 2>/dev/null || echo 'idle'; else echo 'idle'; fi"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(node:*)",
+      "Bash(git:*)",
+      "Bash(cat:*)",
+      "Bash(echo:*)",
+      "Bash(jq:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(rm -rf ~/.*)",
+      "Bash(rm -rf /.*)",
+      "Bash(dd:*)",
+      "Bash(mkfs:*)"
+    ]
+  }
+}