diff --git a/src/cli/planner/pipeline.md b/src/cli/planner/pipeline.md index b5f1cf9a..1eb1e470 100644 --- a/src/cli/planner/pipeline.md +++ b/src/cli/planner/pipeline.md @@ -5,19 +5,21 @@ Multi-agent planning pipeline orchestration for the CLI planner. This module is ## External Interface -### _planner_run_pipeline "" [issue-mode] [verbose] [refine-issue-number] -Runs the full multi-stage planning pipeline (understander -> bold-proposer -> critique/reducer in parallel -> external consensus). +### _planner_run_pipeline "" [issue-mode] [verbose] [refine-issue-number] [pipeline-type] +Runs the full multi-stage planning pipeline driven by a YAML descriptor, followed by external consensus synthesis. **Parameters**: - `feature-description`: Request text or issue body used to build the prompts. - `issue-mode`: `"true"` to create/publish to a GitHub issue when possible; `"false"` for timestamp-only artifacts. - `verbose`: `"true"` to print detailed progress messages to stderr. - `refine-issue-number`: Optional issue number to refine an existing plan; fetches the issue body and appends refinement focus. +- `pipeline-type`: Pipeline descriptor to use; `"ultra"` (default, 4-agent) or `"mega"` (5-agent dual-proposer). **Behavior**: +- Loads pipeline descriptor from `src/cli/planner/pipelines/{pipeline-type}.yaml`. - Creates stage artifacts under `.tmp/` using an issue-based or timestamp prefix. - Loads planner backends from `.agentize.local.yaml` (planner.* keys) when present. -- Runs agent stages via `acw`, then synthesizes a consensus plan via the external-consensus skill. +- Executes stages via `_planner_exec_pipeline`, then synthesizes a consensus plan via the external-consensus skill. - Publishes the plan to the issue when `issue-mode` is true and an issue number is available. **Output**: @@ -26,24 +28,84 @@ Runs the full multi-stage planning pipeline (understander -> bold-proposer -> cr **Exit codes**: - `0`: Success. -- `1`: Configuration or setup failure (repo root/backends). +- `1`: Configuration or setup failure (repo root/backends/pipeline descriptor). - `2`: Pipeline stage failure (prompt render, agent run, or consensus synthesis). -### _planner_render_prompt [context-file] +### _planner_render_prompt [context-file...] Builds a prompt file by concatenating the agent base prompt, optional plan-guideline, the feature request, -and optional context from a previous stage. +and optional context from previous stages (variadic). **Parameters**: - `output-file`: Path to write the rendered prompt. - `agent-md-path`: Repo-relative path to the agent prompt markdown. - `include-plan-guideline`: `"true"` to append the plan-guideline skill content. - `feature-desc`: Feature request text inserted into the prompt. -- `context-file`: Optional path to append prior stage output. +- `context-file...`: Zero or more paths to append prior stage outputs. First file gets header "Previous Stage Output", subsequent files get "Additional Context (N)". **Exit codes**: - `0`: Success. - `1`: Missing repo root or agent prompt file. +### _planner_exec_agent [context-file...] +Executes a single agent stage by rendering the prompt and invoking acw. + +**Parameters**: +- `name`: Agent identifier for error messages. +- `agent-md`: Repo-relative path to agent prompt markdown. +- `backend`: Backend spec in `provider:model` format. +- `tools`: Comma-separated tool list for acw. +- `permission-mode`: Optional permission mode (e.g., `"plan"`). +- `plan-guideline`: `"true"` to include plan-guideline in prompt. +- `input-path`: Path to write rendered prompt. +- `output-path`: Path for agent output. +- `feature-desc`: Feature request text. +- `context-file...`: Variadic context files from prior stages. + +**Exit codes**: +- `0`: Success. +- `2`: Prompt rendering or agent execution failure. + +### _planner_load_pipeline [global-backend] +Parses a YAML pipeline descriptor and emits line-separated stage commands. + +**Parameters**: +- `yaml-path`: Path to pipeline YAML file. +- `backend-overrides`: Newline-delimited `key=value` pairs for agent-specific backends. +- `global-backend`: Optional fallback backend for all agents. + +**Output format**: +``` +STAGE: