@a5c-ai/babysitter-github 0.1.1-staging.0a3fc67d

package/AGENTS.md

@@ -0,0 +1,41 @@
+# Babysitter Orchestration Agent
+
+You are operating under Babysitter orchestration. Babysitter manages complex, multi-step
+workflows with event-sourced state management, hook-based extensibility, and human-in-the-loop
+approval gates.
+
+## Key Behaviors
+
+1. **Follow the process definition exactly.** Each task in the workflow has been defined with
+   specific inputs, outputs, and quality criteria. Do not skip steps or improvise alternatives
+   unless explicitly told to by the orchestrator.
+
+2. **Report completion accurately.** When you finish a task, your output must match the expected
+   result schema. Do not fabricate results or claim success without evidence.
+
+3. **Respect breakpoints.** When you encounter a breakpoint (human approval gate), stop and wait.
+   Do not attempt to bypass or auto-approve breakpoints.
+
+4. **Use structured output.** When the orchestrator requests JSON output, respond with valid JSON
+   only. Do not wrap it in markdown code fences or add commentary outside the JSON.
+
+5. **Completion proof.** When you have completed all assigned work, output the completion proof
+   token provided by the orchestrator: `<promise>COMPLETION_PROOF</promise>`. This signals the
+   Stop hook to allow the session to end.
+
+## Environment
+
+- **Harness**: GitHub Copilot CLI (`copilot`)
+- **SDK CLI**: `babysitter` (installed globally or via npx)
+- **State directory**: `.a5c/` in the project root
+- **Run directory**: `.a5c/runs/<runId>/`
+
+## Commands
+
+You can invoke babysitter CLI commands directly:
+
+```bash
+babysitter run:status --run-id <id> --json     # Check run status
+babysitter task:list --run-id <id> --json       # List pending tasks
+babysitter task:post --run-id <id> --effect-id <eid> --json  # Post task result
+```

package/README.md

@@ -0,0 +1,507 @@
+# @a5c-ai/babysitter-github
+
+Babysitter orchestration plugin for [GitHub Copilot CLI](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-in-the-command-line).
+
+This package ships a complete Copilot CLI plugin bundle -- skills, lifecycle
+hooks, and SDK integration -- that lets you run Babysitter's event-sourced,
+multi-step orchestration engine directly inside GitHub Copilot CLI sessions.
+It uses the Babysitter SDK CLI and the shared `~/.a5c` process-library state.
+The installer registers the plugin bundle and materializes the active skills
+and hooks so Copilot CLI can execute Babysitter commands and hook scripts
+directly.
+
+## Prerequisites
+
+- **Node.js 22+**
+- **GitHub Copilot CLI** (`copilot`) -- requires an active GitHub Copilot
+  subscription
+- **Babysitter SDK CLI** (`@a5c-ai/babysitter-sdk`) -- installed globally
+
+## Installation
+
+Install the SDK CLI first:
+
+```bash
+npm install -g @a5c-ai/babysitter-sdk
+```
+
+Then install the GitHub Copilot plugin globally:
+
+```bash
+npm install -g @a5c-ai/babysitter-github
+babysitter-github install
+```
+
+Or install from source:
+
+```bash
+cd plugins/babysitter-github
+node bin/install.js
+```
+
+Install into a specific workspace:
+
+```bash
+babysitter-github install --workspace /path/to/repo
+```
+
+If the workspace does not already have an active process-library binding, the
+installer bootstraps the shared global SDK process library automatically:
+
+```bash
+babysitter process-library:active --json
+```
+
+## Uninstallation
+
+```bash
+babysitter-github uninstall
+```
+
+## Integration Model
+
+The plugin provides:
+
+- `skills/babysit/SKILL.md` as the core orchestration entrypoint
+- Mode wrapper skills such as `$call`, `$plan`, and `$resume`
+- Plugin-level lifecycle hooks for `SessionStart`, `UserPromptSubmit`, and
+  `Stop`
+
+The process library is fetched and bound through the SDK CLI in
+`~/.a5c/active/process-library.json`.
+
+### Active Process-Library Model
+
+Process discovery prefers active roots in this order:
+
+1. `.a5c/processes` in the current workspace
+2. The SDK-managed active process-library binding returned by
+   `babysitter process-library:active --json`
+3. The cloned process-library repo root from `defaultSpec.cloneDir` when
+   adjacent reference material is needed
+4. Installed extension content only as a compatibility fallback
+
+## Available Skills
+
+The plugin registers ten skills that surface as slash commands within Copilot
+CLI:
+
+| Skill | Description |
+|-------|-------------|
+| `babysit` | Core entrypoint. Orchestrate `.a5c/runs/<runId>/` through iterative execution. Invoke when asked to babysit, orchestrate, or run a workflow. |
+| `call` | Start a new orchestration run. Everything after `$call` becomes the initial Babysitter request. Always creates an interactive run. |
+| `plan` | Design a process definition without executing it. Useful for reviewing or refining a workflow before committing to a run. |
+| `resume` | Resume an incomplete or paused orchestration run from where it left off. |
+| `doctor` | Diagnose run health -- journal integrity, state cache, effects, locks, sessions, logs, and disk usage. |
+| `retrospect` | Analyze a completed run: results, process quality, and suggestions for process improvements and optimizations. |
+| `observe` | Launch the real-time observer dashboard to watch active runs. |
+| `assimilate` | Assimilate an external methodology, harness, or specification into Babysitter process definitions. |
+| `help` | Show documentation for Babysitter command usage, processes, skills, agents, and methodologies. |
+| `user-install` | Set up Babysitter for yourself -- installs dependencies, interviews you about preferences, and configures user-level defaults. |
+
+## How the Hook-Driven Orchestration Loop Works
+
+GitHub Copilot CLI supports plugin lifecycle hooks. This plugin registers
+three hooks that drive the orchestration loop:
+
+### SessionStart
+
+Fires when a new Copilot CLI session begins. The hook:
+
+1. Initializes a Babysitter session for the active Copilot session
+2. Ensures the SDK CLI is installed at the correct version (pinned in
+   `versions.json`)
+3. Creates baseline session state in the `.a5c` state directory
+
+### Stop
+
+The orchestration loop driver. When Copilot CLI attempts to end its turn,
+this hook intercepts the exit and:
+
+1. Checks whether the active run has completed or emitted a completion proof
+2. If the run is still in progress, re-injects the next orchestration step
+   to continue iteration
+3. Only allows the session to exit when the run finishes or reaches a
+   breakpoint requiring human input
+
+This is what keeps Babysitter iterating autonomously within the Copilot CLI
+session -- each turn performs one orchestration phase, and the Stop hook
+decides whether to loop or yield.
+
+### UserPromptSubmit
+
+Fires before a user prompt reaches the model. The hook applies
+density-filter compression to long user prompts to reduce token usage while
+preserving semantic content.
+
+## Configuration
+
+### AGENTS.md
+
+The plugin uses `AGENTS.md` (the Copilot CLI equivalent of `CLAUDE.md`) for
+custom agent instructions. This file is set via the `contextFileName` field
+in `plugin.json` and is read by Copilot CLI to configure agent behavior
+within sessions.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_PROJECT_DIR` | CWD | Project root directory (set by Copilot CLI) |
+| `BABYSITTER_LOG_DIR` | `<plugin>/.a5c/logs` | Log output directory |
+| `BABYSITTER_STATE_DIR` | `<cwd>/.a5c` | State directory for session data |
+
+### SDK Version Pinning
+
+The plugin pins its required SDK version in `versions.json`. The
+SessionStart hook reads this file and ensures the correct version of
+`@a5c-ai/babysitter-sdk` is installed globally before proceeding.
+
+## Copilot CLI Plugin Structure
+
+This section documents the Copilot CLI plugin format that this package
+conforms to. Understanding this structure is useful when extending the plugin
+or building new ones.
+
+### Plugin Manifest Location
+
+Copilot CLI looks for the plugin manifest in these paths, checked in order:
+
+1. `.plugin/plugin.json`
+2. `.github/plugin/plugin.json`
+3. `.claude-plugin/plugin.json`
+4. `plugin.json` (repository root)
+
+The first match wins. This plugin uses `plugin.json` at the package root.
+
+### plugin.json Schema
+
+The manifest declares metadata, skills, hooks, and optional integrations:
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | Yes | `string` | Plugin identifier (e.g., `"babysitter"`) |
+| `description` | No | `string` | Human-readable summary |
+| `version` | No | `string` | Semver version string |
+| `author` | No | `object` | Author info: `{ "name": "...", "email": "..." }` |
+| `license` | No | `string` | SPDX license identifier |
+| `keywords` | No | `string[]` | Searchable tags for marketplace discovery |
+| `agents` | No | `string` | Path to agents directory |
+| `skills` | No | `array` | Array of skill directory paths (see below) |
+| `hooks` | No | `string` | Path to `hooks.json` |
+| `mcpServers` | No | `string` | Path to `.mcp.json` for MCP server configuration |
+
+Example from this plugin:
+
+```json
+{
+  "name": "babysitter",
+  "version": "0.1.0",
+  "description": "Orchestrate complex, multi-step workflows ...",
+  "author": "a5c.ai",
+  "license": "MIT",
+  "hooks": {
+    "sessionStart": "hooks/session-start.sh",
+    "sessionEnd": "hooks/session-end.sh",
+    "userPromptSubmitted": "hooks/user-prompt-submitted.sh"
+  },
+  "skills": [
+    { "name": "babysit", "file": "skills/babysit/SKILL.md" },
+    { "name": "call", "file": "skills/call/SKILL.md" }
+  ],
+  "keywords": ["orchestration", "workflow", "automation"]
+}
+```
+
+### Skills Format
+
+Each skill lives in its own directory under `skills/` and is defined by a
+Markdown file with YAML frontmatter:
+
+```
+skills/
+  babysit/
+    SKILL.md
+  call/
+    SKILL.md
+  plan/
+    SKILL.md
+```
+
+The `SKILL.md` file uses frontmatter to declare metadata:
+
+```markdown
+---
+name: babysit
+description: Orchestrate a multi-step workflow using the Babysitter SDK
+---
+
+Skill body with instructions for the agent...
+```
+
+The `name` and `description` fields in the frontmatter are required. The
+body of the Markdown file contains the instructions the agent follows when
+the skill is invoked.
+
+### hooks.json Format
+
+The `hooks.json` file declares lifecycle hook handlers as an array of
+command descriptors per event type:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "bash": "./hooks/session-start.sh",
+        "powershell": "./hooks/session-start.ps1",
+        "timeoutSec": 30
+      }
+    ],
+    "sessionEnd": [
+      {
+        "type": "command",
+        "bash": "./hooks/session-end.sh",
+        "powershell": "./hooks/session-end.ps1",
+        "timeoutSec": 30
+      }
+    ],
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "bash": "./hooks/user-prompt-submitted.sh",
+        "powershell": "./hooks/user-prompt-submitted.ps1",
+        "timeoutSec": 30
+      }
+    ],
+    "preToolUse": [...],
+    "postToolUse": [...],
+    "errorOccurred": [...]
+  }
+}
+```
+
+Each hook entry specifies a `bash` and/or `powershell` command, a `type`
+(currently always `"command"`), and an optional `timeoutSec`.
+
+**Supported hook event types:**
+
+| Event | Description |
+|-------|-------------|
+| `sessionStart` | Fires when a new CLI session begins |
+| `sessionEnd` | Fires when a CLI session ends |
+| `userPromptSubmitted` | Fires before a user prompt reaches the model |
+| `preToolUse` | Fires before a tool is executed |
+| `postToolUse` | Fires after a tool has executed |
+| `errorOccurred` | Fires when an error is encountered |
+
+**Flow-control decisions:** Only `preToolUse` hooks can return flow-control
+decisions via the `permissionDecision` field in stdout JSON. Valid values
+are `"deny"`, `"allow"`, and `"ask"`. All other hook event outputs are
+ignored by the runtime.
+
+## Marketplace Distribution
+
+Copilot CLI plugins can be distributed through marketplaces -- Git
+repositories that contain a manifest listing available plugins.
+
+### Creating a Marketplace
+
+A marketplace is a Git repository with a `marketplace.json` file in
+`.github/plugin/` or `.claude-plugin/`:
+
+```json
+{
+  "name": "a5c.ai",
+  "owner": {
+    "name": "a5c.ai",
+    "email": "support@a5c.ai"
+  },
+  "metadata": {
+    "description": "Babysitter orchestration plugins",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "babysitter",
+      "description": "Multi-step workflow orchestration with event-sourced state",
+      "version": "0.1.0",
+      "source": "./plugins/babysitter-github"
+    }
+  ]
+}
+```
+
+The `source` field points to the plugin directory relative to the
+marketplace repository root.
+
+### User Commands
+
+Copilot CLI provides built-in commands for plugin and marketplace
+management:
+
+**Marketplace commands:**
+
+```bash
+copilot plugin marketplace add OWNER/REPO        # Register a marketplace
+copilot plugin marketplace list                   # List registered marketplaces
+copilot plugin marketplace browse NAME            # Browse plugins in a marketplace
+```
+
+**Plugin installation:**
+
+```bash
+copilot plugin install PLUGIN@MARKETPLACE         # Install from a marketplace
+copilot plugin install OWNER/REPO                 # Install directly from a GitHub repo
+copilot plugin install ./PATH                     # Install from a local path
+```
+
+**Plugin management:**
+
+```bash
+copilot plugin list                               # List installed plugins
+copilot plugin update PLUGIN                      # Update a plugin
+copilot plugin uninstall PLUGIN                   # Remove a plugin
+```
+
+### Plugin Storage
+
+Installed plugins are stored under `~/.copilot/installed-plugins/`:
+
+- **Marketplace installs:** `~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME/`
+- **Direct installs:** `~/.copilot/installed-plugins/_direct/SOURCE-ID/`
+
+### Default Registries
+
+Copilot CLI ships with two built-in registries:
+
+- `copilot-plugins` -- official first-party plugins
+- `awesome-copilot` -- community-curated plugin collection
+
+These registries are available without running `marketplace add`.
+
+## Plugin Structure (Directory Layout)
+
+```
+plugins/babysitter-github/
+  plugin.json              # Plugin manifest (skills, hooks, metadata)
+  hooks.json               # Hook configuration (sessionStart, sessionEnd, userPromptSubmitted)
+  hooks/
+    session-start.sh       # SessionStart lifecycle hook
+    session-end.sh         # SessionEnd lifecycle hook
+    user-prompt-submitted.sh  # UserPromptSubmitted hook (prompt compression)
+  skills/
+    babysit/SKILL.md       # Core orchestration skill
+    call/SKILL.md          # Start a new run
+    plan/SKILL.md          # Plan without executing
+    resume/SKILL.md        # Resume an incomplete run
+    doctor/SKILL.md        # Diagnose run health
+    retrospect/SKILL.md    # Analyze completed runs
+    observe/SKILL.md       # Observer dashboard
+    assimilate/SKILL.md    # Assimilate external methodologies
+    help/SKILL.md          # Help and documentation
+    user-install/SKILL.md  # User setup
+  bin/
+    cli.js                 # CLI entry point (babysitter-github command)
+    install.js             # Installation script
+    uninstall.js           # Uninstallation script
+  scripts/
+    team-install.js        # Team-level installation
+  versions.json            # SDK version pinning
+  package.json             # npm package metadata
+  AGENTS.md                # Custom instructions for Copilot CLI
+```
+
+## Verification
+
+Verify the installed plugin:
+
+```bash
+npm ls -g @a5c-ai/babysitter-github --depth=0
+```
+
+Verify the active shared process-library binding:
+
+```bash
+babysitter process-library:active --json
+```
+
+## Troubleshooting
+
+### Hook not firing
+
+Run the doctor skill from within a Copilot CLI session to diagnose hook and
+session health:
+
+```text
+$doctor
+```
+
+### Run stuck or not progressing
+
+Check the run status and diagnose:
+
+```text
+$doctor [run-id]
+```
+
+You can also inspect the run directory directly:
+
+```bash
+babysitter run:status --run-id <runId> --json
+babysitter run:events --run-id <runId> --json
+```
+
+### SDK version mismatch
+
+If the plugin reports version incompatibility, ensure the pinned SDK version
+is installed:
+
+```bash
+SDK_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('versions.json','utf8')).sdkVersion)")
+npm install -g @a5c-ai/babysitter-sdk@$SDK_VERSION
+```
+
+### Windows limitations
+
+On native Windows, Copilot CLI may not execute hook scripts depending on
+shell configuration. The plugin still installs correctly, but lifecycle hooks
+may not fire. Using WSL or Git Bash is recommended. The `hooks.json` file
+includes `powershell` entries alongside `bash` entries to improve Windows
+compatibility where PowerShell execution is available.
+
+## Development / Contributing
+
+### Local development
+
+```bash
+git clone https://github.com/a5c-ai/babysitter.git
+cd babysitter
+npm install
+cd plugins/babysitter-github
+node bin/install.js
+```
+
+### Publishing
+
+```bash
+cd plugins/babysitter-github
+npm run deploy            # Publish to npm (public)
+npm run deploy:staging    # Publish to npm with staging tag
+```
+
+### Team installation
+
+```bash
+cd plugins/babysitter-github
+npm run team:install
+```
+
+This sets up the plugin for all team members in a shared workspace,
+writing team-level configuration to `.a5c/team/`.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+function printUsage() {
+  console.error([
+    'Usage:',
+    '  babysitter-github install [--global]',
+    '  babysitter-github install --workspace [path]',
+    '  babysitter-github uninstall',
+  ].join('\n'));
+}
+
+function parseInstallArgs(argv) {
+  let scope = 'global';
+  let workspace = null;
+  const passthrough = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--global') {
+      if (scope === 'workspace') {
+        throw new Error('install accepts either --global or --workspace, not both');
+      }
+      scope = 'global';
+      continue;
+    }
+    if (arg === '--workspace') {
+      if (scope === 'global' && workspace !== null) {
+        throw new Error('install accepts either --global or --workspace, not both');
+      }
+      scope = 'workspace';
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        workspace = path.resolve(next);
+        i += 1;
+      } else {
+        workspace = process.cwd();
+      }
+      continue;
+    }
+    passthrough.push(arg);
+  }
+
+  return {
+    scope,
+    workspace,
+    passthrough,
+  };
+}
+
+function runNodeScript(scriptPath, args, extraEnv = {}) {
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      ...extraEnv,
+    },
+  });
+  process.exitCode = result.status ?? 1;
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    printUsage();
+    process.exitCode = command ? 0 : 1;
+    return;
+  }
+
+  if (command === 'install') {
+    const parsed = parseInstallArgs(rest);
+    if (parsed.scope === 'workspace') {
+      const args = [];
+      if (parsed.workspace) {
+        args.push('--workspace', parsed.workspace);
+      }
+      args.push(...parsed.passthrough);
+      runNodeScript(
+        path.join(PACKAGE_ROOT, 'scripts', 'team-install.js'),
+        args,
+        { BABYSITTER_PACKAGE_ROOT: PACKAGE_ROOT },
+      );
+      return;
+    }
+    runNodeScript(path.join(PACKAGE_ROOT, 'bin', 'install.js'), parsed.passthrough);
+    return;
+  }
+
+  if (command === 'uninstall') {
+    runNodeScript(path.join(PACKAGE_ROOT, 'bin', 'uninstall.js'), rest);
+    return;
+  }
+
+  printUsage();
+  process.exitCode = 1;
+}
+
+main();