/babysit

An interactive mentor that guides you through implementing features from plain-English requirements to completed pull requests. Babysit combines automated context gathering, intelligent task suggestions, and hands-on code assistance.

Quick Start

Copy/agileflow:babysit

The command will:

1. Gather all project context (stories, epics, tests, documentation)
2. Present intelligent task suggestions based on priority and readiness
3. Guide you through implementation step-by-step
4. Update your project status as you work
5. Generate PR descriptions when ready

Key Features

Smart Detection (Auto-Enable Features)

When you start babysit, it automatically detects and enables appropriate features:

• Loop Mode: Auto-enabled for epics with 3+ ready stories and test setup
• Visual Mode: Auto-enabled for UI/component work or AG-UI owner
• Coverage Mode: Auto-enabled if coverage baseline >50%
• Discretion Conditions: Auto-detected from package.json scripts (lint, types, build)

You can override auto-detection with parameters like MODE=once, VISUAL=false, or COVERAGE=0.

Intelligent Task Suggestions

When you start /babysit, it analyzes your project and recommends:

• READY stories (all AC complete, tests stubbed) - Highest priority
• Blocked stories (with clear unblock paths) - High priority
• Near-complete epics (80%+ stories done) - Finish what you started
• Roadmap priorities - Important strategic work
• Research gaps - Prep work to avoid debugging later

Tasks are ranked by what a real developer would prioritize, not just by recency or order.

Hands-On Implementation Guidance

For each story or feature:

Copy1. Validate story readiness (acceptance criteria, tests)
2. Read architecture context relevant to the task
3. Plan implementation in small steps
4. Apply code changes incrementally with diffs
5. Run tests after each change
6. Update project status as you progress
7. Generate PR description when complete

Agent Expert Spawning

For complex work, babysit automatically detects the domain and spawns specialists:

• Database work → AG-DATABASE expert
• API endpoints → AG-API expert
• UI components → AG-UI expert
• Testing → AG-TESTING expert
• Documentation → AG-DOCUMENTATION expert

Specialists handle focused deep work while babysit coordinates overall flow.

Story Claiming (Multi-Session Coordination)

In multi-session projects, babysit prevents conflicts:

• Before suggesting stories: Run story-claiming check to exclude stories claimed by other sessions
• After user selects: Claim the story to mark it as in-progress
• When complete: Release the claim so others can work on it
• Story badges: ⭐ Ready/available, 🔒 Claimed by other session, ✓ Claimed by this session

This prevents accidental merge conflicts when multiple Claude sessions work on the same repo.

Post-Implementation Quality Check

After implementation completes, babysit offers optional quality checks:

• Run tests - Standard verification
• 🔍 Run logic audit - Multi-agent analysis for edge cases, race conditions, type bugs
• Continue to next story - Move on without additional checks
• Review changes - Manual review before PR
• Pause here - Stop for now

Logic audit is recommended for complex code to catch issues tests might miss.

Progress Tracking

All work is tracked step-by-step:

1. Run context script (loads project state)
2. Check for claimed stories (prevent conflicts)
3. Present task suggestions
4. Claim selected story
5. Read story & architecture docs
6. Enter plan mode (for non-trivial tasks)
7. Implement code changes with tests
8. (Optional) Run logic audit
9. Update status.json
10. Release story claim
11. Present next steps

You can see exactly where you are and what's left at each step.

Usage

Basic - Let babysit suggest work

Copy/agileflow:babysit

Babysit will analyze your project and ask what you'd like to work on.

Resume existing work

Copy/agileflow:babysit

If you have stories in in_progress status, babysit will offer to resume them.

Work on specific story

You can tell babysit "I want to work on US-0042" and it will:

• Load the story file
• Validate it's ready
• Plan the implementation
• Guide you through building it

Parameters

Babysit accepts free-form natural language input:

Autonomous Loop Mode

Babysit supports autonomous execution through Loop Mode, which processes an entire epic's stories automatically with optional Visual Mode (screenshots) and Coverage Mode (test coverage tracking).

Quick Start

Copy# Basic loop - test-driven automation
/agileflow:babysit EPIC=EP-0042 MODE=loop MAX=20
 
# With Visual Mode for UI development
/agileflow:babysit EPIC=EP-0042 MODE=loop VISUAL=true
 
# With Coverage Mode for TDD (iterate until 80% coverage)
/agileflow:babysit EPIC=EP-0042 MODE=loop COVERAGE=80

Auto-Detection

You don't always need to specify parameters. Babysit auto-detects:

How It Works

Copy1. Smart Detection: Analyze project, auto-enable features
2. Initialize loop for epic
3. Load first "ready" story, mark in_progress
4. Implement story (with Visual/Coverage checks if enabled)
5. When Claude stops → Stop hook runs tests & gates
   - Run npm test
   - If Visual Mode: verify screenshots
   - If Coverage Mode: check coverage threshold
   - If Conditions: run lint/types/build checks
6. Based on results:
   - PASS all gates → mark story complete, load next
   - FAIL any gate → show errors, continue fixing
7. Repeat until epic complete or max iterations

Parameters

Note: Most parameters are auto-detected. Only override if needed.

Loop Control

Copy# Check loop status
node scripts/ralph-loop.js --status
 
# Stop the loop manually
node scripts/ralph-loop.js --stop
 
# Reset loop state
node scripts/ralph-loop.js --reset

When to Use Loop Mode

Good for:

• Processing a well-defined epic with clear stories
• Test-driven development (tests define "done")
• Batch processing multiple stories

Not good for:

• Exploratory work without clear acceptance criteria
• Stories requiring human review before proceeding
• Complex multi-domain work needing coordination

For comprehensive Loop Mode documentation including Visual Mode and Coverage Mode, see the Loop Mode Feature Guide.

Example Session

Copy/agileflow:babysit EPIC=EP-0042 MODE=loop MAX=20
 
→ Ralph Loop Initialized
  Epic: EP-0042
  Stories: 5 ready, 7 total
  Starting: US-0015 "Add user authentication"
 
[Claude implements US-0015...]
 
→ Stop Hook: Running tests...
  ✓ Tests pass
  ✓ Marked US-0015 complete
  → Moving to US-0016
 
[Claude implements US-0016...]
 
→ Stop Hook: Running tests...
  ✗ 2 tests failing
  → Fix errors and continue
 
[Claude fixes tests...]
 
→ Stop Hook: Running tests...
  ✓ Tests pass
  ✓ Marked US-0016 complete
  → Moving to US-0017
 
[...continues until epic complete...]
 
→ EPIC COMPLETE!
  EP-0042 finished in 12 iterations
  5 stories completed

Examples

Start fresh implementation

Copy/agileflow:babysit
# Babysit suggests: "US-0042: User Login API is READY"
# You confirm → Implementation begins
# Babysit guides through: Plan → Code → Test → PR

Complete multiple related stories

Copy/agileflow:babysit
# Babysit shows: "EP-0005 is 80% done. 1 story left: US-0051"
# You accept → Start final story
# Babysit tracks progress
# When done → Ready for baseline or release

Unknown requirements

Copy/agileflow:babysit
# You: "I want user authentication but not sure the best way"
# Babysit: "Should I research JWT vs sessions first? This prevents debugging later"
# You: "Yes, research"
# Babysit: Runs /agileflow:research:ask, saves findings, then plans implementation

Workflow Overview

CopyStart → Gather Context → Suggest Tasks → Choose Task
  ↓
Read Story & Architecture → Validate Readiness → Plan Steps
  ↓
Implement Code → Run Tests → Update Status
  ↓
Generate PR → Finish

Definition of Ready

Before implementing, babysit checks that stories have:

• ✓ Acceptance Criteria (Given/When/Then format)
• ✓ Architecture Context with source citations
• ✓ Test stubs in docs/07-testing/
• ✓ Dependencies resolved and documented
• ✓ Previous insights from related stories

If any are missing, babysit will suggest completing them first (stories stay "draft" until ready).

Context Loading

When you start babysit, it runs this context script automatically:

Copynode .agileflow/scripts/obtain-context.js babysit

This single command gathers:

• Git status, branch, uncommitted changes
• All stories and epics from status.json
• Session state and active sessions
• Documentation structure
• Research notes (newest first)
• Recent agent messages
• Key file presence

One script call, comprehensive context, fast startup.

When to Use

Best For

• Starting implementation - Need guidance on what to work on
• Picking up mid-feature - Resume from where you left off
• Epic completion - Finish final stories in a feature set
• Uncertain requirements - Research questions before coding
• Multi-step features - Complex work across files
• Testing validation - Ensure tests pass before PR

Not For

• Quick fixes (typos, one-liners) - Just do them yourself
• Pure research - Use /agileflow:research:ask instead
• Architectural decisions - Use /agileflow:adr instead
• Documentation only - Use /agileflow:docs instead

Output Style

Babysit uses clear, actionable output:

• Headings for major sections
• Short bullets for options and explanations
• Code blocks for diffs and examples
• Questions to guide your decisions (never asks you to "type")
• Progress updates as you work

Every response ends with a next-step question so you're always in control.

Integration with Other Commands

Babysit works alongside other AgileFlow commands:

Tips

Get better suggestions

• Keep your story backlog in status.json
• Write clear acceptance criteria
• Mark stories as ready when complete
• Keep architecture docs current

Successful implementations

• Let babysit validate story readiness first
• Read the architecture context section
• Implement in small steps (not all at once)
• Run tests after each change
• Ask for help if stuck

Multi-expert orchestration

For complex features, babysit will automatically:

• Spawn API expert for backend work
• Spawn UI expert for frontend work
• Run both in parallel if independent
• Coordinate the final integration

You don't need to manually manage multiple agents - babysit handles it.

Common Patterns

"I don't know what to work on"

Copy/agileflow:babysit
→ Babysit shows ranked suggestions
→ Pick the one that interests you
→ Let babysit guide the implementation

"I want to finish this epic"

Copy/agileflow:babysit
→ "EP-0005 is 80% done, 2 stories left"
→ Choose story
→ Complete it with babysit's guidance
→ Move to next story
→ When done: /agileflow:baseline "EP-0005 complete"

"I need to research this first"

Copy/agileflow:babysit
→ "Need to understand JWT patterns first?"
→ "Yes, research"
→ /agileflow:research:ask TOPIC="JWT best practices"
→ Copy research results back
→ Babysit plans implementation based on research
→ Code with confidence

Related Commands

• /epic - Create a new epic with stories
• /story - Create individual stories
• /verify - Run tests
• /pr - Generate pull request
• /review - Code review
• /impact - Analyze change impact
• /context - Research and context
• /baseline - Create verified checkpoint

Related Features

• Loop Mode - Full documentation for autonomous story processing
• Visual Mode - Screenshot verification for UI development
• Compact Context - Context preservation during long sessions