@itz4blitz/agentful 0.1.0 → 0.1.5

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

@@ -3,7 +3,7 @@ name: agentful-decide
 description: Answer pending decisions that are blocking development progress.
 ---
 
-# Agentful Decide
+# agentful Decide
 
 This command helps you resolve pending decisions that are blocking development.
 
@@ -18,14 +18,14 @@ Read `.agentful/decisions.json`:
   "pending": [
     {
       "id": "decision-001",
-      "question": "Should auth use JWT or session cookies?",
+      "question": "How should we handle inventory race conditions during flash sales?",
       "options": [
-        "JWT (stateless, scalable)",
-        "Sessions (simpler, built-in)",
-        "Clerk (managed service)"
+        "Pessimistic locking (database row locks during checkout)",
+        "Optimistic locking with automatic retry on conflict",
+        "Queue-based processing (serialize checkout requests)"
       ],
-      "context": "Building authentication system for .claude/product/index.md",
-      "blocking": ["auth-feature", "user-profile-feature"],
+      "context": "Shopfinity e-commerce platform expects 1000+ concurrent checkouts during Black Friday. Current implementation allows overselling when multiple users attempt to purchase the same item simultaneously.",
+      "blocking": ["checkout-feature", "order-history-feature"],
       "timestamp": "2026-01-18T00:00:00Z"
     }
   ],
@@ -41,17 +41,30 @@ For each pending decision, display:
 ┌────────────────────────────────────────────────────────────┐
 │ Decision #1                                                │
 ├────────────────────────────────────────────────────────────┤
-│ Question: Should auth use JWT or session cookies?          │
+│ Question: How should we handle inventory race conditions   │
+│ during flash sales?                                        │
 │                                                            │
-│ Context: Building authentication system for .claude/product/index.md │
+│ Context: Shopfinity expects 1000+ concurrent checkouts     │
+│ during Black Friday. Current implementation allows          │
+│ overselling when multiple users attempt to purchase        │
+│ the same item simultaneously.                              │
 │                                                            │
 │ Options:                                                   │
-│   [1] JWT (stateless, scalable)                            │
-│   [2] Sessions (simpler, built-in)                         │
-│   [3] Clerk (managed service)                              │
+│   [1] Pessimistic locking (database row locks)             │
+│       Pros: Simple, guarantees consistency                 │
+│       Cons: Poor performance under high concurrency        │
+│                                                            │
+│   [2] Optimistic locking with automatic retry              │
+│       Pros: Better performance, handles spikes well        │
+│       Cons: Requires retry logic, potential starvation     │
+│                                                            │
+│   [3] Queue-based processing                               │
+│       Pros: Full control, can prioritize customers         │
+│       Cons: Complex, adds infrastructure                   │
+│                                                            │
 │   [4] Custom input...                                      │
 │                                                            │
-│ Blocking: auth-feature, user-profile-feature              │
+│ Blocking: checkout-feature, order-history-feature          │
 └────────────────────────────────────────────────────────────┘
 
 Your choice:
@@ -67,8 +80,8 @@ After user selects:
   "resolved": [
     {
       "id": "decision-001",
-      "question": "Should auth use JWT or session cookies?",
-      "answer": "JWT (stateless, scalable)",
+      "question": "How should we handle inventory race conditions during flash sales?",
+      "answer": "Queue-based processing",
       "timestamp_resolved": "2026-01-18T00:30:00Z"
     }
   ],
@@ -82,10 +95,60 @@ Remove from `.agentful/state.json` blocked_on array:
 
 ```json
 {
-  "blocked_on": []  // Was: ["auth-feature", "user-profile-feature"]
+  "blocked_on": []  // Was: ["checkout-feature", "order-history-feature"]
 }
 ```
 
+## Example Decisions Across Different Domains
+
+**SaaS Billing Platform:**
+```
+Question: How should we prorate subscription changes mid-cycle?
+
+Options:
+  [1] Prorate to the day (calculate daily rate)
+  [2] Prorate to the week (simpler calculation)
+  [3] Charge full amount, credit next cycle
+  [4] Custom input...
+
+Context: Startup plan users frequently upgrade/downgrade.
+Complex daily proration may confuse customers on invoices.
+
+Blocking: subscription-management, invoice-generation
+```
+
+**Content Management System:**
+```
+Question: How should we handle concurrent content edits?
+
+Options:
+  [1] Last write wins (overwrite without warning)
+  [2] Optimistic locking (show conflict, let user merge)
+  [3] Pessimistic locking (lock document on edit)
+  [4] Google Docs-style real-time collaboration
+
+Context: Marketing team of 12 editors reports frequent
+conflicts when updating blog posts and landing pages.
+
+Blocking: content-editor, version-control
+```
+
+**Project Management Tool:**
+```
+Question: How should we calculate project completion percentage?
+
+Options:
+  [1] Equal weight (all tasks count equally)
+  [2] Story points (weighted by effort estimate)
+  [3] Time spent (weighted by actual hours logged)
+  [4] Custom (manual percentage per task)
+
+Context: Developers complain that completing 10 small tasks
+shows same progress as 1 complex architectural change.
+
+Blocking: dashboard, reporting-metrics
+```
+
 ## Interactive Mode
 
 If there are multiple pending decisions, process them one at a time:
@@ -93,14 +156,14 @@ If there are multiple pending decisions, process them one at a time:
 ```
 You have 3 pending decisions to resolve:
 
-[1/3] Should auth use JWT or session cookies?
-  > 1
+[1/3] How should we handle inventory race conditions?
+  > 3 (Queue-based processing)
 
-[2/3] Which database provider?
-  > 2
+[2/3] Which payment gateway should we use?
+  > 1
 
-[3/3] Styling framework preference?
-  > 4 (custom: "Tailwind CSS")
+[3/3] Should we support international shipping from day 1?
+  > 4 (custom: "Only US and Canada, expand in Q2")
 
 ✅ All decisions resolved! Run /agentful-start to continue.
 ```
@@ -122,18 +185,30 @@ Use AskUserQuestion tool to present decisions interactively:
 ```
 AskUserQuestion({
   questions: [{
-    question: "Should auth use JWT or session cookies?",
+    id: "decision-001",
+    question: "How should we handle inventory race conditions?",
     options: [
-      { label: "JWT", description: "Stateless, scalable" },
-      { label: "Sessions", description: "Simpler, built-in" },
-      { label: "Clerk", description: "Managed service" }
-    ]
+      {
+        label: "Pessimistic locking",
+        description: "Database row locks during checkout"
+      },
+      {
+        label: "Optimistic locking",
+        description: "Automatic retry on conflict"
+      },
+      {
+        label: "Queue-based processing",
+        description: "Serialize checkout requests"
+      }
+    ],
+    context: "Expected 1000+ concurrent checkouts during Black Friday...",
+    blocking: ["checkout-feature", "order-history-feature"]
   }]
 })
 ```
 
 After receiving answers:
-1. Update decisions.json
-2. Update state.json blocked_on
+1. Update decisions.json (move to resolved)
+2. Update state.json blocked_on (clear the array)
 3. Show summary of what was resolved
 4. Suggest running /agentful-start

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

@@ -3,7 +3,7 @@ name: agentful-start
 description: Start or resume autonomous product development loop. Delegates to orchestrator agent.
 ---
 
-# Agentful Start
+# agentful Start
 
 This command initiates the autonomous product development loop.
 
@@ -14,9 +14,9 @@ This command initiates the autonomous product development loop.
 Check if the user provided a specific request with this command:
 
 **Examples:**
-- `/agentful-start "Fix the login bug"` → BUGFIX workflow
-- `/agentful-start "Add authentication"` → FEATURE_DEVELOPMENT workflow
-- `/agentful-start "Refactor user service"` → REFACTOR workflow
+- `/agentful-start "Fix the memory leak in checkout flow"` → BUGFIX workflow
+- `/agentful-start "Add subscription proration logic"` → FEATURE_DEVELOPMENT workflow
+- `/agentful-start "Migrate from REST to GraphQL"` → REFACTOR workflow
 - `/agentful-start` (no args) → Continue autonomous development loop
 
 **User Request Detection:**
@@ -53,15 +53,15 @@ current_checksums = calculate_checksums(".claude/")
 # Compare with stored checksums
 if current_checksums != stored_checksums:
   if context == "agentful_framework":
-    # We're in Agentful repo
+    # We're in agentful repo
     "Framework updated. Changes detected in:
      - orchestrator.md (improved)
      - validation skill (new gate added)
 
      Testing updated framework..."
   else:
-    # User project - Agentful was updated
-    "Agentful framework updated.
+    # User project - agentful was updated
+    "agentful framework updated.
      New capabilities available:
      - Enhanced orchestrator with work classification
      - New validation gates
@@ -89,8 +89,8 @@ if agent_improvements.pending.any(priority == "HIGH"):
 
     # Delegate to orchestrator for META_WORK
   else:
-    "Note: The Agentful framework has suggested improvements.
-     These will be available when you update Agentful."
+    "Note: The agentful framework has suggested improvements.
+     These will be available when you update agentful."
 ```
 
 ### 5. Check Decisions
@@ -99,7 +99,9 @@ If `.agentful/decisions.json` has pending items:
 
 ```
 ⚠️  Pending decisions need your input:
-1. "Should auth use JWT or session cookies?"
+1. "How should we handle race conditions in inventory allocation?"
+   Options: Pessimistic locking, Optimistic locking with retry, Queue-based
+   Blocking: checkout-feature
    Run: /agentful-decide
 
 Cannot proceed until decisions are resolved.
@@ -147,14 +149,14 @@ Output this **ONLY when truly complete** (all features done, all gates passing):
 ## Example Flow
 
 ```
-1. Read state.json → "backend-auth" in progress
-2. Read completion.json → auth: 30% complete
-3. Read .claude/product/index.md → auth requirements
-4. Delegate to @backend → "Complete auth implementation"
+1. Read state.json → "checkout-cart" in progress
+2. Read completion.json → checkout: 60% complete
+3. Read .claude/product/index.md → e-commerce requirements
+4. Delegate to @backend → "Implement tax calculation service"
 5. Wait for completion
-6. Delegate to @reviewer → "Review auth changes"
+6. Delegate to @reviewer → "Review checkout changes"
 7. If issues → @fixer → @reviewer again
-8. Update completion.json → auth: 100%
+8. Update completion.json → checkout: 80%
 9. Loop → What's next?
 ```
 

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

@@ -3,7 +3,7 @@ name: agentful-status
 description: Show current progress, completion percentage, and what's being worked on.
 ---
 
-# Agentful Status
+# agentful Status
 
 This command shows the current state of autonomous product development.
 
@@ -13,26 +13,28 @@ This command shows the current state of autonomous product development.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-           Agentful Development Status
+           agentful Development Status
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Product: [from .claude/product/index.md title]
-Overall Progress: ████░░░░░░░░░░ 48%
-Phase: [current phase from state.json]
-Iterations: [number from state.json]
+Product: Shopfinity E-commerce Platform
+Overall Progress: ████████░░░░░░░ 62%
+Phase: feature_development
+Iterations: 24
 ```
 
 ### Completion Table
 
 ```
-┌─────────────────────┬──────────┬─────────┬────────────────┐
-│ Feature             │ Status   │ Score   │ Notes          │
-├─────────────────────┼──────────┼─────────┼────────────────┤
-│ Authentication      │ ✅ Done  │ 100%    │                │
-│ User Profile        │ 🔄 Active│ 45%     │ Backend done   │
-│ Dashboard           │ ⏸ Pending│ 0%      │ Blocked on UX  │
-│ Settings            │ ⏸ Pending│ 0%      │                │
-└─────────────────────┴──────────┴─────────┴────────────────┘
+┌─────────────────────┬──────────┬─────────┬────────────────────────┐
+│ Feature             │ Status   │ Score   │ Notes                  │
+├─────────────────────┼──────────┼─────────┼────────────────────────┤
+│ Product Catalog     │ ✅ Done  │ 100%    │                        │
+│ Shopping Cart       │ ✅ Done  │ 100%    │                        │
+│ Checkout Flow       │ 🔄 Active│ 65%     │ Tax calc needs tests   │
+│ Payment Integration │ 🔄 Active│ 40%     │ Stripe webhook pending │
+│ Order History       │ ⏸ Pending│ 0%      │ Blocked on checkout   │
+│ Admin Dashboard     │ ⏸ Pending│ 0%      │                        │
+└─────────────────────┴──────────┴─────────┴────────────────────────┘
 ```
 
 ### Quality Gates
@@ -43,8 +45,9 @@ Iterations: [number from state.json]
 ├─────────────────────┼────────┤
 │ Tests Passing       │ ✅     │
 │ No Type Errors      │ ✅     │
-│ No Dead Code        │ ❌     │
-│ Coverage ≥ 80%      │ ⚠️ 72% │
+│ No Dead Code        │ ✅     │
+│ Coverage ≥ 80%      │ ⚠️ 76% │
+│ Security Clean      │ ✅     │
 └─────────────────────┴────────┘
 ```
 
@@ -53,9 +56,12 @@ Iterations: [number from state.json]
 ```
 ⚠️  Decisions Needed:
 
-1. "Should auth use JWT or session cookies?"
-   Options: JWT (stateless), Sessions (simpler), Clerk (managed)
-   Blocking: auth-feature
+1. "How should we handle inventory race conditions during flash sales?"
+   Options: Pessimistic locking, Optimistic locking with retry, Queue-based processing
+   Blocking: payment-integration, order-history
+
+   Context: Current implementation allows overselling when multiple users
+   checkout simultaneously. Peak traffic expected during Black Friday.
 
    → Run /agentful-decide to resolve
 ```
@@ -64,11 +70,11 @@ Iterations: [number from state.json]
 
 ```
 🔧 Currently Working On:
-   Task: user-profile-backend
+   Task: stripe-webhook-handler
    Agent: backend
-   Started: 2 minutes ago
+   Started: 5 minutes ago
 
-   Last output: "Implementing user profile service layer..."
+   Last output: "Implementing webhook signature verification for Stripe events..."
 ```
 
 ## Implementation

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

@@ -3,7 +3,7 @@ name: agentful-validate
 description: Run all quality checks and validation gates. Delegates to reviewer agent.
 ---
 
-# Agentful Validate
+# agentful Validate
 
 This command runs all quality checks and validation gates.
 
@@ -38,20 +38,25 @@ After reviewer completes, display:
 TypeScript      ✅ PASS - No type errors
 Lint            ✅ PASS - No lint errors
 Dead Code       ❌ FAIL - 3 issues found
-Tests           ✅ PASS - 47 tests passed
-Coverage        ⚠️  WARN - 72% (needs 80%)
-Security        ⚠️  WARN - 2 issues found
+Tests           ✅ PASS - 156 tests passed
+Coverage        ⚠️  WARN - 76% (needs 80%)
+Security        ✅ PASS - No issues found
 
-Overall: ❌ FAILED
+Overall: ⚠️ PASSED with warnings
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Issues that must be fixed:
 
-1. Unused export: formatDate in src/utils/date.ts
-2. Unused file: src/components/OldWidget.tsx
-3. Unused dependency: lodash in package.json
-4. Coverage below 80% threshold (8 points needed)
-5. console.log in src/auth/login.ts:45
+1. Unused export: calculateDiscount in src/billing/promotions.ts
+2. Unused file: src/components/LegacyAddressForm.tsx
+3. Unused import: { logger } in src/services/email.ts
+
+Warnings (recommended fixes):
+
+4. Coverage below 80% threshold (4% points needed)
+   Missing tests in:
+   - src/stripe/webhook-handler.ts (45% coverage)
+   - src/inventory/allocation.ts (62% coverage)
 
 Run /agentful-start to auto-fix these issues.
 ```
@@ -66,7 +71,8 @@ Update `.agentful/completion.json` gates:
     "tests_passing": true,
     "no_type_errors": true,
     "no_dead_code": false,
-    "coverage_80": false
+    "coverage_80": false,
+    "security_clean": true
   }
 }
 ```
@@ -82,19 +88,35 @@ When run directly (not via orchestrator):
    ```
 4. If yes, delegate to @fixer
 
-## Quick Mode
+## Example Output for Different Domains
+
+**SaaS Billing Platform:**
+```
+Dead Code       ❌ FAIL - 2 issues found
+   - Unused export: prorateSubscription in src/billing/usage.ts
+   - Unused file: src/components/UsageChartOld.tsx
 
-For faster feedback, use specific checks:
+Coverage        ⚠️  WARN - 74% (needs 80%)
+   Missing: src/stripe/subscription-updates.ts
+```
 
-```bash
-# Quick type check only
-/agentful-validate --type-check
+**Content Management System:**
+```
+Dead Code       ❌ FAIL - 4 issues found
+   - Unused export: parseMarkdownFrontmatter in src/content/parser.ts
+   - Unused file: src/components/RichTextEditorLegacy.tsx
+   - Unused imports in 2 files
 
-# Quick test run only
-/agentful-validate --tests
+Security        ⚠️  WARN - 1 issue found
+   - Debug console.log in src/api/content-preview.ts:23
+```
 
-# Security scan only
-/agentful-validate --security
+**Project Management Tool:**
+```
+Tests           ❌ FAIL - 3 tests failed
+   - TaskAssignmentService › should handle concurrent assignments
+   - ProjectTimeline › should calculate critical path correctly
+   - SprintController › should prevent sprint deletion with active tasks
 ```
 
 ## Exit Codes