@a5c-ai/babysitter-pi 0.1.0 → 0.1.1-staging.0dc03363

package/AGENTS.md

@@ -0,0 +1,131 @@
+# Agent Instructions -- Babysitter Orchestration Plugin for oh-my-pi
+
+This file governs agent behavior when the babysitter-pi plugin is active in an oh-my-pi session. Babysitter is the orchestration layer -- it drives multi-step workflows through process definitions, effects, and an iteration loop.
+
+---
+
+## 1. Session Start -- Auto-Initialization
+
+Babysitter initializes automatically on every oh-my-pi session start. The session-binder extension:
+
+1. Binds the current pi session to the babysitter state directory (`.a5c/`).
+2. Checks for an active run by inspecting `.a5c/runs/` for pending tasks.
+3. If an active run exists, resumes from the first pending effect.
+4. If no run exists, proceeds with normal session behavior until a babysitter command is issued.
+
+You do not need to initialize babysitter manually -- the plugin handles it.
+
+---
+
+## 2. Recognizing Babysitter Commands
+
+When the user types a message starting with `/babysitter:` or `/babysitter`, treat it as a **slash command** and dispatch accordingly:
+
+| Command | Description |
+|---------|-------------|
+| `/babysitter:call` | Start an orchestration run |
+| `/babysitter:status` | Show current run status and pending effects |
+| `/babysitter:resume` | Resume an existing run from where it left off |
+
+Aliases:
+- `/babysitter` (bare) = `/babysitter:call`
+
+Load the corresponding skill from `skills/babysitter/SKILL.md` for detailed execution instructions.
+
+---
+
+## 3. Babysitter Orchestration Protocol
+
+The core loop works as follows:
+
+1. **Create a run** -- A process definition (JS file) is loaded and a run is created under `.a5c/runs/<RUN_ID>/`.
+2. **Iterate** -- The SDK replays resolved effects, then throws when it encounters an unresolved effect. The iteration returns a list of **pending effects** (tasks to execute).
+3. **Execute effects** -- You execute each pending effect using the appropriate tool/action.
+4. **Post results** -- Report the outcome back to babysitter via the SDK bridge.
+5. **Repeat** -- The loop-driver triggers the next iteration automatically. Do NOT loop independently.
+
+The plugin's loop-driver extension controls iteration flow. Complete one task, post the result, and the driver handles the rest.
+
+---
+
+## 4. Effect Types
+
+When babysitter presents pending effects, identify the `kind` field and execute accordingly:
+
+| Kind | Action |
+|------|--------|
+| `agent` | Build a prompt from the agent definition and execute as a sub-agent task |
+| `skill` | Invoke the named skill with the provided parameters |
+| `shell` | Execute the shell command and capture stdout/stderr/exit code |
+| `breakpoint` | Pause execution and present the breakpoint message to the user for approval |
+| `sleep` | Wait until the specified timestamp (handled by the runtime) |
+
+For PI-family generated-process guidance, treat `agent`, `skill`, `shell`, `breakpoint`, and `sleep` as the active effect kinds. Do not present `node` as a generated PI-family effect kind.
+
+---
+
+## 5. Posting Results
+
+After executing an effect, hand the outcome back to the Babysitter plugin/runtime bridge so the run state, journal, and pending-effect cache stay consistent.
+
+Rules:
+- Use the plugin-owned Babysitter bridge/command flow rather than inventing an alternate posting path.
+- Complete one orchestration phase per harness turn, then let the loop-driver trigger the next phase.
+- Do not abort the entire run on a single task failure -- return the effect outcome and let the orchestrator decide the next step.
+- Keep low-level runtime mechanics in the command/extension implementation surface; this file is the behavioral contract for the active agent session.
+
+---
+
+## 6. Task Interception Notice
+
+During an active babysitter run, the plugin's task-interceptor extension **intercepts built-in task and todo tools**. This means:
+
+- Any task/todo creation is routed through babysitter's effect system instead of the default pi task manager.
+- Do not attempt to use native task tools to track babysitter work -- they are redirected automatically.
+- This interception is only active while a run is in progress. Normal tool behavior resumes after the run completes.
+
+---
+
+## 7. TUI Widgets
+
+The babysitter-pi plugin renders TUI widgets showing run progress:
+
+- **Status line** -- Current run ID, iteration count, and run state (running/waiting/completed/failed).
+- **Effect queue** -- List of pending and completed effects with their status.
+- **Progress indicator** -- Visual progress through the process definition.
+
+These widgets update automatically as effects are resolved. No agent action is required to drive them.
+
+---
+
+## 8. Run Completion
+
+When the orchestration run completes successfully, the SDK returns a completion proof. You MUST output it in the following format:
+
+```
+<promise>PROOF_VALUE</promise>
+```
+
+Where `PROOF_VALUE` is the exact proof string returned by the SDK. This signals to the wrapper and any upstream systems that the run finished with a verified result.
+
+---
+
+## 9. Directory Layout Reference
+
+```
+.a5c/
+  runs/
+    <RUN_ID>/
+      run.json              # Run metadata
+      inputs.json           # Process inputs
+      journal/              # Append-only event log
+        000001.<ulid>.json
+      tasks/
+        <EFFECT_ID>/
+          task.json          # Task definition (created by orchestrator)
+          result.json        # Task result (created after posting)
+      state/
+        state.json           # Derived replay cache
+```
+
+All paths are relative to the repository root.

package/README.md

@@ -1,77 +1,128 @@
 # @a5c-ai/babysitter-pi
 
-Babysitter integration plugin for the upstream `pi` coding agent. This package
-owns the Pi-specific install surface, command docs, and skill wiring while the
-shared runtime internals remain compatible with the wider PI-family.
+Babysitter package for the upstream `pi` coding agent.
 
-## Integration Model
+This is a thin Pi package:
 
-The pi plugin keeps Babysitter as the orchestration layer for pi sessions:
-
-- session lifecycle hooks prepare and bind run state
-- pi commands start or resume runs
-- the harness advances one orchestration phase at a time
-- the plugin runtime records effect outcomes and updates the run state
-- completion requires the emitted `completionProof`
+- `skills/` exposes Babysitter workflows through Pi's skill system
+- `extensions/index.ts` adds lightweight slash-command aliases that forward to those skills
+- the SDK remains responsible for orchestration, runs, tasks, and state
 
 ## Installation
 
-Install the published Pi plugin globally:
+Recommended:
 
 ```bash
-npx @a5c-ai/babysitter-pi install
+pi install npm:@a5c-ai/babysitter-pi
+```
+
+Verify the package is available:
+
+```bash
+babysitter harness:discover --json
+```
+
+Project-local:
+
+```bash
+cd /path/to/repo
+pi install -l npm:@a5c-ai/babysitter-pi
 ```
 
-Install into a specific workspace instead of the user profile:
+Development helper:
 
 ```bash
+npx @a5c-ai/babysitter-pi install
 npx @a5c-ai/babysitter-pi install --workspace /path/to/repo
 ```
 
-Or use the Babysitter SDK helper:
+Removal:
 
 ```bash
-babysitter harness:install-plugin pi
-babysitter harness:install-plugin pi --workspace /path/to/repo
+pi remove npm:@a5c-ai/babysitter-pi
 ```
 
-This package installs under:
+## Using Babysitter
+
+Start Pi, then use the thin Babysitter entrypoints exposed by the package:
+
+- `/babysit` or `/babysitter`
+- `/call`
+- `/plan`
+- `/resume`
+- `/doctor`
+- `/yolo`
+
+Each command forwards into Pi's native `/skill:<name>` flow. The orchestration
+contract lives in the skills; the extension only provides convenient aliases.
+
+## Commands And Skills
+
+The package mirrors the canonical Babysitter command docs and exposes the core
+`babysit` skill plus command-backed skills such as `call`, `doctor`, `plan`,
+`resume`, and `yolo`.
+
+The extension layer is intentionally thin. It only forwards slash commands to
+Pi's built-in `/skill:<name>` flow; it does not implement a custom loop driver,
+custom tools, or direct run mutation logic.
+
+## Plugin Layout
 
 ```text
-~/.pi/plugins/babysitter
+plugins/babysitter-pi/
+|-- package.json
+|-- versions.json
+|-- extensions/
+|   `-- index.ts
+|-- commands/
+|-- skills/
+|-- bin/
+`-- scripts/
 ```
 
-If the workspace does not already have an active process-library binding, the
-installer bootstraps the shared global SDK process library automatically:
+## SDK Setup
+
+Read the pinned SDK version from `versions.json` when you need a local CLI:
 
 ```bash
-babysitter process-library:active --json
+PLUGIN_ROOT="${PI_PLUGIN_ROOT:-$(pwd)}"
+SDK_VERSION=$(node -e "try{const fs=require('fs');const path=require('path');const pluginRoot=process.env.PI_PLUGIN_ROOT||process.env.PLUGIN_ROOT||process.cwd();const probes=[path.join(pluginRoot,'versions.json'),path.join(pluginRoot,'plugins','babysitter-pi','versions.json'),path.join(pluginRoot,'node_modules','@a5c-ai','babysitter-pi','versions.json'),path.join(process.cwd(),'node_modules','@a5c-ai','babysitter-pi','versions.json')];for(const probe of probes){if(fs.existsSync(probe)){console.log(JSON.parse(fs.readFileSync(probe,'utf8')).sdkVersion||'latest');process.exit(0)}}console.log('latest')}catch{console.log('latest')}")
+CLI="npx -y @a5c-ai/babysitter-sdk@$SDK_VERSION"
 ```
 
-## Commands
+## Marketplace And Distribution
+
+Pi discovers this package through its native package installation flow. Publish
+new versions to npm under `@a5c-ai/babysitter-pi`, then users can install or
+upgrade through `pi install npm:@a5c-ai/babysitter-pi`.
+
+## Upgrade And Uninstall
 
-The plugin exposes pi-facing Babysitter commands such as:
+Upgrade by reinstalling the package:
 
-- `/babysitter:call`
-- `/babysitter:status`
-- `/babysitter:resume`
-- `/babysitter:doctor`
+```bash
+pi install npm:@a5c-ai/babysitter-pi
+```
+
+Remove it with:
+
+```bash
+pi remove npm:@a5c-ai/babysitter-pi
+```
 
 ## Troubleshooting
 
-- `babysitter harness:discover --json` is the supported way to verify whether
-  `pi` is installed from the current environment.
-- If discovery reports `pi` as installed but a direct invocation fails, validate
-  the current shell `PATH` first with `where pi` on Windows.
+- Verify the harness with `babysitter harness:discover --json`.
+- If `pi` is not available, check `where pi` on Windows or `which pi` on Unix.
+- If commands do not appear, restart Pi after installation so it reloads package metadata.
+- If the wrong SDK version is used, inspect `versions.json` inside the installed package root.
+- Regenerate mirrored commands and command-backed skills with `npm run sync:commands`.
 
 ## Tests
 
 ```bash
 cd plugins/babysitter-pi
 npm test
-npm run test:integration
-npm run test:harness
-npm run test:tui
 ```
 
 ## License

package/bin/cli.cjs

@@ -23,11 +23,9 @@ function parseArgs(argv) {
     const arg = argv[i];
     if (arg === '--workspace') {
       const next = argv[i + 1];
+      workspace = next && !next.startsWith('-') ? path.resolve(next) : process.cwd();
       if (next && !next.startsWith('-')) {
-        workspace = path.resolve(next);
         i += 1;
-      } else {
-        workspace = process.cwd();
       }
       continue;
     }
@@ -65,13 +63,7 @@ function main() {
   }
 
   const parsed = parseArgs(rest);
-  const args = [];
-  if (parsed.workspace) {
-    args.push('--workspace', parsed.workspace);
-  } else {
-    args.push('--global');
-  }
-
+  const args = parsed.workspace ? ['--workspace', parsed.workspace] : ['--global'];
   runNodeScript(path.join(PACKAGE_ROOT, 'bin', `${command}.cjs`), args);
 }
 

package/bin/install.cjs

@@ -2,143 +2,52 @@
 'use strict';
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const INSTALL_ENTRIES = [
-  { source: 'package.json', required: true },
-  { source: 'extensions', required: true },
-  { source: 'skills', required: true },
-  { source: 'commands', required: true },
-  { source: 'scripts', required: true },
-];
+const PACKAGE_JSON = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
 
 function parseArgs(argv) {
-  const args = {
-    workspace: null,
-  };
+  let workspace = null;
   for (let i = 2; i < argv.length; i += 1) {
-    if (argv[i] === '--workspace' && argv[i + 1]) {
-      args.workspace = path.resolve(argv[++i]);
-    } else if (argv[i] === '--global') {
-      args.workspace = null;
-    } else {
-      throw new Error(`unknown argument: ${argv[i]}`);
+    const arg = argv[i];
+    if (arg === '--workspace') {
+      const next = argv[i + 1];
+      workspace = next && !next.startsWith('-') ? path.resolve(argv[++i]) : process.cwd();
+      continue;
     }
-  }
-  return args;
-}
-
-function getGlobalStateDir() {
-  if (process.env.BABYSITTER_GLOBAL_STATE_DIR) {
-    return path.resolve(process.env.BABYSITTER_GLOBAL_STATE_DIR);
-  }
-  return path.join(os.homedir(), '.a5c');
-}
-
-function getPluginRoot(args) {
-  const base = args.workspace ? path.resolve(args.workspace) : os.homedir();
-  return path.join(base, '.pi', 'plugins', 'babysitter');
-}
-
-function copyRecursive(src, dest) {
-  const stat = fs.statSync(src);
-  if (stat.isDirectory()) {
-    fs.mkdirSync(dest, { recursive: true });
-    for (const entry of fs.readdirSync(src)) {
-      if (['node_modules', '.git', 'test', '.gitignore', 'state'].includes(entry)) continue;
-      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    if (arg === '--global') {
+      workspace = null;
+      continue;
     }
-    return;
+    throw new Error(`unknown argument: ${arg}`);
   }
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.copyFileSync(src, dest);
+  return { workspace };
 }
 
-function resolveBabysitterCommand(packageRoot) {
-  if (process.env.BABYSITTER_SDK_CLI) {
-    return {
-      command: process.execPath,
-      argsPrefix: [path.resolve(process.env.BABYSITTER_SDK_CLI)],
-    };
-  }
-  try {
-    return {
-      command: process.execPath,
-      argsPrefix: [
-        require.resolve('@a5c-ai/babysitter-sdk/dist/cli/main.js', {
-          paths: [packageRoot],
-        }),
-      ],
-    };
-  } catch {
-    return {
-      command: 'babysitter',
-      argsPrefix: [],
-    };
-  }
-}
-
-function runBabysitterCli(packageRoot, cliArgs) {
-  const resolved = resolveBabysitterCommand(packageRoot);
-  const result = spawnSync(resolved.command, [...resolved.argsPrefix, ...cliArgs], {
-    cwd: packageRoot,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf8',
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: 'inherit',
     env: process.env,
   });
-  if (result.status !== 0) {
-    const stderr = (result.stderr || '').trim();
-    const stdout = (result.stdout || '').trim();
-    throw new Error(
-      `babysitter ${cliArgs.join(' ')} failed` +
-      (stderr ? `: ${stderr}` : stdout ? `: ${stdout}` : ''),
-    );
+  if ((result.status ?? 1) !== 0) {
+    process.exit(result.status ?? 1);
   }
-  return result.stdout;
 }
 
-function ensureGlobalProcessLibrary() {
-  const active = JSON.parse(
-    runBabysitterCli(
-      PACKAGE_ROOT,
-      ['process-library:active', '--state-dir', getGlobalStateDir(), '--json'],
-    ),
-  );
-  console.log(`[babysitter]   process library: ${active.binding?.dir}`);
-}
-
-function installEntry(pluginRoot, entry) {
-  const src = path.join(PACKAGE_ROOT, entry.source);
-  const dest = path.join(pluginRoot, entry.source);
-  if (!fs.existsSync(src)) {
-    if (entry.required) throw new Error(`required install payload is missing: ${src}`);
+function main() {
+  const { workspace } = parseArgs(process.argv);
+  const packageSpec = `npm:${PACKAGE_JSON.name}@${PACKAGE_JSON.version}`;
+  if (workspace) {
+    console.log(`[babysitter] installing ${packageSpec} into project settings for ${workspace}`);
+    run('pi', ['install', '-l', packageSpec], workspace);
     return;
   }
-  copyRecursive(src, dest);
-  console.log(`[babysitter]   ${entry.source}${fs.statSync(src).isDirectory() ? '/' : ''}`);
-}
-
-function main() {
-  const args = parseArgs(process.argv);
-  const pluginRoot = getPluginRoot(args);
-  console.log(`[babysitter] Installing pi plugin to ${pluginRoot}`);
 
-  try {
-    fs.rmSync(pluginRoot, { recursive: true, force: true });
-    fs.mkdirSync(pluginRoot, { recursive: true });
-    for (const entry of INSTALL_ENTRIES) {
-      installEntry(pluginRoot, entry);
-    }
-    fs.mkdirSync(path.join(pluginRoot, 'state'), { recursive: true });
-    ensureGlobalProcessLibrary();
-    console.log('[babysitter] Installation complete!');
-  } catch (err) {
-    console.error(`[babysitter] Failed to install plugin files: ${err.message}`);
-    process.exitCode = 1;
-  }
+  console.log(`[babysitter] installing ${packageSpec} into global pi settings`);
+  run('pi', ['install', packageSpec], process.cwd());
 }
 
 main();

package/bin/uninstall.cjs

@@ -2,39 +2,39 @@
 'use strict';
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const PACKAGE_JSON = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
 
 function parseArgs(argv) {
-  const args = {
-    workspace: null,
-  };
+  let workspace = null;
   for (let i = 2; i < argv.length; i += 1) {
-    if (argv[i] === '--workspace' && argv[i + 1]) {
-      args.workspace = path.resolve(argv[++i]);
-    } else if (argv[i] === '--global') {
-      args.workspace = null;
-    } else {
-      throw new Error(`unknown argument: ${argv[i]}`);
+    const arg = argv[i];
+    if (arg === '--workspace') {
+      const next = argv[i + 1];
+      workspace = next && !next.startsWith('-') ? path.resolve(argv[++i]) : process.cwd();
+      continue;
+    }
+    if (arg === '--global') {
+      workspace = null;
+      continue;
     }
+    throw new Error(`unknown argument: ${arg}`);
   }
-  return args;
-}
-
-function getPluginRoot(args) {
-  const base = args.workspace ? path.resolve(args.workspace) : os.homedir();
-  return path.join(base, '.pi', 'plugins', 'babysitter');
+  return { workspace };
 }
 
 function main() {
-  const args = parseArgs(process.argv);
-  const pluginRoot = getPluginRoot(args);
-  if (!fs.existsSync(pluginRoot)) {
-    console.log('[babysitter] Nothing to uninstall.');
-    return;
-  }
-  fs.rmSync(pluginRoot, { recursive: true, force: true });
-  console.log(`[babysitter] Removed ${pluginRoot}`);
+  const { workspace } = parseArgs(process.argv);
+  const packageSpec = `npm:${PACKAGE_JSON.name}`;
+  const result = spawnSync('pi', workspace ? ['remove', '-l', packageSpec] : ['remove', packageSpec], {
+    cwd: workspace ?? process.cwd(),
+    stdio: 'inherit',
+    env: process.env,
+  });
+  process.exitCode = result.status ?? 1;
 }
 
 main();

package/commands/assimilate.md

@@ -0,0 +1,37 @@
+---
+description: Assimilate an external methodology, harness, or specification into babysitter process definitions with skills and agents.
+argument-hint: Target to assimilate (e.g. repo URL, harness name, or spec path)
+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).
+
+Use the assimilation domain processes from the active process library to convert external sources into well-defined babysitter process definitions with accompanying skills/ and agents/ directories.
+
+If the workspace does not already have an active process-library binding, initialize it first through the shared global SDK binding:
+
+```bash
+babysitter process-library:active --json
+```
+
+Run the process after formalizing it.
+
+Available assimilation workflows:
+- **methodology-assimilation** (`specializations/meta/assimilation/workflows/methodology-assimilation`) - Learns an external methodology from its repo and converts procedural instructions, commands, and manual flows into babysitter processes with refactored skills and agents. Supports output as methodology or specialization.
+- **harness integration** (`specializations/meta/assimilation/harness/*`) - Integrates babysitter SDK with a specific AI coding harness (generic, codex, opencode, gemini-cli, openclaw, antigravity).
+
+During the interview phase, determine which assimilation workflow to use based on the user's target:
+- If the target is a **repo URL or methodology name** then use the methodology-assimilation workflow.
+- If the target is a **harness name** (e.g. codex, opencode, antigravity) then use the matching harness process.
+- If the target is a **specification or other source** then adapt the methodology-assimilation workflow for the spec format.
+- If unclear, ask the user to clarify the assimilation target and type.
+
+## After Assimilation: Contribute Back
+
+After successfully assimilating a methodology or harness integration, prompt the user to share it with the community. The assimilated process definitions, skills, and agents could benefit other babysitter users:
+
+- **Completed a methodology assimilation**: `/babysitter:contrib library contribution: assimilated [methodology-name] into babysitter process definitions`
+- **Completed a harness integration**: `/babysitter:contrib library contribution: [harness-name] harness integration`
+- **Hit issues during assimilation** (e.g. unsupported patterns, missing SDK features): `/babysitter:contrib bug report: assimilation of [target] failed because [description]` or `/babysitter:contrib feature request: [what the SDK needs to support]`
+
+Even just reporting that an assimilation didn't work well helps improve babysitter for everyone.

package/commands/call.md

@@ -0,0 +1,7 @@
+---
+description: Orchestrate a babysitter run. use this command to start babysitting a complex workflow.
+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).

package/commands/cleanup.md

@@ -0,0 +1,20 @@
+---
+description: Clean up .a5c/runs and .a5c/processes directories. Aggregates insights from completed/failed runs into docs/run-history-insights.md, then removes old run data and orphaned process files.
+argument-hint: "[--dry-run] [--keep-days N] Optional flags. --dry-run shows what would be removed without deleting. --keep-days N keeps runs newer than N days (default 7)."
+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).
+
+Create and run a cleanup process using the process at `skills\babysit\process\cradle\cleanup-runs.js/processes/cleanup-runs.js`.
+
+Implementation notes (for the process):
+- Parse arguments for `--dry-run` flag (if present, set dryRun: true in inputs) and `--keep-days N` (default: 7)
+- The process scans .a5c/runs/ for completed/failed runs, aggregates insights, writes summaries, then removes old data
+- Always show the user what will be removed before removing (in interactive mode via breakpoints)
+- In non-interactive mode (yolo), proceed with cleanup using defaults
+- The insights file goes to docs/run-history-insights.md
+- Only remove terminal runs (completed/failed) older than the keep-days threshold
+- Never remove active/in-progress runs
+- Remove orphaned process files not referenced by remaining runs
+- After cleanup, show remaining run count and disk usage

package/commands/contrib.md

@@ -0,0 +1,33 @@
+---
+description: Submit feedback or contribute to babysitter project
+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).
+
+## Process Routing
+
+Contribution processes live under the active process library's `cradle/` directory. Resolve the active library root with `babysitter process-library:active --json` and route based on arguments:
+
+### Issue-based (opens a GitHub issue in a5c-ai/babysitter)
+ * **Bug report** → `cradle/bug-report.js#process` — Report a bug in the SDK, CLI, process library, etc.
+ * **Feature request** → `cradle/feature-request.js#process` — Request a new feature or enhancement
+ * **Documentation question** → `cradle/documentation-question.js#process` — Ask about undocumented behavior or missing docs
+
+### PR-based (forks repo, creates branch, submits PR to a5c-ai/babysitter)
+ * **Bugfix** → `cradle/bugfix.js#process` — User already has the fix for a bug
+ * **Feature implementation** → `cradle/feature-implementation-contribute.js#process` — User already has a feature implementation
+ * **Harness integration** → `cradle/feature-harness-integration-contribute.js#process` — User has a harness (CI/CD, IDE, editor) integration
+ * **Library contribution** → `cradle/library-contribution.js#process` — New or improved process/skill/subagent for the library
+ * **Documentation answer** → `cradle/documentation-contribute-answer.js#process` — User has an answer for an unanswered docs question
+
+### Router (when arguments are empty or general)
+ * **Contribute** → `cradle/contribute.js#process` — Explains contribution types and routes to the specific process
+
+## Contribution Rules
+
+ * PR-based contributions: fork the babysitter repo (a5c-ai/babysitter) for the user, ask to star if not already starred, perform changes, submit PR
+ * Issue-based contributions: gather details, search for duplicates, review, then open an issue in a5c-ai/babysitter
+ * Add breakpoints (permissions) before ALL gh actions (fork, star, submit PR/issue) to allow user review and cancellation
+ * If arguments are empty: use the `contribute.js` router process to show options and route accordingly