docs/user-guide/01-discovery-analysis
Babysitter User Documentation - Discovery Analysis reference
1. Product Overview(1-product-overview)
Continue reading
Nearby pages in the same section.
Babysitter User Documentation - Discovery Analysis
**Version:** 1.0 **Date:** 2026-01-25 **Author:** Technical Documentation Analyst **Status:** Discovery Phase Complete
---
Table of Contents
1. Product Overview 2. Target Audience Segments 3. Prerequisites 4. Installation Steps 5. Quick Win Scenarios 6. User Journeys 7. Key Terminology and Concepts 8. Common Issues and Pain Points 9. Documentation Recommendations
---
1. Product Overview
1.1 What is Babysitter?
Babysitter is an **event-sourced orchestration framework** for Claude Code that enables deterministic, resumable, and human-in-the-loop workflow management. It transforms how developers interact with AI-assisted coding by providing:
- **Structured multi-step workflows** with built-in quality gates
- **Human approval checkpoints** (breakpoints) for critical decisions
- **Iterative quality convergence** until targets are met
- **Complete audit trails** via append-only event journals
- **Session persistence and resumability** across interruptions
1.2 Core Value Proposition
| Traditional AI Coding | With Babysitter |
|---|---|
| Run once, hope it works | Iterate until quality target met |
| Manual approval via chat | Structured breakpoints with context |
| State lost on session end | Event-sourced, fully resumable |
| Single task execution | Parallel execution with dependencies |
| No audit trail | Complete journal of all events |
| Ad-hoc workflows | Process-driven, customizable methodologies |
1.3 Key Components
1. **Babysitter SDK** (@a5c-ai/babysitter-sdk) - Core orchestration runtime, CLI 2. **Babysitter Plugin** (babysitter@a5c.ai) - Claude Code integration 3. **Process Library** - SDK-managed built-in library of methodologies, shared processes, and domain specializations
1.4 Architecture Summary
User Request --> Claude Code --> Babysitter Skill --> SDK CLI
|
+----------------+----------------+
| | |
Process Engine Journal System Breakpoints
| | |
Task Execution Event Log Human Approval---
2. Target Audience Segments
2.1 Primary Audience
Segment A: Claude Code Power Users
- **Profile:** Developers already using Claude Code for complex tasks
- **Pain Point:** Losing context, manual iteration, no quality assurance
- **Key Need:** Structured workflows that persist across sessions
- **Technical Level:** Intermediate to Advanced
- **Expected Interaction:** Daily use for feature development
Segment B: Team Leads / Tech Leads
- **Profile:** Technical leaders managing AI-assisted development
- **Pain Point:** Lack of audit trails, no approval gates for critical changes
- **Key Need:** Human-in-the-loop controls, compliance, traceability
- **Technical Level:** Advanced
- **Expected Interaction:** Setting up processes, reviewing breakpoints
Segment C: DevOps / Automation Engineers
- **Profile:** Engineers building CI/CD and automation pipelines
- **Pain Point:** Non-deterministic AI behavior, hard to integrate
- **Key Need:** Deterministic execution, CLI interface, scriptability
- **Technical Level:** Advanced
- **Expected Interaction:** CI/CD integration, custom hooks
2.2 Secondary Audience
Segment D: Developers New to Claude Code
- **Profile:** Developers exploring AI-assisted coding
- **Pain Point:** Overwhelming complexity, don't know where to start
- **Key Need:** Simple onboarding, quick wins, clear documentation
- **Technical Level:** Beginner to Intermediate
- **Expected Interaction:** Learning, experimentation
Segment E: Enterprise Teams
- **Profile:** Organizations with compliance requirements
- **Pain Point:** Auditability, security, governance
- **Key Need:** Complete audit trails, approval workflows, access control
- **Technical Level:** Varied
- **Expected Interaction:** Production workflows with approval gates
---
3. Prerequisites
3.1 Required Software
| Requirement | Version | Notes |
|---|---|---|
| **Node.js** | 20.0.0+ (recommend 22.x LTS) | Use nvm for version management |
| **Claude Code** | Latest | Must be installed and configured |
| **npm** | 8.0.0+ | Comes with Node.js |
3.2 Optional Software
| Requirement | Purpose | Notes |
|---|---|---|
| **Git** | Version control | Required for cloning, recommended for workflows |
| **jq** | JSON processing | Helpful for CLI output parsing |
3.3 Knowledge Prerequisites
| Level | What You Should Know | Documentation Section |
|---|---|---|
| **Required** | Basic command line usage | N/A |
| **Required** | Claude Code basics (prompting, tools) | External: Claude Code docs |
| **Helpful** | JavaScript/TypeScript fundamentals | For custom processes |
| **Helpful** | Event sourcing concepts | For understanding journal system |
| **Optional** | TDD/BDD methodologies | For quality-focused workflows |
3.4 Account Requirements
- **Claude API access** (via Claude Code subscription)
- **GitHub account** (for plugin marketplace access)
---
4. Installation Steps
4.1 Quick Installation (Recommended)
**Step 1: Install SDK and Packages**
npm install -g @a5c-ai/babysitter@latest**Step 2: Install Claude Code Plugin**
# Add the plugin repository
claude plugin marketplace add a5c-ai/babysitter-claude
# Install the plugin
claude plugin install --scope user babysitter@a5c.ai
# Enable the plugin
claude plugin enable --scope user babysitter@a5c.ai**Step 3: Restart Claude Code**
**Step 4: Verify Installation**
# Check core CLI version
babysitter --version
# In Claude Code, verify skill is available
/skills # Should list "babysit"4.2 Installation Verification Checklist
- [ ]
babysitter --versionreturns version number - [ ] Claude Code
/skillscommand shows "babysit" - [ ] Can create a test run with
babysitter run:create --help
4.3 Keeping Updated
# Update CLI packages
npm update -g @a5c-ai/babysitter @a5c-ai/babysitter-agent
# Update Claude Code plugin
claude plugin marketplace update a5c.ai
claude plugin update babysitter@a5c.ai---
5. Quick Win Scenarios
5.1 First Quick Win: Simple TDD Feature (10-15 minutes)
**Goal:** Build a small feature using TDD methodology with quality gates.
**Command:**
claude "/babysitter:call implement a simple calculator module with TDD and 80% quality target"**What Happens:** 1. Babysitter creates a run with TDD quality convergence 2. Research phase analyzes codebase 3. Writes tests first, then implementation 4. Iterates until 80% quality score achieved 5. Requests approval via breakpoint before completion
**Success Criteria:**
- Working calculator module created
- Tests passing
- Quality score >= 80%
- Full event history in
.a5c/runs/
5.2 Second Quick Win: Resume Interrupted Work (5 minutes)
**Goal:** Demonstrate session persistence by resuming a paused run.
**Steps:** 1. Start a run: claude "/babysitter:call build a todo API --max-iterations 10" 2. Close Claude Code mid-execution 3. Reopen Claude Code 4. Resume: claude "/babysitter:call resume the babysitter run and continue"
**Success Criteria:**
- Run continues from exact point of interruption
- No work is lost
- Journal shows complete history
5.4 Quick Win Difficulty Progression
| Scenario | Time | Complexity | Prerequisites |
|---|---|---|---|
| Simple TDD feature | 10-15 min | Low | Basic installation |
| Resume interrupted work | 5 min | Low | Completed first scenario |
| Custom process definition | 30+ min | High | JavaScript knowledge |
| CI/CD integration | 60+ min | High | DevOps experience |
---
6. User Journeys
6.1 Journey Map: Getting Started to Mastery
Level 1: First Use (Day 1)
|
+---> Install babysitter
+---> Run first /babysitter:call command
+---> Observe automatic iteration
+---> See quality convergence in action
|
Level 2: Regular Use (Week 1-2)
|
+---> Use TDD methodology for features
+---> Experience session resumption
|
Level 3: Proficient Use (Month 1)
|
+---> Explore different methodologies (GSD, Spec-Kit)
+---> Customize quality targets
+---> Use parallel execution for efficiency
+---> Analyze journal events for debugging
|
Level 4: Advanced Use (Month 2+)
|
+---> Create custom process definitions
+---> Build custom hooks
+---> Integrate with CI/CD pipelines
+---> Contribute to process library
|
Level 5: Expert Use (Ongoing)
|
+---> Architect complex multi-phase workflows
+---> Enterprise deployment with compliance
+---> Team-wide adoption and governance
+---> Custom methodology development6.2 Detailed User Journey: Developer Building a Feature
**Persona:** Sarah, a full-stack developer working on a new API feature
**Journey:**
1. **Awareness** (0-5 min) - Sarah hears about Babysitter from a colleague - Reviews README for value proposition - Decides to try it for her next feature
2. **Installation** (10-15 min) - Follows installation guide - Installs SDK and plugin - Verifies installation works
3. **First Run** (15-30 min) - Uses /babysitter:call with simple prompt - Observes automatic iteration - Sees quality convergence working - Feature delivered with tests
4. **Growing Confidence** (Week 1) - Uses Babysitter for multiple features - Learns to specify quality targets - Experiences session resumption - Starts using breakpoints for critical changes
5. **Customization** (Week 2-4) - Explores different methodologies - Adjusts iteration limits - Reviews journal for debugging - Shares experience with team
6. **Advanced Usage** (Month 2+) - Creates custom processes for team workflows - Integrates with team CI/CD - Advocates for team adoption
6.3 Critical User Journey Moments
| Moment | User Emotion | Risk | Mitigation |
|---|---|---|---|
| First installation | Cautious excitement | Installation failure | Clear prerequisites, verification steps |
| First /babysitter:call command | Curious | Nothing happens | Immediate feedback, progress indicators |
| First breakpoint | Confused | Don't know how to approve | Clear instructions in CLI output |
| Session interruption | Frustrated | Fear of lost work | Clear messaging about resumability |
| Quality not converging | Frustrated | Wasted iterations | Guidance on adjusting targets |
| Custom process creation | Challenged | Steep learning curve | Examples, templates, documentation |
---
7. Key Terminology and Concepts
7.1 Core Concepts
| Term | Definition | Example |
|---|---|---|
| **Run** | A single execution of a process, identified by a run ID | run-20260125-143012 |
| **Process** | A JavaScript function that orchestrates workflow logic | tdd-quality-convergence.js |
| **Journal** | Append-only event log recording all state changes | .a5c/runs/<runId>/journal/ |
| **Iteration** | One pass through the orchestration loop | run:iterate command |
| **Effect** | A side-effect request (task, breakpoint, sleep) | Task execution, human approval |
7.2 Task Types
| Task Type | Description | Use Case |
|---|---|---|
| **Agent** | LLM-powered task | Planning, scoring, analysis |
| **Skill** | Claude Code skill invocation | Code refactoring, search |
| **Node** | JavaScript/Node.js script | Build, test, deploy scripts |
| **Shell** | System shell command | File operations, git commands |
| **Breakpoint** | Human approval gate | Critical decisions, deployments |
7.3 Workflow Concepts
| Term | Definition | Context |
|---|---|---|
| **Quality Convergence** | Iterating until quality score meets target | TDD workflows with 85% target |
| **Breakpoint** | Pause point requiring human approval | Before production deployment |
| **Deterministic Replay** | Same inputs + journal = same execution path | Session resumption |
| **Event Sourcing** | State derived from replaying events | Journal-based state reconstruction |
| **In-Session Loop** | Continuous iteration within a single Claude session | /babysitter:call command with max iterations |
7.4 File Structure Glossary
| Path | Purpose |
|---|---|
.a5c/runs/<runId>/ | Run directory containing all run artifacts |
journal/ | Append-only event log (one file per event) |
state/state.json | Derived state cache (gitignored, rebuildable) |
tasks/<effectId>/ | Task artifacts (inputs, results, logs) |
code/main.js | Process implementation |
artifacts/ | Generated artifacts (plans, specs, reports) |
7.5 Status Values
| Status | Meaning | Action |
|---|---|---|
executed | Tasks ran successfully | Continue iterating |
waiting | Breakpoint or sleep active | Wait for resolution |
completed | Run finished successfully | Exit loop, review results |
failed | Run failed with error | Debug, possibly retry |
none | No pending effects | May indicate completion |
---
8. Common Issues and Pain Points
8.1 Installation Issues
| Issue | Cause | Solution |
|---|---|---|
| CLI not found after install | Global npm path not in PATH | Add npm global bin to PATH, or use npx |
| Plugin not appearing in Claude Code | Plugin not enabled | Run claude plugin enable --scope user babysitter@a5c.ai |
| Version mismatch errors | Mixed versions of packages | Update all packages to latest |
| Permission denied on hooks | Hook files not executable | Run chmod +x on hook files |
8.2 Runtime Issues
| Issue | Cause | Solution |
|---|---|---|
| Session ended unexpectedly | Network issue, Claude Code crash | Resume with /babysitter:call resume --run-id <id> |
| Quality score not improving | Unrealistic target or blocking issues | Lower target, review iteration logs |
| Agent task timeout | Large context, API issues | Reduce task scope, check API status |
| Journal conflict | Concurrent operations | Avoid multiple instances, use resume to recover |
8.3 Conceptual Pain Points
| Pain Point | User Confusion | Resolution Strategy |
|---|---|---|
| Event sourcing mental model | "Why is there a journal?" | Explain benefits: audit trail, resumability, debugging |
| Breakpoint workflow | "How do I approve things?" | Step-by-step breakpoint tutorial with screenshots |
| Process definitions | "How do I customize workflows?" | Templates, examples, progressive complexity |
| Quality scoring | "What determines the score?" | Document scoring criteria, show how to customize |
| In-session loop vs run orchestration | "What's the difference?" | Clear comparison table, use case guidance |
8.4 Error Messages and Solutions
| Error Message | Meaning | Solution |
|---|---|---|
Run encountered an error | Journal or state corruption | Analyze journal, recover from last good state |
Breakpoint not resolving | Service unreachable or timeout | Check service status, verify network |
ENOENT: no such file or directory | Missing file in task | Verify paths, check dependencies installed |
Cannot find module '@a5c-ai/babysitter-sdk' | SDK dependency missing in your project | Run npm install @a5c-ai/babysitter-sdk |
Plugin not found: babysitter@a5c.ai | Plugin not installed in Claude Code | Follow plugin installation steps |
8.5 Performance Pain Points
| Issue | Symptom | Optimization |
|---|---|---|
| Slow iterations | Each iteration takes minutes | Use parallel execution, reduce agent task scope |
| Large journal files | Disk usage grows quickly | Clean old runs, archive completed work |
| Memory issues | Out of memory errors | Limit concurrent tasks, increase Node.js heap |
| Runaway loops | Iterations don't converge | Set iteration limits, review quality criteria |
---
9. Documentation Recommendations
9.1 Recommended Documentation Structure
docs/user-guide/
|
+-- 01-discovery-analysis.md (THIS DOCUMENT)
|
+-- 02-getting-started/
| +-- installation.md (Detailed installation guide)
| +-- first-run.md (Your first babysitter run)
| +-- quick-reference.md (Command cheat sheet)
|
+-- 03-core-concepts/
| +-- event-sourcing.md (Understanding the journal)
| +-- process-definitions.md (How processes work)
| +-- task-types.md (Agent, skill, node, etc.)
| +-- breakpoints.md (Human-in-the-loop approval)
| +-- quality-convergence.md (Iterative quality improvement)
|
+-- 04-workflows/
| +-- tdd-development.md (Test-driven development)
| +-- feature-implementation.md (End-to-end feature workflow)
| +-- code-review.md (Review and refactoring)
|
+-- 05-methodologies/
| +-- tdd-quality-convergence.md
| +-- gsd-get-shit-done.md
| +-- spec-kit.md
| +-- custom-methodologies.md
|
+-- 06-advanced/
| +-- custom-processes.md (Writing process definitions)
| +-- custom-hooks.md (Hook development)
| +-- parallel-execution.md (Optimizing with parallelism)
| +-- troubleshooting.md (Debug and recovery)
|
+-- 07-reference/
| +-- cli-reference.md (Complete CLI documentation)
| +-- api-reference.md (SDK API documentation)
| +-- configuration.md (Environment variables, settings)
| +-- glossary.md (Terminology reference)
|
+-- 08-tutorials/
| +-- tutorial-todo-app.md (Build a todo app step-by-step)
| +-- tutorial-auth-feature.md (Add authentication with TDD)
| +-- tutorial-ci-integration.md (GitHub Actions integration)9.2 Priority Documentation by Audience
For Beginners (Priority 1)
1. Installation guide with troubleshooting 2. First run tutorial (step-by-step) 3. Quick reference / cheat sheet 4. Glossary of terms
For Regular Users (Priority 2)
1. Methodology guides (TDD, GSD, Spec-Kit) 2. Breakpoints workflow guide 3. Session resumption guide 4. Quality target configuration
For Advanced Users (Priority 3)
1. Custom process development 2. Hook development guide 3. CI/CD integration patterns 4. Performance optimization
9.3 Content Format Recommendations
| Content Type | Format | Reason |
|---|---|---|
| Installation | Step-by-step numbered lists | Easy to follow, verify completion |
| Tutorials | Progressive complexity | Build confidence gradually |
| Reference | Tables, code blocks | Quick lookup, copy-paste |
| Concepts | Diagrams, flowcharts | Visual understanding |
| Troubleshooting | Problem-solution tables | Fast resolution |
9.4 Documentation Gaps Identified
Based on analysis of existing documentation:
| Gap | Current State | Recommendation |
|---|---|---|
| Visual diagrams | ASCII art only | Add flowcharts, architecture diagrams |
| Video tutorials | None | Create getting started video |
| Interactive examples | Static code only | Add CodeSandbox/Replit examples |
| Error message catalog | Scattered in troubleshooting | Centralized error reference |
| Upgrade guides | None | Document breaking changes between versions |
| Best practices compilation | Scattered throughout | Dedicated best practices guide |
9.5 Documentation Maintenance Recommendations
1. **Version Sync:** Keep documentation versions aligned with SDK versions 2. **Example Verification:** All code examples should be tested automatically 3. **Link Validation:** Regular broken link checking 4. **User Feedback:** Add feedback mechanism to documentation pages 5. **Analytics:** Track most-visited pages to prioritize updates 6. **Community Contributions:** Accept documentation PRs with clear guidelines
9.6 Immediate Next Steps
1. **Week 1:** Create installation guide with screenshots 2. **Week 2:** Build "First Run" tutorial with complete walkthrough 3. **Week 3:** Document TDD workflow with real example 4. **Week 4:** Create CLI quick reference card 5. **Month 2:** Develop advanced tutorials (custom processes, CI/CD)
---
Appendix A: Source Documents Analyzed
| Document | Path | Key Insights |
|---|---|---|
| Main README | /README.md | Value proposition, installation, examples |
| Plugin Specification | /plugins/babysitter-unified/plugin.json | Canonical plugin metadata and target profiles |
| Skill Documentation | /plugins/babysitter-unified/skills/babysit/SKILL.md | Orchestration workflow |
| CLI Spec | /notes/babysitter_cli_surface_spec.md | CLI commands and behavior |
| CLI Examples | /docs/cli-examples.md | Usage patterns |
| Breakpoints README | /packages/breakpoints/README.md | Human approval system |
| Process Library README | /library/README.md | Built-in library overview |
| SDK Package.json | /packages/sdk/package.json | Version, dependencies |
Appendix B: Key Metrics for Documentation Success
| Metric | Target | Measurement |
|---|---|---|
| Time to first successful run | < 30 minutes | User testing |
| Installation success rate | > 95% | Support tickets |
| Documentation satisfaction | > 4.0/5.0 | User surveys |
| Support ticket reduction | 50% in 6 months | Ticket tracking |
| Community contribution | 5+ PRs/month | GitHub metrics |
---
**Document Status:** Complete **Next Phase:** Create detailed user guide documents per Section 9.1 structure **Review Date:** 2026-02-01