@qball-inc/the-bulwark 1.0.0

package/skills/subagent-prompting/SKILL.md

@@ -0,0 +1,364 @@
+---
+name: subagent-prompting
+description: Template for structured sub-agent invocation using 4-part prompting (GOAL/CONSTRAINTS/CONTEXT/OUTPUT) and F# pipeline notation. Use when orchestrating sub-agents or designing multi-agent workflows.
+user-invocable: false
+---
+
+# Sub-Agent Prompting Template
+
+## Overview
+
+This skill provides a standardized template for invoking sub-agents with deterministic inputs and predictable outputs. Use this when:
+
+- Orchestrating specialist sub-agents (code auditor, test auditor, etc.)
+- Designing multi-agent workflows with conditional branching
+- Ensuring consistent prompt structure across sub-agent invocations
+
+## 4-Part Template (Required)
+
+Every sub-agent invocation MUST include all four parts. Incomplete prompts lead to unpredictable behavior.
+
+### GOAL (What Success Looks Like)
+
+State the high-level objective, not just the action. Good goals are outcome-focused.
+
+```markdown
+## GOAL
+
+[Describe the desired end state, not the process]
+
+Examples:
+- GOOD: "Identify all security vulnerabilities that could allow unauthorized data access"
+- BAD: "Review the auth file"
+
+- GOOD: "Refactor authentication module for improved maintainability without breaking existing tests"
+- BAD: "Refactor the code"
+```
+
+### CONSTRAINTS (What You Cannot Do)
+
+Explicit boundaries prevent scope creep and unexpected changes.
+
+```markdown
+## CONSTRAINTS
+
+- [Hard limit 1: e.g., "Do NOT modify any files"]
+- [Hard limit 2: e.g., "Do NOT add new dependencies"]
+- [Hard limit 3: e.g., "Maintain backward API compatibility"]
+- [Resource limit: e.g., "Complete within 50 tool calls"]
+
+Examples:
+- "Identify issues only - do NOT implement fixes"
+- "Read-only analysis - no file modifications"
+- "Focus only on files in src/auth/ directory"
+```
+
+### CONTEXT (What You Need to Know)
+
+Provide all information required to complete the task. Sub-agents run in isolated context and cannot access parent conversation.
+
+```markdown
+## CONTEXT
+
+### Files to Analyze
+- `path/to/file1.ts` - [brief description of relevance]
+- `path/to/file2.ts` - [brief description of relevance]
+
+### Related Context
+- Previous findings: [summary of relevant prior work]
+- Architecture notes: [relevant design decisions]
+- Known issues: [existing problems to be aware of]
+
+### Standards to Apply
+- [Coding standard or guideline reference]
+- [Security policy reference if applicable]
+```
+
+### OUTPUT (What to Deliver)
+
+Specify concrete deliverables with exact format requirements.
+
+```markdown
+## OUTPUT
+
+### Primary Deliverable
+Write findings to: `logs/{agent-name}-{timestamp}.md`
+
+### Output Format
+[Specify structure: YAML, Markdown sections, etc.]
+
+### Summary Requirements
+Return to main thread: [max 200 tokens summary of key findings]
+
+### Diagnostic Output
+Write to: `logs/diagnostics/{agent-name}-{timestamp}.yaml`
+```
+
+---
+
+## Pipeline Syntax (F# Conceptual Notation)
+
+### Understanding the Notation
+
+F# pipe syntax (`|>`) is a **conceptual notation** for planning and documentation. It is NOT directly executable Claude Code syntax.
+
+```fsharp
+// This is documentation, not executable code
+Agent1 (task) |> Agent2 (task) |> Agent3 (task)
+```
+
+**Purpose**: Visualize workflow dependencies and conditional logic before implementation.
+
+### Mapping to Task() Invocations
+
+Each pipeline stage maps to a sequential `Task()` call from the main thread:
+
+```fsharp
+// Conceptual pipeline
+CodeAuditor (security) |> CodeAuditor (architecture) |> (if findings > 0 then IssueDebugger else Done)
+```
+
+**Actual execution**:
+
+1. Main thread invokes: `Task(description="Security audit", subagent_type="sonnet", prompt="[4-part prompt]")`
+2. Main thread reads log output, extracts findings
+3. Main thread invokes: `Task(description="Architecture audit", subagent_type="sonnet", prompt="[4-part prompt]")`
+4. Main thread reads log output, extracts findings
+5. IF `findings.count > 0`: Main thread invokes IssueDebugger
+6. ELSE: Pipeline complete
+
+### Pipeline Patterns
+
+**Code Review Pipeline:**
+```fsharp
+CodeAuditor (security)
+|> CodeAuditor (architecture)
+|> TestAuditor (coverage)
+|> (if findings > 0 then IssueDebugger else Done)
+```
+
+**Fix Validation Pipeline:**
+```fsharp
+IssueDebugger (root cause)
+|> Implementer (apply fix)
+|> CodeAuditor (verify quality)
+|> TestAuditor (verify tests)
+|> (if issues > 0 then IssueDebugger else Done)  // Loop until clean
+```
+
+**Test Audit Pipeline:**
+```fsharp
+TestAuditor (classify all)
+|> (if mock_heavy > 0 then VerificationScriptCreator else Done)
+|> Implementer (rewrite flagged)
+|> TestAuditor (re-verify)
+```
+
+### Key Constraint
+
+Sub-agents CANNOT spawn other sub-agents. All pipeline orchestration happens from the main thread.
+
+---
+
+## Custom Agent vs Built-in Agent
+
+### Agent Selection Priority
+
+Before spawning a pipeline stage:
+
+1. **Check `.claude/agents/`** for a custom agent matching the task
+2. **If custom agent exists**: Use its `name` field as `subagent_type` - this invokes the custom agent
+3. **If no custom agent**: Use `general-purpose` and provide full specialized instructions in the prompt
+
+### Important: 4-Part Prompt Always Required
+
+Regardless of agent type, every Task invocation MUST include the 4-part prompt (GOAL/CONSTRAINTS/CONTEXT/OUTPUT) and follow subagent-output-templating for output format.
+
+### Built-in Agent Types
+
+| Type | Use Case |
+|------|----------|
+| `general-purpose` | Multi-step tasks, code writing, analysis |
+| `Explore` | Fast codebase exploration, file search |
+| `Plan` | Architecture planning, implementation design |
+| `Bash` | Command execution |
+
+### Example: Custom Agent EXISTS
+
+```python
+# .claude/agents/security-auditor.md exists with name: security-auditor
+Task(
+    description="Security audit",
+    subagent_type="security-auditor",  # Invokes the custom agent
+    prompt="""
+## GOAL
+Identify security vulnerabilities in calculator.ts
+
+## CONSTRAINTS
+- Do NOT modify files
+
+## CONTEXT
+File: src/calculator.ts
+
+## OUTPUT
+Write to: logs/security-audit-{timestamp}.yaml
+"""
+)
+```
+
+### Example: Custom Agent DOES NOT Exist
+
+```python
+# No custom agent for this task - use general-purpose
+Task(
+    description="Security audit",
+    subagent_type="general-purpose",
+    model="sonnet",
+    prompt="""
+## GOAL
+Identify security vulnerabilities in calculator.ts using OWASP Top 10 patterns.
+
+## CONSTRAINTS
+- Do NOT modify files
+- Focus on injection, auth, and data exposure risks
+
+## CONTEXT
+File: src/calculator.ts
+This is a calculator module with arithmetic operations.
+
+## OUTPUT
+Write findings to: logs/security-audit-{timestamp}.yaml
+Format: YAML with findings array, severity, and recommendations
+"""
+)
+```
+
+Note: When no custom agent exists, the prompt must include all specialized instructions that would otherwise be in the custom agent's markdown file.
+
+---
+
+## Model Selection Guidance
+
+### Task-Type Based Selection (Objective)
+
+Model selection is based on **task type**, not subjective complexity. This keeps selection deterministic and objective.
+
+| Model | Task Type | Examples |
+|-------|-----------|----------|
+| **Haiku** | Lookups & Execution | Web fetch, file read/summarize, collect logs, run tests, typecheck, lint, simple classification |
+| **Sonnet** | Review & Analysis | Code review, test review, audits, failure analysis, security analysis |
+| **Opus** | Write & Fix | Write code, write tests, write fixes, apply changes |
+
+### Selection Rules
+
+1. **Determine task type from the action verb**:
+   - Lookup/Execute/Run/Fetch → **Haiku**
+   - Review/Analyze/Audit/Classify → **Sonnet**
+   - Write/Fix/Implement/Apply → **Opus**
+
+2. **Custom agent override**: If a custom sub-agent has `agent:` in its frontmatter, use that model instead of these rules.
+
+3. **Always specify model**: Every Task() invocation must include `subagent_type`.
+
+### Pipeline Example
+
+```
+Orchestrator (Opus) writes initial code
+     ↓
+Sub-agent (Sonnet) reviews → finds issues
+     ↓
+Sub-agent (Opus) fixes
+     ↓
+Sub-agent (Sonnet) re-reviews
+     ↓
+[Loop until clean]
+```
+
+### Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong | Correct Approach |
+|--------------|----------------|------------------|
+| Using Opus for lookups | Wastes budget on simple tasks | Use Haiku for lookups |
+| Using Haiku for code review | Misses nuanced issues | Use Sonnet for analysis |
+| Using Sonnet for writing fixes | Suboptimal quality | Use Opus for writing |
+| No model specified | Unpredictable behavior | Always specify `subagent_type` |
+| Ignoring custom agent frontmatter | Overrides intended behavior | Respect `agent:` field |
+
+---
+
+## Diagnostic Output (Required)
+
+When this skill is used to invoke a sub-agent, the sub-agent MUST write diagnostic output.
+
+### Diagnostic File Location
+
+```
+logs/diagnostics/{skill-name}-{YYYYMMDD-HHMMSS}.yaml
+```
+
+### Diagnostic Format
+
+```yaml
+skill: subagent-prompting
+timestamp: 2026-01-10T12:30:45Z
+diagnostics:
+  model_requested: sonnet
+  model_actual: sonnet
+  context_type: main
+  parent_vars_accessible: true
+  hooks_fired: []
+  execution_time_ms: 1250
+  completion_status: success
+notes: "Skill invoked successfully"
+```
+
+### When to Write Diagnostics
+
+- At the END of skill execution (success or failure)
+- Include actual model used (may differ from requested)
+- Record execution time for performance tracking
+
+---
+
+## Quick Reference
+
+### Prompt Checklist
+
+```markdown
+[ ] GOAL: Outcome-focused objective stated
+[ ] CONSTRAINTS: Hard limits explicitly listed
+[ ] CONTEXT: All required files and background provided
+[ ] OUTPUT: Log path, format, and summary requirements specified
+[ ] DIAGNOSTIC: logs/diagnostics/ path included
+```
+
+### Task() Invocation Template
+
+```python
+Task(
+    description="[3-5 word summary]",
+    subagent_type="sonnet",  # or "haiku", "opus"
+    prompt="""
+## GOAL
+[Outcome-focused objective]
+
+## CONSTRAINTS
+- [Limit 1]
+- [Limit 2]
+
+## CONTEXT
+[Files, background, standards]
+
+## OUTPUT
+Write to: logs/{agent}-{timestamp}.md
+Diagnostic: logs/diagnostics/{agent}-{timestamp}.yaml
+Summary: [max 200 tokens]
+"""
+)
+```
+
+---
+
+## References
+
+For extended examples and edge cases, see `references/examples.md`.

package/skills/subagent-prompting/references/examples.md

@@ -0,0 +1,342 @@
+# Sub-Agent Prompting Examples
+
+Extended examples for the subagent-prompting skill. Load this file for detailed reference when designing sub-agent invocations.
+
+---
+
+## Example 1: Code Auditor Invocation
+
+### Complete 4-Part Prompt
+
+```markdown
+## GOAL
+
+Identify security vulnerabilities and code quality issues in the authentication module that could lead to unauthorized access or data exposure.
+
+## CONSTRAINTS
+
+- Do NOT modify any files - this is read-only analysis
+- Focus only on files in `src/auth/` directory
+- Do NOT analyze test files
+- Complete analysis within 30 tool calls
+- Identify issues only - do NOT implement fixes
+
+## CONTEXT
+
+### Files to Analyze
+- `src/auth/login.ts` - Handles user login flow
+- `src/auth/session.ts` - Session management
+- `src/auth/middleware.ts` - Auth middleware for routes
+- `src/auth/tokens.ts` - JWT token handling
+
+### Related Context
+- Previous audit found XSS in user input handling (fixed in v2.1)
+- Session tokens use RS256 algorithm
+- No rate limiting currently implemented
+
+### Standards to Apply
+- OWASP Top 10 2021
+- Company security policy v3.2
+- TypeScript strict mode compliance
+
+## OUTPUT
+
+### Primary Deliverable
+Write findings to: `logs/code-auditor-20260110-143022.md`
+
+### Output Format
+```markdown
+# Security Audit Report
+
+## Critical Issues
+[List with file:line references]
+
+## High Priority Issues
+[List with file:line references]
+
+## Medium Priority Issues
+[List with file:line references]
+
+## Recommendations
+[Prioritized action items]
+```
+
+### Summary Requirements
+Return to main thread: Max 200 tokens summarizing critical findings count and top recommendation.
+
+### Diagnostic Output
+Write to: `logs/diagnostics/code-auditor-20260110-143022.yaml`
+```
+
+---
+
+## Example 2: Test Auditor Invocation
+
+### Complete 4-Part Prompt
+
+```markdown
+## GOAL
+
+Classify all tests in the repository to identify mock-heavy tests that verify mock behavior rather than real system behavior.
+
+## CONSTRAINTS
+
+- Read-only analysis - do NOT modify test files
+- Process all files matching `**/*.test.ts` and `**/*.spec.ts`
+- Flag tests where >50% of assertions verify mock calls
+- Do NOT flag integration tests that use real dependencies
+
+## CONTEXT
+
+### Test Patterns to Recognize
+
+**Real Integration Test Indicators:**
+- Spawns actual processes
+- Makes real HTTP requests
+- Reads/writes actual files
+- Uses real database connections
+
+**Mock-Heavy Test Indicators:**
+- jest.mock() or vi.mock() for system under test
+- Assertions on mock.toHaveBeenCalledWith()
+- No actual output verification
+- Mocked spawn/exec for CLI tools
+
+### Known Good Tests (Do Not Flag)
+- `tests/integration/` directory - all real integration tests
+- `tests/e2e/` directory - end-to-end tests
+
+## OUTPUT
+
+### Primary Deliverable
+Write to: `logs/test-auditor-20260110-150000.yaml`
+
+### Output Format
+```yaml
+summary:
+  total_tests: 156
+  real_tests: 89
+  mock_heavy: 67
+
+classifications:
+  - file: src/auth/__tests__/login.test.ts
+    type: mock_heavy
+    mock_percentage: 85
+    reason: "Mocks entire auth service, verifies mock calls only"
+    priority: high
+
+  - file: tests/integration/api.test.ts
+    type: real
+    mock_percentage: 0
+    reason: "Spawns actual server, makes real HTTP requests"
+```
+
+### Summary Requirements
+Return: "Classified X tests: Y real, Z mock-heavy (priority rewrite: N)"
+
+### Diagnostic Output
+Write to: `logs/diagnostics/test-auditor-20260110-150000.yaml`
+```
+
+---
+
+## Example 3: Issue Debugger with Validation Loop
+
+### Complete 4-Part Prompt
+
+```markdown
+## GOAL
+
+Identify the root cause of failing login tests and implement a fix that passes all tests without breaking existing functionality.
+
+## CONSTRAINTS
+
+- Only modify files directly related to the bug
+- Do NOT refactor unrelated code
+- Maintain backward API compatibility
+- All existing tests must continue to pass
+- New fix must include a regression test
+
+## CONTEXT
+
+### Failing Test Output
+```
+FAIL src/auth/__tests__/login.test.ts
+  ✕ should reject expired tokens (45ms)
+
+  Expected: 401 Unauthorized
+  Received: 200 OK
+
+  at src/auth/middleware.ts:47
+```
+
+### Recent Changes
+- Commit abc123: "Refactored token validation" (3 days ago)
+- This is when tests started failing
+
+### Files to Investigate
+- `src/auth/middleware.ts:47` - Error location
+- `src/auth/tokens.ts` - Token validation logic
+- `src/auth/__tests__/login.test.ts` - Failing test
+
+## OUTPUT
+
+### Primary Deliverable
+Write debug journey to: `logs/issue-debugger-20260110-160000.md`
+
+### Output Format
+```markdown
+# Debug Journey
+
+## Root Cause Analysis
+[Detailed explanation with file:line references]
+
+## Fix Applied
+[Description of changes made]
+
+## Files Modified
+- [file1]: [what changed]
+- [file2]: [what changed]
+
+## Verification
+- [ ] Failing test now passes
+- [ ] All other tests still pass
+- [ ] Regression test added
+
+## Test Output
+[Paste final test results]
+```
+
+### Validation Loop
+MUST run tests after fix:
+1. Apply fix
+2. Run: `just test`
+3. IF tests fail: Analyze, adjust, repeat
+4. IF tests pass: Document and complete
+
+### Summary Requirements
+Return: "Fixed [root cause] in [file]. All X tests passing."
+
+### Diagnostic Output
+Write to: `logs/diagnostics/issue-debugger-20260110-160000.yaml`
+```
+
+---
+
+## Example 4: Pipeline Orchestration (Main Thread)
+
+### Code Review Pipeline Implementation
+
+```markdown
+# Main Thread Orchestration
+
+## Step 1: Security Audit
+```python
+result1 = Task(
+    description="Security audit of auth module",
+    subagent_type="sonnet",
+    prompt="[4-part prompt for security audit]"
+)
+# Read: logs/code-auditor-security-*.md
+security_findings = extract_findings(result1)
+```
+
+## Step 2: Architecture Audit
+```python
+result2 = Task(
+    description="Architecture review of auth module",
+    subagent_type="sonnet",
+    prompt="[4-part prompt for architecture review]"
+)
+# Read: logs/code-auditor-architecture-*.md
+arch_findings = extract_findings(result2)
+```
+
+## Step 3: Test Coverage Audit
+```python
+result3 = Task(
+    description="Test coverage analysis",
+    subagent_type="haiku",
+    prompt="[4-part prompt for test coverage]"
+)
+# Read: logs/test-auditor-*.yaml
+test_findings = extract_findings(result3)
+```
+
+## Step 4: Conditional Branch
+```python
+total_findings = security_findings + arch_findings + test_findings
+if total_findings > 0:
+    Task(
+        description="Fix identified issues",
+        subagent_type="sonnet",
+        prompt="[4-part prompt including all findings as CONTEXT]"
+    )
+else:
+    # Pipeline complete - all checks passed
+    log_success()
+```
+```
+
+---
+
+## Common Mistakes to Avoid
+
+### Mistake 1: Missing CONSTRAINTS
+
+**Bad:**
+```markdown
+## GOAL
+Review the auth code.
+
+## CONTEXT
+Look at src/auth/
+
+## OUTPUT
+Tell me what you find.
+```
+
+**Good:**
+```markdown
+## GOAL
+Identify security vulnerabilities in authentication that could allow unauthorized access.
+
+## CONSTRAINTS
+- Read-only analysis - do NOT modify files
+- Focus on OWASP Top 10 categories
+- Complete within 25 tool calls
+
+## CONTEXT
+[Specific files, standards, background]
+
+## OUTPUT
+[Specific log path, format, summary requirements]
+```
+
+### Mistake 2: Vague OUTPUT Specification
+
+**Bad:**
+```markdown
+## OUTPUT
+Return the results.
+```
+
+**Good:**
+```markdown
+## OUTPUT
+Write to: `logs/auditor-20260110.md`
+Format: Markdown with Critical/High/Medium sections
+Summary: Max 200 tokens with finding counts
+Diagnostic: `logs/diagnostics/auditor-20260110.yaml`
+```
+
+### Mistake 3: No Diagnostic Output
+
+**Bad:** (missing diagnostic section entirely)
+
+**Good:**
+```markdown
+### Diagnostic Output
+Write to: `logs/diagnostics/{agent}-{timestamp}.yaml`
+Include: model_actual, execution_time_ms, completion_status
+```