@qball-inc/the-bulwark 1.0.0

package/skills/pipeline-templates/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: pipeline-templates
+description: Pre-defined F# pipe workflows for multi-agent orchestration. Provides code review, fix validation, test audit, new feature, research & planning, and test execution pipelines. Triggered via PostToolUse hook after significant code changes.
+user-invocable: false
+---
+
+# Pipeline Templates
+
+## Overview
+
+This skill provides pre-defined F# pipe workflows for common multi-agent scenarios. Pipelines ensure:
+
+- **Deterministic orchestration**: Consistent agent sequencing
+- **Hard validation**: Block incorrect pipeline usage
+- **Progress tracking**: Log all pipeline stages
+- **Model optimization**: Right model for each stage
+
+**When to use**: Multi-agent work requiring more than simple exploration.
+
+**When NOT to use**: Single-agent tasks (explore, search, lookup) bypass pipeline validation automatically.
+
+## Pipeline Selection Guide
+
+Choose the appropriate pipeline based on your task:
+
+```
+Is this a multi-agent task?
+├─ No → No pipeline needed (single-agent bypass)
+└─ Yes → What type of work?
+    ├─ Reviewing existing code → Code Review Pipeline
+    ├─ Fixing a bug/issue → Fix Validation Pipeline
+    ├─ Auditing test quality → Test Audit Pipeline
+    ├─ Implementing new functionality → New Feature Pipeline
+    ├─ Research before implementation → Research & Planning Pipeline
+    └─ Running tests and fixing failures → Test Execution & Fix Pipeline
+```
+
+## Available Pipelines
+
+| Pipeline | Use Case | Model Pattern | Reference |
+|----------|----------|---------------|-----------|
+| Code Review | PR review, code audit | Sonnet (role-based, 4 sections) | `references/code-review.md` |
+| Fix Validation | Bug fixes, issue resolution | Sonnet (analyze) → Opus (fix) → Sonnet (validate) → Sonnet (review) | `references/fix-validation.md` |
+| Test Audit | Test quality assessment | Haiku (classify) → Sonnet (detect) → Sonnet (audit) | `references/test-audit.md` |
+| New Feature | Feature implementation | Haiku (research) → Opus (write) → Sonnet (review) | `references/new-feature.md` |
+| Research & Planning | Pre-implementation research | Haiku (lookup) → Sonnet (review) → loop(min=3) | `references/research-planning.md` |
+| Test Execution & Fix | Run tests, fix failures | Haiku (execute) → Sonnet (analyze) → Opus (fix) | `references/test-execution-fix.md` |
+| **Code Change Workflow** | **Full automation after code edit** | **Composite: chains multiple pipelines** | `references/code-change-workflow.md` |
+
+### Pipeline Architecture Notes
+
+**Role-Based Agents**: Code Review pipeline uses general-purpose sub-agents with specific roles. Each agent loads the `code-review` skill and references a specific section (Security, Type Safety, Linting, Coding Standards).
+
+**Custom Sub-Agents**: Fix Validation pipeline uses custom sub-agents (`bulwark-issue-analyzer`, `bulwark-fix-validator`) that encapsulate stage behavior and load relevant skills via frontmatter.
+
+**Code-Writing Agent**: Fix Validation and New Feature pipelines use `bulwark-implementer` (custom sub-agent, Opus) for code-writing stages with built-in quality enforcement.
+
+## Model Selection
+
+Reference `subagent-prompting` skill for the task-type rubric:
+
+| Task Type | Model | Examples |
+|-----------|-------|----------|
+| **Lookups & Execute** | Haiku | Web fetch, run tests, file search, lint |
+| **Review & Analyze** | Sonnet | Code review, failure analysis, audits |
+| **Write & Fix** | Opus | Write code, write tests, apply fixes |
+
+**Override rule**: If a custom agent specifies `model:` in frontmatter, use that model instead.
+
+## Validation Rules
+
+### Valid Pipeline Invocation
+
+A pipeline invocation is valid when:
+
+1. Uses a defined pipeline template from this skill
+2. Specifies model for each stage (or uses default from task-type rubric)
+3. Includes 4-part prompt for each Task (GOAL/CONSTRAINTS/CONTEXT/OUTPUT)
+4. Reads previous stage output before invoking next stage
+
+### Invalid Invocation (Warning/Block)
+
+The following patterns trigger validation warnings:
+
+| Pattern | Issue | Resolution |
+|---------|-------|------------|
+| Ad-hoc multi-agent with no pipeline | Unpredictable orchestration | Choose appropriate pipeline |
+| Missing model specification | May use wrong model | Specify model or use rubric |
+| Skipping stages without justification | Incomplete workflow | Document skip reason |
+| Using Opus for simple tasks | Wasteful | Use Haiku for lookups |
+
+### Hook Behavior (PostToolUse)
+
+The PostToolUse hook on Write|Edit:
+- **Skips silently**: Small changes below threshold
+- **Suggests pipeline**: Significant changes inject `additionalContext` with pipeline recommendation
+- **Blocks**: Never (suggestion only, not blocking)
+
+## File Type to Pipeline Mapping
+
+When triggered by PostToolUse hook after Write/Edit, select pipeline based on file modified:
+
+| File Pattern | Extension | Recommended Pipeline |
+|--------------|-----------|---------------------|
+| Code files | `.ts`, `.js`, `.py`, `.go`, `.rs`, `.java` | Code Review |
+| Test files | `*.test.ts`, `*.spec.js`, `test_*.py` | Test Audit |
+| Config files | `.json`, `.yaml`, `.toml`, `.env` | Code Review (security focus) |
+| Script files | `.sh`, `.bash`, `.ps1` | Code Review (security focus) |
+| Documentation | `.md`, `.txt`, `.rst` | Light review or skip |
+| Data files | `.xlsx`, `.csv`, `.pdf` | Manual review suggested |
+
+### Small Change Bypass
+
+Skip pipeline for small changes (threshold by file type):
+
+| File Type | Threshold | Rationale |
+|-----------|-----------|-----------|
+| Code | < 5 lines | Minor fixes don't need full review |
+| Tests | < 10 lines | Single test additions are low risk |
+| Config | < 3 lines | Single value changes are quick to verify |
+| Documentation | <= 10 lines | Typo fixes and small updates |
+| Scripts | < 3 lines | Security-sensitive, low threshold |
+| Data | Any change | Always significant, suggest review |
+
+Changes at or below threshold are skipped silently. Changes above threshold trigger pipeline suggestion.
+
+## Pipeline Execution Pattern
+
+All pipelines follow this execution pattern:
+
+```fsharp
+// F# pipe syntax for workflow orchestration
+
+// Sequential execution (each stage reads previous stage's output)
+Stage1 (task)     // First agent runs
+|> Stage2 (task)  // Reads Stage1 output, runs
+|> Stage3 (task)  // Reads Stage2 output, runs
+|> (if condition  // Conditional branching
+    then StageA
+    else StageB)
+|> LOOP(max=N)    // Optional iteration
+
+// Parallel execution (agents run concurrently, results merged)
+[Stage1a, Stage1b, Stage1c]  // Array notation = parallel
+|> Stage2 (reads all Stage1 outputs)
+```
+
+**Key principles**:
+- **Sequential** (`|>`): Each stage reads the previous stage's log output
+- **Parallel** (`[]`): Stages in array notation run concurrently via multiple Task calls in a single message
+- Conditional branches based on stage results
+- Loops have explicit iteration limits
+- All output logged to `logs/`
+
+## Progress Tracking
+
+Pipeline progress is tracked via hooks:
+
+| Event | Hook | Log Entry |
+|-------|------|-----------|
+| Stage start | SubagentStart | `[timestamp] SubagentStart: agent_id (type)` |
+| Stage end | SubagentStop | `[timestamp] SubagentStop: agent_id` |
+
+Logs written to: `logs/pipeline-tracking.log`
+
+## Related Skills
+
+| Skill | Relationship |
+|-------|--------------|
+| `subagent-prompting` | 4-part template, model selection rubric |
+| `subagent-output-templating` | Output format for pipeline stages |
+
+## Quick Reference
+
+```fsharp
+// Code Review (role-based agents, parallel execution)
+[SecurityReviewer (section: Security),          // Sonnet - role-based
+ TypeSafetyReviewer (section: Type Safety),     // Sonnet - role-based
+ LintReviewer (section: Linting),               // Sonnet - role-based
+ StandardsReviewer (section: Coding Standards)] // Sonnet - role-based
+|> ReviewSynthesizer (consolidates all findings)
+|> (if critical_issues then FixWriter else Done)
+
+// Fix Validation (custom sub-agents)
+IssueAnalyzer (bulwark-issue-analyzer, produces debug_report)
+|> FixWriter (bulwark-implementer, implements fix)
+|> (if !tests_cover_scenario                              // Only if tests don't exist
+    then TestWriter |> TestAudit (mock-detection only)    // Audit generated tests for T1-T4
+    else TestAudit (if FixWriter wrote tests))            // Audit implementer tests for T1-T4
+|> FixValidator (bulwark-fix-validator, validates against debug_report)
+|> CodeReviewer (reviews all, approves/rejects)
+|> (if !approved then IssueAnalyzer else Done)
+|> LOOP(max=3)
+
+// Test Audit (Main Context Orchestration - skill-based)
+TestClassifier |> MockDetector |> AuditSynthesizer
+|> (if REWRITE_REQUIRED then TestRewriter else Done)
+|> LOOP(max=2)
+
+// New Feature
+Researcher |> Architect |> Implementer (bulwark-implementer) |> TestWriter |> TestAudit |> CodeReviewer
+
+// Research & Planning (min 3 iterations)
+Researcher |> PlanDraft |> PlanReviewer |> LOOP(min=3)
+
+// Test Execution & Fix (orchestrator fixes, PostToolUse hook enforces quality)
+TestRunner |> (if failures then FailureAnalyzer |> FixWriter (orchestrator) |> LOOP else Done)
+
+// CODE CHANGE WORKFLOW (Composite - chains pipelines after code edit)
+// See references/code-change-workflow.md for full details
+CodeReviewPipeline
+|> TestAuditPipeline (Main Context Orchestration)
+|> TestExecutionPipeline
+|> (if code_bugs then FixValidationPipeline else Done)
+```

package/skills/pipeline-templates/references/code-change-workflow.md

@@ -0,0 +1,277 @@
+# Code Change Workflow (Composite Pipeline)
+
+## Purpose
+
+Full automation after code file creation or edit. Chains multiple pipelines to ensure:
+- Code quality (review)
+- Test coverage and quality (audit)
+- Test execution (verification)
+- Issue resolution (fix validation loop)
+
+## When to Use
+
+- After creating or editing code files (`.ts`, `.js`, `.py`, `.go`, `.rs`, `.java`)
+- PostToolUse hook suggests this workflow for significant code changes
+- Manual invocation when comprehensive quality assurance needed
+
+## Entry Points
+
+| Trigger | How |
+|---------|-----|
+| PostToolUse hook | Automatic suggestion after Write/Edit on code files above threshold |
+| Manual | "Run code change workflow on [files]" |
+| After feature implementation | Chain from New Feature pipeline |
+
+---
+
+## Composite Pipeline Definition
+
+```fsharp
+// CODE CHANGE WORKFLOW
+// Trigger: Code file created or significantly edited
+// Output: Reviewed, tested, validated code
+
+// PHASE 1: Code Review (if code-review skill available)
+CodeReviewPipeline (optional, requires P4.1)
+|> (if critical_issues then FixWriter else Continue)
+
+// PHASE 2: Test Audit (Main Context Orchestration)
+// Orchestrator loads test-audit skill, follows instructions
+TestClassifier (Haiku, surface classification)
+|> MockDetector (Sonnet, T1-T4 violations)
+|> AuditSynthesizer (Sonnet, REWRITE_REQUIRED directive)
+|> (if REWRITE_REQUIRED then TestRewriter(Opus) else Continue)
+|> LOOP(max=2)
+
+// PHASE 3: Test Execution
+TestRunner (Haiku, execute tests)
+|> (if failures > 0
+    then FailureAnalyzer (Sonnet)
+         |> (if test_issue then TestFixWriter(Opus) else CodeBugDetected)
+    else Continue)
+|> LOOP(max=3)
+
+// PHASE 4: Fix Validation (if code bugs detected)
+(if CodeBugDetected
+    then IssueAnalyzer (bulwark-issue-analyzer)
+         |> FixWriter (Opus)
+         |> TestWriter (Opus)
+         |> FixValidator (bulwark-fix-validator)
+         |> CodeReviewer (Sonnet)
+         |> (if !approved then IssueAnalyzer else Done)
+         |> LOOP(max=3)
+    else Done)
+```
+
+---
+
+## Phase Details
+
+### Phase 1: Code Review (Optional)
+
+**Dependency**: Requires `code-review` skill (P4.1)
+
+**Skip Condition**: If code-review skill not available, proceed to Phase 2
+
+**Stages**:
+1. SecurityReviewer (Sonnet) - OWASP patterns
+2. TypeSafetyReviewer (Sonnet) - any, null, unsafe assertions
+3. LintReviewer (Sonnet) - complexity, formatting
+4. StandardsReviewer (Sonnet) - naming, patterns
+5. ReviewSynthesizer (Sonnet) - consolidate findings
+6. FixWriter (Opus) - fix critical/high issues if any
+
+**Output**: Review findings, fixes applied if critical
+
+---
+
+### Phase 2: Test Audit (Main Context Orchestration)
+
+**Pattern**: Orchestrator loads `test-audit` skill and follows its instructions directly. No wrapper agent needed.
+
+**Why Main Context Orchestration?**
+- Test audit requires 3-stage pipeline (classification → detection → synthesis)
+- Sub-agents cannot spawn other sub-agents
+- Orchestrator must stay in main context to spawn each stage
+
+**Stages**:
+1. Load `test-audit` skill
+2. Follow skill instructions to spawn:
+   - TestClassifier (Haiku) → `logs/test-classification-{YYYYMMDD-HHMMSS}.yaml`
+   - MockDetector (Sonnet) → `logs/mock-detection-{YYYYMMDD-HHMMSS}.yaml`
+   - AuditSynthesizer (Sonnet) → `logs/test-audit-{YYYYMMDD-HHMMSS}.yaml`
+3. Read `REWRITE_REQUIRED` directive from audit output
+4. If true: Orchestrator (Opus) rewrites flagged tests
+5. Loop up to 2 times to verify rewrites resolved issues
+
+**Output**: Test audit report, tests rewritten if needed
+
+---
+
+### Phase 3: Test Execution
+
+**Purpose**: Run tests and fix test-related failures
+
+**Stages**:
+1. TestRunner (Haiku) - Execute `just test` or equivalent
+2. If failures:
+   - FailureAnalyzer (Sonnet) - Categorize failures
+   - Determine: Is this a test issue or code bug?
+   - If test issue: TestFixWriter (Opus) fixes test
+   - If code bug: Flag for Phase 4
+3. Re-run tests to verify
+4. Loop up to 3 times
+
+**Failure Categories**:
+| Category | Resolution |
+|----------|------------|
+| Environment | Fix test setup (ports, deps) |
+| Assertion | Update test or fix test logic |
+| Timeout | Increase timeout or optimize |
+| Flaky | Fix race condition |
+| **Code Bug** | Escalate to Phase 4 |
+
+**Output**: Passing tests OR code bugs identified for Phase 4
+
+---
+
+### Phase 4: Fix Validation (Conditional)
+
+**Trigger**: Only runs if Phase 3 detected code bugs (not test issues)
+
+**Agents Required**:
+- `bulwark-issue-analyzer` (P1.2) - Root cause analysis
+- `bulwark-fix-validator` (P1.3) - Validation against debug report
+
+**Stages**:
+1. IssueAnalyzer (bulwark-issue-analyzer, Sonnet)
+   - Produces debug report at `logs/debug-reports/{issue-id}.yaml`
+   - Includes validation plan (P1/P2/P3 tiered tests)
+2. FixWriter (Opus) - Implement fix per root cause
+3. TestWriter (Opus) - Add tests per validation plan
+4. FixValidator (bulwark-fix-validator, Sonnet)
+   - Execute validation plan
+   - Assess confidence (high/medium/low)
+   - Escalate to manual testing if needed
+5. CodeReviewer (Sonnet) - Approve/reject fix
+6. Loop if not approved (max 3 iterations)
+
+**Output**: Verified fix with confidence assessment
+
+---
+
+## Orchestrator Execution Flow
+
+```markdown
+## Step 1: Determine Entry Point
+- Hook-triggered: additionalContext suggests workflow
+- Manual: User requests comprehensive review
+
+## Step 2: Phase 1 - Code Review (if available)
+IF code-review skill exists:
+    Load code-review skill
+    Execute Code Review Pipeline stages
+    Apply fixes for critical/high issues
+ELSE:
+    Skip to Phase 2
+
+## Step 3: Phase 2 - Test Audit
+Load test-audit skill
+Follow Main Context Orchestration instructions:
+    - Spawn TestClassifier (Haiku)
+    - Read classification, spawn MockDetector (Sonnet)
+    - Read violations, spawn AuditSynthesizer (Sonnet)
+    - Read REWRITE_REQUIRED directive
+IF REWRITE_REQUIRED:
+    Rewrite flagged tests (Opus)
+    Loop (max 2)
+
+## Step 4: Phase 3 - Test Execution
+Spawn TestRunner (Haiku)
+IF failures:
+    Spawn FailureAnalyzer (Sonnet)
+    IF test_issue:
+        Fix test (Opus)
+        Re-run (loop max 3)
+    ELSE:
+        Mark CodeBugDetected
+
+## Step 5: Phase 4 - Fix Validation (if needed)
+IF CodeBugDetected:
+    Spawn IssueAnalyzer (bulwark-issue-analyzer)
+    Read debug report
+    Implement fix (Opus)
+    Write tests (Opus)
+    Spawn FixValidator (bulwark-fix-validator)
+    Read validation results
+    Spawn CodeReviewer (Sonnet)
+    IF !approved: Loop (max 3)
+
+## Step 6: Report Completion
+Summarize all phases:
+- Code review findings (if run)
+- Test audit results
+- Test execution status
+- Fix validation outcome (if run)
+```
+
+---
+
+## Dependency Status
+
+| Phase | Dependencies | Status |
+|-------|--------------|--------|
+| Phase 1 | code-review skill (P4.1) | Not yet built |
+| Phase 2 | test-audit skill (P0.8) | **Complete** |
+| Phase 3 | Test Execution pipeline template | **Complete** |
+| Phase 4 | bulwark-issue-analyzer (P1.2), bulwark-fix-validator (P1.3) | Not yet built |
+
+**Current Capability**: Phases 2 and 3 can run today. Phases 1 and 4 require future work.
+
+---
+
+## Termination Conditions
+
+| Condition | Action |
+|-----------|--------|
+| All phases complete, no issues | Workflow done |
+| Phase 2 loop exceeds max=2 | Report remaining audit issues, continue |
+| Phase 3 loop exceeds max=3 | Report unfixable test failures, escalate |
+| Phase 4 loop exceeds max=3 | Report unresolved code bug, escalate to manual |
+| Manual testing required | Notify user, workflow pauses |
+
+---
+
+## User Communication
+
+At key points, the orchestrator should inform the user:
+
+```markdown
+## Code Change Workflow Progress
+
+**Phase 1 (Code Review)**: [Skipped / Completed - N findings]
+**Phase 2 (Test Audit)**: [Completed - REWRITE_REQUIRED: yes/no]
+**Phase 3 (Test Execution)**: [Completed - N tests passed, M failed]
+**Phase 4 (Fix Validation)**: [Not needed / Completed - confidence: high/medium/low]
+
+Overall Status: [Success / Requires Attention]
+```
+
+---
+
+## Related Pipelines
+
+| Pipeline | Relationship |
+|----------|--------------|
+| Code Review | Phase 1 of this workflow |
+| Test Audit | Phase 2 of this workflow (Main Context Orchestration) |
+| Test Execution & Fix | Phase 3 of this workflow |
+| Fix Validation | Phase 4 of this workflow |
+
+---
+
+## Future Enhancements
+
+- **Parallel execution**: Run Code Review and Test Audit in parallel (Phase 1 || Phase 2)
+- **Incremental mode**: Only audit/test files related to the change
+- **CI integration**: Hook into CI/CD for automated workflow trigger