Workflows

┌──────────────────────────────────────────────────────────┐
│  1. PLAN                                                  │
│     • Read state (state.json, completion.json)           │
│     • Read requirements (PRODUCT.md)                     │
│     • Identify next task                                 │
│     • Check for blockers                                 │
└──────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────┐
│  2. DELEGATE                                              │
│     • Select appropriate specialist agent                │
│     • Provide clear task description                     │
│     • Wait for completion                                │
└──────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────┐
│  3. IMPLEMENT                                             │
│     • Specialist agent executes task                     │
│     • Creates/modifies files                             │
│     • Follows best practices                             │
│     • Reports completion                                 │
└──────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────┐
│  4. VALIDATE                                              │
│     • Reviewer runs all checks                           │
│     • TypeScript, lint, tests, coverage, security       │
│     • Generates report                                   │
└──────────────────────────────────────────────────────────┘
                           ↓
                    Issues found?
                         │
              ┌──────────┴──────────┐
              ↓                     ↓
┌─────────────────────────┐  ┌─────────────────────────┐
│  5a. FIX                │  │  5b. COMPLETE           │
│     • Fixer resolves    │  │     • Update completion  │
│     • Re-validate       │  │     • Mark feature done  │
│     • Loop until pass   │  │     • Prepare next task  │
└─────────────────────────┘  └─────────────────────────┘
              │                     │
              └──────────┬──────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│  6. UPDATE STATE                                          │
│     • Update completion.json                             │
│     • Update state.json                                  │
│     • Log progress                                       │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│  7. LOOP                                                  │
│     • Return to step 1                                   │
│     • Continue until all features complete               │
│     • Or until max iterations reached                    │
└──────────────────────────────────────────────────────────┘

1. /agentful-start
2. Orchestrator reads PRODUCT.md → "Contact form" feature
3. Delegates to @frontend → Creates contact form component
4. Delegates to @backend → Creates submission endpoint
5. Delegates to @tester → Writes form validation tests
6. Delegates to @reviewer → Validates all checks pass
7. Updates completion.json → contact-form: 100%
8. Reports success

Iteration 1: Backend auth service
  @backend → Auth service, JWT tokens → @reviewer → Pass
 
Iteration 2: Frontend login page
  @frontend → Login form, useAuth hook → @reviewer → Pass
 
Iteration 3: Registration flow
  @backend → Register endpoint → @frontend → Register form
  → @tester → Integration tests → @reviewer → Fail (coverage 72%)
 
Iteration 4: Fix coverage
  @fixer → Add edge case tests → @reviewer → Pass (coverage 84%)
 
Iteration 5: Password reset
  @backend → Reset flow → @tester → E2E tests → @reviewer → Pass
 
Final: Auth feature 100% complete

1. Report bug to orchestrator
2. Orchestrator delegates to @frontend
3. Frontend agent reproduces bug
4. Identifies root cause: z-index conflict
5. Implements fix
6. Delegates to @tester → Regression tests
7. Delegates to @reviewer → Validates
8. Updates completion.json → bugs-resolved++
9. Reports fix complete

/agentful-start  # Run one task
# Review the output
/agentful-start  # Run next task
# Review the output

# Ralph loop mode - runs 24/7 until complete
/ralph-loop "/agentful-start" \
  --max-iterations 50 \
  --completion-promise "AGENTFUL_COMPLETE"

# Start autonomous development
/agentful-start
 
# [Let it run 30-60 minutes]
 
# Check progress
/agentful-status
 
# If decisions needed:
/agentful-decide
 
# Resume autonomous mode
/agentful-start

Start
  │
  ├─ What do you need to build?
  │    ├─ New feature
  │    │   → Feature Development Workflow
  │    │
  │    ├─ Fix broken code
  │    │   → Bug Fixing Workflow
  │    │
  │    ├─ Improve existing code
  │    │   → Refactoring Workflow
  │    │
  │    └─ Add/improve tests
  │        → Testing Workflow
  │
  └─ How do you want to work?
       ├─ Full control, learn system
       │   → Manual mode
       │
       ├─ Fast, hands-off
       │   → Autonomous mode
       │
       └─ Balance of both
           → Hybrid mode (recommended)

# Check current status
/agentful-status
 
# Typical output:
🔧 Working on: User Authentication Backend
   Phase: implementation
   Iterations: 8
   Progress: ████████░░░░░░░░░░░ 40%
 
Quality Gates:
   ✅ Tests Passing
   ✅ No Type Errors
   ⚠️  Coverage 76% (needs 80%)
   ✅ No Dead Code
 
Next Actions:
   • /agentful-start    - Continue development
   • /agentful-decide  - Answer pending decision

# Current work
cat .agentful/state.json
 
# Completion status
cat .agentful/completion.json
 
# Pending decisions
cat .agentful/decisions.json
 
# Last validation
cat .agentful/last-review.json

# Check for pending decisions
/agentful-decide
 
# Verify state files exist
ls -la .agentful/
 
# Check PRODUCT.md exists
cat PRODUCT.md
 
# Try running orchestrator directly
Task("orchestrator", "Test orchestrator")

# Check status
/agentful-status
 
# Run validation to see issues
/agentful-validate
 
# If validation keeps failing:
# 1. Review last-review.json
# 2. Fix manually if needed
# 3. Restart: /agentful-start

# See specific failures
/agentful-validate
 
# Let Fixer auto-fix
/agentful-start
 
# If Fixer can't resolve:
# Manual intervention needed
# Review .agentful/last-review.json

### 1. User Authentication - CRITICAL
**Description**: Email/password authentication with JWT
 
**Acceptance Criteria**:
- [ ] Login endpoint: POST /api/auth/login
- [ ] Register endpoint: POST /api/auth/register
- [ ] JWT token generation
- [ ] Token refresh flow
- [ ] Secure password hashing (bcrypt)
 
**Tech Stack**:
- Frontend: Next.js 14
- Backend: Next.js API Routes
- Auth: JWT (jsonwebtoken)
- Database: PostgreSQL + Prisma

## Features
1. Authentication
2. User management
3. Dashboard

# Good: Always validate after major features
/agentful-start  # Complete feature
/agentful-validate  # Verify quality
 
# Bad: Skip validation
/agentful-start  # Complete feature
# Move on immediately without checking

# Every 30-60 minutes during active development
/agentful-status
 
# After each completed feature
/agentful-status

# When warned about decisions:
⚠️  Pending decisions need your input
 
# Resolve immediately:
/agentful-decide
 
# Then resume:
/agentful-start

# Work on 2 features simultaneously
# .agentful/state.json
{
  "parallel_tasks": 2,
  "active_tasks": [
    "auth-backend",
    "user-profile-frontend"
  ]
}
 
/agentful-start

# Create branch for feature
git checkout -b feature/authentication
 
# Run autonomous workflow
/agentful-start
 
# When complete, commit and merge
git add .
git commit -m "feat: authentication system"
git checkout main
git merge feature/authentication

# Deliver features in batches
# PRODUCT.md
## Phase 1 - MVP
- Authentication
- User profile
- Basic dashboard
 
## Phase 2 - Enhancement
- Advanced search
- Notifications
- Settings
 
# Run for Phase 1 only
/agentful-start
 
# Deliver Phase 1, then run for Phase 2
/agentful-start

# If something goes wrong:
# 1. Stop agentful
# 2. Review changes
git diff
 
# 3. Rollback if needed
git reset --hard HEAD
 
# 4. Reset state
echo '{"version":"1.0","current_task":null,"current_phase":"idle","iterations":0}' > .agentful/state.json
 
# 5. Start fresh
/agentful-start

/ralph-loop "/agentful-start" \
  --max-iterations 50 \
  --completion-promise "AGENTFUL_COMPLETE"