Branch Builder

English | Simplified Chinese

Architecture-first virtual task branching for agentic work.

Branch Builder helps an agent stop treating complex work as a flat checklist. It creates a virtual branch graph, routes tools and subagents through scoped branch packets, and merges outputs only after merge contracts pass.

It is packaged in skill format for portability, but it should be treated as a root-task planning layer, not as a repeatedly invoked tool skill. It can run standalone or as the shared planning layer inside Fabric and Agent Shared Fabric. It is not Git branching. It is task architecture.

complex task -> virtual branch graph -> branch packets -> scoped dispatch -> merge contracts -> final synthesis

Recommended Start-up Prompt

Use this as a portable prompt fragment and adapt paths or lifecycle names to your harness:

Use Branch Builder as the planning layer for medium or complex tasks.

Branch Builder is virtual task branching, not Git branching.
After normal harness boot and context loading, initialize or load `.agents/branch-builder/branch_state.yaml`.
Never create Branch Builder state with `touch` or `echo '{}'`; use the Branch Builder init script when state is missing or invalid.
Run Branch Builder state-changing commands serially; do not parallelize init, dispatch preparation, branch resolution, or checkpoints.
Run one root task lifecycle only. Do not run boot, postflight, or the full lifecycle per virtual branch.
If the harness has a shared planning-layer root, check that before declaring Branch Builder unavailable.

Before specialist dispatch, create a branch packet.
Do not use init --force to fix pre_dispatch; prepare a working branch packet instead.
Before root synthesis, validate merge contracts.
Before final response, resolve working branches as merged, blocked, or pruned.
Final synthesis should use merged branch outputs only.

Report `[BRANCH_BUILDER_ACTIVE]` only after `task_start` returns that `status_marker`.
Report `[BRANCH_BUILDER_REPORT]` only after `final_response` returns that `status_marker`.
Report `[BRANCH_BUILDER_OPEN]` when unresolved working branches remain.
After every successful checkpoint, print a user-visible Branch Builder receipt.
Do not leave the branch map only inside hidden tool output.
The receipt must include status_marker, root objective, current phase, standing branches, working branches, merge queue, pruned branches, and open/unresolved branches when present.

Local checkpoint adapter:

python3 skills/branch-builder/scripts/init_branch_state.py --objective "<current task objective>" --complexity medium
python3 adapters/local/branch_builder_checkpoint.py --checkpoint task_start --emit-summary
python3 skills/branch-builder/scripts/prepare_dispatch.py --name "<dispatch branch>" --scope "<bounded scope>" --expected-output "<expected result>" --capability scripts:"<tool>"
python3 adapters/local/branch_builder_checkpoint.py --checkpoint pre_dispatch --emit-summary
python3 skills/branch-builder/scripts/resolve_branch.py --branch-id B001 --status ready_to_merge --output "<branch result summary>"
python3 adapters/local/branch_builder_checkpoint.py --checkpoint pre_merge --emit-summary
python3 skills/branch-builder/scripts/resolve_branch.py --branch-id B001 --status merged --output "<merged branch result>"
python3 adapters/local/branch_builder_checkpoint.py --checkpoint final_response --emit-summary --emit-delta

Optional Shared Planning-Layer Install

If your harness has a shared skill/protocol root, install Branch Builder once there instead of copying it into every project. The included installer targets Agent Shared Fabric-compatible layouts; other harnesses can copy the same skills/branch-builder package and wire the commands into their own boot/checkpoint system.

python3 adapters/shared_fabric/install_branch_builder_shared_fabric.py \
  --global-root /path/to/global-agent-fabric \
  --update-global-rule \
  --export-antigravity

Then each workspace can use shared scripts while keeping branch state local:

python3 /path/to/global-agent-fabric/skills/generated/branch-builder/scripts/init_branch_state.py \
  --workspace /path/to/workspace \
  --objective "<current task objective>" \
  --complexity medium

Use the shared prepare_dispatch.py, resolve_branch.py, and branch_builder_checkpoint.py for dispatch and closure. Treat the exact command paths below as examples, not requirements. Full sequence: docs/harness_integration.md.

Workspace state stays in:

<workspace>/.agents/branch-builder/branch_state.yaml
<workspace>/.agents/branch-builder/branch_events.ndjson

Example

Task:

Design a research-grade bird-acoustic analysis pipeline that ingests field recordings, detects bird vocalizations, computes ecological indicators, validates model quality, and produces a reproducible report.

Branch Builder turns it into:

flowchart TB
    ROOT["Bird-acoustic pipeline"]
    S1["Intent & constraints"]
    S2["Architecture boundary"]
    S3["Verification"]
    B1["Data ingestion"]
    B2["Model strategy"]
    B3["Ecological indicators"]
    B4["Reporting"]

    ROOT --> S1
    ROOT --> S2
    ROOT --> S3
    ROOT --> B1 --> B2 --> B3 --> B4
    S2 -. guides .-> B1
    S2 -. guides .-> B2
    S2 -. guides .-> B3
    S3 -. validates .-> B3
    S3 -. validates .-> B4

Loading

Each branch has a purpose, allowed capabilities, expected output, and merge contract. Full visual walkthrough: docs/branch_builder_visual_report.md

Run The Demo

bash examples/github_intro/run_test.sh

Expected output:

[1/5] task_start fixture: ok [BRANCH_BUILDER_ACTIVE]
[2/5] pre_dispatch fixture: ok [BRANCH_BUILDER_CHECKPOINT_OK]
[3/5] pre_merge fixture: ok [BRANCH_BUILDER_CHECKPOINT_OK]
[4/5] final_response fixture: ok [BRANCH_BUILDER_REPORT]
[5/5] unresolved final_response guard: ok [BRANCH_BUILDER_OPEN]
Branch Builder GitHub intro test passed.

What Is Included

skills/branch-builder/                         # portable planning-layer package
skills/branch-builder/scripts/                 # validator + checkpoint adapter
adapters/local/                          # project-local adapter
adapters/shared_fabric/                  # optional Agent Shared Fabric-compatible installer
examples/github_intro/                   # runnable proof
docs/                                    # integration and visual reports

Docs

• Harness integration
• Visual branch report
• GitHub intro test
• Branch Builder planning-layer package
• Chinese docs: README.zh-CN.md

Design Boundaries

• Branch Builder is not Git branching.
• Branch Builder is not a workflow runtime.
• Branch Builder is not a traditional repeatedly-invoked skill.
• Branch Builder does not replace runtime boot, phase logging, postflight sync, or memory systems.
• Branch Builder keeps task state local and leaves durable memory write-back to the host harness.

Tags

agentic-workflow llm-agents task-planning virtual-branches skill-routing mcp-ready merge-contracts persistent-artifacts