Advanced Features

These features unlock collaborative, large-scale, and parallel SDD workflows. They build on the core lifecycle — make sure you are familiar with the SDD Workflow before using them.

1. Spec Branching

Tools: branch_spec, merge_spec_branch

Think of spec branches like Git branches — but for your plans. Create an A/B variant to explore a different implementation approach before committing.

When to use:

• Architecture decisions with multiple valid approaches
• UI experiments (redesign spec A vs incremental spec B)
• When a stakeholder requests an alternative estimate

When NOT to use

Do not branch specs for minor wording changes or typo fixes. Branches are for fundamentally different implementation strategies — if both approaches touch the same files, resolve the decision first, then implement.

How it works:

1. Branch an existing spec to create a variant:

"Branch spec SPEC-042 as variant-B with a microservices approach"
→ branch_spec(specId: "SPEC-042", branchName: "variant-b", description: "...")

2. Develop both variants independently. Each branch has its own acceptance criteria and PLAN.md.

3. Compare estimates and choose the winner. Then merge:

"Merge spec branch variant-b into SPEC-042"
→ merge_spec_branch(specId: "SPEC-042", branchName: "variant-b")

Planu detects conflicts between variants and flags criteria that contradict each other before merging.

---

2. Spec Federation

Tools: federate_specs, federation_status

Share and sync specs across multiple repositories. Essential for monorepos, microservices, and platform teams.

When to use:

• Platform team owns shared specs (auth, payments, logging)
• Monorepo with multiple services that share requirements
• API contract specs shared between frontend and backend repos

When NOT to use

Do not federate specs that are tightly coupled to a single service's internals. Federation is for shared contracts — not for replicating implementation details across repos.

How it works:

1. In the source repo, publish a spec to a downstream target:

"Federate spec SPEC-010 to team/payments-service"
→ federate_specs(...)

2. In the target repo, the spec appears read-only with an upstream link. Downstream teams can reference but not modify it directly.

3. Changes sync automatically or on demand. Check the sync state at any time:

"Check federation status"
→ federation_status()

The status report shows which specs are ahead, behind, or in conflict with their upstream source.

---

3. Agent Team Orchestration

Tools: plan_team_distribution, orchestrate_runtime, orchestrate_agents

Distribute a large spec across multiple parallel AI agents, each with exclusive ownership over specific files.

When to use:

• Specs touching 5+ independent modules
• Large refactors with clear file boundaries
• Time-sensitive features that can be parallelized

When NOT to use

Do not orchestrate small specs (under 3 files). The coordination overhead outweighs the time saved. Also avoid orchestration when modules are tightly coupled — agents cannot resolve cross-file conflicts mid-run.

How it works:

1. Plan the distribution — Planu analyzes the spec and proposes agent assignments:

"Plan team distribution for SPEC-099"
→ plan_team_distribution(specId: "SPEC-099")
→ Returns: 3 agents, file assignments, estimated time

2. Launch the orchestration — agents work in parallel, each with its assigned files:

"Orchestrate SPEC-099 with 3 agents"
→ orchestrate_runtime(specId: "SPEC-099", agentCount: 3)
→ Agents work in parallel, Planu monitors progress

3. Monitor and finalize:

"Check orchestration status"
→ orchestrate_agents(action: "status")

Rules Planu enforces:

• Each agent owns exclusive files — no concurrent edits
• Integration tests run after all agents complete
• Conflicts are flagged, not auto-resolved

---

Next Steps

• See the Tools Reference for full parameter documentation
• Return to the SDD Workflow for the core lifecycle