Standard patterns for multi-task workflows with mandatory checkpoints, state management, and error recovery. Use when orchestrating sequential tasks with decision points.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
The workflow loop is the foundational pattern for all multi-task work in devloop. It enforces checkpoints after every task completion and provides clear decision points for continuation, commitment, or context refresh.
┌─────────────────────────────────────────────────────────┐
│ WORKFLOW LOOP │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ PLAN │────▶│ WORK │────▶│ CHECKPOINT │ │
│ │(continue)│ │ (agent) │ │ (mandatory) │ │
│ └──────────┘ └──────────┘ └────────┬─────────┘ │
│ ▲ │ │
│ │ ┌──────────────────────────┼───────┐ │
│ │ │ ▼ │ │
│ │ │ ┌─────────┐ ┌─────────┐ │ │
│ │ │ │ COMMIT │◀──────│ DECIDE │ │ │
│ │ │ │(if yes) │ │ │ │ │
│ │ │ └────┬────┘ └────┬────┘ │ │
│ │ │ │ │ │ │
│ │ │ ▼ ▼ │ │
│ │ │ ┌─────────┐ ┌─────────┐ │ │
│ └───────────┼──│CONTINUE │ │ STOP │───┼───┘
│ │ │ (next) │ │(summary)│ │
│ │ └─────────┘ └─────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌─────────┐ │
│ │ │ FRESH │ (optional) │
│ │ │ (clear) │ │
│ │ └────┬────┘ │
│ │ │ │
│ │ ▼ │
│ │ [New Session] │
│ │ │ │
│ └───────┼──────────────────────────┘
│ │
│ ▼
│ [SessionStart detects state]
│ │
│ ▼
│ [Back to PLAN]
│ │
└─────────────────────────────────────────────────────────┘
What happens: Identify the next task to execute from the plan.
Inputs:
.devloop/plan.md with task listOutputs:
Actions:
# Find next pending task
grep "^- \[ \]" .devloop/plan.md | head -1
# Extract task ID and description
# Present to user if multiple options exist
What happens: Execute the task using agents or direct operations.
Inputs:
Outputs:
Agent Selection:
devloop:engineercode-reviewerrefactor-analyzercode-explorertest-generatorKey Principle: Agents execute autonomously during this phase. Do NOT interrupt with questions mid-task.
What happens: Verify work completion and decide next action.
CRITICAL: This phase MUST ALWAYS run after every work phase. Never skip.
Success Indicators:
✓ Agent explicitly states task is complete
✓ Acceptance criteria are met
✓ No errors reported in agent output
✓ Required files were created/modified
Partial Indicators:
~ Agent completed but with limitations
~ Some acceptance criteria met, others pending
~ Errors occurred but recovered
Failure Indicators:
✗ Agent encountered blocking error
✗ Task not addressed at all
✗ Critical requirements missing
If .devloop/plan.md exists:
# Update task marker
# - [ ] → - [x] if complete
# - [ ] → - [~] if partial
# - [ ] → - [!] if blocked
# Add Progress Log entry
- [YYYY-MM-DD HH:MM]: Completed Task X.Y - [Description]
# Update file timestamp
**Updated**: [Current ISO timestamp]
Present mandatory decision:
AskUserQuestion:
question: "Task [X.Y] complete. How should we proceed?"
header: "Checkpoint"
options:
- label: "Commit now"
description: "Create atomic commit for this work"
- label: "Continue working"
description: "Group with related tasks before committing"
- label: "Fresh start"
description: "Save state, clear context, resume in new session"
- label: "Stop here"
description: "Generate summary and end session"
If "Commit now":
1. Prepare commit message:
- Type: feat/fix/refactor/docs/test/chore
- Scope: [component or file]
- Message: Task X.Y - [description]
2. Run git commit (or invoke devloop:engineer in git mode)
3. Verify commit succeeded
4. Update worklog with commit hash
5. Return to Step 5b (continuation decision)
If "Continue working":
1. No commit yet - changes remain staged
2. Return to Step 5b immediately
3. Proceed to next task in same phase
If "Fresh start":
1. Generate brief session summary
2. Write state to .devloop/next-action.json
3. Instruct user to run /clear
4. END workflow
5. SessionStart hook will detect state on new session
If "Stop here":
1. Invoke devloop:summary-generator
2. Present summary of work completed
3. Show suggested next steps
4. END workflow
What happens: Choose whether to continue or stop.
Inputs:
Decision Tree:
Checkpoint done?
├─ Yes: Continue to next task?
│ ├─ Yes: All tasks complete?
│ │ ├─ Yes: → COMPLETE (all done, ask about shipping)
│ │ └─ No: → Plan (next task)
│ └─ No: → STOP (summary and end)
└─ No: Error recovery
├─ Retry? → WORK (same task again)
├─ Skip? → Plan (next task, mark blocked)
└─ Investigate? → Manual review
What happens: Return to plan for next task or end session.
LOOP path (continue to next task):
[x] in planFRESH path (context refresh):
STOP path (end session):
Every checkpoint MUST verify:
| Requirement | Check | How |
|---|---|---|
| Work Output | Success/Failure/Partial | Agent output + human verification |
| Plan Markers | Tasks marked [x] or [~] | Read plan, verify entries |
| Decision Made | User selected option | AskUserQuestion response |
| Worklog Updated | Entry added if committed | Read worklog, verify entry |
| Loop Completion | Check remaining tasks | Count - [ ] entries |
PLAN ─────────────▶ WORK ────────────▶ CHECKPOINT
▲ │
│ ▼
│ DECIDE
│ │
│ ┌────────────────────────────────┼────────────────┐
│ │ │ │
│ ▼ ▼ ▼
│ CONTINUE COMMIT STOP
│ │ │ │
│ │ ▼ │
│ │ [Commit] │
│ │ │ │
│ └──────────────┬────────────────┘ │
│ │ │
│ ┌──────────────┴──────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ [Next Task] [All Complete?] │
│ │ │ │
│ │ ├─ Yes ─▶ SHIP │
│ │ │ │
│ └─────────────────┬───────────┘ │
│ │ │
│ ▼ │
│ [Back to PLAN] │
│ │ │
└──────────────────────────┘ │
│
┌───────────────────────────────┘
│
▼
[END]
SUMMARY LOG
| From | To | Trigger | Action |
|---|---|---|---|
| PLAN | WORK | Task identified | Launch agent |
| WORK | CHECKPOINT | Agent completes | Verify output |
| CHECKPOINT | COMMIT | User selects "Commit" | Create commit |
| CHECKPOINT | CONTINUE | User selects "Continue" | Next task |
| CHECKPOINT | FRESH | User selects "Fresh" | Save state |
| CHECKPOINT | STOP | User selects "Stop" | Generate summary |
| COMMIT | CONTINUE | Commit succeeds | Next task |
| CONTINUE | PLAN | Loop back | Increment counter |
| FRESH | [End] | State saved | User runs /clear |
| STOP | [End] | Summary generated | Session ends |
| [New Session] | PLAN | State file detected | Resume |
Agent fails → Checkpoint detects failure
AskUserQuestion:
question: "Agent failed on Task X.Y. How to proceed?"
header: "Recovery"
options:
- Retry (launch agent again with more context)
- Skip (move to next task, mark blocked)
- Investigate (show agent output for review)
- Abort (end workflow entirely)
If Retry:
[~]If Skip:
[!] (blocked)If Investigate:
Agent completes but task not fully done
Checkpoint detects: Not all acceptance criteria met
AskUserQuestion:
question: "Task X.Y partially complete. Acceptance: [criteria not met]. What now?"
header: "Partial"
options:
- Mark done anyway (continue to next task)
- Continue work (stay in WORK phase, maybe different agent)
- Note as tech debt (mark blocked, document issue)
After task, user selects "Commit now" → Commit fails
AskUserQuestion:
question: "Commit failed. Reason: [error]. What now?"
header: "Commit Error"
options:
- Fix and retry (show what needs fixing)
- Skip commit (continue without committing)
- Investigate (show git status, diff)
Task X.Y depends on Task X.1, which is still pending
AskUserQuestion:
question: "Task X.Y blocked on Task X.1. What now?"
header: "Blocked"
options:
- Reorder (move blocking task up)
- Skip (come back to this later)
- Investigate (show why it's blocked)
Context becomes stale when:
| Metric | Threshold | Action |
|---|---|---|
| Tasks completed | > 5 in session | Suggest fresh start |
| Agent invocations | > 10 in session | Suggest fresh start |
| Session duration | > 2 hours active | Suggest fresh start |
| Errors in session | > 3 distinct errors | Suggest fresh start |
| Last checkpoint | > 1 hour ago | Suggest fresh start |
| Plan file not updated | > 3 tasks | Suggest fresh start |
AskUserQuestion:
question: "Continue with current context?"
header: "Context"
options:
- Continue (stay in current session)
- Compact (use /compact to summarize)
- Fresh start (clear context, new session)
AskUserQuestion:
question: "We've completed significant work. Context may be getting heavy. Refresh?"
header: "Context"
options:
- Yes, fresh start (save state, clear context)
- No, continue (keep current session)
- Compact only (summarize without clearing)
For parallel tasks that benefit from isolation:
Task:
agent: devloop:engineer
mode: background
context: fresh # Separate from main session
prompt: |
[Task details...]
Benefits:
Costs:
After every checkpoint, check if workflow is complete:
# Count remaining work
pending=$(grep -c "^- \[ \]" .devloop/plan.md 2>/dev/null || echo "0")
in_progress=$(grep -c "^- \[~\]" .devloop/plan.md 2>/dev/null || echo "0")
if [ "$pending" -eq 0 ] && [ "$in_progress" -eq 0 ]; then
# All tasks complete!
# → COMPLETE state
fi
When all tasks are complete:
AskUserQuestion:
question: "🎉 All plan tasks complete! What would you like to do?"
header: "Complete"
options:
- label: "Ship it"
description: "Run /devloop:ship for final validation"
- label: "Add more tasks"
description: "Extend the plan with additional work"
- label: "Review"
description: "Review all completed work"
- label: "End session"
description: "Generate summary and finish"
Auto-updates:
The checkpoint MUST run:
# Anti-pattern: Skip checkpoint
if task_trivial; then
mark_complete
continue_to_next
fi
# Correct pattern: Always checkpoint
agent_result=$(launch_agent $task)
checkpoint "$agent_result" # Always runs
case "$user_decision" in
commit) ;;
continue) ;;
fresh) ;;
stop) ;;
esac
## Task 1.1: Create user model
Agent launches → Completes in 5 minutes
**Checkpoint**: ✓ Output verified
- File `models/User.go` created ✓
- Acceptance criteria met ✓
- No errors ✓
**Decision**: User selects "Commit now"
**Commit**: feat(models): add User type
- Created User type with full struct fields
- Added validation methods
**Result**: Committed as abc1234
**Continuation**: User selects "Continue working"
→ **Next**: Task 1.2
## Task 2.3: Implement OAuth2 flow
Agent launches → Encounters error in step 3
**Checkpoint**: ✗ Work incomplete
- OAuth2 provider setup failed
- Token refresh not implemented
- Error: "Invalid client ID in config"
**Recovery**: User selects "Investigate"
Shows:
- Agent error log
- What was completed
- Why it failed
**User decides**: "Retry with AWS credentials"
→ Agent relaunches with new context
## Task 3.2: Add caching layer
Agent completes quickly (2 minutes)
❌ WRONG: Command skips checkpoint
// "Trivial task, no need to verify"
// Directly marks complete and continues
Result:
- Agent actually only partially implemented feature
- Test failures appear later in review
- Wasted time tracking down issue
✓ CORRECT: Always checkpoint
Checkpoint verifies:
- Cache properly integrated
- All cache hits working
- Fallback on miss works
- Tests passing
→ Only then proceed
Session has now:
- 8 tasks completed
- 15 agent calls
- 90 minutes elapsed
- 2 errors encountered
❌ WRONG: Continue without refreshing
Command keeps going without offering context refresh
→ Quality degrades as model gets confused
✓ CORRECT: Offer fresh start
After task 8 checkpoint:
"We've done significant work. Context may be heavy.
- Continue (same session)
- Fresh start (clear, resume next task)
- Compact (summarize, stay)"
→ User decides fresh start
→ Quality improves for remaining tasks
The checkpoint updates the worklog:
## .devloop/worklog.md
### Completed Tasks
- [x] Task 1.1: Create user model (abc1234) - 2024-12-23 14:30
- [x] Task 1.2: Add validation (def5678) - 2024-12-23 15:00
- [x] Task 2.1: Create database schema (ghi9012) - 2024-12-23 16:15
Worklog entry created at checkpoint only if:
Problem: Asking too many questions at checkpoints
Solution: Batch related decisions:
# WRONG: Three separate questions
AskUserQuestion: "Commit now?"
AskUserQuestion: "Continue to next task?"
AskUserQuestion: "Refresh context?"
# RIGHT: One question with all options
AskUserQuestion:
question: "Task complete. What's next?"
options:
- Commit then continue
- Continue without commit
- Fresh start
- Stop here
Problem: Agent fails, command just moves to next task
Solution: Always give user recovery options
# WRONG: Just skip
if agent_failed:
mark_blocked
next_task()
# RIGHT: Offer recovery
if agent_failed:
AskUserQuestion:
options: [Retry, Skip, Investigate, Abort]
Problem: Checkpoint happens but plan doesn't reflect reality
Solution: Update plan immediately after verification
# Update before AskUserQuestion
if task_complete:
sed -i "s/^- \[ \] $task_id/- [x] $task_id/" plan.md
add_progress_log_entry "$task_id"
update_timestamp
# Then ask user
AskUserQuestion: ...
Problem: Session degrades after 10+ agent calls
Solution: Proactively offer fresh start at thresholds
# After checkpoint, check metrics
tasks_done=$((tasks_done + 1))
agent_calls=$((agent_calls + 1))
if [ $tasks_done -gt 5 ] || [ $agent_calls -gt 10 ]; then
AskUserQuestion: "Context refresh time?"
fi
The workflow loop pattern ensures:
✓ Reliability: Every task is verified before moving on ✓ Visibility: User always knows what's happening ✓ Recoverability: Errors are handled gracefully ✓ Flexibility: Multiple paths (commit, continue, fresh, stop) ✓ Sustainability: Context refresh prevents degradation ✓ Traceability: Plan and worklog stay in sync
Use this pattern in any workflow that: