## Subagent Usage Templates and Orchestration

This helper provides the Management agent with templates to create robust and repeatable `runSubagent` calls.

1) Basic runSubagent Template

```
runSubagent({
  prompt: "<Clear, short instruction for the subagent>",
  description: "<Agent role name - e.g., Backend Dev>",
  metadata: {
    plan_file: "docs/plans/current_spec.md",
    files_to_change: ["..."],
    commands_to_run: ["..."],
    tests_to_run: ["..."],
    timeout_minutes: 60,
    acceptance_criteria: ["All tests pass", "No lint warnings"]
  }
})
```

2) Orchestration Checklist (Management)

- Validate: `plan_file` exists and contains a `Handoff Contract` JSON.
- Kickoff: call `Planning` to create the plan if not present.
- Decide: check if work should be split into multiple PRs (size, risk, cross-domain impact).
- Run: execute `Backend Dev` then `Frontend Dev` sequentially.
- Parallel: run `QA and Security`, `DevOps` and `Doc Writer` in parallel for CI / QA checks and documentation.
- Return: a JSON summary with `subagent_results`, `overall_status`, and aggregated artifacts.

2.1) Multi-Cmmit Slicing Protocol

- If a task is large or high-risk, split into PR slices and execute in order.
- Each slice must have:
  - Scope boundary (what is included/excluded)
  - Dependency on previous slices
  - Validation gates (tests/scans required for that slice)
  - Explicit rollback notes
- Do not start the next slice until the current slice is complete and verified.
- Keep each slice independently reviewable and deployable.

3) Return Contract that all subagents must return

```
{
  "changed_files": ["path/to/file1", "path/to/file2"],
  "summary": "Short summary of changes",
  "tests": {"passed": true, "output": "..."},
  "artifacts": ["..."],
  "errors": []
}
```

4) Error Handling

- On a subagent failure, the Management agent must capture `tests.output` and decide to retry (1 retry maximum), or request a revert/rollback.
- Clearly mark the `status` as `failed`, and include `errors` and `failing_tests` in the `summary`.
- For multi-PR execution, mark failed slice as blocked and stop downstream slices until resolved.

5) Example: Run a full Feature Implementation

```
// 1. Planning
runSubagent({ description: "Planning", prompt: "<generate plan>", metadata: { plan_file: "docs/plans/current_spec.md" } })

// 2. Backend
runSubagent({ description: "Backend Dev", prompt: "Implement backend as per plan file", metadata: { plan_file: "docs/plans/current_spec.md", commands_to_run: ["cd backend && go test ./..."] } })

// 3. Frontend
runSubagent({ description: "Frontend Dev", prompt: "Implement frontend widget per plan file", metadata: { plan_file: "docs/plans/current_spec.md", commands_to_run: ["cd frontend && npm run build"] } })

// 4. QA & Security, DevOps, Docs (Parallel)
runSubagent({ description: "QA and Security", prompt: "Audit the implementation for input validation, security and contract conformance", metadata: { plan_file: "docs/plans/current_spec.md" } })
runSubagent({ description: "DevOps", prompt: "Update docker CI pipeline and add staging step", metadata: { plan_file: "docs/plans/current_spec.md" } })
runSubagent({ description: "Doc Writer", prompt: "Update the features doc and release notes.", metadata: { plan_file: "docs/plans/current_spec.md" } })
```

This file is a template; management should keep operations terse and the metadata explicit. Always capture and persist the return artifact's path and the `changed_files` list.