[refactor][#735] YAML-driven pipeline refactoring for planner by Tonny-Gu · Pull Request #15 · Tonny-Gu/agentize

Tonny-Gu · 2026-02-01T19:16:46Z

Summary

Refactored the multi-agent planning pipeline to use external YAML descriptors instead of hardcoded stage logic. This enables flexible workflow configuration for both Ultra-Planner (4-agent) and Mega-Planner (5-agent dual-proposer) pipelines from the same codebase.

Changes

Created src/cli/planner/pipelines/ultra.yaml - Ultra-Planner (4-agent) pipeline descriptor
Created src/cli/planner/pipelines/mega.yaml - Mega-Planner (5-agent dual-proposer) pipeline descriptor
Created src/cli/planner/pipelines/README.md - Documentation for pipeline YAML structure
Modified src/cli/planner/pipeline.sh:
- Added _planner_exec_agent function encapsulating render-acw-check pattern
- Added _planner_load_pipeline function for parsing YAML via inline Python heredoc
- Added _planner_exec_pipeline function for generic stage execution with parallel support
- Extended _planner_render_prompt to accept variadic context files
- Refactored _planner_run_pipeline to use generic executor with pipeline-type parameter
- Added early validation for empty agent_md paths in YAML parser
Updated src/cli/planner/pipeline.md - Documented new and updated function signatures
Modified tests/cli/test-lol-plan-pipeline-stubbed.sh - Added YAML validation test
Created tests/cli/test-planner-render-prompt-multi.sh - Test for variadic context file handling

Testing

All 54 shell tests passed (make test-fast)
New test test-planner-render-prompt-multi.sh verifies:
- Multiple context files are correctly appended to prompts
- Headers "Previous Stage Output" and "Additional Context (N)" are properly generated
Updated test test-lol-plan-pipeline-stubbed.sh verifies:
- Pipeline YAML files exist and are structurally valid
- Backend override from .agentize.local.yaml still applies
- All stage artifacts are generated correctly

Related Issue

Closes Synthesys-Lab#735

src/cli/planner/pipeline.sh: Refactor multi-agent pipeline to use external YAML descriptors - Add _planner_exec_agent for encapsulating render-acw-check pattern - Add _planner_load_pipeline for parsing YAML via inline Python heredoc - Add _planner_exec_pipeline for generic stage execution with parallel support - Extend _planner_render_prompt to accept variadic context files - Refactor _planner_run_pipeline to use generic executor with pipeline-type parameter src/cli/planner/pipelines/ultra.yaml: Ultra-Planner (4-agent) pipeline descriptor src/cli/planner/pipelines/mega.yaml: Mega-Planner (5-agent dual-proposer) pipeline descriptor src/cli/planner/pipelines/README.md: Document pipeline descriptor structure tests/cli/test-planner-render-prompt-multi.sh: Test for variadic context file handling tests/cli/test-lol-plan-pipeline-stubbed.sh: Add YAML validation test Implements issue Synthesys-Lab#735 (YAML-Driven Pipeline Refactoring). Tests: 54/54 shell tests passed.

src/cli/planner/pipeline.md: Document new and updated functions - Add _planner_exec_agent, _planner_load_pipeline, _planner_exec_pipeline - Update _planner_render_prompt signature for variadic context files - Update _planner_run_pipeline with pipeline-type parameter src/cli/planner/pipeline.sh: Add early validation for empty agent_md paths in YAML parser

Copilot

Pull request overview

This pull request refactors the multi-agent planning pipeline to use external YAML descriptors instead of hardcoded stage logic. The refactoring enables flexible workflow configuration for both Ultra-Planner (4-agent) and Mega-Planner (6-agent dual-proposer) pipelines from the same codebase.

Changes:

Introduced YAML-driven pipeline configuration with ultra.yaml and mega.yaml descriptors
Refactored shell functions to support variadic context files and generic pipeline execution
Added comprehensive documentation and tests for the new architecture

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`src/cli/planner/pipelines/ultra.yaml`	Defines 4-agent Ultra-Planner pipeline configuration
`src/cli/planner/pipelines/mega.yaml`	Defines 6-agent Mega-Planner dual-proposer pipeline configuration
`src/cli/planner/pipelines/README.md`	Documents pipeline YAML structure and usage patterns
`src/cli/planner/pipeline.sh`	Refactors pipeline orchestration with generic YAML-driven execution
`src/cli/planner/pipeline.md`	Updates function documentation to reflect new signatures and behavior
`tests/cli/test-planner-render-prompt-multi.sh`	Tests variadic context file handling in prompt rendering
`tests/cli/test-lol-plan-pipeline-stubbed.sh`	Adds YAML descriptor validation tests

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-01T19:24:46Z

src/cli/planner/pipelines/README.md

+## Files
+
+- `ultra.yaml` - Ultra-Planner (4-agent single-proposer debate)
+- `mega.yaml` - Mega-Planner (5-agent dual-proposer debate)


The description says "Mega-Planner (5-agent dual-proposer debate)" but the mega pipeline actually has 6 agents. This should say "6-agent" to match the actual agent count.

Suggested change

- `mega.yaml` - Mega-Planner (5-agent dual-proposer debate)

- `mega.yaml` - Mega-Planner (6-agent dual-proposer debate)

Copilot · 2026-02-01T19:24:46Z

src/cli/planner/pipeline.md

 - `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).


The description says "5-agent dual-proposer" but the mega pipeline actually has 6 agents. This should say "6-agent" to be accurate.

Suggested change

- `pipeline-type`: Pipeline descriptor to use; `"ultra"` (default, 4-agent) or `"mega"` (5-agent dual-proposer).

- `pipeline-type`: Pipeline descriptor to use; `"ultra"` (default, 4-agent) or `"mega"` (6-agent dual-proposer).

Copilot · 2026-02-01T19:24:46Z

src/cli/planner/pipeline.sh

-    local bold_backend="${planner_bold:-$default_bold}"
-    local critique_backend="${planner_critique:-$default_critique}"
-    local reducer_backend="${planner_reducer:-$default_reducer}"



The refactored code only validates the global backend but doesn't validate agent-specific backend overrides from the configuration. Previously, each agent backend (understander, bold, critique, reducer) was individually validated. Consider adding validation for the backend_overrides entries to catch configuration errors early rather than at runtime when acw is invoked.

Suggested change

# Validate backend overrides if any are set

if [ -n "$backend_overrides" ]; then

while IFS='=' read -r override_key override_value; do

# Skip empty lines or keys

[ -z "$override_key" ] && continue

if ! _planner_validate_backend "$override_value" "planner.${override_key}"; then

return 1

fi

done <<< "$backend_overrides"

fi

Copilot · 2026-02-01T19:24:47Z

src/cli/planner/pipeline.sh

+    local -a consensus_inputs=("$bold_output" "$critique_output" "$reducer_output")
+
+    if [ "$pipeline_type" = "mega" ]; then
+        local paranoia_output="${prefix}-paranoia.txt"
+        local code_reducer_output="${prefix}-code-reducer.txt"
+        consensus_inputs=("$bold_output" "$paranoia_output" "$critique_output" "$reducer_output" "$code_reducer_output")


The mega pipeline will fail at runtime because the consensus script only accepts exactly 3 report paths, but this code passes 5 inputs. The consensus script at .claude-plugin/skills/external-consensus/scripts/external-consensus.sh has a hardcoded validation if [ $# -ne 3 ] and expects exactly 3 reports to combine. The mega pipeline needs either: (1) the consensus script to be updated to accept a variable number of reports, or (2) a different consensus integration approach for the mega pipeline.

Suggested change

local -a consensus_inputs=("$bold_output" "$critique_output" "$reducer_output")

if [ "$pipeline_type" = "mega" ]; then

local paranoia_output="${prefix}-paranoia.txt"

local code_reducer_output="${prefix}-code-reducer.txt"

consensus_inputs=("$bold_output" "$paranoia_output" "$critique_output" "$reducer_output" "$code_reducer_output")

# external-consensus.sh currently expects exactly 3 report paths

local -a consensus_inputs=("$bold_output" "$critique_output" "$reducer_output")

if [ "$pipeline_type" = "mega" ]; then

local paranoia_output="${prefix}-paranoia.txt"

local code_reducer_output="${prefix}-code-reducer.txt"

# NOTE: paranoia_output and code_reducer_output are generated for mega,

# but we only pass 3 inputs to the external consensus script to match

# its current interface (it requires exactly 3 arguments).

consensus_inputs=("$bold_output" "$critique_output" "$reducer_output")

Copilot · 2026-02-01T19:24:47Z

src/cli/planner/pipeline.sh

+        agent_md = agent.get("agent_md", "")
+        if not agent_md:
+            print(f"Error: Agent '{name}' missing agent_md path", file=sys.stderr)
+            sys.exit(1)


The YAML parser validates that agent_md is not empty, but doesn't verify that the referenced agent markdown files actually exist. This means errors won't be caught until runtime during prompt rendering. Consider adding file existence validation in the Python YAML parser to fail fast with a clear error message during pipeline loading rather than during execution.

Suggested change

sys.exit(1)

sys.exit(1)

# Validate that the agent_md file actually exists. Interpret relative

# paths as relative to the YAML configuration file.

from pathlib import Path # pathlib is already used elsewhere; this is safe in Python

md_path = Path(agent_md)

if not md_path.is_absolute():

md_path = (Path(yaml_path).parent / md_path).resolve()

if not md_path.is_file():

print(

f"Error: Agent '{name}' agent_md file not found: {md_path}",

file=sys.stderr,

)

sys.exit(1)

Copilot · 2026-02-01T19:24:47Z

src/cli/planner/pipelines/mega.yaml

+# Mega-Planner pipeline (5-agent dual-proposer debate)
+name: mega
+description: Dual-proposer debate with understander, bold, paranoia, critique, reducer, code-reducer


The description says "5-agent dual-proposer debate" but the pipeline actually has 6 agents (understander, bold, paranoia, critique, reducer, code-reducer). The description should say "6-agent" to be accurate.

Suggested change

# Mega-Planner pipeline (5-agent dual-proposer debate)

name: mega

description: Dual-proposer debate with understander, bold, paranoia, critique, reducer, code-reducer

# Mega-Planner pipeline (6-agent dual-proposer debate)

name: mega

description: 6-agent dual-proposer debate with understander, bold, paranoia, critique, reducer, code-reducer

Tonny-Gu added 2 commits February 1, 2026 21:54

Copilot AI review requested due to automatic review settings February 1, 2026 19:16

Tonny-Gu added the agentize:pr PR created by agentize workflow label Feb 1, 2026

Copilot started reviewing on behalf of Tonny-Gu February 1, 2026 19:17 View session

Copilot AI reviewed Feb 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[refactor][#735] YAML-driven pipeline refactoring for planner#15

[refactor][#735] YAML-driven pipeline refactoring for planner#15
Tonny-Gu wants to merge 2 commits intomainfrom
issue-735

Tonny-Gu commented Feb 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	- `mega.yaml` - Mega-Planner (5-agent dual-proposer debate)
	- `mega.yaml` - Mega-Planner (6-agent dual-proposer debate)

	- `pipeline-type`: Pipeline descriptor to use; `"ultra"` (default, 4-agent) or `"mega"` (5-agent dual-proposer).
	- `pipeline-type`: Pipeline descriptor to use; `"ultra"` (default, 4-agent) or `"mega"` (6-agent dual-proposer).

+    # Validate backend overrides if any are set
+    if [ -n "$backend_overrides" ]; then
+        while IFS='=' read -r override_key override_value; do
+            # Skip empty lines or keys
+            [ -z "$override_key" ] && continue
+            if ! _planner_validate_backend "$override_value" "planner.${override_key}"; then
+                return 1
+            fi
+        done <<< "$backend_overrides"
+    fi

-            sys.exit(1)
+            sys.exit(1)
+        # Validate that the agent_md file actually exists. Interpret relative
+        # paths as relative to the YAML configuration file.
+        from pathlib import Path  # pathlib is already used elsewhere; this is safe in Python
+        md_path = Path(agent_md)
+        if not md_path.is_absolute():
+            md_path = (Path(yaml_path).parent / md_path).resolve()
+        if not md_path.is_file():
+            print(
+                f"Error: Agent '{name}' agent_md file not found: {md_path}",
+                file=sys.stderr,
+            )
+            sys.exit(1)

Conversation

Tonny-Gu commented Feb 1, 2026

Summary

Changes

Testing

Related Issue

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant