{
  "id": "page:docs-user-guide-getting-started-first-run",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/getting-started/first-run.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/getting-started/first-run.md",
    "sourceKind": "repo-docs",
    "title": "First Run Deep Dive: Understanding What Happened",
    "displayName": "First Run Deep Dive: Understanding What Happened",
    "slug": "docs/user-guide/getting-started/first-run",
    "articlePath": "wiki/docs/user-guide/getting-started/first-run.md",
    "article": "\n[Docs](../index.md) › [Getting Started](./README.md) › First Run\n\n# First Run Deep Dive: Understanding What Happened\n\n**Time:** 10 minutes | **Level:** Beginner | **Prerequisites:** [Completed the Quickstart](./quickstart.md)\n\nIn the quickstart, you built a calculator with a single command and watched Babysitter run a deterministic process where the orchestrator only did what the code permitted — stopping after every step, checking what the process allowed next, and (among other gates) iterating a quality gate until its target was met. Now let's understand exactly what happened under the hood. This knowledge will help you use Babysitter more effectively and debug issues when they arise.\n\n> **Note on commands:** This page uses Claude Code's `/babysitter:call` command. Babysitter is harness-agnostic, and the in-session command surface varies by harness (for example, `$babysitter:call` on Codex, `$call` on Cursor/Copilot, `/status` on opencode). The run directory, journal, and convergence concepts described here are identical across all harnesses. See the [Slash Commands reference](../reference/slash-commands.md) and the [Install Matrix](../harnesses/install-matrix.md) for your harness's token.\n\n---\n\n## On this page\n\n- [The Anatomy of a Babysitter Run](#the-anatomy-of-a-babysitter-run)\n- [Understanding the Run Directory](#understanding-the-run-directory)\n- [The Event Journal Explained](#the-event-journal-explained)\n- [How Quality Convergence Works](#how-quality-convergence-works)\n- [TDD Quality Convergence in Action](#tdd-quality-convergence-in-action)\n- [Configuration and Customization](#configuration-and-customization)\n- [Verifying Success](#verifying-success)\n- [Keep Practicing](#keep-practicing)\n- [Next steps](#next-steps)\n\n---\n\n## The Anatomy of a Babysitter Run\n\nWhen you typed `/babysitter:call create a calculator with TDD and 80% quality target`, here's the sequence of events:\n\n```\nYour Command\n    |\n    v\n+-------------------+\n| 1. Parse Request  |  Babysitter interprets your natural language\n+-------------------+\n    |\n    v\n+-------------------+\n| 2. Create Run     |  A unique run ID and directory are created\n+-------------------+\n    |\n    v\n+-------------------+\n| 3. Load Process   |  TDD Quality Convergence process is loaded\n+-------------------+\n    |\n    v\n+-------------------+\n| 4. Execute Phases |  Research -> Specs -> TDD Loop\n+-------------------+\n    |\n    v\n+-------------------+\n| 5. Quality Loop   |  Iterate until target (80%) is met\n+-------------------+\n    |\n    v\n+-------------------+\n| 6. Complete       |  Final results and summary\n+-------------------+\n```\n\n### Step-by-Step Breakdown\n\n#### Step 1: Parse Request\nBabysitter analyzed your prompt and extracted:\n- **Goal:** Create a calculator module\n- **Methodology:** TDD (Test-Driven Development)\n- **Quality Target:** 80%\n- **Max Iterations:** 5 (default)\n\n#### Step 2: Create Run\nA unique run was created with:\n- **Run ID:** `01KFFTSF8TK8C9GT3YM9QYQ6WG` (ULID format)\n- **Directory:** `.a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/`\n- **Journal:** Empty, ready to record events\n\n#### Step 3: Load Process\nThe TDD Quality Convergence process was loaded. This defines:\n- Which phases to execute\n- How to measure quality\n- When to iterate vs. complete\n\n#### Step 4: Execute Phases\nThe process ran through:\n1. **Research Phase:** Analyzed your codebase\n2. **Specification Phase:** Defined what to build\n3. **Implementation Phase:** TDD loop (write tests, implement, score)\n\n#### Step 5: Quality Loop\nWithin the implementation phase:\n- **Iteration 1:** Score 72/100 (below 80% target)\n- **Iteration 2:** Score 88/100 (above target - success!)\n\n#### Step 6: Complete\nRun marked as complete, final summary generated.\n\n---\n\n## Understanding the Run Directory\n\nLet's explore what Babysitter created. Navigate to your run directory:\n\n```bash\ncd .a5c/runs/\nls\n```\n\nYou'll see your run ID (e.g., `01KFFTSF8TK8C9GT3YM9QYQ6WG`). Let's explore its structure:\n\n```\n.a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/\n|\n+-- run.json              # Run metadata\n+-- inputs.json           # Run inputs\n|\n+-- journal/\n|   +-- 000001.<ulid>.json  # Event log (individual JSON files, source of truth)\n|   +-- 000002.<ulid>.json\n|   +-- ...\n|\n+-- state/\n|   +-- state.json        # Current state cache (derived)\n|\n+-- tasks/\n|   +-- <effectId>/       # Task artifacts per effect\n|   +-- ...\n|\n+-- artifacts/\n|   +-- specifications.md # Generated specs\n|   +-- plan.md          # Implementation plan\n|\n+-- code/\n    +-- main.js          # Process definition used\n```\n\n### Key Files Explained\n\n#### journal/ (individual JSON files)\nThe **source of truth**. Each event is stored as an individual JSON file named `{SEQ}.{ULID}.json` (e.g., `000001.01ARZ3NDEKTSV4RRFFQ69G5FAV.json`). This directory is:\n- Append-only (files are never modified, only new files are added)\n- Human-readable (each file is a standalone JSON document)\n- The basis for session resumption\n\n#### state/state.json\nA **derived cache** of current state. This is:\n- Rebuilt from journal if deleted\n- Used for fast state access\n- Not the source of truth (journal is)\n\n#### tasks/\nContains **artifacts from each task**:\n- Input parameters\n- Output results\n- Logs and intermediate files\n\n#### artifacts/\n**Generated documents** like:\n- Specifications\n- Plans\n- Reports\n\n---\n\n## The Event Journal Explained\n\nThe [journal](../reference/glossary.md) is the heart of Babysitter's persistence. Let's examine it:\n\n```bash\n# List all journal events (each is an individual JSON file)\nls .a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/journal/\n\n# View a specific event\ncat .a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/journal/000001.*.json | jq .\n```\n\n### Journal Event Types\n\nHere's what each event type means:\n\n#### Run Lifecycle Events\n\nEach event is stored as an individual JSON file in `journal/` with the naming pattern `{SEQ}.{ULID}.json`. The event schema is:\n\n```json\n// 000001.<ulid>.json\n{\"type\":\"RUN_CREATED\",\"recordedAt\":\"2026-01-25T14:30:12Z\",\"data\":{\"runId\":\"01KFF...\",\"inputs\":{}},\"checksum\":\"sha256hex...\"}\n\n// (final event, e.g., 000012.<ulid>.json)\n{\"type\":\"RUN_COMPLETED\",\"recordedAt\":\"2026-01-25T14:34:45Z\",\"data\":{\"status\":\"success\"},\"checksum\":\"sha256hex...\"}\n```\n\n- `RUN_CREATED`: A new run began with specific inputs\n- `RUN_COMPLETED`: Run finished successfully\n- `RUN_HALTED`: Run intentionally stopped early via `ctx.halt(...)`; inspect `run:status --json` for `reason` and `payload`\n- `RUN_FAILED`: Run finished with an error\n\n**Note:** The `seq` number is derived from the filename, not stored in the event body. Each event includes a `checksum` field (sha256 hex) for integrity verification.\n\n#### Effect Events\n\nEffects represent tasks and interactions that Babysitter delegates (agent calls, skill invocations, scripts, breakpoints). There are exactly two effect event types:\n\n```json\n// EFFECT_REQUESTED: An effect (task) has been requested\n// e.g., 000003.<ulid>.json\n{\"type\":\"EFFECT_REQUESTED\",\"recordedAt\":\"2026-01-25T14:30:45Z\",\"data\":{\"effectId\":\"<effectId>\",\"kind\":\"agent\",\"args\":{}},\"checksum\":\"sha256hex...\"}\n\n// EFFECT_RESOLVED: An effect has completed (successfully or with error)\n// e.g., 000004.<ulid>.json\n{\"type\":\"EFFECT_RESOLVED\",\"recordedAt\":\"2026-01-25T14:31:10Z\",\"data\":{\"effectId\":\"<effectId>\",\"status\":\"ok\",\"result\":{}},\"checksum\":\"sha256hex...\"}\n\n// EFFECT_RESOLVED with error status\n// e.g., 000005.<ulid>.json\n{\"type\":\"EFFECT_RESOLVED\",\"recordedAt\":\"2026-01-25T14:31:15Z\",\"data\":{\"effectId\":\"<effectId>\",\"status\":\"error\",\"error\":\"...\"},\"checksum\":\"sha256hex...\"}\n```\n\n- `EFFECT_REQUESTED`: Records when a task, agent call, or breakpoint is initiated\n- `EFFECT_RESOLVED` (status: ok): Records successful completion of an effect\n- `EFFECT_RESOLVED` (status: error): Records when an effect fails\n\nTask artifacts are stored in `tasks/<effectId>/` directories containing `task.json`, `input.json`, `result.json`, `output.json`, `stdout.log`, and `stderr.log`.\n\n#### Breakpoint Events\n\nBreakpoints are modeled as effects. When human approval is needed:\n\n```json\n// Breakpoint requested as an effect\n{\"type\":\"EFFECT_REQUESTED\",\"recordedAt\":\"...\",\"data\":{\"effectId\":\"<effectId>\",\"kind\":\"breakpoint\",\"question\":\"Deploy to prod?\"},\"checksum\":\"sha256hex...\"}\n\n// Breakpoint resolved (approved or rejected)\n{\"type\":\"EFFECT_RESOLVED\",\"recordedAt\":\"...\",\"data\":{\"effectId\":\"<effectId>\",\"status\":\"ok\",\"approver\":\"user\"},\"checksum\":\"sha256hex...\"}\n```\n\n**Note on breakpoint modes:** These events are recorded regardless of whether the breakpoint was handled:\n- **Interactively** (via AskUserQuestion in Claude Code chat), or\n- **Non-interactively** (via the breakpoints web UI at http://localhost:3184)\n\n**Note on quality tracking:** Quality scores and iteration/phase progress are not tracked as separate event types in the journal. Quality metrics can be tracked within effect data or via custom application logic on top of the core event types: `RUN_CREATED`, `EFFECT_REQUESTED`, `EFFECT_RESOLVED`, `RUN_COMPLETED`, `RUN_HALTED`, and `RUN_FAILED`.\n\n### Why Event Sourcing Matters\n\nThe journal enables:\n\n1. **Deterministic Replay:** Given the same inputs and journal, you get the same state\n2. **Session Resumption:** Replay events to restore exactly where you left off\n3. **Audit Trail:** Complete history of what happened and when\n4. **Debugging:** Trace through events to find issues\n\n---\n\n## How Quality Convergence Works\n\nQuality convergence is one of Babysitter's gate types — a consequence of the fact that gates are code-defined. It is not the product thesis (that's deterministic, obedient orchestration of complex workflows), but it's a useful gate to understand because the calculator run used one. Here's how it works:\n\n### The Quality Loop\n\n```\n        +------------------+\n        |  Write Tests     |\n        +------------------+\n               |\n               v\n        +------------------+\n        |  Implement Code  |\n        +------------------+\n               |\n               v\n        +------------------+\n        |  Run Quality     |\n        |  Checks          |\n        +------------------+\n               |\n               v\n        +------------------+\n        |  Score Quality   |---> Score >= Target? ---> Done!\n        +------------------+           |\n               ^                       | No\n               |                       v\n               +-----------------------+\n                    Continue loop\n```\n\n### Quality Metrics\n\nFor your calculator run, these metrics were evaluated:\n\n| Metric | Iteration 1 | Iteration 2 | Weight |\n|--------|-------------|-------------|--------|\n| Tests Passing | 11/12 (92%) | 12/12 (100%) | 40% |\n| Code Coverage | 75% | 92% | 30% |\n| Linting | 2 warnings | 0 warnings | 15% |\n| Complexity | Low | Low | 15% |\n\n**Weighted Score Calculation:**\n- Iteration 1: `(0.92 * 40) + (0.75 * 30) + (0.80 * 15) + (1.0 * 15) = 72`\n- Iteration 2: `(1.0 * 40) + (0.92 * 30) + (1.0 * 15) + (1.0 * 15) = 88`\n\n### Agent-Based Scoring\n\nThe quality score isn't just automated metrics. An AI agent also evaluates:\n- Code readability\n- Best practices adherence\n- Error handling quality\n- Documentation completeness\n\nThis hybrid approach catches issues that pure metrics miss.\n\n### Setting Quality Targets\n\nYou can customize targets in your prompts:\n\n```\n# Conservative (high quality)\n/babysitter:call build feature with TDD and 90% quality target\n\n# Balanced (default-ish)\n/babysitter:call build feature with TDD and 80% quality target\n\n# Fast (lower quality, fewer iterations)\n/babysitter:call build feature with TDD and 70% quality target\n```\n\nHigher targets = more iterations = longer runtime = higher quality\n\n---\n\n## TDD Quality Convergence in Action\n\nThe quickstart used the **TDD Quality Convergence** methodology. TDD (shorthand used throughout this guide) combines test-first development with iterative quality improvement. Here's what it does:\n\n### Phase 1: Research\n\n**Purpose:** Understand the context before coding\n\n**What happens:**\n- Analyze existing codebase structure\n- Identify coding patterns and conventions\n- Detect test framework (Jest, Mocha, etc.)\n- Note dependencies and constraints\n\n**Output:** Research summary with recommendations\n\n### Phase 2: Specifications\n\n**Purpose:** Define what to build before building it\n\n**What happens:**\n- Create detailed specifications from your request\n- Define function signatures and interfaces\n- List test cases to write\n- Create implementation plan\n\n**Output:** `artifacts/specifications.md`\n\n### Phase 3: TDD Implementation Loop\n\n**Purpose:** Build with quality through iteration\n\n**Each iteration:**\n1. **Write Tests First**\n   - Create test files with test cases\n   - Tests should fail (code doesn't exist yet)\n\n2. **Implement Code**\n   - Write minimal code to pass tests\n   - Follow specifications from Phase 2\n\n3. **Run Quality Checks**\n   - Execute tests\n   - Measure coverage\n   - Run linting\n   - Check complexity\n\n4. **Score Quality**\n   - Calculate weighted score\n   - Compare to target\n   - If below target, identify improvements\n\n5. **Iterate or Complete**\n   - Below target? Fix issues and repeat\n   - Above target? Mark as complete\n\n### Why TDD Works Well with Babysitter\n\nTDD and Babysitter are a natural fit because:\n\n1. **Clear success criteria:** Tests define when you're done\n2. **Measurable progress:** Test pass rate and coverage are numbers\n3. **Incremental improvement:** Each iteration fixes specific test failures\n4. **Quality guarantee:** Passing tests = working code\n\n---\n\n## Configuration and Customization\n\nYou can customize Babysitter's behavior in several ways:\n\n### Via Prompt Parameters\n\n```bash\n# Set quality target\n/babysitter:call build API with 85% quality target\n\n# Set max iterations\n/babysitter:call build API with max 10 iterations\n\n# Combine options\n/babysitter:call build API with TDD, 90% quality, max 8 iterations\n```\n\n### Via Process Selection\n\nDifferent methodologies for different needs:\n\n| Methodology | Best For | Quality Focus |\n|-------------|----------|---------------|\n| TDD Quality Convergence | Feature development | High |\n| GSD (Get Stuff Done) | Quick prototypes | Medium |\n| Spec-Kit | Complex specifications | High |\n\n```bash\n# Explicit methodology selection\n/babysitter:call build feature using TDD methodology\n/babysitter:call prototype using GSD methodology\n```\n\n### Via Iteration Limits\n\nPrevent runaway loops:\n\n```bash\n# Low limit (fast, may not reach target)\n/babysitter:call build feature with max 3 iterations\n\n# High limit (thorough, takes longer)\n/babysitter:call build feature with max 15 iterations\n```\n\nIf max iterations reached without meeting quality target, Babysitter completes with a warning.\n\n---\n\n## Verifying Success\n\nHow do you know your Babysitter run succeeded? Here's a checklist:\n\n### Success Indicators\n\n| Check | How to Verify | Expected |\n|-------|---------------|----------|\n| Run completed | Check run summary | \"Run completed successfully\" |\n| Quality met | Check final score | Score >= your target |\n| Tests passing | Run `npm test` | All tests pass |\n| Files created | `ls` your directory | New implementation files |\n| Journal complete | Check last event | `RUN_COMPLETED` with success |\n\n### Verification Commands\n\n```bash\n# Check run status\ncat .a5c/runs/<runId>/state/state.json | jq '.status'\n# Expected: \"completed\"\n\n# View the last journal event (check for RUN_COMPLETED)\nls .a5c/runs/<runId>/journal/ | sort | tail -1 | xargs -I {} cat .a5c/runs/<runId>/journal/{} | jq '.type'\n# Expected: \"RUN_COMPLETED\"\n\n# Run tests manually\nnpm test\n# Expected: All passing\n\n# Check for the implementation\nls -la calculator.js calculator.test.js\n# Expected: Both files exist\n```\n\n### What If Something Went Wrong?\n\n**Run failed:**\n```bash\n# Check the journal for RUN_FAILED or error events\nfor f in .a5c/runs/<runId>/journal/*.json; do cat \"$f\" | jq 'select(.type == \"RUN_FAILED\" or (.type == \"EFFECT_RESOLVED\" and .data.status == \"error\"))'; done\n```\n\n**Quality not reached:**\n```bash\n# View all EFFECT_RESOLVED events to check task results\nfor f in .a5c/runs/<runId>/journal/*.json; do cat \"$f\" | jq 'select(.type == \"EFFECT_RESOLVED\")'; done\n```\n\n**Incomplete run:**\n```bash\n# Resume and continue\nclaude \"/babysitter:call resume the babysitter run <runId>\"\n```\n\n---\n\n## Hands-On Exercise: Analyze Your Run\n\nLet's practice what you've learned. Complete these exercises:\n\n### Exercise 1: Count Iterations\n\nHow many iterations did your run take?\n\n```bash\n# Your command here (count EFFECT_REQUESTED events as a proxy for tasks per iteration):\nfor f in .a5c/runs/<your-run-id>/journal/*.json; do cat \"$f\" | jq -r 'select(.type == \"EFFECT_REQUESTED\") | .type'; done | wc -l\n```\n\n**Answer:** The number of effects requested gives you insight into the work performed across iterations.\n\n### Exercise 2: Find Quality Progression\n\nWhat was the quality score after each iteration?\n\n```bash\n# Your command here (view all EFFECT_RESOLVED events to see task results):\nfor f in .a5c/runs/<your-run-id>/journal/*.json; do cat \"$f\" | jq 'select(.type == \"EFFECT_RESOLVED\") | .data'; done\n```\n\n**Expected:** Effect results showing progression toward quality target.\n\n### Exercise 3: Identify Tasks\n\nHow many tasks were executed?\n\n```bash\n# Your command here:\nfor f in .a5c/runs/<your-run-id>/journal/*.json; do cat \"$f\" | jq -r 'select(.type == \"EFFECT_REQUESTED\") | .type'; done | wc -l\n```\n\n### Exercise 4: Check Run Duration\n\nHow long did the run take?\n\n```bash\n# Find start and end times (first and last journal files)\ncat .a5c/runs/<your-run-id>/journal/$(ls .a5c/runs/<your-run-id>/journal/ | sort | head -1) | jq '.recordedAt'\ncat .a5c/runs/<your-run-id>/journal/$(ls .a5c/runs/<your-run-id>/journal/ | sort | tail -1) | jq '.recordedAt'\n```\n\n---\n\n## Key Concepts Summary\n\n### Terms to Remember\n\n| Term | Definition |\n|------|------------|\n| **Run** | A single execution of a Babysitter workflow |\n| **Run ID** | Unique identifier for a run (ULID format) |\n| **Journal** | Append-only event log, source of truth |\n| **Iteration** | One pass through the quality loop |\n| **Quality Score** | Weighted metric combining tests, coverage, etc. |\n| **Breakpoint** | Human approval checkpoint |\n| **Process** | Definition of workflow phases and logic |\n\n### Key Files\n\n| File | Purpose |\n|------|---------|\n| `journal/*.json` | Event log as individual JSON files (never delete!) |\n| `state/state.json` | State cache (can be rebuilt) |\n| `tasks/` | Task artifacts |\n| `artifacts/` | Generated documents |\n\n### Important Commands\n\n```bash\n# View all journal events\nfor f in .a5c/runs/<runId>/journal/*.json; do cat \"$f\" | jq .; done\n\n# Check run status\ncat .a5c/runs/<runId>/state/state.json | jq '.status'\n\n# Resume a run\nclaude \"Resume the babysitter run <runId>\"\n\n# List all runs\nls -la .a5c/runs/\n```\n\n---\n\n## Keep Practicing\n\nNow that you understand what happened in your first run, you're ready to explore more:\n\n### Immediate Next Steps\n\n1. **Try Different Quality Targets**\n   ```\n   /babysitter:call add validation to calculator with 90% quality\n   ```\n\n2. **Experience Breakpoints**\n   ```\n   /babysitter:call refactor calculator with breakpoint approval before changes\n   ```\n   Claude will ask you directly in the chat when approval is needed!\n\n   (For non-interactive mode, you'd approve at http://localhost:3184)\n\n3. **Test Session Resumption**\n   - Start a longer run\n   - Interrupt it (Ctrl+C or close Claude Code)\n   - Resume with `/babysitter:call resume`\n\n### This Week\n\n- [ ] Read [TDD Methodology Deep Dive](../features/quality-convergence.md)\n- [ ] Try the [GSD Methodology](../features/process-library.md) for faster prototyping\n\n### Coming Up\n\n- [ ] Learn about [Parallel Execution](../features/parallel-execution.md)\n- [ ] Create [Custom Processes](../features/process-definitions.md)\n\n---\n\n## Quick Reference Card\n\nPrint this for your desk:\n\n```\nBABYSITTER QUICK REFERENCE\n==========================\n\nSTART A RUN:\n  /babysitter:call <request> with TDD and <X>% quality\n\nRESUME A RUN:\n  /babysitter:call resume\n  /babysitter:call resume --run-id <id>\n\nVIEW JOURNAL:\n  for f in .a5c/runs/<id>/journal/*.json; do cat \"$f\" | jq .; done\n\nCHECK STATUS:\n  cat .a5c/runs/<id>/state/state.json | jq '.status'\n\nBREAKPOINTS:\n  Interactive (Claude Code): Handled in chat - no setup!\n  Non-Interactive: genty call --harness internal --process <path>#<export> --workspace . --no-interactive\n  Web UI (non-interactive): http://localhost:3184\n\nLIST ALL RUNS:\n  ls .a5c/runs/\n\nKEY EVENT TYPES (exactly 5):\n  RUN_CREATED, RUN_COMPLETED, RUN_HALTED, RUN_FAILED\n  EFFECT_REQUESTED, EFFECT_RESOLVED\n\nJOURNAL FORMAT:\n  Individual JSON files: journal/{SEQ}.{ULID}.json\n  Fields: type, recordedAt, data, checksum\n```\n\n---\n\nCongratulations! You now understand how Babysitter works under the hood. This knowledge will help you use it more effectively, debug issues when they arise, and eventually create your own custom processes.\n\n**Happy orchestrating!**\n\n---\n\n## Next steps\n\n- **Next:** [Build a REST API tutorial](../tutorials/beginner-rest-api.md) — apply what you learned on a real project\n- **Previous:** [Quickstart](./quickstart.md)\n- **Related:** [Two-Loops Architecture](../features/two-loops-architecture.md), [Journal System](../features/journal-system.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-getting-started",
      "to": "page:docs-user-guide-getting-started-first-run",
      "kind": "contains_page"
    }
  ]
}