Sub-Agent Output Templating

Overview

This skill provides standardized templates for sub-agent OUTPUT formatting. It complements subagent-prompting (P0.1) which defines INPUT structure:

| Skill | Purpose | |-------|---------| | subagent-prompting | How to prompt sub-agents (GOAL/CONSTRAINTS/CONTEXT/OUTPUT) | | subagent-output-templating | How sub-agents report results (logs, summaries, diagnostics) |

Use this skill when:

Defining output requirements for sub-agent invocations
Parsing sub-agent results in pipeline stages
Ensuring consistent log formats across all agents

Log File Format

File Location

logs/{agent-name}-{YYYYMMDD-HHMMSS}.yaml

Example: logs/bulwark-code-auditor-20260111-143022.yaml

YAML Schema

# Required: Metadata block
metadata:
  agent: {agent-name}           # e.g., bulwark-code-auditor
  timestamp: {ISO-8601}         # e.g., 2026-01-11T14:30:22Z
  model: {model-used}           # sonnet, haiku, or opus
  task_id: {unique-identifier}  # For tracking across pipeline stages
  duration_ms: {execution-time} # Execution duration in milliseconds

# Required: Goal from the prompt (for traceability)
goal: "{GOAL from 4-part prompt}"

# Required: Completion report
completion:
  why:
    problem: "{What was broken/missing}"
    root_cause: "{Why it happened}"
    solution: "{What was implemented}"

  what:
    - file: {path}
      lines: "{range}"
      change: "{description}"

  trade_offs:
    gained:
      - "{benefit 1}"
    cost:
      - "{drawback 1}"

  risks:
    - risk: "{description}"
      mitigation: "{how addressed}"
      severity: {low|medium|high|critical}

  next_steps:
    - "{action item 1}"

# Required for code-writing agents (omit for read-only agents):
# Pipeline suggestions from implementer-quality.sh output
pipeline_suggestions:
  - pipeline: "{recommended pipeline name}"
    target_files:
      - "{file path}"
    reason: "{why this pipeline is recommended}"

# Required: Summary for main thread (100-300 tokens)
summary: |
  {Concise summary for main thread consumption}

# Required: Diagnostic output
diagnostics:
  model_requested: {model}
  model_actual: {model}
  context_type: {main|forked}
  parent_vars_accessible: {true|false}
  hooks_fired:
    - {hook-name}
  execution_time_ms: {duration}
  completion_status: {success|error|timeout}

Task Completion Report (WHY/WHAT/TRADE-OFFS/RISKS)

Every sub-agent MUST conclude with this structured report. This enables explicit decision documentation rather than implicit code changes.

WHY Section

Document the problem and solution rationale.

why:
  problem: "Authentication bypass vulnerability in refresh token path"
  root_cause: "Token validation skips expiry check on refresh"
  solution: "Added isExpired() check to refresh token handler"

Guidelines:

problem: What was broken, missing, or needs improvement
root_cause: The underlying reason (not just symptoms)
solution: What was done to address it

WHAT Section

List all changes made with file locations.

what:
  - file: src/auth/token.ts
    lines: "45-52"
    change: "Added isExpired() check before token refresh"
  - file: src/auth/token.test.ts
    lines: "120-145"
    change: "Added test for expired refresh token rejection"

Guidelines:

One entry per file modified
Include line ranges for precise location
Describe the change, not the code

TRADE-OFFS Section

Acknowledge explicit compromises made.

trade_offs:
  gained:
    - "Security: Expired tokens now properly rejected"
    - "Compliance: Meets OWASP session management requirements"
  cost:
    - "Performance: Additional DB lookup on refresh (negligible)"
    - "Complexity: New error handling path for expired tokens"

Guidelines:

Be honest about costs
Quantify impact where possible
Include both technical and business trade-offs

RISKS Section

Document forward-looking concerns.

risks:
  - risk: "Existing sessions with expired refresh tokens will fail"
    mitigation: "Grace period of 24h for migration"
    severity: medium
  - risk: "Grace period could be exploited"
    mitigation: "Monitor for unusual refresh patterns"
    severity: low

Severity Levels: | Level | Definition | |-------|------------| | low | Unlikely or minor impact | | medium | Possible impact, manageable | | high | Likely impact, needs attention | | critical | Must be addressed before deployment |

NEXT STEPS Section

List follow-up actions for pipeline or human.

next_steps:
  - "Monitor refresh failure rate for 24h"
  - "Remove grace period after migration window"
  - "Update documentation for new error codes"

Guidelines:

Actionable items only
Include owner if known (e.g., "DevOps: Update monitoring dashboard")
Order by priority

Summary Format for Main Thread

Purpose

The summary is returned to the main thread for pipeline decision-making. It should enable the orchestrator to:

Understand key findings without reading full log
Decide next pipeline stage
Report status to user

Token Budget

| Complexity | Target Tokens | Use Case | |------------|---------------|----------| | Simple | 100-150 | Single finding, clear action | | Moderate | 150-250 | Multiple findings, some nuance | | Complex | 250-300 | Many findings, trade-off decisions |

Summary Template

Found [N] [severity] issue(s): [brief description].
[Action taken / recommendation].
[Key risk or follow-up if any].

Examples

Simple (120 tokens):

Found 1 critical vulnerability: refresh tokens not validated for expiry.
Fixed by adding isExpired() check in token.ts:45-52. Added regression test.
Risk: existing sessions may fail during 24h migration window.

Moderate (200 tokens):

Found 3 issues in authentication module:
- 1 critical: token expiry bypass (fixed)
- 1 medium: weak password hashing (fixed, migration needed)
- 1 low: verbose error messages (fixed)

All issues addressed with tests added. Migration script created for password re-hashing.
Next: run migration in staging, monitor for 48h before production.

What to Include

Finding count and severity
Actions taken
Key risks or blockers
Recommended next steps

What to Exclude

Full reasoning or analysis
Code snippets
Verbose explanations
Duplicate information from log

Pipeline Suggestions in Summary (Code-Writing Agents)

Code-writing agents (e.g., bulwark-implementer) that invoke implementer-quality.sh and receive pipeline suggestions MUST include them in the summary with MANDATORY language. This ensures the orchestrator sees and acts on them per SA6.

MANDATORY FOLLOW-UP (SA6): Run the following pipeline(s):
  - {pipeline} on {target_files} ({reason})
Orchestrator MUST evaluate each suggestion and either execute or document deferral per SA6.

Read-only agents (reviewers, auditors) omit this section.

Diagnostic Output

Purpose

Enable automated behavioral testing without mocking. Diagnostics verify:

Correct model was used
Context isolation worked (for context: fork agents)
Hooks fired as expected
Execution completed successfully

Location

logs/diagnostics/{agent-name}-{YYYYMMDD-HHMMSS}.yaml

Format

skill: subagent-output-templating
timestamp: 2026-01-11T14:30:22Z
diagnostics:
  model_requested: sonnet
  model_actual: sonnet
  context_type: forked      # main or forked
  parent_vars_accessible: false  # Should be false for forked
  hooks_fired:
    - Stop
  execution_time_ms: 4520
  completion_status: success  # success, error, timeout
notes: "Task completed successfully"

Diagnostic Fields

| Field | Purpose | Values | |-------|---------|--------| | model_requested | Model specified in prompt | haiku, sonnet, opus | | model_actual | Model that actually ran | haiku, sonnet, opus | | context_type | Execution context | main, forked | | parent_vars_accessible | Context isolation test | true, false | | hooks_fired | Lifecycle hooks that executed | Array of hook names | | execution_time_ms | Duration | Integer | | completion_status | Final status | success, error, timeout |

Quick Reference

Minimal Log Template

metadata:
  agent: {name}
  timestamp: {ISO-8601}
  model: sonnet
  task_id: "{id}"
  duration_ms: 0

goal: "{goal}"

completion:
  why:
    problem: "{problem}"
    root_cause: "{cause}"
    solution: "{solution}"
  what:
    - file: {path}
      lines: "{range}"
      change: "{description}"
  trade_offs:
    gained: ["{benefit}"]
    cost: ["{cost}"]
  risks:
    - risk: "{risk}"
      mitigation: "{mitigation}"
      severity: medium
  next_steps:
    - "{action}"

# Include for code-writing agents only (omit for read-only agents):
pipeline_suggestions:
  - pipeline: "{pipeline name}"
    target_files: ["{path}"]
    reason: "{reason}"

summary: |
  {100-300 token summary}

diagnostics:
  model_requested: sonnet
  model_actual: sonnet
  context_type: forked
  parent_vars_accessible: false
  hooks_fired: []
  execution_time_ms: 0
  completion_status: success

Summary Checklist

[ ] Count and severity of findings stated
[ ] Actions taken described
[ ] Key risks mentioned
[ ] Next steps listed
[ ] Under 300 tokens
[ ] Pipeline suggestions with MANDATORY language (code-writing agents only)

Output Location Checklist

[ ] Main log: logs/{agent}-{YYYYMMDD-HHMMSS}.yaml
[ ] Diagnostics: logs/diagnostics/{agent}-{YYYYMMDD-HHMMSS}.yaml

Timestamp Formats

| Context | Placeholder | Format | Example | |---------|-------------|--------|---------| | File paths | {YYYYMMDD-HHMMSS} | Compact, filesystem-safe | 20260119-143022 | | YAML fields | {ISO-8601} | Standard ISO format | 2026-01-19T14:30:22Z |

Why two formats?

File names: No colons (filesystem-safe on Windows), compact, lexically sortable
YAML fields: Standard ISO-8601 for parsing and interoperability

Important: Always use {YYYYMMDD-HHMMSS} in file paths, never {timestamp} or {ts}.

Related Skills

subagent-prompting (P0.1): Defines INPUT structure (GOAL/CONSTRAINTS/CONTEXT/OUTPUT)
pipeline-templates (P0.3): Pre-defined workflows that consume this output format

References

For extended examples and edge cases, see references/examples.md.