@qball-inc/the-bulwark 1.1.0 → 1.2.0

package/skills/subagent-output-templating/SKILL.md

@@ -1,415 +1,417 @@
----
-name: subagent-output-templating
-description: Template for structured sub-agent output including YAML log format, task completion reports (WHY/WHAT/TRADE-OFFS/RISKS), and summary constraints. Use when defining how sub-agents should report results.
-user-invocable: false
----
-
-# 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
-
-```yaml
-# 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.
-
-```yaml
-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.
-
-```yaml
-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.
-
-```yaml
-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.
-
-```yaml
-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.
-
-```yaml
-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:
-1. Understand key findings without reading full log
-2. Decide next pipeline stage
-3. 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
-
-```yaml
-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
-
-```yaml
-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`.
+---
+name: subagent-output-templating
+description: Template for structured sub-agent output including YAML log format, task completion reports (WHY/WHAT/TRADE-OFFS/RISKS), and summary constraints. Use when defining how sub-agents should report results.
+user-invocable: false
+version: 1.0.0
+author: "Ashay Kubal @ Qball Inc."
+---
+
+# 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
+
+```yaml
+# 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.
+
+```yaml
+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.
+
+```yaml
+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.
+
+```yaml
+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.
+
+```yaml
+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.
+
+```yaml
+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:
+1. Understand key findings without reading full log
+2. Decide next pipeline stage
+3. 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
+
+```yaml
+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
+
+```yaml
+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`.