ejs-sub-agent-capture - SKILL.md Agent Skill

name: ejs-sub-agent-capture description: > Capture sub-agent decisions, rationale, and inter-agent handoffs during multi-agent Engineering Journey System (EJS) workflows. Ensures that delegated work is properly attributed and traceable.

EJS Sub-Agent Capture

Use this skill during multi-agent workflows — when a main agent delegates tasks to sub-agents (e.g., explore, task, general-purpose, or custom agents) and their decisions and outputs need to be captured in the Session Journey.

Note: Copilot hooks (scripts/hooks/subagent-stop.sh) automatically log sub-agent completion events and create timestamped placeholder entries in the journey file. This skill enriches those placeholders with semantic content — decisions, rationale, alternatives, and handoff context — that only an LLM can provide.

When Delegating to a Sub-Agent

Record the delegation in the Interaction Summary:

- Human: <request that triggered delegation>
  - Agent [main-agent]: Delegated [task] to sub-agent [sub-agent-name]
  - Context provided: <what constraints or prior work was shared>

Provide context from prior sub-agent work when relevant:
- Pass earlier sub-agent findings to subsequent sub-agents
- Example: code review findings → testing agent, test results → documentation agent
Instruct sub-agents to follow EJS conventions:
- Use the ADR template at ejs-docs/adr/0000-adr-template.md
- Place ADRs under ejs-docs/adr/
- Do not let sub-agents create conflicting templates or instruction files

When a Sub-Agent Completes

Capture the sub-agent's contribution in the Sub-Agent Contributions section:

## Sub-Agent: <agent-name / agent-type>
- **Task delegated:** What was the sub-agent asked to do?
- **Decisions made:** What did the sub-agent decide (approach, trade-offs)?
- **Alternatives considered:** What other approaches did the sub-agent evaluate?
- **Outcome:** What was the result?
- **Handoff to other agents:** Did this sub-agent's output feed into another's work?

Record inter-agent handoff chains when one sub-agent's output informs another:
```
SA1 (Code Review) → found missing input validation
  ↓ handoff
SA2 (Testing) → added edge-case tests based on SA1 findings
  ↓ handoff
SA3 (Documentation) → added validation examples based on SA2 test cases
```
Document:
- The dependency: which sub-agent's output became another's input
- Any disagreements between sub-agents and how conflicts were resolved
- Which agent ultimately influenced the final decision

At Session Finalization

Populate the SUB_AGENT_EXTRACT in the machine extracts section with:
- List of sub-agents involved (by name/type)
- Summary of each sub-agent's decisions and rationale
- Inter-agent handoff chain documentation
- Any disagreements or conflicts resolved

Example

## Sub-Agent: Code Review (explore agent)
- **Task delegated:** Review authentication refactor for security and code quality
- **Decisions made:** Flagged missing input validation on JWT claims (chose depth-first security review over breadth-first style review)
- **Alternatives considered:** Could have focused on code style first, but prioritized security given auth context
- **Outcome:** 3 security findings, 1 code quality suggestion
- **Handoff to other agents:** Findings passed to Testing agent as context for edge-case test generation

## Sub-Agent: Testing (task agent)
- **Task delegated:** Run and extend test suite for auth changes, with Code Review findings as context
- **Decisions made:** Added 3 new edge-case tests targeting validation gaps found by Code Review
- **Alternatives considered:** Could have run existing tests only, but SA1 findings warranted new test cases
- **Outcome:** 2 test failures found and fixed, 3 new tests added
- **Handoff to other agents:** Test results and new test cases passed to Documentation agent

Sub-Agent Instruction Fragment

When delegating to a sub-agent, include this in the delegation prompt to close the sub-agent EJS blind spot — sub-agents have no automatic awareness of EJS:

EJS: Append your work to [journey-file-path] under "Sub-Agent Contributions".
Record: task, decisions (with rationale), alternatives considered, outcome.
Attribute all entries to your agent name.

Replace [journey-file-path] with the actual path, e.g. ejs-docs/journey/2026/ejs-session-2026-03-13-01.md.

Contextual References

Session Journey template: ejs-docs/journey/_templates/journey-template.md
Sub-Agent Handoff Protocol: ejs-docs/session-lifecycle-patterns.md
ADR 0012: Sub-agent decision capture protocol

Key Principle

Sub-agent decisions are first-class artifacts. Every decision a sub-agent makes — and every handoff between sub-agents — must be attributed, recorded with rationale, and traceable in the Session Journey.