diff --git a/README.md b/README.md index ac51439c..81cc626d 100644 --- a/README.md +++ b/README.md @@ -67,11 +67,15 @@ codex plugin marketplace add ericlitman/open-pstack --ref main codex plugin add pstack@open-pstack ``` -Turn on Codex subagents in `~/.codex/config.toml` so pstack can compare work in parallel: +Enable native Codex subagents in `~/.codex/config.toml` so pstack can compare work in parallel: ```toml -[features] -multi_agent = true +[features.multi_agent_v2] +enabled = true + +# Optional: enable the task plan tool +[tools.update_plan] +enabled = true ``` Start a new Codex task after installation so it can discover the new skills and setting. diff --git a/docs/reference.md b/docs/reference.md index a6af5699..9c64a106 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -33,11 +33,11 @@ codex plugin marketplace add ericlitman/open-pstack --ref main codex plugin add pstack@open-pstack ``` -Codex discovers the plugin skills under the `pstack` namespace, so they list as `pstack:poteto-mode`, `pstack:tdd`, and so on. The namespace comes from `plugins/pstack/.codex-plugin/plugin.json`. To enable the multi-model and parallel-subagent skills (`interrogate`, `arena`, `how`, `why`, `reflect`, `architect`), turn on subagents in `~/.codex/config.toml`: +Codex discovers the plugin skills under the `pstack` namespace, so they list as `pstack:poteto-mode`, `pstack:tdd`, and so on. The namespace comes from `plugins/pstack/.codex-plugin/plugin.json`. To enable native subagents for parallel skills (`interrogate`, `arena`, `how`, `why`, `reflect`, `architect`), turn on multi-agent V2 in `~/.codex/config.toml`: ```toml -[features] -multi_agent = true +[features.multi_agent_v2] +enabled = true ``` For local plugin development, you can clone the repository and link its skills directly: @@ -86,7 +86,7 @@ The Codex build shares one `skills/` tree with the Claude Code build. Nothing is - **Skill invocation.** Codex loads `SKILL.md` natively. There is no `Skill` tool. You invoke a skill by name (ask for it, or pick `pstack:poteto-mode` from the list). - **Package surface.** The native `skills/` tree is the only workflow source. The plugin ships no `commands/` layer and does not link prompts into `~/.codex/prompts/`. Codex would migrate such files into duplicate source-command skills while loading the native skill tree. The 24 `principle-*` leaves declare `user-invocable: false`. Claude keeps them out of its user picker; Codex 0.149.0 currently shows them despite that metadata ([#8](https://github.com/ericlitman/open-pstack/issues/8)). - **Tool and built-in mapping.** Claude tool names and built-in skills resolve through [`codex-tools.md`](../plugins/pstack/skills/poteto-mode/references/codex-tools.md). Model execution resolves separately through [`provider-dispatch.md`](../plugins/pstack/skills/poteto-mode/references/provider-dispatch.md), so Codex models stay native while other providers run through the external runner. -- **Subagents.** The `Agent` tool maps to Codex `spawn_agent` / `wait_agent`, enabled by `multi_agent = true`. Parallel fan-out is multiple `spawn_agent` calls in one turn. If the native Codex lane is unavailable, record that lane as a dropout; the configured external lanes still run, and no provider is silently substituted. There is no `poteto-agent` subagent type on Codex; route ad-hoc subagents by dispatching a `spawn_agent` told to read `poteto-mode` first. +- **Subagents.** The `Agent` tool maps to Codex `spawn_agent` / `wait_agent`. Enable `multi_agent_v2` as shown above and check that the current tool surface exposes `spawn_agent`. Parallel fan-out is multiple `spawn_agent` calls in one turn. If the native Codex lane is unavailable, record that lane as a dropout; the configured external lanes still run, and no provider is silently substituted. There is no `poteto-agent` subagent type on Codex; route ad-hoc subagents by dispatching a `spawn_agent` told to read `poteto-mode` first. - **Auto-fire.** The `hooks/` SessionStart injection is Claude Code-only; Codex has no plugin hook runtime. Enter `pstack:poteto-mode` by name, or add a standing instruction to `~/.codex/AGENTS.md` if you want the same always-on routing. - **Models.** `/setup-pstack` writes provider-qualified descriptors and asks one requested effort per assigned family (`low`, `medium`, `high`, `xhigh`, `max`, and `ultra` where the model's CLI lists it, today Sol and Astra). The first-run sheet is the model catalog's [role defaults](../plugins/pstack/skills/poteto-mode/references/model-catalog.md#role-defaults), with a panel of Opus, Sol, and Grok; Fable, Sonnet, Luna, Astra, Haiku 5.5 and an exact Opus pin stay selectable. Fable, Opus and Sonnet use Claude's rolling aliases; a registered exact pin keeps its own model. Runtime dispatch normalizes older versioned descriptors in memory, so an installed sheet stops pinning immediately. A setup rerun persists that migration while keeping each role's family and effort. In Codex, Codex families such as Sol use native `spawn_agent`; every other provider uses the deterministic external runner. In Claude Code, Claude families use native agents; every other provider uses the runner. In Grok, `inherit-parent` and `auto` use `spawn_subagent`; every explicit descriptor, including Grok's, uses the runner with `--parent grok`. A Codex writer that the runner launches stays in Codex's `workspace-write` sandbox unless the sheet opts in with the line `codex writer sandbox: full-access`, which setup asks about once. Full access lets the writer launch a browser and write dot-folders such as `.agents/`, and removes every sandbox limit. A provider whose writes no sandbox confines, such as OpenCode, Cursor or Muse, writes only when the sheet holds ` writer sandbox: full-access`, which setup asks about when a writer role uses that provider. Children never detect the parent or reroute themselves. The `bug-fix`, `perf-issue`, and `hillclimb` roles stay on Sol instead of upstream's Grok default. diff --git a/plugins/pstack/skills/poteto-help/SKILL.md b/plugins/pstack/skills/poteto-help/SKILL.md index d2c3d0a6..870f7ee4 100644 --- a/plugins/pstack/skills/poteto-help/SKILL.md +++ b/plugins/pstack/skills/poteto-help/SKILL.md @@ -35,7 +35,7 @@ When the model rule is missing and it matters, ask whether the user wants to pic ## Get set up -1. Install. In Claude Code, run `/plugin marketplace add ericlitman/open-pstack`, then `/plugin install pstack@open-pstack`, then `/reload-plugins`. In Codex, run `codex plugin marketplace add ericlitman/open-pstack --ref main`, then `codex plugin add pstack@open-pstack`, and turn on `multi_agent` per [`codex-tools.md`](../poteto-mode/references/codex-tools.md). +1. Install. In Claude Code, run `/plugin marketplace add ericlitman/open-pstack`, then `/plugin install pstack@open-pstack`, then `/reload-plugins`. In Codex, run `codex plugin marketplace add ericlitman/open-pstack --ref main`, then `codex plugin add pstack@open-pstack`, and turn on `multi_agent_v2` per [`codex-tools.md`](../poteto-mode/references/codex-tools.md). 2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It maps a model to each role, asks one requested effort for each model family it assigns, probes those models, and writes a model sheet. A rerun that keeps a valid sheet and names no change asks none of these questions: it keeps the sheet's roles and efforts, probes them, and writes when every probe passes. The sheet applies to new sessions. Then it offers once each to generate a verification skill and a formal verification skill for the project, unless the project already has one. On a rerun that keeps the sheet, it mentions each offer in one line instead of asking. 3. Start a real task with `/poteto-mode`, a goal, and a check that can pass or fail. diff --git a/plugins/pstack/skills/poteto-mode/references/codex-tools.md b/plugins/pstack/skills/poteto-mode/references/codex-tools.md index 2494d4bf..53282724 100644 --- a/plugins/pstack/skills/poteto-mode/references/codex-tools.md +++ b/plugins/pstack/skills/poteto-mode/references/codex-tools.md @@ -65,18 +65,19 @@ The copy registers under its plain name beside the plugin's `pstack:`, an | Dispatch a subagent (the `Agent`/`Task` tool) | `spawn_agent` | `spawn_subagent` with `subagent_type: pstack:poteto-agent` | | Dispatch N parallel subagents in one turn | N `spawn_agent` calls in one response | N `spawn_subagent` calls in one response | | Wait for a subagent result | `wait_agent` | `get_command_or_subagent_output`, as [Waits on Grok](#waits-on-grok) says | -| Free a finished subagent slot | `close_agent` | None | -| Track tasks (the todolist / `TodoWrite`) | `update_plan` | `todo_write` | -| Ask the human a fixed-choice question (`AskUserQuestion`) | Ask in plain text and let the user answer. Codex has no structured-choice tool. | `ask_user_question` | +| Track tasks (the todolist / `TodoWrite`) | Use `update_plan` when exposed; otherwise keep a short checklist in the conversation. | `todo_write` | +| Ask the human a fixed-choice question (`AskUserQuestion`) | Use a structured question tool when exposed; otherwise ask in plain text. | `ask_user_question` | -Subagent dispatch needs `multi_agent` enabled. Add to `/config.toml`, using Codex's [config-home rule](#harness-config-homes): +For predictable native subagent dispatch, enable stable multi-agent V2 in `/config.toml`, using Codex's [config-home rule](#harness-config-homes): ```toml -[features] -multi_agent = true +[features.multi_agent_v2] +enabled = true ``` -Without it, the native Codex lane is a named dropout. Independent external lanes still run, and the parent records the reduced provider count. Never collapse a panel into a sequential single-model pass. +For larger panels, set `max_concurrent_threads_per_session` in the V2 table. The limit includes the root thread. Start a new Codex task after changing the setting. + +Check that the current Codex tool surface exposes `spawn_agent` before a native lane. If it does not, the native lane is a named dropout. Independent external lanes still run, and the parent records the reduced provider count. Never collapse a panel into a sequential single-model pass. ## Subagent policy