@itz4blitz/agentful 0.4.0 → 1.0.0

package/template/.claude/product/EXAMPLES.md

@@ -0,0 +1,167 @@
+# Product Structure Examples
+
+agentful supports two product specification formats.
+
+## Flat Structure (Simple Projects)
+
+**Best for**: Small projects with < 20 features
+
+**Structure**:
+```
+.claude/product/
+└── index.md                 # All features in one file
+```
+
+**Example** (.claude/product/index.md):
+```markdown
+# TaskFlow - Task Management App
+
+## Tech Stack
+
+- **Frontend**: Next.js 14, TypeScript, Tailwind
+- **Backend**: Node.js, Prisma, PostgreSQL
+- **Testing**: Vitest, Playwright
+
+## Features
+
+### 1. User Authentication - CRITICAL
+**Description**: User registration, login, JWT tokens
+
+**Acceptance Criteria**:
+- [ ] User can register with email/password
+- [ ] User can login and receive JWT token
+- [ ] Protected routes require valid token
+
+---
+
+### 2. Task Management - CRITICAL
+**Description**: Create, read, update, delete tasks
+
+**Acceptance Criteria**:
+- [ ] User can create task with title, description, due date
+- [ ] User can edit and delete tasks
+- [ ] Tasks paginated (20 per page)
+
+---
+
+### 3. Project Organization - HIGH
+**Description**: Group tasks into projects
+
+**Acceptance Criteria**:
+- [ ] User can create projects
+- [ ] User can assign tasks to projects
+```
+
+**Tracking** (.agentful/completion.json):
+```json
+{
+  "features": {
+    "user-authentication": { "status": "complete", "score": 100 },
+    "task-management": { "status": "in_progress", "score": 60 },
+    "project-organization": { "status": "pending", "score": 0 }
+  },
+  "overall": 53
+}
+```
+
+---
+
+## Hierarchical Structure (Complex Projects)
+
+**Best for**: Large projects with 20+ features, team collaboration
+
+**Structure**:
+```
+.claude/product/
+├── index.md                          # Product overview
+└── domains/
+    ├── authentication/
+    │   ├── index.md                  # Domain overview
+    │   └── features/
+    │       ├── registration.md
+    │       ├── login.md
+    │       └── password-reset.md
+    ├── task-management/
+    │   ├── index.md
+    │   └── features/
+    │       ├── task-crud.md
+    │       └── task-search.md
+    └── dashboard/
+        ├── index.md
+        └── features/
+            └── analytics.md
+```
+
+**Example** (.claude/product/index.md):
+```markdown
+# TaskFlow - Task Management App
+
+## Tech Stack
+
+- **Frontend**: Next.js 14, TypeScript, Tailwind
+- **Backend**: Node.js, Prisma, PostgreSQL
+
+## Domains
+
+| Domain | Priority | Description |
+|--------|----------|-------------|
+| Authentication | CRITICAL | User identity and access |
+| Task Management | CRITICAL | Core task CRUD |
+| Dashboard | MEDIUM | Analytics and insights |
+```
+
+**Example** (.claude/product/domains/authentication/features/login.md):
+```markdown
+# Feature: User Login
+
+## Priority
+CRITICAL
+
+## Description
+Authenticate users with email/password and issue JWT tokens.
+
+## Acceptance Criteria
+- [ ] POST /api/auth/login endpoint
+- [ ] Returns JWT on success
+- [ ] Rate limit: 5 attempts per 15min
+- [ ] HTTP-only refresh token cookie
+
+## User Stories
+- As a user, I want to login so that I can access my account
+```
+
+**Tracking** (.agentful/completion.json):
+```json
+{
+  "domains": {
+    "authentication": {
+      "status": "in_progress",
+      "score": 50,
+      "features": {
+        "registration": { "status": "complete", "score": 100 },
+        "login": { "status": "in_progress", "score": 50 },
+        "password-reset": { "status": "pending", "score": 0 }
+      }
+    },
+    "task-management": {
+      "status": "pending",
+      "score": 0
+    }
+  },
+  "overall": 25
+}
+```
+
+---
+
+## Comparison
+
+| Aspect | Flat | Hierarchical |
+|--------|------|--------------|
+| **Files** | 1 file | 10+ files |
+| **Organization** | Feature list | Domains → Features |
+| **Best for** | < 20 features | 20+ features |
+| **Team collab** | Harder (merge conflicts) | Easier (separate files) |
+| **Visibility** | Feature-level | Subtask-level |
+
+Choose based on your project size and team needs!

package/{.claude → template/.claude}/settings.json

@@ -1,12 +1,15 @@
 {
   "includeCoAuthoredBy": false,
+  "env": {
+    "ENABLE_TOOL_SEARCH": "true"
+  },
   "hooks": {
     "SessionStart": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "bash bin/hooks/health-check.sh",
+            "command": "node bin/hooks/health-check.js",
             "timeout": 5,
             "description": "Quick agentful health check"
           }
@@ -15,11 +18,13 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Write|Edit",
+        "tools": ["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"
+            "command": "node bin/hooks/block-random-docs.js",
+            "timeout": 3,
+            "description": "Block random markdown file creation (disable with AGENTFUL_ALLOW_RANDOM_DOCS=true)"
           }
         ]
       }
@@ -30,7 +35,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash bin/hooks/analyze-trigger.sh",
+            "command": "node bin/hooks/analyze-trigger.js",
             "timeout": 3,
             "description": "Check if file changes warrant analysis"
           }
@@ -68,15 +73,6 @@
     ]
   },
   "permissions": {
-    "allow": [
-      "Bash(npm:*)",
-      "Bash(npx:*)",
-      "Bash(node:*)",
-      "Bash(git:*)",
-      "Bash(cat:*)",
-      "Bash(echo:*)",
-      "Bash(jq:*)"
-    ],
     "deny": [
       "Bash(rm -rf /)",
       "Bash(rm -rf ~/.*)",

package/{.claude → template/.claude}/skills/conversation/SKILL.md

@@ -338,12 +338,18 @@ function route_to_handler(
     };
   }
 
-  // Product planning → product-planning skill
+  // Product planning → reference product-planning skill guidance (inline)
+  // Note: product-planning is a skill, not a separate agent
+  // When user asks planning/requirements questions, use product-planning skill's guidance
   if (/plan|requirements|spec|analyze/i.test(intentName)) {
     return {
-      handler: 'product-planning',
+      handler: 'inline',
       skill: 'product-planning',
-      context: { intent: intentName }
+      context: {
+        intent: intentName,
+        use_skill_guidance: 'product-planning',
+        action: 'answer_with_planning_guidance'
+      }
     };
   }
 
@@ -548,16 +554,16 @@ ${routing.context.domain_filter ? `Filter: domain ${routing.context.domain_filte
       Task('validation', `Run quality gates. Scope: ${routing.context.scope || 'all'}`);
       break;
 
-    case 'product-planning':
-      Task('product-planning', userMessage);
-      break;
-
     case 'inline':
       if (routing.context.needs_clarification) {
         return 'Could you please provide more details about what you\'d like me to do?';
       } else if (routing.context.action === 'pause_work') {
         pause_current_work();
         return 'Work paused. Run `/agentful` when ready to continue.';
+      } else if (routing.context.action === 'answer_with_planning_guidance') {
+        // Use product-planning skill guidance to answer planning/requirements questions
+        // The skill provides structured approach to product planning, requirements analysis
+        return answer_planning_question(userMessage, routing.context);
       } else if (routing.context.intent === 'question') {
         return answer_question(userMessage, routing.context);
       }

package/template/.claude/skills/deployment/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: deployment
+description: Guides deployment preparation and production readiness validation
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Deployment Skill
+
+## Pre-Deployment Checklist
+
+Before deploying to production:
+
+### Code Quality
+- [ ] All tests passing (unit, integration, e2e)
+- [ ] Code coverage ≥80%
+- [ ] No type errors
+- [ ] No linter errors or warnings
+- [ ] No formatting issues
+- [ ] Security vulnerabilities checked
+
+### Build & Configuration
+- [ ] Production build succeeds locally
+- [ ] Environment variables documented in `.env.example`
+- [ ] All required secrets configured
+- [ ] Database migrations ready and tested
+- [ ] Migration rollback scripts prepared
+
+### Deployment Plan
+- [ ] Rollback procedure documented
+- [ ] Stakeholders notified
+- [ ] Monitoring and health checks configured
+- [ ] Post-deployment verification steps defined
+
+## Environment Variables
+
+**Create `.env.example`:**
+```bash
+# Document all required variables
+DATABASE_URL=
+API_KEY=
+JWT_SECRET=
+NODE_ENV=production
+```
+
+**Runtime Validation:**
+Validate environment variables at application startup to catch configuration errors early.
+
+## Database Migrations
+
+**Safe Migration Strategy:**
+1. Test migrations in staging environment
+2. Backup production database before migration
+3. Write rollback scripts for all migrations
+4. Apply migrations before or after code deployment (depending on breaking changes)
+5. Monitor application after migration
+
+## Health Checks
+
+Implement health check endpoints:
+- `/health` - Overall system health (database, cache, external services)
+- `/ready` - Readiness to serve traffic
+- `/alive` - Process liveness
+
+## Rollback Procedures
+
+**Always have a rollback plan:**
+1. Know how to revert code deployment on your platform
+2. Know how to rollback database migrations
+3. Test rollback procedure in staging
+4. Document rollback commands
+
+## Post-Deployment Verification
+
+After deployment:
+1. Verify health checks return 200 OK
+2. Test critical user workflows
+3. Monitor error rates and logs for 15+ minutes
+4. Verify database migrations applied correctly
+
+## Common Deployment Platforms
+
+Choose platform based on your stack and requirements:
+- **Static sites**: Netlify, Vercel, CloudFlare Pages, GitHub Pages
+- **Serverless**: AWS Lambda, Vercel Functions, Netlify Functions, CloudFlare Workers
+- **Containers**: AWS ECS, Google Cloud Run, Azure Container Apps, Railway, Render
+- **Virtual Machines**: AWS EC2, DigitalOcean, Linode, Hetzner
+- **Kubernetes**: AWS EKS, Google GKE, Azure AKS, DigitalOcean Kubernetes
+
+Consult your platform's documentation for specific deployment commands and configuration.
+
+## Rules
+
+### DO
+- Run full test suite before deploying
+- Validate environment configuration
+- Test production build locally
+- Document rollback procedure
+- Monitor after deployment
+- Tag releases in version control
+
+### DON'T
+- Deploy with failing tests
+- Commit secrets to version control
+- Deploy without rollback plan
+- Skip environment validation
+- Deploy breaking changes without coordination
+- Deploy on Friday afternoon without monitoring capacity
+
+## Integration
+
+The orchestrator uses this skill when:
+- User requests deployment
+- Feature is complete and ready to ship
+- Rollback is needed
+- Environment setup required