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

package/.github/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "babysitter",
+  "version": "0.1.0",
+  "description": "Orchestrate complex, multi-step workflows with event-sourced state management, hook-based extensibility, and human-in-the-loop approval -- powered by the Babysitter SDK",
+  "author": { "name": "a5c.ai", "email": "support@a5c.ai" },
+  "license": "MIT",
+  "skills": "skills/",
+  "hooks": "hooks.json",
+  "commands": "commands/",
+  "agents": "AGENTS.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a5c-ai/babysitter"
+  },
+  "keywords": [
+    "orchestration",
+    "workflow",
+    "automation",
+    "event-sourced",
+    "hooks",
+    "github-copilot",
+    "agent",
+    "LLM"
+  ]
+}

package/README.md

@@ -1,6 +1,9 @@
 # @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).
+Babysitter orchestration plugin for GitHub Copilot. It supports both:
+
+- **GitHub Copilot CLI** via the local plugin and hook model
+- **GitHub Copilot coding agent / cloud agent** via repository-installed skills and instructions
 
 This package ships a complete Copilot CLI plugin bundle -- skills, lifecycle
 hooks, and SDK integration -- that lets you run Babysitter's event-sourced,
@@ -19,6 +22,32 @@ directly.
 
 ## Installation
 
+### From marketplace (recommended)
+
+Register the a5c.ai marketplace and install the plugin:
+
+```bash
+# Register the marketplace
+copilot plugin marketplace add a5c-ai/babysitter
+
+# Install the plugin
+copilot plugin install babysitter
+```
+
+### Direct GitHub install
+
+Install directly from the Git repository using Copilot CLI. Copilot CLI
+discovers the plugin via `.github/plugin/marketplace.json` at the repo root:
+
+```bash
+copilot plugin install a5c-ai/babysitter
+```
+
+### Alternative Installation (npm / development)
+
+For development or environments where the Copilot CLI plugin system is not
+available, install via npm:
+
 Install the SDK CLI first:
 
 ```bash
@@ -45,6 +74,30 @@ Install into a specific workspace:
 babysitter-github install --workspace /path/to/repo
 ```
 
+### GitHub Copilot cloud agent installation
+
+For GitHub Copilot's cloud-hosted coding agent, install repository-scoped
+Babysitter support instead of the local `~/.copilot` CLI plugin surface:
+
+```bash
+babysitter-github install --cloud-agent --workspace /path/to/repo
+```
+
+This installs:
+
+- a mirrored Babysitter GitHub plugin bundle under `.github/babysitter/github-plugin/`
+- Babysitter skills under `.github/skills/`
+- a managed Babysitter block in `AGENTS.md`
+- a managed Babysitter block in `.github/copilot-instructions.md`
+- a `copilot-setup-steps` workflow, or a generated merge candidate if the repo already has one
+
+If the repository already has a custom `copilot-setup-steps.yml`, the
+installer preserves it and writes a merge candidate to:
+
+```text
+.github/workflows/copilot-setup-steps.babysitter.generated.yml
+```
+
 If the workspace does not already have an active process-library binding, the
 installer bootstraps the shared global SDK process library automatically:
 
@@ -54,6 +107,14 @@ babysitter process-library:active --json
 
 ## Uninstallation
 
+Via Copilot CLI:
+
+```bash
+copilot plugin uninstall babysitter
+```
+
+Via npm:
+
 ```bash
 babysitter-github uninstall
 ```
@@ -64,8 +125,13 @@ 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`
+- Plugin-level lifecycle hooks for `sessionStart`, `sessionEnd`, and
+  `userPromptSubmitted`
+
+For Copilot cloud agent, the hook scripts are mirrored into the repository as
+part of the installed plugin bundle for reference and parity, but the hosted
+agent path is driven by repository instructions, skills, and setup workflow
+instead of local `~/.copilot/hooks.json`.
 
 The process library is fetched and bound through the SDK CLI in
 `~/.a5c/active/process-library.json`.
@@ -113,10 +179,10 @@ Fires when a new Copilot CLI session begins. The hook:
    `versions.json`)
 3. Creates baseline session state in the `.a5c` state directory
 
-### Stop
+### SessionEnd
 
-The orchestration loop driver. When Copilot CLI attempts to end its turn,
-this hook intercepts the exit and:
+The orchestration loop driver. Registered as `sessionEnd` in `hooks.json`,
+this hook fires when the Copilot CLI session ends 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
@@ -128,7 +194,7 @@ 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
+### UserPromptSubmitted
 
 Fires before a user prompt reaches the model. The hook applies
 density-filter compression to long user prompts to reduce token usage while
@@ -139,9 +205,21 @@ preserving semantic content.
 ### 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.
+custom agent instructions. The cloud-agent installer appends a managed
+Babysitter section to the repository root `AGENTS.md` so the hosted agent can
+see the same orchestration guidance.
+
+### .github/copilot-instructions.md
+
+The cloud-agent installer also appends a managed Babysitter block to
+`.github/copilot-instructions.md`. This gives GitHub-hosted Copilot sessions a
+repository-wide entrypoint for the Babysitter skills and setup workflow.
+
+### copilot-setup-steps workflow
+
+The cloud-agent path seeds `.github/workflows/copilot-setup-steps.yml` with a
+`copilot-setup-steps` job that installs the Babysitter SDK and initializes the
+active process library before the cloud agent starts working.
 
 ### Environment Variables
 
@@ -174,6 +252,10 @@ Copilot CLI looks for the plugin manifest in these paths, checked in order:
 
 The first match wins. This plugin uses `plugin.json` at the package root.
 
+For marketplace discovery, Copilot CLI looks for `.github/plugin/marketplace.json`
+at the repository root. This file lists all available plugins in the repo and is
+used when installing via `copilot plugin install OWNER/REPO`.
+
 ### plugin.json Schema
 
 The manifest declares metadata, skills, hooks, and optional integrations:
@@ -187,7 +269,7 @@ The manifest declares metadata, skills, hooks, and optional integrations:
 | `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) |
+| `skills` | No | `string` | Path to skills directory (auto-discovers SKILL.md files in subdirectories) |
 | `hooks` | No | `string` | Path to `hooks.json` |
 | `mcpServers` | No | `string` | Path to `.mcp.json` for MCP server configuration |
 
@@ -200,15 +282,9 @@ Example from this plugin:
   "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" }
-  ],
+  "skills": "skills/",
+  "hooks": "hooks.json",
+  "commands": [],
   "keywords": ["orchestration", "workflow", "automation"]
 }
 ```
@@ -309,8 +385,8 @@ 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/`:
+A marketplace is a Git repository with a `marketplace.json` file at the
+repository root in `.github/plugin/marketplace.json`:
 
 ```json
 {
@@ -387,6 +463,7 @@ These registries are available without running `marketplace add`.
 ```
 plugins/babysitter-github/
   plugin.json              # Plugin manifest (skills, hooks, metadata)
+  .github/plugin.json      # Plugin manifest (alternate discovery path)
   hooks.json               # Hook configuration (sessionStart, sessionEnd, userPromptSubmitted)
   hooks/
     session-start.sh       # SessionStart lifecycle hook
@@ -414,8 +491,30 @@ plugins/babysitter-github/
   AGENTS.md                # Custom instructions for Copilot CLI
 ```
 
+Cloud-agent installation additionally writes into the target repository:
+
+```
+.github/
+  babysitter/github-plugin/                # Mirrored plugin bundle for repo-local visibility
+  skills/
+    babysitter-babysit/SKILL.md            # Installed Babysitter cloud skills
+    babysitter-call/SKILL.md
+    ...
+  copilot-instructions.md                  # Managed Babysitter block appended
+  workflows/
+    copilot-setup-steps.yml                # Managed workflow when no custom file exists
+    copilot-setup-steps.babysitter.generated.yml  # Merge candidate when a custom file already exists
+AGENTS.md                                  # Managed Babysitter block appended
+```
+
 ## Verification
 
+Verify marketplace registration:
+
+```bash
+copilot plugin marketplace list
+```
+
 Verify the installed plugin:
 
 ```bash

package/bin/cli.js

@@ -11,6 +11,7 @@ function printUsage() {
     'Usage:',
     '  babysitter-github install [--global]',
     '  babysitter-github install --workspace [path]',
+    '  babysitter-github install --cloud-agent [--workspace [path]]',
     '  babysitter-github uninstall',
   ].join('\n'));
 }
@@ -18,6 +19,7 @@ function printUsage() {
 function parseInstallArgs(argv) {
   let scope = 'global';
   let workspace = null;
+  let cloudAgent = false;
   const passthrough = [];
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -43,10 +45,16 @@ function parseInstallArgs(argv) {
       }
       continue;
     }
+    if (arg === '--cloud-agent') {
+      cloudAgent = true;
+      passthrough.push(arg);
+      continue;
+    }
     passthrough.push(arg);
   }
 
   return {
+    cloudAgent,
     scope,
     workspace,
     passthrough,
@@ -75,6 +83,10 @@ function main() {
 
   if (command === 'install') {
     const parsed = parseInstallArgs(rest);
+    if (parsed.cloudAgent) {
+      runNodeScript(path.join(PACKAGE_ROOT, 'bin', 'install.js'), parsed.passthrough);
+      return;
+    }
     if (parsed.scope === 'workspace') {
       const args = [];
       if (parsed.workspace) {

package/bin/install-shared.js

@@ -5,7 +5,7 @@ const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
-const PLUGIN_NAME = 'babysitter-github';
+const PLUGIN_NAME = 'babysitter';
 const PLUGIN_CATEGORY = 'Coding';
 const LEGACY_HOOK_SCRIPT_NAMES = [
   'session-start.sh',
@@ -35,6 +35,22 @@ const PLUGIN_BUNDLE_ENTRIES = [
   'versions.json',
   'AGENTS.md',
 ];
+const CLOUD_AGENT_BUNDLE_ENTRIES = [
+  '.github',
+  'AGENTS.md',
+  'README.md',
+  'bin',
+  'commands',
+  'hooks',
+  'hooks.json',
+  'package.json',
+  'plugin.json',
+  'scripts',
+  'skills',
+  'versions.json',
+];
+const MANAGED_BLOCK_START = '<!-- BEGIN BABYSITTER GITHUB CLOUD AGENT -->';
+const MANAGED_BLOCK_END = '<!-- END BABYSITTER GITHUB CLOUD AGENT -->';
 
 function getCopilotHome() {
   if (process.env.COPILOT_HOME) return path.resolve(process.env.COPILOT_HOME);
@@ -145,6 +161,79 @@ function writeJson(filePath, value) {
   writeFileIfChanged(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function replaceManagedMarkdownBlock(existing, block) {
+  const normalized = String(existing || '').replace(/\r\n/g, '\n');
+  const managedBlock = `${MANAGED_BLOCK_START}\n${block.trim()}\n${MANAGED_BLOCK_END}`;
+  const escapedStart = MANAGED_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const escapedEnd = MANAGED_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const managedPattern = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}`, 'm');
+
+  if (managedPattern.test(normalized)) {
+    return normalized.replace(managedPattern, managedBlock).replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+  }
+
+  if (normalized.trim().length === 0) {
+    return `${managedBlock}\n`;
+  }
+
+  return `${normalized.trimEnd()}\n\n${managedBlock}\n`;
+}
+
+function writeManagedMarkdown(filePath, block) {
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  return writeFileIfChanged(filePath, replaceManagedMarkdownBlock(existing, block));
+}
+
+function readSdkVersion(packageRoot) {
+  const versionsPath = path.join(packageRoot, 'versions.json');
+  if (!fs.existsSync(versionsPath)) {
+    return 'latest';
+  }
+  try {
+    const parsed = readJson(versionsPath);
+    return typeof parsed.sdkVersion === 'string' && parsed.sdkVersion.trim() !== ''
+      ? parsed.sdkVersion.trim()
+      : 'latest';
+  } catch {
+    return 'latest';
+  }
+}
+
+function toLowerHyphenName(name) {
+  return String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function rewriteCloudSkill(skillId, contents) {
+  const normalized = String(contents).replace(/\r\n/g, '\n');
+  const prefixedName = `babysitter-${skillId}`;
+  let next = normalized;
+
+  if (next.startsWith('---\n')) {
+    next = next.replace(/^---\n([\s\S]*?)\n---\n?/, (_match, frontmatter) => {
+      const lines = String(frontmatter).split('\n');
+      let sawName = false;
+      const updatedLines = lines.map((line) => {
+        if (/^name:\s*/.test(line)) {
+          sawName = true;
+          return `name: ${prefixedName}`;
+        }
+        return line;
+      });
+      if (!sawName) {
+        updatedLines.push(`name: ${prefixedName}`);
+      }
+      return `---\n${updatedLines.join('\n')}\n---\n`;
+    });
+  }
+
+  next = next.replace(/^#\s+.+$/m, `# ${prefixedName}`);
+  return next.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
 function ensureMarketplaceEntry(marketplacePath, pluginSourcePath) {
   const marketplace = fs.existsSync(marketplacePath)
     ? readJson(marketplacePath)
@@ -369,6 +458,167 @@ function installCopilotSurface(packageRoot, copilotHome) {
   installManagedHooks(packageRoot, copilotHome);
 }
 
+function renderCloudAgentAgentsBlock() {
+  return [
+    '## Babysitter Cloud Agent',
+    '',
+    'This repository is configured to let GitHub Copilot cloud agent use Babysitter orchestration assets.',
+    '',
+    '- For complex multi-step work, use the Babysitter skills installed under `.github/skills/` when relevant.',
+    '- The cloud-agent setup workflow installs the Babysitter SDK before work begins.',
+    '- If you need the full orchestration instructions, run `babysitter instructions:babysit-skill --harness github-copilot --json`.',
+    '- Execute requested shell and Node tasks directly and report the results instead of describing what should be done.',
+    '- Do not revert unrelated user changes.',
+  ].join('\n');
+}
+
+function renderCloudAgentCopilotInstructionsBlock() {
+  return [
+    '# Babysitter Copilot Cloud Agent Support',
+    '',
+    'This repository includes Babysitter support for GitHub Copilot cloud agent.',
+    '',
+    '- Read the nearest `AGENTS.md` instructions before making changes.',
+    '- Consider the Babysitter skills under `.github/skills/` when the task is a multi-step workflow, orchestration run, diagnosis, planning, or retrospective.',
+    '- The `copilot-setup-steps` workflow installs the Babysitter SDK and initializes the active process library before the agent starts working.',
+    '- Add repository-specific build, test, and validation commands below this managed section if they are not already documented elsewhere in the repo.',
+  ].join('\n');
+}
+
+function renderCloudAgentSetupWorkflow(packageRoot) {
+  const sdkVersion = readSdkVersion(packageRoot);
+  return [
+    'name: "Copilot Setup Steps"',
+    '',
+    'on:',
+    '  workflow_dispatch:',
+    '  push:',
+    '    paths:',
+    '      - .github/workflows/copilot-setup-steps.yml',
+    '      - .github/copilot-instructions.md',
+    '      - .github/skills/**',
+    '      - AGENTS.md',
+    '  pull_request:',
+    '    paths:',
+    '      - .github/workflows/copilot-setup-steps.yml',
+    '      - .github/copilot-instructions.md',
+    '      - .github/skills/**',
+    '      - AGENTS.md',
+    '',
+    'jobs:',
+    '  copilot-setup-steps:',
+    '    runs-on: ubuntu-latest',
+    '    permissions:',
+    '      contents: read',
+    '    steps:',
+    '      - name: Check out repository',
+    '        uses: actions/checkout@v4',
+    '',
+    '      - name: Set up Node.js',
+    '        uses: actions/setup-node@v4',
+    '        with:',
+    '          node-version: 22',
+    '          cache: npm',
+    '',
+    '      - name: Install Babysitter SDK',
+    `        run: npm install -g @a5c-ai/babysitter-sdk@${sdkVersion}`,
+    '',
+    '      - name: Initialize active process library',
+    '        run: babysitter process-library:active --json',
+  ].join('\n') + '\n';
+}
+
+function installCloudAgentBundle(packageRoot, workspaceRoot) {
+  const bundleRoot = path.join(workspaceRoot, '.github', 'babysitter', 'github-plugin');
+  fs.rmSync(bundleRoot, { recursive: true, force: true });
+  fs.mkdirSync(bundleRoot, { recursive: true });
+  for (const entry of CLOUD_AGENT_BUNDLE_ENTRIES) {
+    const sourcePath = path.join(packageRoot, entry);
+    if (!fs.existsSync(sourcePath)) {
+      continue;
+    }
+    copyRecursive(sourcePath, path.join(bundleRoot, entry));
+  }
+  return bundleRoot;
+}
+
+function installCloudAgentSkills(packageRoot, workspaceRoot) {
+  const sourceRoot = path.join(packageRoot, 'skills');
+  if (!fs.existsSync(sourceRoot)) return [];
+
+  const targetRoot = path.join(workspaceRoot, '.github', 'skills');
+  fs.mkdirSync(targetRoot, { recursive: true });
+  const installed = [];
+
+  for (const entry of fs.readdirSync(sourceRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const sourceDir = path.join(sourceRoot, entry.name);
+    const skillId = toLowerHyphenName(entry.name);
+    const targetDir = path.join(targetRoot, `babysitter-${skillId}`);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    copyRecursive(sourceDir, targetDir);
+    const skillPath = path.join(targetDir, 'SKILL.md');
+    if (fs.existsSync(skillPath)) {
+      const rewritten = rewriteCloudSkill(skillId, fs.readFileSync(skillPath, 'utf8'));
+      fs.writeFileSync(skillPath, rewritten, 'utf8');
+    }
+    installed.push(targetDir);
+  }
+
+  return installed;
+}
+
+function installCloudAgentInstructions(packageRoot, workspaceRoot) {
+  const agentsPath = path.join(workspaceRoot, 'AGENTS.md');
+  const copilotInstructionsPath = path.join(workspaceRoot, '.github', 'copilot-instructions.md');
+
+  writeManagedMarkdown(agentsPath, renderCloudAgentAgentsBlock(packageRoot));
+  writeManagedMarkdown(copilotInstructionsPath, renderCloudAgentCopilotInstructionsBlock(packageRoot));
+
+  return {
+    agentsPath,
+    copilotInstructionsPath,
+  };
+}
+
+function installCloudAgentSetupSteps(packageRoot, workspaceRoot) {
+  const workflowsDir = path.join(workspaceRoot, '.github', 'workflows');
+  const workflowPath = path.join(workflowsDir, 'copilot-setup-steps.yml');
+  const examplePath = path.join(workflowsDir, 'copilot-setup-steps.babysitter.generated.yml');
+  const contents = renderCloudAgentSetupWorkflow(packageRoot);
+
+  fs.mkdirSync(workflowsDir, { recursive: true });
+
+  if (!fs.existsSync(workflowPath)) {
+    writeFileIfChanged(workflowPath, contents);
+    fs.rmSync(examplePath, { force: true });
+    return { workflowPath, examplePath: null, managed: true, needsManualMerge: false };
+  }
+
+  const existing = fs.readFileSync(workflowPath, 'utf8');
+  if (existing.includes('copilot-setup-steps') && existing.includes('@a5c-ai/babysitter-sdk')) {
+    writeFileIfChanged(workflowPath, contents);
+    fs.rmSync(examplePath, { force: true });
+    return { workflowPath, examplePath: null, managed: true, needsManualMerge: false };
+  }
+
+  writeFileIfChanged(examplePath, contents);
+  return { workflowPath, examplePath, managed: false, needsManualMerge: true };
+}
+
+function installCloudAgentSurface(packageRoot, workspaceRoot) {
+  const bundleRoot = installCloudAgentBundle(packageRoot, workspaceRoot);
+  const skillDirs = installCloudAgentSkills(packageRoot, workspaceRoot);
+  const instructions = installCloudAgentInstructions(packageRoot, workspaceRoot);
+  const setupWorkflow = installCloudAgentSetupSteps(packageRoot, workspaceRoot);
+  return {
+    bundleRoot,
+    skillDirs,
+    ...instructions,
+    setupWorkflow,
+  };
+}
+
 function resolveBabysitterCommand(packageRoot) {
   if (process.env.BABYSITTER_SDK_CLI) {
     return {
@@ -442,6 +692,7 @@ module.exports = {
   getHomeMarketplacePath,
   getHomePluginRoot,
   installCopilotSurface,
+  installCloudAgentSurface,
   registerCopilotPlugin,
   removeLegacyHooks,
   removeMarketplaceEntry,