@qball-inc/the-bulwark 1.0.0

package/skills/create-subagent/references/agent-conventions.md

@@ -0,0 +1,268 @@
+# Agent Conventions
+
+Conventions for generating Claude Code agents. The Stage 2 generator sub-agent references this to produce agents that follow the correct register, include proper configuration, and document permission requirements.
+
+---
+
+## System-Prompt Register
+
+Agent bodies in `.claude/agents/` are system prompts. They define WHO the agent IS, not WHAT to DO.
+
+### The Critical Distinction
+
+**System-prompt register (CORRECT for agents):**
+
+The body reads as identity, expertise, and behavioral guidelines.
+
+```markdown
+# Security Reviewer
+
+You are a code security reviewer specializing in web application vulnerabilities. Your expertise covers OWASP top 10, injection attacks, authentication flaws, and cryptographic misuse.
+
+## Your Mission
+
+Analyze code changes for security vulnerabilities. You prioritize:
+1. Input validation and sanitization
+2. Authentication and authorization boundaries
+3. Data exposure and information leakage
+4. Dependency vulnerabilities
+
+## How You Work
+
+When reviewing code, you:
+1. Read all changed files completely
+2. Trace data flow from user input to output
+3. Classify each finding by CVSS severity
+4. Report findings in structured format with remediation guidance
+```
+
+**Task-instruction register (WRONG for agents):**
+
+The body reads as step-by-step execution instructions.
+
+```markdown
+# Security Review Steps
+
+## Steps
+1. Read the files provided in the prompt
+2. Look for security issues
+3. Check for SQL injection
+4. Check for XSS
+5. Write a report to logs/security-review.md
+
+## Output
+Write findings to logs/security-review.md
+```
+
+### Why This Matters
+
+- Agents run as forked contexts — the body IS the system prompt
+- System prompts establish identity, which produces consistent behavior across invocations
+- Task instructions belong in the invoking prompt (GOAL/CONSTRAINTS/CONTEXT/OUTPUT), not the agent definition
+- Identity-based agents adapt to different tasks while maintaining consistent quality
+
+### Register Checklist
+
+When generating an agent body, verify:
+
+- [ ] Opens with "You are a..." or equivalent identity statement
+- [ ] Describes expertise and specialization areas
+- [ ] Explains behavioral patterns ("When you encounter X, you...")
+- [ ] Uses present tense, not imperative ("You analyze..." not "Analyze...")
+- [ ] Protocol section describes HOW the agent works, not WHAT to do for a specific task
+- [ ] Output section describes format conventions, not specific file paths for one invocation
+
+---
+
+## Frontmatter Structure
+
+### Required Fields
+
+```yaml
+---
+name: {agent-name}
+description: {single-line description with "Use when..." trigger}
+model: {haiku|sonnet|opus}
+tools:
+  - {tool-1}
+  - {tool-N}
+---
+```
+
+### Optional Fields
+
+```yaml
+skills:
+  - {skill-dependency-1}
+  - {skill-dependency-N}
+```
+
+### Model Selection Guidance
+
+| Use Case | Model | Rationale |
+|----------|-------|-----------|
+| Quick lookups, simple classification | haiku | Fast, low-cost |
+| Analysis, review, research, generation | sonnet | Balanced capability and speed |
+| Complex implementation, architecture, novel problems | opus | Highest quality reasoning |
+
+**Default to Sonnet** unless the task clearly requires Haiku's speed or Opus's depth.
+
+### Tool Selection
+
+Only include tools the agent actually needs. Common patterns:
+
+| Agent Type | Typical Tools |
+|------------|--------------|
+| Read-only reviewer | Read, Glob, Grep, Write (for reports only) |
+| Code writer | Read, Grep, Glob, Write, Edit, Bash |
+| Research agent | Read, Glob, Grep, WebFetch, WebSearch |
+
+---
+
+## Stop Hooks
+
+Agents that emit diagnostic output should have a Stop hook configured. The hook runs when the agent completes.
+
+### Hook Configuration
+
+Stop hooks are configured in `.claude/hooks.json` (or project-level hooks), NOT in the agent's frontmatter (agent-scoped hooks are broken per GitHub #18392/#19213).
+
+```json
+{
+  "hooks": {
+    "SubagentStop": [
+      {
+        "matcher": "bulwark-{agent-name}",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Agent {agent-name} completed'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### What to Document
+
+Since Stop hooks must be configured separately (not in the agent .md file), the generated agent should include a "Permissions Setup" section that documents:
+
+1. The Stop hook command to add
+2. Where to add it (`.claude/hooks.json` or project hooks)
+3. What the hook does (e.g., log completion, trigger follow-up)
+
+---
+
+## Permissions Setup
+
+Tool permissions for agents cannot be enforced automatically (GitHub feature request #10093, closed NOT_PLANNED Jan 2026). Generated agents must include manual permission setup documentation.
+
+### Required Documentation
+
+Every generated agent must include a section like:
+
+```markdown
+## Permissions Setup
+
+This agent requires the following permissions to be configured in your project settings:
+
+### Tool Permissions
+
+Add to `.claude/settings.json` or `.claude/settings.local.json`:
+
+\`\`\`json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "Write($PROJECT_DIR/logs/*)"
+    ]
+  }
+}
+\`\`\`
+
+### Hook Configuration (Optional)
+
+If this agent emits diagnostic output, add a SubagentStop hook:
+
+\`\`\`json
+{
+  "hooks": {
+    "SubagentStop": [
+      {
+        "matcher": "{agent-name}",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '{agent-name} completed at $(date)' >> logs/agent-completions.log"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+```
+
+---
+
+## Output Conventions
+
+### Diagnostic Output
+
+Agents that produce diagnostic output should follow this pattern:
+
+```yaml
+diagnostic:
+  agent: {agent-name}
+  timestamp: "{ISO-8601}"
+
+  task:
+    description: "{what was requested}"
+    input: "{input provided}"
+
+  execution:
+    steps_completed: 0
+    findings: 0
+    errors: 0
+
+  output:
+    report_path: "{path to main output}"
+    verdict: "{pass/fail/complete/partial}"
+```
+
+### Log Output (SA2)
+
+All agent output goes to `$PROJECT_DIR/logs/`. The agent definition should specify:
+
+```markdown
+## Output
+
+Write all output to `$PROJECT_DIR/logs/` directory (`$PROJECT_DIR` is the project root where `.claude/` lives):
+- Main report: `$PROJECT_DIR/logs/{agent-name}-{timestamp}.{ext}`
+- Diagnostics: `$PROJECT_DIR/logs/diagnostics/{agent-name}-{timestamp}.yaml`
+```
+
+**IMPORTANT**: `$PROJECT_DIR` ensures paths resolve to the project root, not the skill directory or CWD. Without this prefix, agents may write output into `.claude/skills/` or other incorrect locations.
+
+---
+
+## Invocation Documentation
+
+Every generated agent should include an Invocation section:
+
+```markdown
+## Invocation
+
+This agent is invoked via the **Task tool**:
+
+| Method | How to Use |
+|--------|-----------|
+| **Direct** | `Task(subagent_type="{agent-name}", prompt="...")` |
+| **Pipeline stage** | Referenced by orchestrator skills |
+| **User request** | Ask Claude to "run the {agent-name}" |
+```

package/skills/create-subagent/references/content-guidance.md

@@ -0,0 +1,232 @@
+# Content Guidance
+
+Instruction writing patterns, description rules, and common pitfalls for generating high-quality agents. The Stage 2 generator sub-agent references this alongside agent-conventions.md to produce agents that behave reliably and instruct clearly.
+
+---
+
+## Description Field Rules
+
+The YAML frontmatter `description` field controls agent discovery and activation.
+
+### Format Rules
+
+1. **Single line only.** Multi-line descriptions silently break discovery (GitHub #9817/#4700).
+2. **Maximum ~200 characters.** Longer descriptions get truncated in menus.
+3. **Start with an action noun or role.** "Code-writing agent that...", "Critical analysis of..."
+
+### "When to Use" Framing
+
+The description must tell the invoker WHEN to use this agent.
+
+**Good — trigger-specific:**
+```yaml
+description: Code-writing agent that implements fixes and features following Bulwark standards. Quality enforced by direct implementer-quality.sh invocation after each Write/Edit.
+```
+
+**Bad — vague:**
+```yaml
+description: An agent for implementing code changes.
+```
+
+**Bad — too broad:**
+```yaml
+description: Helps with code and testing across various projects and frameworks.
+```
+
+### Pattern
+
+```
+{Role/action} that {what it does} {using what method/standard}. {Quality/safety note if applicable}.
+```
+
+---
+
+## System-Prompt Writing Patterns
+
+How to write agent bodies that produce consistent, reliable behavior. See agent-conventions.md for the full system-prompt vs task-instruction distinction.
+
+### Identity First
+
+Open with a clear identity statement. This anchors all subsequent behavior.
+
+**Good:**
+```markdown
+You are a meticulous standards reviewer for Claude Code assets. Your role is to critically analyze assets against official standards and produce structured validation reports.
+```
+
+**Bad:**
+```markdown
+This document describes how to review standards.
+```
+
+### Expertise Anchoring
+
+After identity, establish expertise areas. This constrains behavior to relevant domains.
+
+**Good:**
+```markdown
+Your expertise covers:
+- OWASP top 10 vulnerabilities
+- Authentication and authorization patterns
+- Input validation and sanitization
+- Cryptographic best practices
+```
+
+**Bad:**
+```markdown
+You know about security stuff.
+```
+
+### Behavioral Patterns Over Procedures
+
+Describe HOW the agent behaves, not step-by-step task execution.
+
+**Good:**
+```markdown
+When reviewing code, you:
+1. Read all changed files completely before forming any opinion
+2. Trace data flow from input boundaries to output
+3. Classify findings by severity using CVSS scoring
+4. Provide specific remediation for every finding
+```
+
+**Bad:**
+```markdown
+Steps:
+1. Read file A
+2. Read file B
+3. Write report to logs/review.md
+```
+
+---
+
+## Binding Language for Agents
+
+Without explicit binding language, Claude treats agent instructions as suggestions.
+
+### Pre-Flight Gate Pattern
+
+```markdown
+## Pre-Flight Gate
+
+**MANDATORY: Read this section FIRST. These instructions are BINDING, not advisory.**
+
+Before doing ANY work, confirm you understand these REQUIRED obligations:
+
+1. **REQUIRED**: [obligation 1]
+2. **REQUIRED**: [obligation 2]
+
+Failure to follow these obligations produces non-compliant output.
+```
+
+### Mission DO/DO NOT Pattern
+
+```markdown
+## Mission
+
+**DO**:
+- [concrete action 1]
+- [concrete action 2]
+
+**DO NOT**:
+- [specific prohibition 1]
+- [specific prohibition 2]
+```
+
+### Anti-Thought Traps
+
+Address rationalizations Claude uses to skip obligations:
+
+```markdown
+If you find yourself thinking "this step isn't necessary for this particular task" — STOP.
+The obligation exists for consistency across all invocations, not just this one.
+```
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Task-Instruction Register
+
+Writing an agent body as step-by-step task instructions instead of identity and behavioral guidelines. See agent-conventions.md for the full distinction and examples.
+
+**Impact**: Agent behaves inconsistently because it has no stable identity to anchor behavior.
+
+### Pitfall 2: Over-Specified Output Paths
+
+Hardcoding specific file paths in the agent body for a single use case.
+
+```markdown
+# WRONG — too specific, no $PROJECT_DIR prefix
+Write your report to logs/security-review-PR-123.md
+
+# CORRECT — parameterized convention with $PROJECT_DIR
+Write your report to $PROJECT_DIR/logs/{agent-name}-{timestamp}.md
+```
+
+**Impact**: Agent only works for one invocation pattern.
+
+### Pitfall 3: Missing Tool Constraints
+
+Agents with Write/Edit/Bash access but no constraints on what they can modify.
+
+**Prevention**: Include explicit allowed/forbidden sections:
+
+```markdown
+## Tool Usage Constraints
+
+### Write
+- **Allowed**: Source files (within scope), $PROJECT_DIR/logs/
+- **Forbidden**: Config files, files outside task scope
+
+### Bash
+- **Allowed**: Quality checks, read-only git, file inspection
+- **Forbidden**: Git modifications, package installation, destructive commands
+```
+
+### Pitfall 4: No Diagnostic Output
+
+Agents that complete work but produce no observable artifact for the orchestrator.
+
+**Prevention**: Always include a diagnostic output section, even for simple agents:
+
+```markdown
+## Diagnostic Output
+
+Write to: $PROJECT_DIR/logs/diagnostics/{agent-name}-{timestamp}.yaml
+```
+
+### Pitfall 5: Missing Permissions Documentation
+
+Agent works in development but fails in other environments because tool permissions aren't documented.
+
+**Prevention**: Always include a "Permissions Setup" section (see agent-conventions.md).
+
+### Pitfall 6: Undocumented Skill Dependencies
+
+Agent silently depends on skills listed in frontmatter but doesn't reference them in the body.
+
+**Prevention**: Include a "Related Skills" section explaining what each skill dependency provides.
+
+---
+
+## Generate-and-Customize Contract
+
+All generated agents are scaffolds, not production-ready output.
+
+### Required Disclaimer
+
+Every generated agent should include this understanding in the post-generation summary:
+
+```
+This is a scaffold — a starting point for your agent. You should:
+1. Review and customize the identity and expertise sections
+2. Adjust tool permissions to match your project's security requirements
+3. Configure permissions in .claude/settings.json
+4. Test by invoking via Task tool and reviewing output quality
+5. Add project-specific protocol steps as needed
+```
+
+### Why This Matters
+
+Agent bodies define system prompts that anchor all behavior. A generic scaffold provides structure, but domain expertise and project-specific conventions must be customized by the user.

package/skills/create-subagent/references/decision-framework.md

@@ -0,0 +1,134 @@
+# Decision Framework
+
+Interview questions and classification logic for the create-subagent pipeline. The orchestrator uses this at Stage 0 (Pre-Flight) for interview + routing, and Stage 1 (Classify) for tool permissions and configuration decisions.
+
+---
+
+## Stage 0: Adaptive Interview
+
+### Core Questions (Always Ask)
+
+Present all 5 questions to the user via AskUserQuestion. These determine routing (single vs pipeline/teams redirect), tool needs, and diagnostic requirements.
+
+| # | Question | What It Reveals |
+|---|----------|-----------------|
+| Q1 | What is this agent's identity and mission? Describe WHO it is and what expertise it has. Give 2-3 examples of how it would be invoked. | System-prompt content, invocation patterns, scope |
+| Q2 | What tools does it need access to? (Read/Write/Edit/Bash/Glob/Grep/WebFetch/WebSearch/Task/other) | Tool permissions, safety constraints |
+| Q3 | Does it orchestrate multiple distinct stages or operations, or perform a single focused task? | Routing check (single → proceed, multiple → follow-ups → possible redirect) |
+| Q4 | Does it need to emit structured diagnostic output (logs, reports, YAML)? | Diagnostic section, output paths |
+| Q5 | Should it have restricted permissions, or full access to available tools? | permissionMode, tool allowlist |
+
+### Follow-Up Questions (Conditional)
+
+Ask follow-ups when Q3 indicates multiple stages/operations. These determine whether to redirect to create-skill.
+
+| Trigger | Follow-Up Questions |
+|---------|-------------------|
+| Q3 = "multiple stages" | Q6: Do the stages depend on each other's output? (sequential vs parallel) |
+| Q3 = "multiple stages" | Q7: Do workers need to communicate with each other directly? (Task tool vs Agent Teams) |
+| Q4 = "yes, diagnostics" | Q8: What format — YAML report, Markdown log, or both? |
+| Q5 = "restricted" | Q9: Which specific tools should be allowed? Which should be explicitly forbidden? |
+
+### Interview Behavior
+
+- Present Q1-Q5 in a single AskUserQuestion call (not one-at-a-time)
+- If answers are ambiguous, ask 1-2 clarifying follow-ups (do not over-interview)
+- If the user provides a `--doc` requirements document, extract Q1-Q5 answers from it and present for confirmation instead of asking fresh
+- Total interview: 1-2 AskUserQuestion rounds maximum
+
+---
+
+## Stage 0: Routing Check
+
+After receiving all interview answers, check whether the use case requires pipeline orchestration. Sub-agents are single-purpose — they cannot spawn other sub-agents.
+
+### Routing Logic
+
+```
+Q3 = "single focused task"                → PROCEED to Stage 1 (single-agent)
+Q3 = "multiple stages"
+  AND Q6 = "dependent stages"             → REDIRECT to /create-skill
+Q3 = "multiple stages"
+  AND Q7 = "direct worker communication"  → REDIRECT to /create-skill
+Q3 = "multiple stages"
+  AND Q6 = "independent"
+  AND Q7 = "no direct communication"      → PROCEED to Stage 1 (independent parallel
+                                             workers are still single-purpose agents —
+                                             create each one separately)
+```
+
+### Redirect Message
+
+If routing check triggers a redirect, present this message and STOP:
+
+```
+This use case requires a pipeline skill that orchestrates multiple sub-agents.
+Sub-agents are single-purpose — they can't spawn other sub-agents.
+
+Use /create-skill instead. It will generate:
+- An orchestrating skill (SKILL.md) with pipeline stages
+- Dedicated sub-agent files (.claude/agents/*.md) for each stage
+
+The generated sub-agents will have deterministic behavior locked into their
+system prompts, and the orchestrating skill handles sequencing, error handling,
+and synthesis.
+```
+
+Do NOT proceed to Stage 1 after a redirect. Write diagnostic YAML with `outcome: redirected`.
+
+---
+
+## Stage 1: Two-Decision Classification
+
+After the interview (and routing check passes), make two independent decisions. Each decision is self-contained.
+
+### Decision A: Tool Permissions
+
+Determines the agent's tool access and safety constraints.
+
+```
+Q5 = "full access"                       → no tools: list in frontmatter (inherits all)
+Q5 = "restricted"
+  AND Q9 = specific list                → tools: [listed tools] in frontmatter
+Q2 = includes "Write" or "Edit"          → include quality gate guidance in protocol
+Q2 = includes "Bash"                     → include allowed/forbidden command lists in protocol
+```
+
+**Default**: Restrict tools to what the agent actually needs. Fewer tools = safer agent.
+
+### Decision B: Supporting Configuration
+
+Determines what additional configuration the agent needs.
+
+```
+Always:
+  → Include "Permissions Setup" section documenting manual config
+
+If Q4 = "yes, diagnostics":
+  → Include diagnostic output section with paths and schema
+  → Add subagent-output-templating to skills: dependency (if reporting to orchestrator)
+```
+
+### Classification Output
+
+After classification, present the two decisions to the user for confirmation before proceeding to Stage 2:
+
+```
+Classification:
+- Tool permissions: {full/restricted: [list]} — {one-line reason}
+- Configuration: {list of extras} — {one-line reason}
+
+Proceed with generation? [Yes / Adjust]
+```
+
+---
+
+## Edge Cases
+
+| Scenario | Resolution |
+|----------|------------|
+| Q3 = "multiple stages" but Q6/Q7 answers are ambiguous | Ask one clarifying question. If still ambiguous, default to redirect (safer to use create-skill than to create an infeasible agent). |
+| Agent needs Write but no quality gates exist in target project | Include quality gate section with "adapt to project's quality enforcement" note. |
+| User provides conflicting Q2/Q5 answers | Ask one clarifying question to resolve. |
+| Very complex agent (>250 lines estimated) | Warn about complexity. Suggest splitting into focused agent + orchestrating skill. |
+| User explicitly requests a pipeline agent | Redirect to create-skill. Explain: "Pipeline agents are infeasible as sub-agents because sub-agents cannot spawn other sub-agents." |