@itz4blitz/agentful 0.1.0

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

@@ -0,0 +1,139 @@
+---
+name: agentful-decide
+description: Answer pending decisions that are blocking development progress.
+---
+
+# Agentful Decide
+
+This command helps you resolve pending decisions that are blocking development.
+
+## Process
+
+### 1. Read Decisions
+
+Read `.agentful/decisions.json`:
+
+```json
+{
+  "pending": [
+    {
+      "id": "decision-001",
+      "question": "Should auth use JWT or session cookies?",
+      "options": [
+        "JWT (stateless, scalable)",
+        "Sessions (simpler, built-in)",
+        "Clerk (managed service)"
+      ],
+      "context": "Building authentication system for .claude/product/index.md",
+      "blocking": ["auth-feature", "user-profile-feature"],
+      "timestamp": "2026-01-18T00:00:00Z"
+    }
+  ],
+  "resolved": []
+}
+```
+
+### 2. Present to User
+
+For each pending decision, display:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ Decision #1                                                │
+├────────────────────────────────────────────────────────────┤
+│ Question: Should auth use JWT or session cookies?          │
+│                                                            │
+│ Context: Building authentication system for .claude/product/index.md │
+│                                                            │
+│ Options:                                                   │
+│   [1] JWT (stateless, scalable)                            │
+│   [2] Sessions (simpler, built-in)                         │
+│   [3] Clerk (managed service)                              │
+│   [4] Custom input...                                      │
+│                                                            │
+│ Blocking: auth-feature, user-profile-feature              │
+└────────────────────────────────────────────────────────────┘
+
+Your choice:
+```
+
+### 3. Record Decision
+
+After user selects:
+
+```bash
+# Move from pending to resolved
+{
+  "resolved": [
+    {
+      "id": "decision-001",
+      "question": "Should auth use JWT or session cookies?",
+      "answer": "JWT (stateless, scalable)",
+      "timestamp_resolved": "2026-01-18T00:30:00Z"
+    }
+  ],
+  "pending": []
+}
+```
+
+### 4. Update State
+
+Remove from `.agentful/state.json` blocked_on array:
+
+```json
+{
+  "blocked_on": []  // Was: ["auth-feature", "user-profile-feature"]
+}
+```
+
+## Interactive Mode
+
+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
+
+[2/3] Which database provider?
+  > 2
+
+[3/3] Styling framework preference?
+  > 4 (custom: "Tailwind CSS")
+
+✅ All decisions resolved! Run /agentful-start to continue.
+```
+
+## No Pending Decisions
+
+If decisions.json is empty or pending array is empty:
+
+```
+✅ No pending decisions!
+
+All features are unblocked. Run /agentful-start to continue development.
+```
+
+## Implementation
+
+Use AskUserQuestion tool to present decisions interactively:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Should auth use JWT or session cookies?",
+    options: [
+      { label: "JWT", description: "Stateless, scalable" },
+      { label: "Sessions", description: "Simpler, built-in" },
+      { label: "Clerk", description: "Managed service" }
+    ]
+  }]
+})
+```
+
+After receiving answers:
+1. Update decisions.json
+2. Update state.json blocked_on
+3. Show summary of what was resolved
+4. Suggest running /agentful-start

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

@@ -0,0 +1,180 @@
+---
+name: agentful-start
+description: Start or resume autonomous product development loop. Delegates to orchestrator agent.
+---
+
+# Agentful Start
+
+This command initiates the autonomous product development loop.
+
+## Startup Sequence
+
+### 1. Detect User Intent
+
+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` (no args) → Continue autonomous development loop
+
+**User Request Detection:**
+```
+If user provided a specific request:
+  - Pass it to orchestrator for classification
+  - Orchestrator will route to appropriate workflow
+  - May or may not loop depending on work type
+
+If no request provided:
+  - Assume FEATURE_DEVELOPMENT
+  - Read product specs and continue autonomous loop
+```
+
+### 2. Load State
+
+Read these files in order:
+- `.claude/product/index.md` - What we're building
+- `.agentful/state.json` - Current work state
+- `.agentful/completion.json` - What's done vs not done
+- `.agentful/decisions.json` - Pending user decisions
+- `.agentful/agent-improvements.json` - Agent improvement suggestions (if exists)
+- `.agentful/skill-improvements.json` - Skill improvement suggestions (if exists)
+- `.agentful/last-known-framework-version.json` - Framework version tracking (if exists)
+
+### 3. Check Framework Updates
+
+If `.agentful/last-known-framework-version.json` exists:
+
+```bash
+# Calculate current checksums
+current_checksums = calculate_checksums(".claude/")
+
+# Compare with stored checksums
+if current_checksums != stored_checksums:
+  if context == "agentful_framework":
+    # 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.
+     New capabilities available:
+     - Enhanced orchestrator with work classification
+     - New validation gates
+
+     Would you like to:
+     1. Continue using current setup
+     2. Re-run architect to regenerate specialized agents
+     3. See what's new"
+
+    # Update stored checksums
+    update_last_known_version()
+```
+
+### 4. Check Agent Improvement Suggestions
+
+If `.agentful/agent-improvements.json` has HIGH priority items:
+
+```bash
+if agent_improvements.pending.any(priority == "HIGH"):
+  if context == "agentful_framework":
+    "Agent improvement suggestions detected:
+     - Backend agent needs migration workflow
+
+     Proceeding with agent improvements..."
+
+    # Delegate to orchestrator for META_WORK
+  else:
+    "Note: The Agentful framework has suggested improvements.
+     These will be available when you update Agentful."
+```
+
+### 5. Check Decisions
+
+If `.agentful/decisions.json` has pending items:
+
+```
+⚠️  Pending decisions need your input:
+1. "Should auth use JWT or session cookies?"
+   Run: /agentful-decide
+
+Cannot proceed until decisions are resolved.
+```
+
+### 6. Initialize State if Needed
+
+If `.agentful/state.json` doesn't exist or is empty:
+
+```bash
+echo '{
+  "version": "1.0",
+  "current_task": null,
+  "current_phase": "idle",
+  "iterations": 0,
+  "last_updated": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",
+  "blocked_on": []
+}' > .agentful/state.json
+```
+
+### 7. Delegate to Orchestrator
+
+You are NOT the orchestrator. Use the Task tool to delegate:
+
+**If user provided a specific request:**
+```
+Task("orchestrator", "User request: [USER_REQUEST]. Classify work type and execute appropriate workflow.")
+```
+
+**If no request provided (default autonomous mode):**
+```
+Task("orchestrator", "Run autonomous development loop. Read state, pick next task, delegate to specialist agents, validate, update state, continue until complete.")
+```
+
+## Ralph Wiggum Integration
+
+When running in a Ralph loop (`/ralph-loop`), this command will be called repeatedly.
+
+Output this **ONLY when truly complete** (all features done, all gates passing):
+
+```
+<promise>AGENTFUL_COMPLETE</promise>
+```
+
+## 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"
+5. Wait for completion
+6. Delegate to @reviewer → "Review auth changes"
+7. If issues → @fixer → @reviewer again
+8. Update completion.json → auth: 100%
+9. Loop → What's next?
+```
+
+## Manual Usage
+
+For one-shot development (not a Ralph loop):
+1. Run `/agentful-start`
+2. Orchestrator picks one task
+3. Completes it with validation
+4. Reports progress
+5. Run again to continue
+
+## Autonomous Usage
+
+For continuous development:
+```bash
+/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"
+```
+
+This will run 24/7 until:
+- All features complete (100%)
+- All quality gates passing
+- Or max-iterations reached

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

@@ -0,0 +1,96 @@
+---
+name: agentful-status
+description: Show current progress, completion percentage, and what's being worked on.
+---
+
+# Agentful Status
+
+This command shows the current state of autonomous product development.
+
+## Display Format
+
+### Header
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+           Agentful Development Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Product: [from .claude/product/index.md title]
+Overall Progress: ████░░░░░░░░░░ 48%
+Phase: [current phase from state.json]
+Iterations: [number from state.json]
+```
+
+### Completion Table
+
+```
+┌─────────────────────┬──────────┬─────────┬────────────────┐
+│ Feature             │ Status   │ Score   │ Notes          │
+├─────────────────────┼──────────┼─────────┼────────────────┤
+│ Authentication      │ ✅ Done  │ 100%    │                │
+│ User Profile        │ 🔄 Active│ 45%     │ Backend done   │
+│ Dashboard           │ ⏸ Pending│ 0%      │ Blocked on UX  │
+│ Settings            │ ⏸ Pending│ 0%      │                │
+└─────────────────────┴──────────┴─────────┴────────────────┘
+```
+
+### Quality Gates
+
+```
+┌─────────────────────┬────────┐
+│ Quality Gate        │ Status │
+├─────────────────────┼────────┤
+│ Tests Passing       │ ✅     │
+│ No Type Errors      │ ✅     │
+│ No Dead Code        │ ❌     │
+│ Coverage ≥ 80%      │ ⚠️ 72% │
+└─────────────────────┴────────┘
+```
+
+### Pending Decisions
+
+```
+⚠️  Decisions Needed:
+
+1. "Should auth use JWT or session cookies?"
+   Options: JWT (stateless), Sessions (simpler), Clerk (managed)
+   Blocking: auth-feature
+
+   → Run /agentful-decide to resolve
+```
+
+### Current Work
+
+```
+🔧 Currently Working On:
+   Task: user-profile-backend
+   Agent: backend
+   Started: 2 minutes ago
+
+   Last output: "Implementing user profile service layer..."
+```
+
+## Implementation
+
+Read and display:
+
+1. `.agentful/state.json` - Current work, phase, iterations
+2. `.agentful/completion.json` - Features and gates
+3. `.agentful/decisions.json` - Pending decisions
+4. `.claude/product/index.md` - Product name and overview
+
+Format the output nicely with ASCII art for readability.
+
+## Quick Actions
+
+At the end, suggest next actions:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next Actions:
+  • /agentful-start    - Continue development
+  • /agentful-decide  - Answer pending decisions
+  • /agentful-validate- Run quality checks
+```

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

@@ -0,0 +1,105 @@
+---
+name: agentful-validate
+description: Run all quality checks and validation gates. Delegates to reviewer agent.
+---
+
+# Agentful Validate
+
+This command runs all quality checks and validation gates.
+
+## What It Validates
+
+Delegate to the reviewer agent to run:
+
+1. **TypeScript Check** - `npx tsc --noEmit`
+2. **Lint Check** - `npm run lint`
+3. **Dead Code Detection** - Find unused exports, files, imports
+4. **Test Check** - `npm test`
+5. **Coverage Check** - Verify ≥ 80% coverage
+6. **Security Check** - Scan for secrets, vulnerabilities, debug logs
+
+## Process
+
+### 1. Run Reviewer
+
+```
+Task("reviewer", "Run all validation checks on the current codebase and report results.")
+```
+
+### 2. Display Results
+
+After reviewer completes, display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+              Validation Results
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+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
+
+Overall: ❌ FAILED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+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
+
+Run /agentful-start to auto-fix these issues.
+```
+
+### 3. Update Completion JSON
+
+Update `.agentful/completion.json` gates:
+
+```json
+{
+  "gates": {
+    "tests_passing": true,
+    "no_type_errors": true,
+    "no_dead_code": false,
+    "coverage_80": false
+  }
+}
+```
+
+## Standalone Mode
+
+When run directly (not via orchestrator):
+1. Execute all checks
+2. Display results
+3. Ask if user wants to auto-fix:
+   ```
+   Issues found. Would you like to auto-fix them? [y/N]
+   ```
+4. If yes, delegate to @fixer
+
+## Quick Mode
+
+For faster feedback, use specific checks:
+
+```bash
+# Quick type check only
+/agentful-validate --type-check
+
+# Quick test run only
+/agentful-validate --tests
+
+# Security scan only
+/agentful-validate --security
+```
+
+## Exit Codes
+
+For CI/CD integration:
+- `0` - All checks passed
+- `1` - One or more checks failed
+- `2` - Unable to run checks (missing dependencies, etc.)