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