Summary

Kiro has a working subagent system where the primary agent can invoke custom subagents defined in .kiro/agents/*.json. agentsys currently strips Task() calls when transforming commands for Kiro (replacing with "Invoke the X agent" text). Instead, we should transform them into Kiro-native subagent invocations.

How Kiro Subagent Spawning Works

• Primary agent can invoke subagents by name from .kiro/agents/*.json
• Subagents run synchronously - parent waits for result, then continues
• Direct CLI: kiro-cli --agent <name> launches a specific agent
• In-session: primary agent uses the subagent tool to delegate tasks
• Subagent discovery is by name lookup in the agents directory
• Regression in v1.26.0 (Subagent failing to spawn with "unable to find agent with name <agent>" kirodotdev/Kiro#5743): "unable to find agent" - shows this is an active, used feature

Current behavior (agentsys)

In transformCommandForKiro() (lib/adapter-transforms.js):

content = content.replace(/await\s+Task\s*\(\s*\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}\s*\);?/g, (match) => {
    const agentMatch = match.match(/subagent_type:\s*["'](?:[^"':]+:)?([^"']+)["']/);
    if (agentMatch) return `Invoke the ${agentMatch[1]} agent`;
    return '';
});

This strips Task() and replaces with plain text. But since agentsys also installs agents to .kiro/agents/*.json, we should instead transform Task() calls into instructions that tell the Kiro agent to use its subagent invocation system.

Proposed behavior

Transform Task() calls into Kiro subagent invocation instructions:

// Instead of: "Invoke the exploration-agent agent"
// Generate: "Use the exploration-agent subagent to: <prompt text>"

Or better, generate a structured instruction the Kiro agent can follow:

Delegate to the `exploration-agent` subagent:
> <extracted prompt from Task() call>

This way the Kiro primary agent knows to:

1. Look up exploration-agent in .kiro/agents/
2. Invoke it with the given prompt
3. Wait for the result and continue

Limitations to document

• Sequential only: Kiro subagents run one at a time (no parallel spawning)
• Pre-defined only: Subagent must exist in .kiro/agents/*.json
• Parallel orchestration (Team/swarm) not supported until Multi-Agent Orchestration: Support sync/async subagents, native context handoff, and context-efficient coordinator workflow kirodotdev/Kiro#4262 and Enable Parallel Task Execution with Sub-Agent Sessions in Kiro kirodotdev/Kiro#2288 are implemented
• Subagent permission inheritance is an open issue (Subagents should inherit parent agent's allowedTools kirodotdev/Kiro#5449)

Acceptance criteria

• transformCommandForKiro() produces subagent delegation instructions instead of plain text
• Instructions reference the agent by its installed name in .kiro/agents/
• Prompt text from Task() call is preserved in the instruction
• Parallel Task() calls are documented as sequential on Kiro
• Tests updated for new transform behavior