Recursive Subagent

recursive-subagent

Use this skill to decide whether subagents help a recursive-mode phase and to enforce the handoff contract when they do.

This skill does not relax the canonical workflow. The main agent remains responsible for:

• one active recursive phase at a time
• serving as the single orchestrator the user is currently interacting with
• full audit rigor before lock
• rejecting incomplete or context-free subagent output
• falling back to self-audit when subagents are unavailable

If recursive-router is installed, consult it when the user has explicitly asked to use routing or when an active configured external route exists for the selected delegated role. Because router discovery and configuration may inspect local CLI and provider configuration on the device, ask the user first before new setup or policy changes. Do not ask again merely to honor an already configured external route for a role that must now be dispatched.

Once the user confirms routed setup, explicitly requests routed delegation, or the role has an active configured external route, consult:

• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json
• ../recursive-router/SKILL.md

before choosing a routed external CLI/model path for a role.

Re-read those files from disk immediately before every routed dispatch. Do not reuse an earlier in-memory resolution if policy, discovery state, or fallback behavior may have changed during the run. If recursive-router-resolve returns external-cli, use recursive-router-invoke for that delegated slot. Local/self-audit execution is only the valid path when the route resolves to fallback-local, local-only, blocked, or ask-user, and the recorded artifact must say so.

Priority Of Use

Use subagents in this order of value:

1. analyst
2. planner
3. code reviewer
4. memory auditor
5. tester
6. implementer for truly disjoint write scopes

Do not treat subagents as required infrastructure. They are optional infrastructure, but delegated audit/review is the preferred default when subagents are available and the context bundle is complete.

Capability Detection Is A Hard Control Point

At the start of a phase where delegation is being considered, determine whether the environment actually supports subagents/tasks.

If subagents are unavailable:

• record Subagent Availability: unavailable
• record Audit Execution Mode: self-audit
• perform the same audit locally

If subagents are available:

• record Subagent Availability: available
• delegate by default for audit/review work when the context bundle is complete
• consult router policy before dispatch when the current task explicitly requests routed delegation or external CLI routing is configured for the selected role
• if the controller still chooses self-audit, record a concrete Delegation Override Reason
• keep the same audit checklist and acceptance standard

Before delegating, read /.recursive/memory/skills/SKILLS.md plus the relevant skill-memory shards for delegated review, review-bundle fit, and stale-context risks.

Never skip or weaken an audit because delegation is unavailable.

Canonical Constraints

• Recursive phases stay sequential. There is exactly one active phase per run.
• Subagents may help inside the active phase; they do not authorize parallel phase work.
• Parallel write-capable implementation is allowed only for explicitly independent sub-phases with disjoint write scopes and no blocking dependency chain.
• Audit, review, and read-only verification are the safest default delegation modes.

Delegated Audit Contract

A delegated audit is valid only when the controller passes a complete context bundle. Prefer a canonical review bundle file under /.recursive/run/<run-id>/evidence/review-bundles/ so the handoff is durable and repeatable.

The controller must pass all of:

1. phase name and artifact path
2. current phase draft
3. exact upstream artifact paths that must be reread
4. relevant addendum paths
5. relevant prior recursive evidence and memory refs
6. diff basis from 00-worktree.md
7. changed file list
8. targeted code file paths or file groups to inspect
9. relevant control-plane docs when needed
10. exact audit questions/checklist for the phase
11. required output shape including findings and verdict

Vague delegation such as "review this phase" or "audit implementation" is invalid.

If any required item is missing, do not delegate. Perform the audit yourself.

If repairs materially change reviewed scope, changed files, or evidence, refresh the bundle before re-audit.

Controller Checklist

Before dispatch:

• Confirm delegation is optional, not required
• Confirm the phase is still the single active phase
• Confirm the handoff bundle is complete
• Confirm the canonical review bundle path exists when delegation is being recorded in a phase artifact
• Confirm a durable subagent action record will be written under /.recursive/run/<run-id>/subagents/
• Confirm initial prompt bundles are cited from a prompt-bundle path, and routed assistant output, stdout/stderr transcripts, and invoke metadata will be captured under /.recursive/run/<run-id>/evidence/router/, not directly under subagents/
• Confirm the target subagent role matches the task
• Confirm write scopes are disjoint before any write-capable delegation

Before accepting a result:

• Verify the routed invocation has success: true and exit code 0 when external CLI routing was used
• Verify the subagent read the named upstream artifacts
• Verify the subagent read the review bundle or its full equivalent
• Verify the subagent returned enough detail to populate the action record fields
• Verify Current Artifact points at a stable reviewed artifact or refresh the record after any material draft edits
• Verify the output cites the diff basis and changed files
• Verify the bundle still matches the current artifact hash after any repairs
• Verify the output contains concrete findings or an explicit no-findings conclusion
• Verify the output includes requirement/plan alignment comments where relevant
• Verify the output ends with a clear verdict
• Verify any claimed file impact, artifact impact, or findings against the actual worktree diff, actual artifacts, and earlier locked recursive docs before acceptance
• Verify the phase artifact records Reviewed Action Records, Main-Agent Verification Performed, Acceptance Decision, Refresh Handling, and Repair Performed After Verification
• Reject action records that leave claimed file impact or claimed artifact impact as none for materially contributing work
• Reject the output if it is context-free, hand-wavy, or missing required checks

If a routed subagent reports failures, findings, incomplete work, success: false, or a nonzero external CLI exit code, do not accept the result. The controller must run an audit-repair-retry loop: record the failed attempt and diagnostic evidence, tell the same bounded role exactly what to fix when it has ownership to fix it, rerun the route, and then repeat controller verification against the actual diff and artifacts. If the routed role cannot fix the issue or the route remains unavailable, record an explicit fallback before using local repair or self-audit evidence.