{
  "id": "page:docs-user-guide",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/index.md",
    "sourceKind": "repo-docs",
    "title": "Babysitter User Guide",
    "displayName": "Babysitter User Guide",
    "slug": "docs/user-guide",
    "articlePath": "wiki/docs/user-guide/index.md",
    "article": "\n# Babysitter User Guide\n\n**Babysitter enforces obedience on agentic workforces: it runs your workflow as deterministic, code-defined orchestration on any supported harness, where the orchestrator can only do what your process permits. Manage extremely complex, multi-agent workflows with a hook-enforced mandatory stop after every step — enforcement, not assistance.**\n\nNew here? Jump straight to [Start here](#start-here) for the 20-minute path, or use the [task-based](#i-want-to) and [role-based](#by-role-and-level) entry points below to go directly to the page you need.\n\n---\n\n## Start here\n\nThe fastest path from zero to a working run:\n\n1. [Installation](./getting-started/installation.md) — install the CLI and your harness plugin (5 min)\n2. [Quickstart](./getting-started/quickstart.md) — run your first workflow (10 min)\n3. [First Run Deep Dive](./getting-started/first-run.md) — understand what just happened (10 min)\n\nPrefer to learn the ideas first? Read [What is Babysitter?](#what-is-babysitter-start-here-if-youre-new) (2 min), then see **[how the whole ecosystem fits together](./architecture.md)** (vision + diagram + runtime flow) and the [Two-Loops Architecture](./features/two-loops-architecture.md).\n\nWant the lay of the land first? The [Ecosystem Overview](./ecosystem/overview.md) tours every component (the core engine, the adapters family, atlas, genty, the observer dashboard, kradle, and kip-sdk) and helps you choose which you need.\n\n---\n\n## I want to…\n\nTask-based entry points — pick the goal that matches what you are doing right now.\n\n| I want to… | Go to |\n|------------|-------|\n| **Create a process** (custom workflow) | [Process Definitions](./features/process-definitions.md) → [Custom Process tutorial](./tutorials/intermediate-custom-process.md) |\n| **Run on my harness** (Codex, Cursor, Gemini, …) | [Install Matrix](./harnesses/install-matrix.md) → [Slash Commands](./reference/slash-commands.md) |\n| **Debug a run** (errors, stuck runs, recovery) | [Troubleshooting](./reference/troubleshooting.md) → [Error Catalog](./reference/error-catalog.md) |\n| **Write tests / set quality targets** | [Quality Convergence](./features/quality-convergence.md) → [Best Practices](./features/best-practices.md) |\n| **Understand the architecture** | [Architecture & How It Fits Together](./architecture.md) → [Two-Loops Architecture](./features/two-loops-architecture.md) |\n| **Tour the components** | [Ecosystem Overview](./ecosystem/overview.md) → [Adapter Types](./reference/adapter-types.md) |\n| **Run Babysitter from CI** | [Adapters CLI](./reference/adapters-cli.md) → [Configuration](./reference/configuration.md) |\n| **Look up a command or flag** | [CLI Reference](./reference/cli-reference.md) · [Adapters CLI](./reference/adapters-cli.md) |\n| **Learn a term** | [Glossary](./reference/glossary.md) |\n\n---\n\n## By role and level\n\nRole-based entry points — start where you fit, then follow the detailed [Learning Paths](#learning-paths) below.\n\n| You are a… | Start with |\n|------------|-----------|\n| **New user** (first time) | [Getting Started overview](./getting-started/README.md) → [Quickstart](./getting-started/quickstart.md) |\n| **Process author** (build workflows) | [Process Definitions](./features/process-definitions.md) → [Custom Process tutorial](./tutorials/intermediate-custom-process.md) |\n| **CI / automation integrator** | [Adapters CLI](./reference/adapters-cli.md) → [Configuration](./reference/configuration.md) → [Security](./reference/security.md) |\n| **Technical lead / architect** | [Two-Loops Architecture](./features/two-loops-architecture.md) → [Best Practices](./features/best-practices.md) |\n\n---\n\n## Quick Start\n\nGet up and running with Babysitter in minutes.\n\n| Step | Description | Time |\n|------|-------------|------|\n| [Installation](./getting-started/installation.md) | Install the CLI and Claude Code plugin | 5 min |\n| [Quickstart](./getting-started/quickstart.md) | Configure your environment | 5 min |\n| [First Run](./getting-started/first-run.md) | Execute your first babysitter workflow | 10 min |\n\n---\n## What is Babysitter? (Start Here if You're New)\n\n**Babysitter makes agentic work obedient.** It rests on three pillars:\n\n1. **Deterministic process execution** — your workflow is real JavaScript code (`async function process(inputs, ctx)`), and the orchestrator can *only* do what that code permits. State is event-sourced in an immutable journal, so any run can be replayed and resumed from any point.\n2. **Complex agentic workflows** — tasks, breakpoints, sleeps, parallel dispatch, dependencies, and sub-agent delegation across harnesses. A single headless entry point can orchestrate multi-agent work, delegating each task to whichever installed harness is best suited.\n3. **Policy / process adherence (obedience)** — after *every* step there is a hook-enforced **mandatory stop**, a process check (\"what does the process permit next?\"), and a decision: permit the next task, or halt until a gate passes. **Enforcement, not assistance — gates block progression until satisfied; they're not suggestions.**\n\n### The Problem Babysitter Solves\n\nWhen you turn an AI agent loose on real work, it tends to keep going on its own judgment — skipping steps, declaring \"done\" without evidence, and drifting from the process you intended. Babysitter removes that discretion: the agent does exactly what the process permits, nothing more, and cannot advance past a gate it hasn't satisfied.\n\nOne illustration of how a gate works is the familiar \"try, check, fix, repeat\" loop — a code-defined gate keeps iterating until its quality criterion is met, then permits the next step. That quality convergence is *one* consequence of code-defined gates, not the whole product.\n\n### How It Works (In Plain English)\n\nYour process is code; the orchestrator enforces it. After each step it stops, checks what the process permits next, and only then permits the next task — or halts until a gate passes. The loop below shows one such gate (a quality gate) doing its job:\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  YOU: \"Build a login page with tests\"                           │\n│                         ↓                                       │\n│  BABYSITTER: Enforces your process; one gate iterates:          │\n│    1. AI writes code                                            │\n│    2. Tests run → 60% pass                                      │\n│    3. AI fixes failures                                         │\n│    4. Tests run → 85% pass                                      │\n│    5. AI fixes remaining issues                                 │\n│    6. Tests run → 95% pass ✓ Target met!                       │\n│                         ↓                                       │\n│  YOU: Review and approve the final result                       │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Key Terms You'll See\n\n| Term | What It Means | Example |\n|------|---------------|---------|\n| **Process** | A workflow definition | \"Build feature with TDD\" |\n| **Run** | One execution of a process | Running the TDD workflow for your login page |\n| **Task** | A single step in the process | \"Write tests\", \"Run linter\", \"Check coverage\" |\n| **Quality Gate** | A check that must pass | Tests must be 90% passing |\n| **Breakpoint** | A pause for human approval | \"Review this code before I deploy it\" (handled in chat or via web UI) |\n| **Iteration** | One try-check-fix cycle | Attempt #3 to pass the tests |\n| **Convergence** | Improving until target met | Going from 60% → 85% → 95% |\n\n### Your First 5 Minutes\n\n**What you'll do:**\n1. Install Babysitter (1 command)\n2. Run a simple workflow (1 command)\n3. See it iterate until tests pass\n4. Approve the result\n\n**What you'll learn:**\n- How the orchestrator only does what your process permits\n- What the mandatory stop and process check do after each step\n- How to approve at breakpoints\n- What a quality gate looks like (one gate type among several)\n\n**What you'll see:**\n\n```\n/babysitter:call build a calculator with add, subtract, multiply, divide using TDD\n\nCreating run: calculator-20260125-143012\nProcess: TDD Quality Convergence\nTarget: 90% quality\n\nIteration 1: Quality 65/100 - Tests: 6/10 passing\n  → AI fixing test failures...\n\nIteration 2: Quality 82/100 - Tests: 9/10 passing\n  → AI improving code coverage...\n\nIteration 3: Quality 95/100 - Target met! ✅\n\nClaude: The implementation is complete. Quality score: 95/100.\n        Do you approve the final result?\n        [Approve] [Request Changes]\n\nYou: [Approve]\n\nDone! Your calculator module is ready.\n```\n\n**Note:** Breakpoints (approval prompts) are handled directly in the chat when using Claude Code. No external service needed!\n\n**The main command:** `/babysitter:call <your request>` handles everything automatically.\n\n→ **[Start the Quick Start Tutorial](./getting-started/quickstart.md)**\n\n---\n\n## Documentation Sections\n\n### Ecosystem & Architecture\n\nThe monorepo is one core engine surrounded by a family of components. Start with the architecture, then tour each piece.\n\n| Page | Description |\n|------|-------------|\n| [Architecture & How It Fits Together](./architecture.md) | Vision, a component diagram, and the runtime flow — how the engine, adapters, atlas, genty, kradle, and the dashboard cooperate |\n| [Ecosystem Overview](./ecosystem/overview.md) | The whole monorepo and how to choose among components |\n| [babysitter-sdk](./ecosystem/babysitter-sdk.md) | The core event-sourced orchestration engine (GA) |\n| [adapters (the family)](./ecosystem/adapters.md) | The multiplexer for all agents — a family of 20 package types, not one thing |\n| [atlas](./ecosystem/atlas.md) | The catalog / knowledge graph and `atlas` CLI (GA) |\n| [genty](./ecosystem/genty.md) | The unified agent runtime and `genty` CLI (GA) |\n| [observer-dashboard](./ecosystem/observer-dashboard.md) | Real-time SSE run dashboard (GA) |\n| [kradle](./ecosystem/kradle.md) | Kubernetes-native Git forge with per-org assistant (**MVP**) |\n| [kip-sdk](./ecosystem/kip-sdk.md) | Intended memory substrate — **spec/design only, no shipping code** |\n\n---\n\n### Tutorials\n\nStep-by-step learning guides that take you from beginner to expert.\n\n| Tutorial | Level | Time | Description |\n|----------|-------|------|-------------|\n| [Getting Started](./getting-started/README.md) | Beginner | 20 min | Installation, setup, and your first run |\n| [Build a REST API](./tutorials/beginner-rest-api.md) | Beginner | 45 min | Create a complete REST API with TDD |\n| [Custom Process](./tutorials/intermediate-custom-process.md) | Intermediate | 60 min | Build your own process definition |\n| [Multi-Phase Workflows](./tutorials/advanced-multi-phase.md) | Advanced | 90 min | Orchestrate complex multi-phase development |\n\n---\n\n### Features\n\nDeep dives into Babysitter's core capabilities.\n\n<!-- user-guide-index:features-table:start -->\n| Feature | Description |\n|---------|-------------|\n| [**Two-Loops Architecture**](./features/two-loops-architecture.md) | **Deterministic enforcement** - a symbolic orchestrator that can only do what your code permits, with a mandatory stop after every step (enforcement, not assistance) |\n| [**Process Definitions**](./features/process-definitions.md) | **Workflows as real JavaScript** - tasks, breakpoints, sleeps, parallel dispatch, dependencies, and sub-agent delegation orchestrated from code |\n| [**Adapters**](./features/adapters.md) | **Run complex agentic workflows on any supported harness** (v6) - harness-agnostic runtime, sub-agent delegation across harnesses, plus the host-side `adapters` CLI |\n| [**Journal System**](./features/journal-system.md) | **Event-sourced, immutable journal** - deterministic replay and resume from any point |\n| [**Process Library**](./features/process-library.md) | **2,239 JavaScript process files in the live generated snapshot**, plus methodology, shared-process, skill, and agent layers discovered under `library/` |\n| [Breakpoints](./features/breakpoints.md) | Human-in-the-loop approval gates - enforced pauses for critical decisions |\n| [Parallel Execution](./features/parallel-execution.md) | Concurrent task execution and dependencies for faster results |\n| [Run Resumption](./features/run-resumption.md) | Continue interrupted workflows from any point via journal replay |\n| [Quality Convergence](./features/quality-convergence.md) | One gate type among several - **five quality gate categories** (tests, code quality, static analysis, security, performance) with 90-score patterns; a consequence of code-defined gates |\n| [Best Practices](./features/best-practices.md) | **Four guardrail layers**, multi-gate validation, workflow design, and team collaboration patterns |\n<!-- user-guide-index:features-table:end -->\n\n<!-- user-guide-index:process-library-highlight:start -->\n> **Highlight:** The Process Library snapshot currently tracks 2,239 process files across 38 methodology families and the full specialization tree. [Explore the library →](./features/process-library.md)\n<!-- user-guide-index:process-library-highlight:end -->\n\n> **Essential Reading:** Understanding the [Two-Loops Architecture](./features/two-loops-architecture.md) is key to designing reliable, bounded agentic workflows with proper guardrails and evidence-driven completion. For how the v6 subsystems fit together, start with the [Architecture Overview](./features/architecture-overview.md).\n\n---\n\n### Harnesses\n\nBabysitter v6 runs on a dozen AI coding harnesses. Pick yours and follow its install and invocation guide.\n\n| Harness | Description |\n|---------|-------------|\n| [Install Matrix](./harnesses/install-matrix.md) | Every supported harness - install commands, invocation token, and per-harness hook model |\n| [Claude Code](./harnesses/claude-code.md) | Fully supported - `/babysitter:*` slash-commands and the `babysit` skill |\n| [Codex](./harnesses/codex.md) | Fully supported - `$babysitter:*` via the mention picker |\n\n> Migrating from the `0.0.x` series? See the [Migration Guide](./getting-started/migration.md) for every breaking change.\n\n---\n\n### Reference\n\nTechnical specifications and lookup resources.\n\n| Reference | Description |\n|-----------|-------------|\n| [Slash Commands](./reference/slash-commands.md) | **Core modes** (call, yolo, forever, plan) and utility commands for Claude Code |\n| [CLI Reference](./reference/cli-reference.md) | Complete command-line interface documentation |\n| [Adapters CLI](./reference/adapters-cli.md) | The host-side `adapters` CLI - run, install, and manage any harness (v6) |\n| [Package & Plugin Map](../package-and-plugin-map.md) | Canonical public/internal docs map for active packages, apps, and harness plugins |\n| [Configuration](./reference/configuration.md) | Environment variables and config file options |\n| [Security](./reference/security.md) | Security model, trust boundaries, and hardening guidance |\n| [Error Catalog](./reference/error-catalog.md) | All error codes with solutions |\n| [Glossary](./reference/glossary.md) | Terminology and definitions |\n| [FAQ](./reference/faq.md) | Frequently asked questions |\n| [Troubleshooting](./reference/troubleshooting.md) | Common issues and resolutions |\n\n---\n\n## Learning Paths\n\nChoose a path based on your role and goals.\n\n### For Developers New to Babysitter\n\n**Start here if this is your first time using Babysitter:**\n\n1. **First:** Read the [\"What is Babysitter?\" section](#what-is-babysitter-start-here-if-youre-new) above - it takes 2 minutes and explains the core concepts\n2. **Then:** Complete the [Getting Started](./getting-started/README.md) tutorial (20 min) - you'll install and run your first workflow\n3. **Practice:** Build your first project with [REST API Tutorial](./tutorials/beginner-rest-api.md) (45 min)\n4. **Reference:** Use the [Glossary](./reference/glossary.md) when you encounter unfamiliar terms (it has a quick-reference table at the top)\n\n### For Experienced Developers\n\n1. Quick setup via [Installation](./getting-started/installation.md)\n2. Learn the [Five Quality Gate Types](./features/quality-convergence.md#the-five-quality-gate-categories) for robust validation\n3. Study [Best Practices](./features/best-practices.md) for workflow design\n4. Reference the [CLI](./reference/cli-reference.md) for automation\n\n### For Technical Leads and Architects\n\n1. **Start here:** Understand the [Two-Loops Architecture](./features/two-loops-architecture.md) philosophy\n2. Study [Quality Convergence](./features/quality-convergence.md) for the 90-score convergence pattern\n3. Review the [Four Guardrail Layers](./features/best-practices.md#the-four-guardrail-layers) for safety and control\n4. Learn [Journal System](./features/journal-system.md) for audit compliance\n5. Explore [Custom Process](./tutorials/intermediate-custom-process.md) for team workflows\n\n### For Quality Engineers\n\n1. **Essential:** Study the [Five Quality Gate Types](./features/quality-convergence.md#the-five-quality-gate-categories)\n2. Review [The 90-Score Convergence Pattern](./features/quality-convergence.md#the-90-score-quality-convergence-pattern)\n3. Understand [Evidence-Driven Completion](./features/two-loops-architecture.md#quality-gates-turning-agentic-work-into-reliable-outcomes)\n4. Apply [Domain-Specific Targets](./features/best-practices.md) from Best Practices\n\n### For DevOps and Automation Engineers\n\n1. Install using [Quickstart](./getting-started/quickstart.md)\n2. Master the [CLI Reference](./reference/cli-reference.md)\n3. Configure via [Configuration Reference](./reference/configuration.md)\n4. Automate with [Run Resumption](./features/run-resumption.md)\n\n---\n\n## What's New\n\n### Version 6.0.0\n\n- v6 launch edition: documented the harness-agnostic Adapters runtime across all 12 supported harnesses\n- Unified the public npm surface around `@a5c-ai/babysitter` for the main CLI\n- Split optional runtime orchestration into `@a5c-ai/genty-platform`\n- Refreshed user-facing docs to match the current package and command boundaries\n\n### Recent Updates\n\n| Version | Date | Highlights |\n|---------|------|------------|\n| 6.0.0 | 2026-06-22 | v6 launch edition: harness-agnostic Adapters runtime documented across 12 harnesses |\n| 5.0.0 | 2026-04-25 | CLI/runtime package split clarified across public docs |\n\nFor the complete changelog, see the [GitHub Releases](https://github.com/a5c-ai/babysitter/releases).\n\n---\n\n## Search Tips\n\nFinding what you need quickly:\n\n- **Commands:** Search for the command name (e.g., `run:create`, `effects:get`)\n- **Errors:** Search for the error code or key words from the message\n- **Concepts:** Use terms from the [Glossary](./reference/glossary.md)\n- **Tasks:** Search for what you want to do (e.g., \"resume\", \"breakpoint\", \"quality\")\n\n---\n\n## Getting Help\n\n### Documentation Resources\n\n- [FAQ](./reference/faq.md) - Common questions answered\n- [Troubleshooting](./reference/troubleshooting.md) - Problem resolution guides\n- [Error Catalog](./reference/error-catalog.md) - Error codes and fixes\n\n### Community and Support\n\n- **GitHub Issues:** [Report bugs or request features](https://github.com/a5c-ai/babysitter/issues)\n- **Discussions:** [Community Q&A and discussions](https://github.com/a5c-ai/babysitter/discussions)\n\n---\n\n## Documentation Structure\n\nThis documentation follows the [Diataxis framework](https://diataxis.fr/):\n\n| Category | Purpose | User Mode |\n|----------|---------|-----------|\n| **Tutorials** | Learning through guided projects | Study |\n| **Features** | Understanding capabilities | Study |\n| **Reference** | Technical lookup information | Work |\n| **How-to Guides** | Task-focused problem solving | Work |\n\n---\n\n## Contributing\n\nFound an issue with the documentation? Contributions are welcome.\n\n1. Check existing [issues](https://github.com/a5c-ai/babysitter/issues) first\n2. Submit corrections via pull request\n3. Follow the documentation style guide\n\n---\n\n*Last updated: 2026-06-23*\n",
    "documents": []
  },
  "outgoingEdges": [
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-architecture",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-adapters",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-atlas",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-babysitter-sdk",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-genty",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-kip-sdk",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-kradle",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-observer-dashboard",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-overview",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-features",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-getting-started",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-harnesses-claude-code",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-harnesses-codex",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-harnesses-install-matrix",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-navigation",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-reference",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-summary",
      "kind": "contains_page"
    },
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-tutorials",
      "kind": "contains_page"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:docs",
      "to": "page:docs-user-guide",
      "kind": "contains_page"
    }
  ]
}