@a5c-ai/babysitter-codex 0.1.6-staging.4ebefe91 → 0.1.6-staging.551a5f7a

package/.codex-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "babysitter-codex",
+  "version": "0.1.5",
+  "description": "Babysitter orchestration plugin for Codex with skill entrypoints and lifecycle hooks.",
+  "author": {
+    "name": "a5c.ai",
+    "email": "support@a5c.ai",
+    "url": "https://github.com/a5c-ai/babysitter"
+  },
+  "homepage": "https://github.com/a5c-ai/babysitter/tree/main/plugins/babysitter-codex#readme",
+  "repository": "https://github.com/a5c-ai/babysitter",
+  "license": "MIT",
+  "keywords": [
+    "babysitter",
+    "codex",
+    "orchestration",
+    "hooks",
+    "skills"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "interface": {
+    "displayName": "Babysitter",
+    "shortDescription": "Run Babysitter orchestration flows from Codex",
+    "longDescription": "Babysitter adds orchestration entrypoints such as $call, $plan, and $resume, plus Codex lifecycle hooks that keep runs and workspace state in sync.",
+    "developerName": "a5c.ai",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/a5c-ai/babysitter",
+    "privacyPolicyURL": "https://github.com/a5c-ai/babysitter",
+    "termsOfServiceURL": "https://github.com/a5c-ai/babysitter",
+    "defaultPrompt": [
+      "Use Babysitter to start a new orchestration run",
+      "Plan a Babysitter workflow before executing it",
+      "Resume the latest Babysitter run in this workspace"
+    ],
+    "brandColor": "#0F766E",
+    "screenshots": []
+  }
+}

package/README.md

@@ -2,41 +2,16 @@
 
 Babysitter integration package for OpenAI Codex CLI.
 
-This package is a Codex skill bundle plus installer assets. It is not a native
-Codex plugin manifest and it does not run an external orchestrator. The Codex
-plugin path is:
+This package now ships as a real Codex plugin bundle:
 
-- installed skill bundle under `~/.codex/skills/babysitter-codex`
-- workspace `.codex/hooks.json`
-- workspace `.codex/config.toml`
-- workspace `.a5c/` state
-- Babysitter SDK CLI for run creation, iteration, result posting, and
-  process-library binding
+- `.codex-plugin/plugin.json`
+- `skills/`
+- `hooks.json`
+- `hooks/`
 
-## What This Package Installs
-
-Global install copies the Codex-facing bundle into `CODEX_HOME`:
-
-- `SKILL.md`
-- `.codex/`
-- `agents/`
-- `commands/`
-- `bin/`
-- `scripts/`
-- `babysitter.lock.json`
-
-It does not bundle the process library.
-
-## Integration Model
-
-Babysitter for Codex uses only the hooks model:
-
-- `SessionStart` seeds Babysitter session state
-- `UserPromptSubmit` handles prompt-time transformations
-- `Stop` yields continuation back into the Babysitter orchestration loop
-
-The process library is fetched at workspace-install time through the SDK CLI and
-bound for active use in `.a5c/active/process-library.json`.
+It still uses the Babysitter SDK CLI and the shared `~/.a5c` process-library
+state, but it no longer installs itself by copying fake skill and hook payloads
+into `~/.codex/skills` and `~/.codex/hooks.json`.
 
 ## Installation
 
@@ -46,92 +21,74 @@ Install the SDK CLI first:
 npm install -g @a5c-ai/babysitter-sdk
 ```
 
-Install the Codex package:
+Install the Codex plugin globally:
 
 ```bash
-npm install -g @a5c-ai/babysitter-codex
+npx @a5c-ai/babysitter-codex install
 ```
 
-Then install the Codex plugin payload into the target workspace:
+This copies the plugin into `~/.codex/plugins/babysitter-codex`, registers it
+in `~/.agents/plugins/marketplace.json`, merges the required global Codex
+config into `~/.codex/config.toml`, and ensures the Babysitter process library
+is active in `~/.a5c`.
+
+Install the plugin into a specific workspace:
 
 ```bash
-babysitter harness:install-plugin codex --workspace /path/to/repo
+npx @a5c-ai/babysitter-codex install --workspace /path/to/repo
 ```
 
-If `npm install -g @a5c-ai/babysitter-codex` is run from inside the target
-workspace, `postinstall` will also auto-run the packaged `team-install.js`
-against that workspace.
+This copies the plugin into `<workspace>/plugins/babysitter-codex`, registers
+it in `<workspace>/.agents/plugins/marketplace.json`, merges
+`<workspace>/.codex/config.toml`, and records install metadata under
+`<workspace>/.a5c/team/`.
 
-## What `team-install.js` Does
-
-`scripts/team-install.js` is the workspace installer used by the package and by
-`babysitter harness:install-plugin codex`.
+## Integration Model
 
-It:
+The plugin provides:
 
-1. Resolves the installed package root.
-2. Reads `babysitter.lock.json`.
-3. Clones or updates the upstream Babysitter repo into
-   `<workspace>/.a5c/process-library/babysitter-repo`.
-4. Binds `<workspace>/.a5c/process-library/babysitter-repo/library` with
-   `babysitter process-library:use`.
-5. Writes `<workspace>/.a5c/active/process-library.json`.
-6. Writes or refreshes `<workspace>/.codex/hooks.json`.
-7. Creates or merges `<workspace>/.codex/config.toml` so the workspace has the
-   required Codex settings.
-8. Writes `<workspace>/.a5c/team/install.json`.
-9. Creates `<workspace>/.a5c/team/profile.json` if it does not already exist.
+- `skills/babysit/SKILL.md` as the core entrypoint
+- mode wrapper skills such as `$call`, `$plan`, and `$resume`
+- plugin-level lifecycle hooks for `SessionStart`, `UserPromptSubmit`, and
+  `Stop`
 
-It does not create an external orchestrator, bundle the process library, or
-turn the workspace into a fake Codex plugin manifest.
+The process library is fetched and bound through the SDK CLI in
+`~/.a5c/active/process-library.json`.
 
-## Resulting Workspace Files
+## Workspace Output
 
-After a successful workspace install, the important files are:
+After `install --workspace`, the important files are:
 
-- `.codex/hooks.json`
+- `plugins/babysitter-codex/.codex-plugin/plugin.json`
+- `plugins/babysitter-codex/skills/babysit/SKILL.md`
+- `plugins/babysitter-codex/hooks.json`
+- `.agents/plugins/marketplace.json`
 - `.codex/config.toml`
 - `.a5c/team/install.json`
 - `.a5c/team/profile.json`
-- `.a5c/active/process-library.json`
-- `.a5c/process-library/babysitter-repo/library`
-
-## Using It In Codex
-
-Use normal Codex chat phrases:
-
-```text
-babysitter call implement authentication with tests
-babysitter resume
-babysitter doctor
-babysitter team-install
-babysitter project-install
-```
-
-The Codex skill and hooks own the plugin flow. Low-level SDK commands are still
-the runtime mechanism, but they are not the user-facing interface.
 
 ## Verification
 
-Verify the installed skill bundle:
+Verify the installed plugin bundle:
 
 ```bash
 npm ls -g @a5c-ai/babysitter-codex --depth=0
-ls -1 ~/.codex/skills/babysitter-codex
-test -f ~/.codex/skills/babysitter-codex/scripts/team-install.js
-test -f ~/.codex/skills/babysitter-codex/.codex/hooks/babysitter-stop-hook.sh
+test -f ~/.codex/plugins/babysitter-codex/.codex-plugin/plugin.json
+test -f ~/.codex/plugins/babysitter-codex/hooks.json
+test -f ~/.codex/plugins/babysitter-codex/hooks/babysitter-stop-hook.sh
+test -f ~/.codex/plugins/babysitter-codex/skills/babysit/SKILL.md
+test -f ~/.agents/plugins/marketplace.json
 ```
 
-Verify the active process-library binding for a workspace:
+Verify the active shared process-library binding:
 
 ```bash
-babysitter process-library:active --state-dir /path/to/repo/.a5c --json
+babysitter process-library:active --json
 ```
 
-## Docs
-
-- [commands/README.md](./commands/README.md)
-- Internal orchestration details: [.codex/skills/babysitter/call/SKILL.md](./.codex/skills/babysitter/call/SKILL.md)
+On native Windows, Codex currently does not execute hooks. The plugin still
+installs correctly, but the lifecycle hooks will not fire until Codex enables
+Windows hook execution.
 
 ## License
 

package/SKILL.md

@@ -1,21 +1,24 @@
 ---
-name: babysitter-codex
+name: babysit
 description: >-
-  Run babysitter workflows from Codex using the installed skill bundle,
-  workspace Codex hooks, workspace Codex config, and the Babysitter SDK runtime
-  loop.
-  Use when the user wants to babysit a task, resume a run, diagnose run health,
-  install the Codex skill, or assimilate a methodology for Codex.
+  Run babysitter workflows from Codex using the installed babysit skill bundle,
+  Codex mode-wrapper skills, Codex hooks/config, and the Babysitter SDK runtime
+  loop. Use when the user wants to babysit a task, start or resume a run,
+  diagnose run health, install Codex integration, or assimilate a methodology.
 ---
 
-# Babysitter for Codex CLI
+# babysit
 
 Babysitter on Codex is implemented as:
 
-- the installed skill bundle under `~/.codex/skills/babysitter-codex`
-- workspace `.codex/hooks.json`
-- workspace `.codex/config.toml`
+- the installed plugin under `~/.codex/plugins/babysitter-codex` or `<workspace>/plugins/babysitter-codex`
+- the plugin skill tree under `skills/babysit` and `skills/<mode>`
+- the plugin hook registry at `hooks.json`
+- the plugin hook scripts under `hooks/`
+- global `~/.codex/config.toml`
+- optional workspace `.codex/config.toml`
 - workspace `.a5c/`
+- shared global `.a5c/` process-library state
 - the Babysitter SDK CLI for `run:create`, `run:iterate`, `run:status`,
   `task:list`, `task:post`, and process-library binding
 
@@ -25,79 +28,361 @@ machinery for the Codex integration.
 
 ## Choosing a Mode
 
-Read the matching sub-skill from `.codex/skills/babysitter/<mode>/SKILL.md`.
-If the user intent is unclear, default to `call/SKILL.md`.
+Use this skill whenever it is invoked directly, and whenever one of the
+installed mode-wrapper skills such as `$call`, `$plan`, `$resume`, or `$yolo`
+loads it.
+
+Choose the mode from either:
+
+1. the direct user intent when the skill is invoked as `$babysit`
+2. the installed wrapper skill name when the user invoked `$call`, `$plan`,
+   `$resume`, `$yolo`, and the rest
 
 | User intent | Mode |
 |-------------|------|
 | Start an orchestration run | `call` |
+| Work an issue-centric flow | `issue` |
 | Run autonomously | `yolo` |
+| Run continuously / recurring workflow | `forever` |
 | Resume an existing run | `resume` |
 | Plan without executing | `plan` |
+| Observe or inspect a run | `observe` |
+| Summarize a completed run | `retrospect` |
 | Diagnose run health | `doctor` |
+| Change or inspect model routing | `model` |
 | Help and documentation | `help` |
 | Install into a project | `project-install` |
 | Install user profile/setup | `user-install` |
 | Install team-pinned setup | `team-install` |
 | Assimilate external methodology | `assimilate` |
 
-## Runtime Contract
+Deprecated prompt aliases are not the Codex command surface anymore. Do not
+depend on `.codex/prompts` for normal operation.
+
+## Dependencies
+
+### Babysitter SDK and CLI
+
+Use the installed CLI alias:
+
+```bash
+CLI="babysitter"
+```
+
+If it is not available on the path, use:
+
+```bash
+CLI="npx -y @a5c-ai/babysitter-sdk"
+```
+
+### jq
+
+Make sure `jq` is available in the path. Install it if missing.
+
+## Core Iteration Workflow
+
+The Babysitter workflow has 8 steps:
+
+1. **Create or find the process** - interview the user or parse the prompt,
+   research the repo and process library, and build a process definition
+2. **Create run and bind session** - create the run via the Babysitter CLI and
+   bind it to the current Codex session honestly
+3. **Run iteration** - execute one orchestration step
+4. **Get effects** - inspect pending effects
+5. **Perform effects** - execute the requested tasks through skills, agents, or
+   shell work
+6. **Post results** - commit results back through `task:post`
+7. **Stop and yield** - the Codex stop hook decides whether to continue
+8. **Completion proof** - finish only when the emitted proof is returned
+
+### 1. Create or find the process for the run
+
+#### Interview phase
+
+##### Interactive mode (default)
+
+Interview the user for intent, requirements, goals, scope, and constraints
+before entering the hook-driven loop.
+
+This phase should be iterative and adaptive:
+
+- inspect the current repo state first
+- resolve the active process-library root with
+  `babysitter process-library:active --json`
+- conduct an actual search against that active process library before writing a
+  process
+- research the repo, online references, methodologies, specializations, skills,
+  agents, and related processes as needed
+- ask the user follow-up questions when the intent or constraints are still not
+  clear
+
+Do not plan more than one step ahead during the interview phase. After each
+step, decide the next best step from the current evidence.
+
+The `process-library:active` command bootstraps the shared global SDK process
+library automatically if no binding exists yet. Read:
+
+- `binding.dir` as the active process-library root that must be searched
+- `defaultSpec.cloneDir` as the cloned repo root when adjacent repo-level
+  material is needed
+
+After that, treat `specializations/**/**/**`, `methodologies/`, `contrib/`, and
+`reference/` as paths relative to `binding.dir`.
+
+##### Non-interactive mode
+
+When running non-interactively:
+
+1. parse the initial prompt to extract intent, scope, and constraints
+2. inspect the repo structure
+3. resolve the active process-library root with
+   `babysitter process-library:active --json`
+4. search that active library for the most relevant specialization,
+   methodology, process, skill, or agent
+5. proceed directly to process creation
+
+Do not skip the active-library search step.
+
+#### User Profile Integration
+
+Before building the process, check for an existing user profile:
+
+1. run `babysitter profile:read --user --json`
+2. use the profile to pre-fill user preferences, expertise, and communication
+   style
+3. calibrate breakpoint density from `breakpointTolerance`
+4. prefer tools, skills, and agents the user already uses
+5. adapt explanations and breakpoint text to the user's communication style
+6. if no profile exists, proceed normally and consider suggesting `$user-install`
+
+All profile read/write/merge/render operations must go through the Babysitter
+CLI, never direct SDK imports.
+
+#### Process creation phase
+
+After the interview phase, create the full custom process files for the run
+according to the process-library patterns and the process-creation guidelines
+below.
+
+Install `@a5c-ai/babysitter-sdk` into `.a5c/` if it is missing. When doing so,
+run the install from the project root and use either `npm i --prefix .a5c ...`
+or a subshell so the working directory does not stay inside `.a5c/`.
+
+Always use an **absolute path** for `--entry` when calling `run:create`.
+
+After the process is created and before creating the run:
+
+- in interactive mode, describe the process at a high level, generate
+  `[process-name].diagram.md` and `[process-name].process.md`, and get user
+  confirmation before proceeding
+- in non-interactive mode, proceed directly to `run:create`
+
+Common mistakes to avoid:
+
+- wrong: skipping repo/process-library research before writing the process
+- wrong: bypassing the orchestration model with helper scripts or inline logic
+- wrong: using `kind: 'node'` in generated tasks
+- correct: use `agent` or `skill` tasks for reasoning work, with `shell` only
+  for existing CLIs, tests, linters, git, or builds
+- correct: include verification loops, refinement loops, quality gates, and
+  breakpoints where appropriate
 
-Use the Babysitter SDK CLI for orchestration:
+### 2. Create run and bind session
+
+For new runs:
+
+```bash
+$CLI run:create \
+  --process-id <id> \
+  --entry <absolute-path>#<export> \
+  --inputs <file> \
+  --prompt "$PROMPT" \
+  --harness codex \
+  --state-dir .a5c \
+  --plugin-root "${CODEX_PLUGIN_ROOT}" \
+  --json
+```
+
+Required flags:
+
+- `--process-id <id>` - unique identifier for the process definition
+- `--entry <absolute-path>#<export>` - process JS file plus named export
+- `--prompt "$PROMPT"` - the user's initial request
+- `--harness codex` - activates Codex session binding
+- `--state-dir .a5c` - required for honest workspace-local Codex session state
+- `--plugin-root "${CODEX_PLUGIN_ROOT}"` - plugin root used for session/state
+  resolution
+
+Optional flags:
+
+- `--inputs <file>` - process input JSON
+- `--run-id <id>` - override the generated run id
+- `--runs-dir <dir>` - override the default runs directory
+
+Inside a real Codex hook/session environment, do **not** pass `--session-id`
+explicitly. The Codex adapter auto-resolves the session/thread id from
+`CODEX_THREAD_ID`, `CODEX_SESSION_ID`, or `CODEX_ENV_FILE`. Only pass
+`--session-id` in out-of-band recovery flows where no ambient Codex session
+identity exists.
+
+In normal Codex usage, `run:create` must bind the session into the active
+workspace `.a5c`, not the global `~/.a5c`, so the Stop hook can find the same
+session state file in later turns.
+
+For resuming existing runs in a manual recovery flow:
 
 ```bash
-babysitter run:create   --process-id <id> --entry <path>#<export> ...
-babysitter run:iterate  <runDir> --json --iteration <n>
-babysitter run:status   <runDir> --json
-babysitter task:list    <runDir> --pending --json
-babysitter task:post    <runDir> <effectId> --status ok --value <file> --json
+$CLI session:resume \
+  --session-id <id> \
+  --state-dir .a5c \
+  --run-id <runId> \
+  --runs-dir .a5c/runs \
+  --json
 ```
 
-When a Codex session ID is available, bind it honestly:
+### 3. Run iteration
 
 ```bash
-babysitter run:create ... --harness codex --session-id <id> --state-dir .a5c --json
+$CLI run:iterate .a5c/runs/<runId> --json --iteration <n> --plugin-root "${CODEX_PLUGIN_ROOT}"
 ```
 
-## Result Posting Protocol
+Status values:
+
+- `"executed"` - tasks executed, continue looping
+- `"waiting"` - breakpoint or sleep is pending
+- `"completed"` - run finished successfully
+- `"failed"` - run failed
+- `"none"` - no runnable effects exist
+
+### 4. Get effects
+
+```bash
+$CLI task:list .a5c/runs/<runId> --pending --json
+```
+
+### 5. Perform effects
+
+Run the effect externally to the SDK, then post the outcome summary with
+`task:post`.
+
+Important:
+
+- delegate using Codex skills or agent tooling when possible
+- make sure the requested change actually happened
+- do not describe or imply success without verifying the requested effect
+- do not use the `babysit` skill itself inside delegated task execution
+
+#### 5.1 Breakpoint handling
+
+##### Interactive mode
 
-1. Write the result value to `tasks/<effectId>/output.json`
-2. Post it with `babysitter task:post`
-3. Never write `result.json` directly
+Ask the user explicitly for approval. If the Codex environment provides a
+structured question UI, include explicit approve/reject options. If not, ask in
+chat and require an explicit approval response.
+
+Never infer approval from silence, ambiguity, or dismissal.
+
+Breakpoint rejections must still be posted with `--status ok` and a value such
+as `{"approved": false, "response": "..."}`.
+
+##### Non-interactive mode
+
+Choose the best option from context and post the result. Rejections still use
+`--status ok` with `{"approved": false}`.
+
+### 6. Results posting
+
+Never write `result.json` directly.
+
+Workflow:
+
+1. write the result value to `tasks/<effectId>/output.json`
+2. call `task:post` with `--value tasks/<effectId>/output.json`
+3. let the SDK write `result.json`, append the journal event, and update state
+
+### 7. Stop after every phase after run-session association
+
+After `run:create` or any posted effect result, end the current assistant turn
+and yield back to the Codex hook loop. Do not run multiple `run:iterate` steps
+in the same turn.
+
+### 8. Completion proof
+
+When `run:iterate` or `run:status` returns `completionProof`, return that exact
+value wrapped in `<promise>...</promise>`.
 
 ## Hook Loop
 
-Workspace onboarding must install `.codex/hooks.json` and `.codex/config.toml`
-so:
+Global install must register the plugin in `~/.agents/plugins/marketplace.json`
+with the plugin bundle at `~/.codex/plugins/babysitter-codex`, and must merge
+`~/.codex/config.toml`.
+
+Workspace onboarding may also register the plugin in
+`<workspace>/.agents/plugins/marketplace.json` with the plugin bundle at
+`<workspace>/plugins/babysitter-codex`, and may merge `.codex/config.toml` for
+repo-local pinning.
+
+Both levels must provide:
 
 1. `SessionStart` seeds `.a5c` session state
 2. `UserPromptSubmit` performs prompt-time transformations when needed
 3. `Stop` decides whether the run is complete or Codex should receive the next
    Babysitter iteration context
 
-## Process Library Model
+## Task Kinds
 
-The Codex package does not bundle the process library.
+Never generate `kind: 'node'` effects.
 
-Workspace onboarding must:
+| Kind | When to use |
+|------|-------------|
+| `agent` | default for planning, implementation, analysis, debugging, scoring, research |
+| `skill` | when a matching installed skill exists |
+| `shell` | existing CLI tools, tests, git, linters, builds |
+| `breakpoint` | human approval gates |
+| `sleep` | time gates |
 
-1. clone or update the upstream Babysitter repo into
-   `.a5c/process-library/babysitter-repo`
-2. bind `.a5c/process-library/babysitter-repo/library` with
-   `babysitter process-library:use`
-3. resolve the active binding later with
-   `babysitter process-library:active --state-dir .a5c --json`
+## Process Creation Guidelines
 
-Preferred discovery order:
+- always research the repo and the active process library before writing the
+  process
+- prefer composing multiple relevant library processes rather than copying just
+  one template blindly
+- include verification and refinement loops
+- prefer processes that close the widest practical quality loop
+- add `@skill` and `@agent` discovery markers to generated process files for
+  the dependencies you actually selected
+- prefer incremental work that can be tested as you go
 
-1. project-local `.a5c/processes`
-2. the active SDK-managed process-library binding
+Search for relevant processes, skills, agents, methodologies, and references
+in:
+
+1. `.a5c/processes/`
+2. the active process-library root from `binding.dir`
+3. the cloned repo root from `defaultSpec.cloneDir` when adjacent material is
+   needed
 
 ## Codex-Specific Rules
 
-- Prefer natural-language activation such as `babysitter call ...`
-- Legacy `/babysitter:*` aliases may exist only as optional user-installed
-  prompt sugar; they are not a native Codex plugin feature
-- Never fabricate a session ID when none is available from Codex or the caller
-- Use `notify` only for monitoring and telemetry, never as the orchestration
+- `$babysit` is the core skill
+- `$call`, `$plan`, `$resume`, `$yolo`, and the other mode skills are thin
+  wrappers that must only load `babysit` for the matching mode
+- do not revive prompt aliases as a parallel integration surface
+- do not fabricate a session id
+- use `notify` only for telemetry or monitoring, never as the orchestration
   control loop
+
+## Critical Rules
+
+CRITICAL RULE: The completion proof is emitted only when the run is truly
+completed. Output `<promise>SECRET</promise>` only when the orchestration status
+is completed.
+
+CRITICAL RULE: Never bypass the Babysitter orchestration model when this skill
+is active. Do not replace it with ad-hoc direct execution.
+
+CRITICAL RULE: Never build helper scripts or wrapper programs to drive the run.
+Use the CLI and the hook loop directly.
+
+CRITICAL RULE: In interactive mode, never auto-approve breakpoints.
+
+CRITICAL RULE: Do not use `kind: 'node'` in generated process files.