@a5c-ai/babysitter-gemini 4.0.153

package/commands/doctor.md

@@ -0,0 +1,426 @@
+---
+description: Diagnose babysitter run health - journal integrity, state cache, effects, locks, sessions, logs, and disk usage
+argument-hint: "[run-id] Optional run ID to diagnose. If omitted, uses the most recent run."
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Grep, Glob, WebFetch, WebSearch, Search, AskUserQuestion, TodoWrite, TodoRead, Skill, BashOutput, KillShell, MultiEdit, LS
+---
+
+You are a diagnostic agent for the babysitter runtime. Your job is to perform a comprehensive health check across 10 areas and produce a structured diagnostic report. Follow each section methodically. Track results as you go and produce the final summary at the end.
+
+Initialize a results tracker with these 10 checks, all starting as PENDING:
+1. Run Discovery
+2. Journal Integrity
+3. State Cache Consistency
+4. Effect Status
+5. Lock Status
+6. Session State
+7. Log Analysis
+8. Disk Usage
+9. Process Validation
+10. Hook Execution Health
+
+---
+
+## 1. Run Discovery
+
+**Goal:** Identify the target run and display its metadata.
+
+- List all runs by running: `ls -lt .a5c/runs/`
+- If the user provided a run ID argument, use that as the run ID. Otherwise, use the most recent run directory (the first entry from the listing).
+- Store the resolved run ID and construct the run directory path: `.a5c/runs/<runId>`
+- Verify the run directory exists. If it does not exist, report FAIL for this check and stop the entire diagnostic (no run to diagnose).
+- Show run metadata by running: `npx babysitter run:status .a5c/runs/<runId> --json`
+- Parse and display: runId, processId, entrypoint/importPath, createdAt, current state.
+- Mark this check as PASS.
+
+---
+
+## 2. Journal Integrity
+
+**Goal:** Verify the append-only event journal is well-formed and uncorrupted.
+
+- List all journal events by running: `npx babysitter run:events .a5c/runs/<runId> --json`
+- List all files in `.a5c/runs/<runId>/journal/` sorted by name.
+- If the journal directory is empty or missing, mark as FAIL and note "No journal entries found."
+
+For each journal file (named `<seq>.<ulid>.json`):
+
+**Sequential numbering check:**
+- Extract the sequence number prefix from each filename (e.g., `000001` from `000001.01JAXYZ.json`).
+- Verify sequence numbers are contiguous starting from 000001 with no gaps.
+- If gaps found, mark as WARN and list the missing sequence numbers.
+
+**Checksum verification:**
+
+The SDK computes checksums as follows: it first builds the event payload **without** the `checksum` field (`{ type, recordedAt, data }`), serializes it with `JSON.stringify(payload, null, 2) + "\n"` (pretty-printed with a trailing newline), then computes SHA256 of that string. To verify:
+
+- Read each journal file as JSON.
+- Extract and remove the `checksum` field from the parsed object.
+- Re-serialize the remaining object with `JSON.stringify(remaining, null, 2) + "\n"` — **must** use 2-space indentation and a trailing newline to match the SDK.
+- Compute SHA256 (hex) of that exact string.
+- Compare computed checksum with the stored checksum.
+- If any mismatch, mark as FAIL and list the corrupt files.
+
+Example bash one-liner for a single file:
+```bash
+node -e "const fs=require('fs'); const f=process.argv[1]; const obj=JSON.parse(fs.readFileSync(f,'utf8')); const stored=obj.checksum; delete obj.checksum; const expected=require('crypto').createHash('sha256').update(JSON.stringify(obj,null,2)+'\n').digest('hex'); console.log(stored===expected?'OK':'MISMATCH',f)" <file>
+```
+
+**Timestamp monotonicity check:**
+- Extract `recordedAt` from each event.
+- Verify each timestamp is >= the previous one.
+- If any timestamp goes backward, mark as WARN and list the offending entries.
+
+**Event type summary:**
+- Count events by type: RUN_CREATED, EFFECT_REQUESTED, EFFECT_RESOLVED, STOP_HOOK_INVOKED, RUN_COMPLETED, RUN_FAILED, and any other types encountered.
+- Display the counts in a table.
+
+**Orphan detection:**
+- Flag any files in the journal directory that do not match the expected `<seq>.<ulid>.json` naming pattern.
+
+If all sub-checks pass, mark as PASS. If any sub-check is WARN, mark as WARN. If any sub-check is FAIL, mark as FAIL.
+
+---
+
+## 3. State Cache Consistency
+
+**Goal:** Verify the derived state cache matches the current journal.
+
+- Check if `.a5c/runs/<runId>/state/state.json` exists.
+- If it does not exist, mark as WARN and recommend: `npx babysitter run:rebuild-state .a5c/runs/<runId>`
+
+If it exists:
+- Read `state.json` and extract the `journalHead` field (contains `seq`, `ulid`, and `checksum`).
+- Determine the actual last journal entry by reading the last file in `.a5c/runs/<runId>/journal/` (highest sequence number).
+- Extract the sequence number and ULID from the last journal filename, and the checksum from its content.
+- Compare:
+  - `journalHead.seq` should match the last journal file's sequence number.
+  - `journalHead.ulid` should match the last journal file's ULID.
+  - `journalHead.checksum` should match the last journal file's checksum.
+- If all match, mark as PASS.
+- If any mismatch, mark as WARN and recommend: `npx babysitter run:rebuild-state .a5c/runs/<runId>`
+- Also verify `schemaVersion` field is present and report its value.
+
+---
+
+## 4. Effect Status
+
+**Goal:** Identify stuck, errored, or pending effects.
+
+- Run: `npx babysitter task:list .a5c/runs/<runId> --json`
+- Run: `npx babysitter task:list .a5c/runs/<runId> --pending --json`
+- Parse the JSON output from both commands.
+
+**All effects summary:**
+- Count total effects, resolved effects, and pending effects.
+- Group and count effects by `kind` (node, breakpoint, orchestrator_task, sleep, etc.).
+
+**Stuck effect detection:**
+- For each pending effect, check its `requestedAt` timestamp.
+- If any pending effect was requested more than 30 minutes ago, flag it as STUCK.
+- List stuck effects with their effectId, kind, taskId, and age.
+
+**Error detection:**
+- Identify any effects with error status in their results.
+- List errored effects with their effectId and error message.
+
+**Pending summary:**
+- Summarize pending effects grouped by kind with count per kind.
+
+Mark as PASS if no stuck or errored effects. Mark as WARN if there are pending effects older than 30 minutes. Mark as FAIL if there are errored effects.
+
+---
+
+## 5. Lock Status
+
+**Goal:** Detect stale or orphaned run locks.
+
+- Check if `.a5c/runs/<runId>/run.lock` exists.
+- If it does not exist, mark as PASS ("No lock held -- run is not actively being iterated").
+
+If it exists:
+- Read the lock file (JSON with `pid`, `owner`, `acquiredAt`).
+- Display the lock info: PID, owner, acquired time, and age of the lock.
+- Check if the PID is still alive by running: `kill -0 <pid> 2>/dev/null; echo $?` (exit code 0 means alive, non-zero means dead). On Windows/MINGW, use `tasklist //FI "PID eq <pid>" 2>/dev/null` or equivalent.
+- If the process is alive, mark as PASS ("Lock held by active process").
+- If the process is dead, mark as FAIL ("Stale lock detected -- process <pid> is no longer running").
+  - Recommend: `rm .a5c/runs/<runId>/run.lock`
+
+---
+
+## 6. Session State
+
+**Goal:** Inspect babysitter session files for health and detect runaway loops.
+
+- Search for session state files using Glob:
+  - `plugins/babysitter/skills/babysit/state/*.md`
+  - `.a5c/state/*.md`
+  - `.a5c/state/*.json`
+- For each session state file found:
+  - Read the file and extract available information: iteration count, associated runId, timestamps, session status.
+  - Display: filename, iteration count, runId (if present), last activity time.
+
+**Runaway loop detection:**
+- If any session file contains iteration timing data, compute the average time between iterations.
+- If the average iteration time is less than 3 seconds, flag as WARN ("Possible runaway loop detected -- average iteration time is under 3 seconds").
+
+**Session classification:**
+- Active: session has recent activity (within last 30 minutes).
+- Stale: session has no activity for more than 30 minutes.
+- Display counts of active vs stale sessions.
+
+Mark as PASS if no issues. Mark as WARN if runaway loops or stale sessions detected.
+
+---
+
+## 7. Log Analysis
+
+**Goal:** Analyze babysitter log files for errors, warnings, and stop hook decisions.
+
+Read the last 50 lines of each of these log files (if they exist):
+- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/hooks.log`
+- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-stop-hook.log`
+- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-stop-hook-stderr.log`
+- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-session-start-hook.log`
+- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-session-start-hook-stderr.log`
+- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter.log`
+- `$HOME/.a5c/logs/` and relevant logs and run/session specific logs there
+
+
+For each log file:
+- If the file does not exist, note it as "Not found (OK if hooks have not run yet)."
+- If the file exists, analyze its content.
+
+**Stop hook analysis (babysitter-stop-hook.log):**
+- Count lines containing "approve" vs "block" decisions (case-insensitive).
+- Display the approve/block ratio.
+- Show the last 20 stop hook decision entries (lines containing "approve" or "block").
+- Count and display CLI exit codes from lines containing "CLI exit code=".
+
+**Stderr analysis (babysitter-stop-hook-stderr.log, babysitter-session-start-hook-stderr.log):**
+- If stderr logs contain content, display the last 20 lines from each.
+- Look for common failure patterns: "command not found", "MODULE_NOT_FOUND", "ENOENT", "EACCES", "permission denied", "npm ERR", "Cannot find module".
+- Flag any stderr content as a potential issue.
+
+**Error/Warning detection (all logs):**
+- Count and list lines containing "ERROR" or "WARN" (case-insensitive).
+- Display the last 10 error/warning lines from each log.
+
+Mark as PASS if no ERROR lines found and stderr logs are empty. Mark as WARN if WARN lines found or stderr has content but no ERROR. Mark as FAIL if ERROR lines found.
+
+---
+
+## 8. Disk Usage
+
+**Goal:** Report disk consumption and identify oversized files.
+
+- Run `du -sh .a5c/runs/<runId>` for the total run directory size.
+- Run `du -sh` on each subdirectory:
+  - `.a5c/runs/<runId>/journal/`
+  - `.a5c/runs/<runId>/tasks/`
+  - `.a5c/runs/<runId>/blobs/`
+  - `.a5c/runs/<runId>/state/`
+  - `.a5c/runs/<runId>/process/` (if it exists)
+
+- Display results in a table: directory, size.
+
+**Large file detection:**
+- Find individual files larger than 10MB within the run directory: `find .a5c/runs/<runId> -type f -size +10M -exec ls -lh {} \;`
+- If any found, list them with their paths and sizes.
+
+- Report the total run directory size prominently.
+
+Mark as PASS if total size < 500MB and no files > 10MB. Mark as WARN if total size > 500MB or any files > 10MB. Mark as FAIL if total size > 2GB.
+
+---
+
+## 9. Process Validation
+
+**Goal:** Verify the process entrypoint and SDK dependency are valid.
+
+- Read `.a5c/runs/<runId>/run.json` and extract the `importPath` (or `entrypoint`) field.
+- Check if the referenced process file exists on disk. Use Glob or file read to verify.
+- If the file does not exist, mark as FAIL ("Process entrypoint not found on disk").
+
+**SDK dependency check:**
+- Read `.a5c/package.json` (if it exists) or the project root `package.json`.
+- Check for `@a5c-ai/babysitter-sdk` in `dependencies` or `devDependencies`.
+- Report the installed version.
+- If the dependency is missing, mark as WARN.
+- If present, verify it looks like a valid semver version and mark as PASS.
+
+---
+
+## 10. Hook Execution Health
+
+**Goal:** Verify that the stop hook and session-start hook are properly configured, can execute, and have been running. If the stop hook has NOT been running, diagnose why.
+
+### 10a. Hook Registration
+
+- Locate the plugin root. Check for `CLAUDE_PLUGIN_ROOT` env var, or search for `plugins/babysitter/hooks/hooks.json` by walking up from the current directory.
+- If found, read `hooks.json` and verify:
+  - A `Stop` hook entry exists with a command referencing `babysitter-stop-hook.sh`.
+  - A `SessionStart` hook entry exists with a command referencing `babysitter-session-start-hook.sh`.
+- If `hooks.json` is not found, mark as FAIL ("Hook registration file not found — hooks are not registered with Claude Code").
+
+### 10b. Hook Script Availability
+
+- Locate the hook scripts relative to the plugin root:
+  - `hooks/babysitter-stop-hook.sh`
+  - `hooks/babysitter-session-start-hook.sh`
+- For each script:
+  - Check if the file exists.
+  - Check if it is executable (`test -x <path>`).
+- If any script is missing or not executable, mark as FAIL and list which scripts are missing/not-executable.
+
+### 10c. CLI Availability (babysitter command)
+
+The hooks delegate to the `babysitter` CLI. Check if it is available:
+- Run: `command -v babysitter 2>/dev/null && babysitter --version 2>/dev/null`
+- If the command is found, display its path and version. Mark sub-check as PASS.
+- If not found, check the user-local prefix: `$HOME/.local/bin/babysitter --version 2>/dev/null`
+- If neither is found, mark sub-check as FAIL ("babysitter CLI not found — hooks will fail with exit code 127. Install with: `npm i -g @a5c-ai/babysitter-sdk`").
+
+### 10d. Stop Hook Execution Evidence
+
+Check whether the stop hook has actually been invoked during this run's lifetime:
+
+**From log files:**
+- Read `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-stop-hook.log` (if it exists).
+- Count the number of "Hook script invoked" lines. This is the total invocation count.
+- Count the number of "CLI exit code=" lines and extract exit codes.
+- If the log file does not exist or has zero invocations, the stop hook has NOT been running.
+
+**From journal events:**
+- Search the run's journal events for `STOP_HOOK_INVOKED` type events (using the run:events output from section 2 if available).
+- Count the number of STOP_HOOK_INVOKED events.
+- If present, display the last 5 with their timestamps and decision data.
+- If no STOP_HOOK_INVOKED events exist in the journal, note that the stop hook has not recorded any decisions for this run.
+
+**From stderr:**
+- Read `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-stop-hook-stderr.log`.
+- If it contains error output, display it and diagnose:
+  - "command not found" or exit code 127 → CLI not installed (see 10c)
+  - "MODULE_NOT_FOUND" or "Cannot find module" → SDK package corrupted or not built
+  - "ENOENT" → Missing file referenced by the hook
+  - "EACCES" or "permission denied" → Permission issue on hook script or CLI
+  - "npm ERR" → npm installation failure during hook execution
+
+### 10e. Stop Hook Not Running — Root Cause Diagnosis
+
+If the stop hook shows NO evidence of execution (no log entries, no journal events, zero invocations):
+
+Perform these diagnostic steps in order and report the first failure found:
+
+1. **Plugin not installed**: Check if `plugins/babysitter/` exists relative to the project root and if `CLAUDE_PLUGIN_ROOT` is set. If the plugin directory doesn't exist, report: "Plugin not installed — the babysitter plugin directory is missing."
+
+2. **Plugin not enabled**: Check for Claude settings files:
+   - `~/.claude/settings.json` — look for `babysitter` in `enabledPlugins`.
+   - `~/.claude/plugins/installed_plugins.json` — look for `babysitter` in the plugins list.
+   - If not found in either, report: "Plugin not enabled in Claude Code settings."
+
+3. **hooks.json not registered**: If `hooks.json` doesn't contain a `Stop` hook entry (checked in 10a), report: "Stop hook not registered in hooks.json."
+
+4. **Hook script missing or not executable**: If the stop hook script doesn't exist or isn't executable (checked in 10b), report with the specific file path.
+
+5. **CLI not available**: If `babysitter` CLI is not found (checked in 10c), report: "babysitter CLI not installed — hook script will fail silently."
+
+6. **Hook running but failing silently**: If the log file exists but shows exit codes other than 0, or if stderr has content, report: "Stop hook is being invoked but failing — see stderr log for details."
+
+7. **No active session**: If no session state files exist (from section 6), report: "No active babysitter session — the stop hook only activates when a session is bound to a run."
+
+8. **All checks pass but hook still not running**: Report: "All prerequisites are met but the stop hook shows no evidence of execution. Possible causes: Claude Code may not be invoking plugin hooks (check Claude Code version), or the session may have ended before the hook could fire."
+
+### 10f. Verdict
+
+Mark as PASS if:
+- Hook registration is correct (10a)
+- Hook scripts exist and are executable (10b)
+- CLI is available (10c)
+- There is evidence of stop hook execution (10d) with exit code 0
+
+Mark as WARN if:
+- Hooks are registered and scripts exist, but there's no evidence of execution yet
+- Stop hook ran but had non-zero exit codes
+
+Mark as FAIL if:
+- Hook registration is missing
+- Hook scripts are missing or not executable
+- CLI is not available
+- Stop hook is failing (consistent non-zero exit codes or stderr errors)
+
+---
+
+## Final Report
+
+After completing all 10 checks, produce the diagnostic report in this format:
+
+```
+============================================
+  BABYSITTER DIAGNOSTIC REPORT
+  Run: <runId>
+  Time: <current timestamp>
+============================================
+
+OVERALL HEALTH: <HEALTHY | WARNING | CRITICAL>
+
+--------------------------------------------
+  CHECK RESULTS
+--------------------------------------------
+
+| #  | Check                    | Status |
+|----|--------------------------|--------|
+| 1  | Run Discovery            | <status> |
+| 2  | Journal Integrity        | <status> |
+| 3  | State Cache Consistency  | <status> |
+| 4  | Effect Status            | <status> |
+| 5  | Lock Status              | <status> |
+| 6  | Session State            | <status> |
+| 7  | Log Analysis             | <status> |
+| 8  | Disk Usage               | <status> |
+| 9  | Process Validation       | <status> |
+| 10 | Hook Execution Health    | <status> |
+
+--------------------------------------------
+  ISSUES & RECOMMENDATIONS
+--------------------------------------------
+
+<For each WARN or FAIL check, list:>
+- [WARN|FAIL] <Check name>: <description of issue>
+  Fix: <specific actionable command or instruction>
+
+--------------------------------------------
+```
+
+**Overall health determination:**
+- **HEALTHY**: All 10 checks are PASS.
+- **WARNING**: At least one check is WARN but none are FAIL.
+- **CRITICAL**: At least one check is FAIL.
+
+Present the full detailed findings for each check BEFORE the summary table, so the user can see the evidence. End with the summary table and recommendations. Also, create a single HTML report file with all the findings that uses the arwes UI framework and open it for the user in the browser.
+
+---
+
+## Escalation: Claude /debug
+
+If any check results in FAIL and the root cause is unclear after your own analysis -- especially for environment issues, hook execution failures, CLI availability problems, or permission errors that may relate to the Claude Code runtime itself -- invoke the built-in Claude `/debug` command to get additional diagnostic context from the Claude Code environment. This is particularly useful for:
+- Hook scripts that should be running but show no evidence of execution (check 10)
+- Permission or path resolution issues that don't match expected behavior
+- Unexpected CLI behavior that might be a Claude Code environment issue rather than a babysitter issue
+
+Call `/debug` with a summary of the failing check and what you've already ruled out, so it can focus on environment-level causes.
+
+---
+
+## After Diagnosis: Contribute Back
+
+After diagnosing issues, prompt the user to report or fix what was found -- they don't need to fix the bug themselves, just reporting it is valuable. Suggest `/babysitter:contrib` based on the situation:
+
+- **Found a bug but didn't fix it**: `/babysitter:contrib bug report: [what the doctor found, e.g. "state cache rebuild silently drops EFFECT_RESOLVED events when journal has duplicate invocation keys"]`
+- **Found and fixed a bug**: `/babysitter:contrib bugfix: [description of the fix]`
+- **Found confusing or missing docs that made diagnosis harder**: `/babysitter:contrib documentation question: [what was unclear or missing]`
+- **Found an issue in a plugin**: `/babysitter:contrib bug report: [plugin-name] [description]`
+- **Improved a process or skill during diagnosis**: `/babysitter:contrib library contribution: [description]`
+
+Example prompt after diagnosis:
+
+> "Diagnosis found a stale lock -- process 12847 crashed without cleanup. This is a known edge case in the orchestration loop. Even if you don't want to fix it yourself, reporting it helps: run `/babysitter:contrib bug report: orchestration loop doesn't release lock on unhandled rejection` to open an issue."

package/commands/forever.md

@@ -0,0 +1,7 @@
+---
+description: Use this command to start babysitting a never-ending babysitter run.
+argument-hint: Specific instructions for the run.
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Grep, Glob, WebFetch, WebSearch, Search, AskUserQuestion, TodoWrite, TodoRead, Skill, BashOutput, KillShell, MultiEdit, LS
+---
+
+Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md). but create a process that uses an infinte loop and a ctx.sleep to create a never-ending babysitter loop. an example of such process is a daily process that reads new support ticket every day and tries to resolve them, then sleeps for 4 hours and repeats the process. 

package/commands/help.md

@@ -0,0 +1,244 @@
+---
+description: help and documentation for babysitter command usage, processes, skills, agents, and methodologies. use this command to understand how to use babysitter effectively.
+argument-hint: Specific command, process, skill, agent, or methodology you want help with (e.g. "help command doctor" or "help process retrospect").
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Grep, Glob, WebFetch, WebSearch, Search, AskUserQuestion, TodoWrite, TodoRead, Skill, BashOutput, KillShell, MultiEdit, LS
+---
+
+## if no arguments provided:
+
+show this message:
+
+```
+Welcome to the Babysitter Help Center! Here you can find documentation and guidance on how to use Babysitter effectively.
+
+Documentation: Explore our comprehensive documentation to understand Babysitter's features, processes, skills, agents, and methodologies. Read the Docs: https://github.com/a5c-ai/babysitter
+
+Or ask specific questions about commands, processes, skills, agents, methodologies, domains, specialities to get targeted help.
+
+Just type /babysitter:help followed by your question or the topic you want to learn more about.
+
+
+PRIMARY COMMANDS
+================
+
+/babysitter:call [input]
+  Start a babysitter-orchestrated run. Babysitter analyzes your request, interviews you
+  to gather requirements, selects or creates the best process definition (from 50+
+  domain-specific processes covering science, business, engineering, and more), then
+  executes it step by step with breakpoints where you can steer direction.
+
+  How it works: The babysitter skill reads your input, explores the process library to
+  find matching processes, interviews you to refine scope, creates an SDK run with
+  run:create, and orchestrates iterations with run:iterate -- dispatching tasks,
+  handling breakpoints, and posting results until the run completes or you pause it.
+
+  Example: /babysitter:call migrate our Express.js REST API to Fastify, keeping all
+  existing routes and middleware behavior identical, with integration tests proving
+  parity
+
+
+/babysitter:resume [run id or name]
+  Resume a paused or interrupted babysitter run. If you don't specify a run, babysitter
+  discovers all runs under .a5c/runs/, shows their status (created, waiting, completed,
+  failed), and suggests which incomplete run to pick up based on its process, pending
+  effects, and last activity.
+
+  How it works: Reads run metadata and journal, rebuilds state cache if stale, identifies
+  pending effects (breakpoints awaiting approval, tasks needing results), and continues
+  orchestration from exactly where it left off -- no work is repeated thanks to the
+  replay engine.
+
+  Example: /babysitter:resume
+  (discovers runs and offers: "Run abc123 is waiting on a breakpoint in the 'review
+  test results' phase of your API migration -- resume this one?")
+
+
+/babysitter:yolo [input]
+  Start a babysitter run in fully autonomous mode. Identical to /call but all breakpoints
+  are auto-approved and no user interaction is requested. The babysitter makes every
+  decision on its own until the run completes or hits a critical failure it can't recover
+  from. Best for well-understood tasks where you trust the process.
+
+  How it works: Same orchestration as /call, but the process context is configured to
+  skip breakpoint effects -- instead of pausing for human approval, each breakpoint
+  resolves immediately with an auto-approve result.
+
+  Example: /babysitter:yolo add comprehensive unit tests for all functions in
+  src/utils/ using vitest with >90% branch coverage
+
+
+/babysitter:plan [input]
+  Generate a detailed execution plan without running anything. Babysitter goes through
+  the full interview and process selection flow, designs the process definition with
+  all tasks, breakpoints, and dependencies, but stops before creating the actual SDK run.
+  You get a complete plan you can review, modify, or execute later with /call.
+
+  How it works: Runs the babysitter skill's planning phase only -- analyzes input,
+  matches to domain processes, interviews for requirements, then outputs the process
+  definition file and a human-readable execution plan showing each phase, task, and
+  decision point.
+
+  Example: /babysitter:plan redesign our database schema to support multi-tenancy,
+  migrate existing data, and update all queries -- I want to review the plan before
+  we touch anything
+
+
+/babysitter:forever [input]
+  Start a babysitter run that loops indefinitely with sleep intervals. Designed for
+  ongoing operational tasks: monitoring, periodic maintenance, continuous improvement,
+  or recurring workflows. The process uses an infinite loop with ctx.sleepUntil() to
+  pause between iterations.
+
+  How it works: Creates a process definition with a while(true) loop. Each cycle performs
+  the task (e.g., check metrics, process tickets, run audits), then calls ctx.sleepUntil()
+  to pause for a configured interval. The run stays in "waiting" state during sleep and
+  resumes automatically when the sleep expires on the next orchestration iteration.
+
+  Example: /babysitter:forever every 4 hours, check our GitHub issues labeled "bug",
+  attempt to reproduce and fix any that look straightforward, and submit PRs for the fixes
+
+
+SECONDARY COMMANDS
+==================
+
+/babysitter:doctor [issue]
+  Run a comprehensive 10-point health check on a babysitter run. Inspects journal
+  integrity (checksum verification, sequence gaps, timestamp ordering), state cache
+  consistency, stuck/errored effects, stale locks, session state, log files, disk usage,
+  process validation, and hook execution health. Produces a structured diagnostic report
+  with PASS/WARN/FAIL status per check and specific fix commands.
+
+  If no run ID is provided, automatically targets the most recent run. Can also diagnose
+  environment-wide issues like missing CLI, unregistered hooks, or plugin problems.
+
+  Example: /babysitter:doctor
+  (checks the latest run: "CRITICAL -- Check 5 Lock Status: FAIL -- stale lock detected,
+  process 12847 is no longer running. Fix: rm .a5c/runs/abc123/run.lock")
+
+
+/babysitter:assimilate [target]
+  Convert an external methodology, AI coding harness, or specification into native
+  babysitter process definitions. Takes a GitHub repo URL, harness name, or spec file
+  and produces a complete process package with skills/ and agents/ directories.
+
+  Two workflows available:
+  - Methodology assimilation: clones the repo, learns its procedures and commands,
+    converts manual flows into babysitter processes with refactored skills and agents
+  - Harness integration: wires babysitter's SDK into a specific AI coding tool
+    (codex, opencode, gemini-cli, antigravity, etc.) so it can orchestrate runs
+
+  Example: /babysitter:assimilate https://github.com/some-org/their-deployment-playbook
+  (clones the repo, analyzes their deployment procedures, and generates babysitter
+  processes that replicate the same workflow with proper task definitions and breakpoints)
+
+
+/babysitter:user-install
+  First-time onboarding for new babysitter users. Installs dependencies, runs an
+  interactive interview about your development specialties, preferred tools, coding
+  style, and how much autonomy you want babysitter to have. Builds a user profile
+  stored at ~/.a5c/user-profile.json that personalizes future runs.
+
+  Uses the cradle/user-install process which covers: dependency verification, user
+  interview (expertise areas, preferred languages, IDE, terminal setup), profile
+  generation, tool configuration, and optional global plugin installation.
+
+  Example: /babysitter:user-install
+  (walks you through: "What's your primary programming language? What frameworks do
+  you use most? Do you prefer babysitter to auto-approve routine tasks or always ask?")
+
+
+/babysitter:project-install
+  Onboard a new or existing project for babysitter orchestration. Researches the
+  codebase (reads package.json, scans directory structure, identifies frameworks and
+  patterns), interviews you about project goals and workflows, generates a project
+  profile at .a5c/project-profile.json, and optionally sets up CI/CD integration.
+
+  Uses the cradle/project-install process which covers: codebase analysis, project
+  interview, profile creation, recommended plugin installation, hook configuration,
+  and optional CI pipeline setup.
+
+  Example: /babysitter:project-install
+  (scans your repo: "I see this is a Next.js 16 app with Tailwind, using vitest for
+  tests and PostgreSQL. What are your main development goals for this project?")
+
+
+/babysitter:retrospect [run id or name]
+  Analyze a completed run to extract lessons and improve future runs. Reviews what
+  happened (journal events, task results, timing, errors), evaluates the process that
+  was followed, and suggests concrete improvements to process definitions, skills,
+  and agents. Interactive -- multiple breakpoints let you steer the analysis and
+  decide which improvements to implement.
+
+  Covers: run result analysis, process effectiveness review, improvement suggestions,
+  implementation of changes, and routing to /contrib if improvements belong in the
+  shared process library.
+
+  Example: /babysitter:retrospect
+  (analyzes the last run: "The API migration run completed but the 'verify parity'
+  phase took 8 iterations because test assertions were too brittle. Suggestion: add
+  a fuzzy comparison step before strict assertion. Implement this fix?")
+
+
+/babysitter:plugins [action]
+  Manage babysitter plugins: list installed plugins, browse marketplaces, install,
+  update, configure, uninstall, or create new plugins. Plugins are version-managed
+  instruction packages (not executable code) that guide the agent through install,
+  configure, and uninstall steps via markdown files.
+
+  Without arguments: shows installed plugins (name, version, marketplace, dates) and
+  available marketplaces. With arguments: routes to the specific action.
+
+  Key actions:
+  - install <name> --global|--project: fetch install.md from marketplace and execute
+  - configure <name> --global|--project: fetch configure.md and walk through options
+  - update <name> --global|--project: resolve migration chain via BFS and apply steps
+  - uninstall <name> --global|--project: fetch uninstall.md and execute removal
+  - create: scaffold a new plugin package with the meta/plugin-creation process
+
+  Example: /babysitter:plugins install sound-hooks --project
+  (fetches sound-hooks from marketplace, reads install.md, walks you through player
+  detection, sound selection, hook configuration, and registers in plugin-registry.json)
+
+
+/babysitter:contrib [feedback]
+  Submit feedback or contribute to the babysitter project. Routes to the appropriate
+  workflow based on what you want to do:
+
+  Issue-based (opens GitHub issue in a5c-ai/babysitter):
+  - Bug report: describe a bug in the SDK, CLI, or process library
+  - Feature request: propose a new feature or enhancement
+  - Documentation question: flag undocumented behavior or missing docs
+
+  PR-based (forks repo, creates branch, submits PR):
+  - Bugfix: you already have a fix ready
+  - Feature implementation: you've built a new feature
+  - Library contribution: new or improved process/skill/agent for the library
+  - Harness integration: CI/CD or IDE integration
+
+  Without arguments: shows all contribution types and helps you pick the right one.
+  Breakpoints are placed before all GitHub actions (fork, star, PR, issue) so you
+  can review before anything is submitted.
+
+  Example: /babysitter:contrib bug report: plugin:update-registry fails when the
+  marketplace hasn't been cloned yet, even though the registry update doesn't need
+  marketplace access
+
+
+/babysitter:observe
+  Launch the babysitter observer dashboard -- a real-time web UI that monitors active
+  and past runs. Displays task progress, journal events, orchestration state, and
+  effect status in your browser. Useful when running /yolo or /forever to watch
+  progress without interrupting the run.
+
+  How it works: Runs npx @yoavmayer/babysitter-observer-dashboard@latest which watches
+  the .a5c/runs/ directory (or a parent directory containing multiple projects) and
+  serves a live dashboard. The process is blocking -- it runs until you stop it.
+
+  Example: /babysitter:observe
+  (opens browser showing all runs with live-updating task
+  status, journal event stream, and effect resolution timeline)
+```
+
+## if arguments provided:
+
+if the argument is "command [command name]", "process [process name]", "skill [skill name]", "agent [agent name]", or "methodology [methodology name]", then show the detailed documentation for that specific command, process, skill, agent, or methodology after reading the relevant files.