79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
## 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-PR 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.
|