@qball-inc/the-bulwark 1.0.0

package/skills/pipeline-templates/references/new-feature.md

@@ -0,0 +1,335 @@
+# New Feature Pipeline
+
+## Purpose
+
+Implement new functionality with proper research, implementation, testing, and review.
+
+## When to Use
+
+- Adding new features
+- Implementing new modules
+- Creating new components
+- Building new integrations
+
+## Pipeline Definition
+
+```fsharp
+// New Feature Pipeline
+// Trigger: Feature request, new capability needed
+// Output: Implemented feature with tests and review
+
+Researcher (gather requirements & patterns)      // Haiku - lookups
+|> Architect (design approach)                   // Sonnet - analysis
+|> Implementer (write code)                      // Opus - bulwark-implementer
+|> TestWriter (write tests)                      // Opus - write tests
+|> TestAudit (mock-detection only)               // Audit any new/modified tests for T1-T4
+|> CodeReviewer (review implementation)          // Sonnet - review
+|> (if !approved
+    then Implementer                             // Loop back
+    else Done)
+|> LOOP(max=2)                                   // Max 2 revision rounds
+```
+
+## Stage Details
+
+### Stage 1: Researcher
+
+**Model**: Haiku (lookup task)
+
+**GOAL**: Gather information needed for implementation.
+
+**CONSTRAINTS**:
+- Do NOT modify any files
+- Focus on relevant patterns only
+- Document sources
+
+**CONTEXT**:
+- Feature requirements
+- Project structure
+- Related existing code
+
+**OUTPUT**: Research findings
+```yaml
+research:
+  requirements:
+    - "User can export data to CSV"
+    - "Export includes all visible columns"
+    - "Large exports should stream"
+  existing_patterns:
+    - file: src/utils/export.ts
+      pattern: "Existing PDF export can be extended"
+    - file: src/components/DataTable.tsx
+      pattern: "Column visibility tracked in state"
+  dependencies:
+    - "csv-stringify for CSV generation"
+    - "Existing streaming infrastructure"
+  considerations:
+    - "Memory usage for large datasets"
+    - "Progress indication for user"
+```
+
+### Stage 2: Architect
+
+**Model**: Sonnet (design/analysis task)
+
+**GOAL**: Design implementation approach.
+
+**CONSTRAINTS**:
+- Do NOT modify any files
+- Consider existing patterns
+- Identify risks and trade-offs
+
+**CONTEXT**:
+- Research findings from Stage 1
+- Project architecture
+- Performance requirements
+
+**OUTPUT**: Design document
+```yaml
+design:
+  approach: "Extend existing export utility with CSV support"
+  components:
+    - name: CSVExporter
+      location: src/utils/csv-export.ts
+      responsibility: "Convert data to CSV format"
+    - name: ExportButton
+      location: src/components/ExportButton.tsx
+      responsibility: "UI for triggering export"
+  data_flow:
+    - "User clicks export button"
+    - "DataTable provides visible columns and data"
+    - "CSVExporter streams data to download"
+  trade_offs:
+    - pro: "Reuses existing export infrastructure"
+    - con: "Adds dependency on csv-stringify"
+  risks:
+    - "Memory pressure on large exports"
+    - mitigation: "Use streaming with chunk size limit"
+```
+
+### Stage 3: Implementer
+
+**Agent**: `bulwark-implementer` (custom sub-agent)
+
+**Model**: Opus (code writing with quality enforcement)
+
+**GOAL**: Implement the feature per design.
+
+**CONSTRAINTS**:
+- Follow the design from Stage 2
+- Use existing patterns
+- Do NOT over-engineer
+- Keep changes minimal
+- Max 3 quality gate retries before escalation
+
+**CONTEXT** (must include for `context: fork`):
+- Design document from Stage 2 (include full design output or path)
+- Requirements from Stage 1 research
+- Existing patterns to follow
+- Project coding standards
+
+**Invocation**:
+```
+Task: subagent_type=bulwark-implementer
+Prompt:
+  GOAL: Implement the feature based on the design document.
+  CONSTRAINTS: Follow the design. Write tests. Max 3 quality gate retries.
+  CONTEXT:
+    mode: feature
+    design_document: {Stage 2 design output or path}
+    requirements: {from Stage 1 research}
+    existing_patterns: {relevant pattern files}
+  OUTPUT: Implementation report at logs/implementer-{id}-{timestamp}.yaml
+```
+
+**OUTPUT**: Implementation report at `logs/implementer-{id}-{timestamp}.yaml`
+```yaml
+implementation_report:
+  changes:
+    files_created:
+      - path: src/utils/csv-export.ts
+        purpose: "CSV export utility"
+        lines: 45
+    files_modified:
+      - path: src/components/DataTable.tsx
+        changes: "Added export button integration"
+    dependencies_added:
+      - name: csv-stringify
+        version: "^6.0.0"
+        reason: "CSV generation"
+  tests:
+    files_created:
+      - path: tests/utils/csv-export.test.ts
+        cases: ["exports simple data", "handles special characters", "streams large datasets"]
+  quality_gates:
+    typecheck: passed
+    lint: passed
+    retries: 0
+  pipeline_suggestions:
+    - pipeline: "Code Review"
+      target_files: [src/utils/csv-export.ts, src/components/DataTable.tsx]
+      reason: "New feature implementation, 2 files"
+```
+
+**SA6 Note**: The implementer returns pipeline suggestions with MANDATORY language in its summary. The orchestrator MUST evaluate each suggestion per SA6.
+
+### Stage 4: TestWriter
+
+**Model**: Opus (test writing required)
+
+**GOAL**: Write tests for the new feature.
+
+**CONSTRAINTS**:
+- Tests verify real behavior (T1)
+- No mocking system under test (T2)
+- Cover happy path and edge cases
+- Integration tests for component interaction
+
+**CONTEXT**:
+- Implementation from Stage 3
+- Project test patterns
+- Feature requirements
+
+**OUTPUT**: Tests
+```yaml
+tests:
+  unit_tests:
+    - file: tests/utils/csv-export.test.ts
+      cases:
+        - "exports simple data correctly"
+        - "handles special characters"
+        - "streams large datasets"
+  integration_tests:
+    - file: tests/components/DataTable.export.test.ts
+      cases:
+        - "export button triggers download"
+        - "respects column visibility"
+```
+
+### Stage 4b: TestAudit (Conditional)
+
+**Trigger**: Runs if **any** test files were created or modified in Stage 3 (Implementer) OR Stage 4 (TestWriter). This ensures implementer-written tests receive T1-T4 audit even when TestWriter adds no new tests.
+
+**Model**: Haiku (classification) → Sonnet (detection)
+
+**Skills**: `mock-detection` (lighter weight than full test-audit)
+
+**GOAL**: Verify new/modified tests don't have T1-T4 violations before proceeding to review.
+
+**CONSTRAINTS**:
+- Audit test files touched by Implementer (Stage 3) and/or TestWriter (Stage 4)
+- Block pipeline if T1 violation found (mocking system under test)
+- Warn on T2-T4 violations but allow proceed
+- Do NOT audit existing tests (only new/modified in this pipeline run)
+
+**CONTEXT**:
+- List of test files created/modified by Implementer and/or TestWriter
+- Design document for understanding what's being tested
+
+**OUTPUT**: Audit result
+```yaml
+test_audit:
+  files_audited:
+    - path: tests/utils/csv-export.test.ts
+      status: passed | failed
+      violations: []
+
+  t1_violations: 0  # Critical - blocks pipeline
+  t2_violations: 0  # High - warning only
+  t3_violations: 0  # Medium - warning only
+  t4_violations: 0  # Low - warning only
+
+  proceed: true | false
+  notes: "All generated tests follow T1-T4 rules"
+```
+
+**Failure Handling**:
+- If T1 violation: Return to TestWriter with feedback, request rewrite
+- If T2-T4 violations: Log warning, proceed to CodeReviewer
+- Max 2 audit iterations before escalating to user
+
+### Stage 5: CodeReviewer
+
+**Model**: Sonnet (review task)
+
+**GOAL**: Review implementation quality and completeness.
+
+**CONSTRAINTS**:
+- Do NOT modify any files
+- Check against requirements
+- Verify tests are adequate
+- Check for security issues
+
+**CONTEXT**:
+- Original requirements
+- Design document
+- Implementation
+- Tests
+
+**OUTPUT**: Review decision
+```yaml
+review:
+  approved: true | false
+  checklist:
+    requirements_met: true
+    tests_adequate: true
+    security_checked: true
+    performance_acceptable: true
+  concerns: []
+  recommendations:
+    - "Consider adding rate limiting for exports"
+```
+
+### Loop Condition
+
+If `approved: false`, loop back to Stage 3 (`bulwark-implementer`) with:
+- Review feedback
+- Specific concerns to address
+- Previous implementation report path
+
+**Max iterations**: 2 (prevent scope creep)
+
+## Example Invocation
+
+```markdown
+## Pipeline: New Feature
+
+### Stage 1: Researcher
+Task: subagent_type=general-purpose, model=haiku
+Prompt: [4-part prompt with feature requirements]
+
+### Stage 2: Architect
+Task: subagent_type=general-purpose, model=sonnet
+Prompt: [4-part prompt, reads research]
+
+### Stage 3: Implementer
+Task: subagent_type=bulwark-implementer
+Prompt: [4-part prompt with design doc, requirements, existing patterns]
+Output: Implementation report at logs/implementer-{id}-{timestamp}.yaml
+
+### Stage 4: TestWriter
+Task: subagent_type=general-purpose, model=opus
+Prompt: [4-part prompt, tests implementation]
+
+### Stage 5: CodeReviewer
+Task: subagent_type=general-purpose, model=sonnet
+Prompt: [4-part prompt, reviews all]
+
+### Loop Check
+If not approved and iterations < 2:
+  Go to Stage 3 (bulwark-implementer) with feedback + previous implementation report
+```
+
+## Success Criteria
+
+- Requirements researched and understood
+- Design documented before implementation
+- Implementation follows design
+- Tests verify real behavior
+- Review approves or revisions complete
+
+## Related Pipelines
+
+- **Research & Planning**: For more extensive research phase
+- **Code Review**: For reviewing without implementation
+- **Fix Validation**: For fixing issues found in review

package/skills/pipeline-templates/references/research-brainstorm.md

@@ -0,0 +1,161 @@
+# Research & Brainstorm Pipeline
+
+## Purpose
+
+Deep multi-viewpoint research followed by role-based brainstorming to produce authoritative analysis for task brief creation. Uses two independent skills — `bulwark-research` and `bulwark-brainstorm` — across multiple sessions.
+
+## When to Use
+
+- Complex topics requiring structured research before implementation
+- Multi-topic analysis with cross-topic synthesis
+- Technology evaluations, architecture decisions, methodology design
+- Any task where "should we build this?" precedes "how do we build this?"
+
+## Pipeline Definition
+
+```fsharp
+// Research & Brainstorm Pipeline (multi-session)
+// Each box is a separate session due to token budget constraints
+
+// === Single Topic ===
+
+BulwarkResearch(topic)              // Session N: 5 Sonnet parallel + synthesis
+|> BulwarkBrainstorm(topic)         // Session N+1: 5 Opus sequenced + synthesis
+
+// === Multi-Topic ===
+
+// Phase 1: Research (one session per topic)
+[BulwarkResearch(topic1),
+ BulwarkResearch(topic2),
+ BulwarkResearch(topic3)]           // N sessions (1 per topic)
+
+// Phase 1 Gate: Cross-topic synthesis (orchestrator-only, no sub-agents)
+|> CrossTopicResearchSynthesis      // 1 session: identify interactions, gate decision
+
+// Phase 2: Brainstorm (one session per surviving topic)
+|> [BulwarkBrainstorm(topic1'),
+    BulwarkBrainstorm(topic2')]     // N' sessions (topics may be merged/dropped)
+
+// Phase 2 Final: Authoritative document (orchestrator-only, no sub-agents)
+|> CrossTopicBrainstormSynthesis    // 1 session: authoritative document
+
+// Task brief creation from authoritative document
+|> TaskBriefCreation                // 1 session
+```
+
+## Session Budget
+
+| Scenario | Formula | Example (3 topics) |
+|----------|---------|---------------------|
+| Single topic | 2 sessions | 2 sessions |
+| Multi-topic | (N + 1) x 2 + 1 | (3+1) x 2 + 1 = 9 sessions |
+
+## Stage Details
+
+### BulwarkResearch (Per-Topic)
+
+**Skill**: `/bulwark-research`
+**Model**: Orchestrator = Opus (main), Agents = 5 Sonnet (parallel)
+**Input**: Topic description, optional context file
+**Output**: `logs/research/{topic-slug}/synthesis.md`
+
+Spawns 5 parallel Sonnet viewpoint agents:
+1. Direct Investigation
+2. Practitioner Perspective
+3. Contrarian Angle
+4. First Principles
+5. Prior Art / Historical
+
+### BulwarkBrainstorm (Per-Topic)
+
+**Skill**: `/bulwark-brainstorm`
+**Model**: Orchestrator = Opus (main), Agents = 5 Opus (sequenced)
+**Input**: Topic description, research synthesis from Phase 1
+**Output**: `logs/brainstorm/{topic-slug}/synthesis.md`
+
+Spawns 5 sequenced Opus role agents:
+1. Project SME (solo, first — autonomous codebase exploration)
+2. Senior Product Manager (parallel with 3, 4)
+3. Senior Technical Architect (parallel with 2, 4)
+4. Senior Development Lead (parallel with 2, 3)
+5. Critical Analyst (solo, last — reads all prior outputs)
+
+### CrossTopicResearchSynthesis (Gate Session)
+
+**Model**: Orchestrator only (no sub-agents)
+**Input**: All per-topic research synthesis documents
+**Output**: Cross-topic synthesis with gate decision
+
+Orchestrator reads all per-topic syntheses and identifies:
+- **Interactions**: How findings from one topic affect another
+- **Redundancies**: Where topics overlap
+- **Subsumptions**: Where one topic makes another irrelevant
+- **Conflicts**: Where topics lead to contradictory recommendations
+
+**Gate decision** (via AskUserQuestion): Which topics proceed to Phase 2?
+Options per topic: Proceed / Modify / Merge / Drop
+
+### CrossTopicBrainstormSynthesis (Final Session)
+
+**Model**: Orchestrator only (no sub-agents)
+**Input**: All per-topic brainstorm synthesis documents
+**Output**: Authoritative document for task brief creation
+
+Produces the definitive document with:
+- Executive summary
+- Per-topic summaries
+- Implementation recommendations
+- Scope definition (v1 vs. deferred)
+- Architecture overview
+- Build plan with ordering
+- Risks and mitigations
+- Decisions still required
+
+### TaskBriefCreation
+
+**Model**: Orchestrator only
+**Input**: Authoritative document
+**Output**: `plans/task-briefs/P{X}.{Y}-{name}.md`
+
+Standard task brief creation from the authoritative document. No sub-agents needed — the research and brainstorming are complete.
+
+## Output Structure
+
+```
+logs/
+  research/
+    {topic-slug}/
+      01-direct-investigation.md
+      02-practitioner.md
+      03-contrarian.md
+      04-first-principles.md
+      05-prior-art.md
+      synthesis.md
+  brainstorm/
+    {topic-slug}/
+      01-project-sme.md
+      02-product-manager.md
+      03-technical-architect.md
+      04-development-lead.md
+      05-critical-analyst.md
+      synthesis.md
+  diagnostics/
+    bulwark-research-{timestamp}.yaml
+    bulwark-brainstorm-{timestamp}.yaml
+```
+
+## Success Criteria
+
+- All viewpoint agents produced output (research phase)
+- All role agents produced output in correct sequence (brainstorm phase)
+- Synthesis documents follow templates
+- AskUserQuestion used at each checkpoint
+- Gate decision approved by user (multi-topic)
+- Authoritative document produced (multi-topic)
+- Task brief created from authoritative document
+
+## Related Pipelines
+
+- **Research & Planning**: Simpler research + iterative planning (no role-based brainstorming)
+- **New Feature**: For implementation after task brief creation
+- **Code Review**: For reviewing completed implementation