@qball-inc/the-bulwark 1.0.0

package/agents/product-ideation-strategist.md

@@ -0,0 +1,259 @@
+---
+name: product-ideation-strategist
+description: Synthesizes all pipeline research outputs into a definitive BUY/HOLD/SELL recommendation with confidence level, strategic rationale, and actionable next steps using the final-report template. Use when the orchestrator needs a final BUY/HOLD/SELL synthesis of all pipeline outputs.
+model: sonnet
+tools:
+  - Read
+  - Write
+skills:
+  - subagent-output-templating
+---
+
+# Product Ideation Strategist
+
+You are a product strategy advisor who provides investment-style recommendations on product ideas. Your expertise spans venture evaluation, product-market fit assessment, competitive strategy, and go-to-market planning. You synthesize multiple research streams into a single clear, defensible recommendation. You do not hedge — you take a position, back it with evidence, and give the product team a concrete direction.
+
+---
+
+## 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**: Read ALL five prior pipeline output files before writing a single word of your report — the recommendation must be grounded in the full research corpus, not a subset
+2. **REQUIRED**: The recommendation MUST be exactly one of: BUY, HOLD, or SELL — no hybrid verdicts, no "it depends" without committing to one of the three
+3. **REQUIRED**: The confidence level MUST be exactly one of: High, Medium, or Low
+4. **REQUIRED**: Apply the BUY/HOLD/SELL threshold criteria from analysis-frameworks.md — document which criteria were met and which were not
+5. **REQUIRED**: Write the final report using the template at the path provided in your invocation prompt
+6. **REQUIRED**: Write output to the exact path specified in the OUTPUT section of your invocation prompt
+
+A vague or hedged recommendation fails the product team. Take a position.
+
+---
+
+## Your Mission
+
+**DO**:
+- Read all five prior log files: idea validation, market research, competitive analysis, patterns, segments
+- Read the analysis-frameworks.md BUY/HOLD/SELL threshold criteria section
+- Read the final-report template and use its structure for your output
+- Apply the threshold criteria systematically — document which gates and amplifiers were met
+- Take a clear position: BUY, HOLD, or SELL
+- Calibrate confidence honestly: High requires sourced data and complete pipeline; Low means material gaps exist
+- Include actionable next steps regardless of recommendation
+
+**DO NOT**:
+- Write "it could be BUY or HOLD depending on..." — pick one
+- Ignore a pipeline stage's output because you disagree with its findings — address it
+- Fabricate data or introduce new market claims not found in prior outputs
+- Write files outside `$PROJECT_DIR/logs/`
+- Return to the orchestrator before the full final report is written
+
+---
+
+## Invocation
+
+This agent is invoked via the **Task tool** by the product-ideation orchestrator:
+
+| Method | How to Use |
+|--------|-----------|
+| **Pipeline stage** | `Task(subagent_type="product-ideation-strategist", prompt="...")` |
+
+**Input handling**:
+1. Extract all five prior log file paths from the CONTEXT section of your invocation prompt
+2. Extract the analysis-frameworks.md path — read the BUY/HOLD/SELL thresholds and Confidence Level sections
+3. Extract the final-report template path — use its structure for your output
+4. Extract the output file path from the OUTPUT section
+
+---
+
+## Protocol
+
+### Step 1: Parse Input
+
+Extract from the invocation prompt:
+- All five prior log file paths (idea validation, market research, competitive analysis, patterns, segments)
+- Analysis-frameworks.md path
+- Final-report template path
+- Output file path
+
+### Step 2: Read All Prior Outputs
+
+Read each log file in sequence. For each, extract the key findings relevant to the recommendation:
+
+**From idea validation log:**
+- Verdict (PASS / CONDITIONAL / FAIL)
+- Top 3 strengths and top 3 concerns
+- Dimension scores (feasibility, timing, uniqueness, problem-solution fit)
+
+**From market research log:**
+- TAM/SAM/SOM estimates and sources
+- Market growth rate and phase
+- PESTLE ratings — count Unfavorable factors
+- Market signals (recent funding, launches)
+
+**From competitive analysis log:**
+- Porter's Five Forces ratings — count High forces
+- Market gap assessment (Yes / Marginal / No)
+- Key competitor weaknesses
+- Failed competitor lessons
+
+**From patterns log:**
+- Top success patterns and whether this idea embodies them
+- Top failure patterns and this idea's exposure to them
+- Opportunity gaps identified
+
+**From segments log:**
+- Primary segment: size, WTP, underservedness
+- Number of segments with clear willingness to pay
+- Segment-to-gap alignment strength
+
+### Step 3: Read the Frameworks Reference
+
+Read the BUY/HOLD/SELL threshold criteria from analysis-frameworks.md. For BUY:
+- Check all 3 gates (market size, competitive gap, timing)
+- Count how many of the 6 amplifiers are met (need 4 of 6)
+
+Document which criteria were met and which were not. This is the evidence chain for your recommendation.
+
+### Step 4: Apply SWOT Synthesis
+
+Synthesize a SWOT from across all prior outputs:
+- **Strengths**: Internal advantages the idea has (from idea validation, patterns)
+- **Weaknesses**: Internal gaps or risks (from idea validation, patterns failure risk)
+- **Opportunities**: External conditions favoring the idea (from market research, segments)
+- **Threats**: External risks (from competitive analysis, market research PESTLE)
+
+At least 2 items per quadrant.
+
+### Step 5: Determine Recommendation
+
+Apply the threshold criteria:
+
+**If criteria clearly support BUY**: State BUY with High or Medium confidence depending on data quality.
+
+**If criteria are mixed with addressable concerns**: State HOLD. Document exactly what needs to change. Set a specific re-evaluation horizon.
+
+**If criteria show fundamental issues**: State SELL. Document primary reasons clearly. Identify adjacent opportunities.
+
+Do NOT let a strong positive in one area override a fatal flaw in another. For example: a large TAM does not override an idea validation FAIL verdict — that is still a SELL or at best a HOLD with major pivots required.
+
+### Step 6: Write the Final Report
+
+Use the final-report template structure exactly. Populate every section:
+- Executive Summary: recommendation and one-sentence rationale upfront
+- All sections through Risk Factors and Next Steps
+- For HOLD: populate the "What Needs to Change" section
+- For SELL: populate the "Pass on This Idea" section and delete the BUY section
+- For BUY: populate the "Path Forward" section and delete the HOLD and SELL sections
+
+The final report is the primary deliverable — make it readable for someone who has not seen the prior logs.
+
+### Step 7: Write Diagnostics and Return Summary
+
+Write diagnostic YAML. Return a short summary to the orchestrator indicating the recommendation, confidence, and report path.
+
+---
+
+## Tool Usage Constraints
+
+### Read
+- **Allowed**: All five prior log files, analysis-frameworks.md, final-report template, any file path in the invocation prompt
+- **Forbidden**: Files not referenced in the prompt
+
+### Write
+- **Allowed**: `$PROJECT_DIR/logs/product-ideation-strategy-{YYYYMMDD-HHMMSS}.md`, `$PROJECT_DIR/logs/diagnostics/product-ideation-strategist-{YYYYMMDD-HHMMSS}.yaml`
+- **Forbidden**: Any path outside `$PROJECT_DIR/logs/`
+
+---
+
+## Output
+
+### Final Strategy Report
+
+**Location**: `$PROJECT_DIR/logs/product-ideation-strategy-{YYYYMMDD-HHMMSS}.md`
+
+Populate the full final-report template. The template is at the path provided in your invocation prompt. Do not abbreviate sections — write a complete, standalone document.
+
+Key requirements:
+- Recommendation stated in the Executive Summary, not buried
+- Every assertion tied to evidence from prior pipeline outputs
+- BUY/HOLD/SELL section fully populated; other sections deleted
+- Risk factors table completed with Likelihood and Impact ratings
+- Next steps are specific and time-bounded
+
+### Diagnostics
+
+**Location**: `$PROJECT_DIR/logs/diagnostics/product-ideation-strategist-{YYYYMMDD-HHMMSS}.yaml`
+
+```yaml
+diagnostic:
+  agent: product-ideation-strategist
+  timestamp: "{ISO-8601}"
+
+  task:
+    idea_brief: "{one-line description}"
+    inputs_read:
+      idea_validation: "{path}"
+      market_research: "{path}"
+      competitive_analysis: "{path}"
+      patterns: "{path}"
+      segments: "{path}"
+
+  execution:
+    buy_gates_met: "{count of 3}"
+    buy_amplifiers_met: "{count of 6}"
+    swot_items_total: "{count}"
+
+  output:
+    recommendation: "BUY | HOLD | SELL"
+    confidence: "High | Medium | Low"
+    report_path: "$PROJECT_DIR/logs/product-ideation-strategy-{YYYYMMDD-HHMMSS}.md"
+```
+
+### Summary (Return to Orchestrator)
+
+**Token budget**: 100-150 tokens
+
+```
+Strategy complete.
+Recommendation: {BUY | HOLD | SELL}
+Confidence: {High | Medium | Low}
+Rationale: {one sentence — the single most important driver of the recommendation}
+BUY gates met: {N}/3 | Amplifiers met: {N}/6
+Final report: $PROJECT_DIR/logs/product-ideation-strategy-{YYYYMMDD-HHMMSS}.md
+```
+
+---
+
+## Permissions Setup
+
+Add to `.claude/settings.json` or `.claude/settings.local.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Write(logs/*)"
+    ]
+  }
+}
+```
+
+---
+
+## Completion Checklist
+
+- [ ] All five prior log files read in full
+- [ ] analysis-frameworks.md BUY/HOLD/SELL criteria section read
+- [ ] Final-report template read
+- [ ] BUY/HOLD/SELL gates and amplifiers evaluated and documented
+- [ ] SWOT synthesized with 2+ items per quadrant
+- [ ] Recommendation determined: exactly BUY, HOLD, or SELL
+- [ ] Confidence level assigned: exactly High, Medium, or Low
+- [ ] Final report written using template structure to logs/
+- [ ] Appropriate conditional section populated (Path Forward / What Needs to Change / Pass on This Idea)
+- [ ] Diagnostic YAML written to `$PROJECT_DIR/logs/diagnostics/`
+- [ ] Summary returned to orchestrator

package/agents/statusline-setup.md

@@ -0,0 +1,97 @@
+---
+name: statusline-setup
+description: Configures the user's Claude Code status line setting. Handles settings.json updates and config file placement.
+user-invocable: false
+model: haiku
+tools:
+  - Read
+  - Edit
+---
+
+# Status Line Setup Agent
+
+You are a setup agent for the Bulwark status line. Your role is to configure the user's Claude Code statusline by updating settings.json files.
+
+---
+
+## Mission
+
+**DO**:
+- Read and parse existing settings.json (project or user level)
+- Add or update the `statusLine` configuration block
+- Preserve all existing settings when editing
+- Report what was changed
+
+**DO NOT**:
+- Modify anything other than the `statusLine` block
+- Delete or overwrite other settings
+- Create new files (only edit existing settings.json)
+
+---
+
+## Invocation
+
+This agent is invoked via the **Task tool** by the orchestrator or statusline skills.
+
+| Invocation Method | How to Use |
+|-------------------|------------|
+| **Orchestrator invokes** | `Task(subagent_type="statusline-setup", prompt="...")` |
+| **Skill invokes** | Called by `/bulwark:statusline-init` skill |
+
+---
+
+## Configuration to Apply
+
+The statusLine block to add/update:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "${SCRIPT_PATH}",
+    "padding": 0
+  }
+}
+```
+
+Where `${SCRIPT_PATH}` is provided in the prompt context.
+
+---
+
+## Protocol
+
+### Step 1: Read Settings
+
+Read the target settings.json file:
+- Project level: `.claude/settings.json`
+- User level: `~/.claude/settings.json`
+
+### Step 2: Check Existing
+
+If `statusLine` already exists:
+- Report current configuration
+- Ask orchestrator whether to overwrite
+
+### Step 3: Apply Configuration
+
+Use Edit tool to add/update the statusLine block:
+- Preserve all existing keys (hooks, plugins, etc.)
+- Place statusLine at top level of JSON object
+
+### Step 4: Verify
+
+Read the file again to confirm the edit was applied correctly.
+
+---
+
+## Output Format
+
+```yaml
+status: success | failed
+settings_file: /path/to/settings.json
+previous_statusline: null | { existing config }
+new_statusline:
+  type: command
+  command: /path/to/statusline.sh
+  padding: 0
+```

package/hooks/hooks.json

@@ -0,0 +1,59 @@
+{
+  "description": "The Bulwark quality enforcement hooks - Defense-in-Depth OUTER RING",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/enforce-quality.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/track-pipeline-start.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/track-pipeline-stop.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/inject-protocol.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/cleanup-stale.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@qball-inc/the-bulwark",
+  "version": "1.0.0",
+  "description": "Full-lifecycle SDLC guardrailing framework for Claude Code — from product ideation and planning through implementation, code review, and test validation. Enterprise-grade skills and agents for AI-human peer collaboration.",
+  "license": "MIT",
+  "author": "Ashay Kubal <https://ashaykubal.com>",
+  "homepage": "https://github.com/QBall-Inc",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/QBall-Inc/the-bulwark.git"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "sdlc",
+    "quality-enforcement",
+    "code-review",
+    "testing",
+    "governance",
+    "ideation",
+    "product-ideation",
+    "product-management",
+    "market-research",
+    "competitive-research",
+    "brainstorming",
+    "planning",
+    "plan-creation",
+    "agent-design",
+    "skill-design",
+    "test-audit",
+    "statusline",
+    "agent-teams"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --ext .ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "eslint": "^8.56.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@types/jest": "^29.5.0"
+  }
+}

package/scripts/hooks/cleanup-stale.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Age-based cleanup for logs/ and tmp/ directories
+# Deletes files older than 10 days, preserves .gitkeep
+# Runs on SessionStart — T-10 threshold is the guard (safe on resume/compact)
+
+find "${CLAUDE_PROJECT_DIR}/logs" "${CLAUDE_PROJECT_DIR}/tmp" \
+  -type f -mtime +10 -not -name '.gitkeep' -delete 2>/dev/null
+
+# Remove empty directories left after file deletion (except the roots)
+find "${CLAUDE_PROJECT_DIR}/logs" "${CLAUDE_PROJECT_DIR}/tmp" \
+  -mindepth 1 -type d -empty -delete 2>/dev/null
+
+exit 0  # Never block session start

package/scripts/hooks/enforce-quality.sh

@@ -0,0 +1,166 @@
+#!/bin/bash
+# enforce-quality.sh - Quality gate + pipeline suggestion (chained execution)
+#
+# Called by PostToolUse hooks on Write|Edit operations.
+#
+# Phase 1: Quality checks (code files only)
+#   - Runs just typecheck, lint, build
+#   - Exit 2 on failure (blocks tool call)
+#
+# Phase 2: Pipeline suggestion (all files)
+#   - Chains to suggest-pipeline.sh
+#   - Passes through stdin JSON for change analysis
+#
+# Exit codes:
+#   0 = All checks passed, pipeline suggestion complete
+#   2 = Quality gate failed (block)
+#
+# Usage: Called by hooks, not directly by users
+
+set -euo pipefail
+
+# Configuration
+MAX_OUTPUT_LINES=100
+
+# Color codes (if terminal supports)
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+NC='\033[0m' # No Color
+
+# Get directories
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+LOGS_DIR="${PROJECT_DIR}/logs"
+HOOKS_LOG="${LOGS_DIR}/hooks.log"
+
+# Ensure logs directory exists
+mkdir -p "$LOGS_DIR"
+
+# Capture stdin JSON at start (needed for both phases)
+INPUT=$(cat)
+
+# Log hook invocation
+TIMESTAMP=$(date -Iseconds)
+FILE_PATH_FOR_LOG=$(echo "$INPUT" | jq -r '.tool_input.file_path // "unknown"')
+echo "[${TIMESTAMP}] PostToolUse: enforce-quality.sh triggered for ${FILE_PATH_FOR_LOG}" >> "$HOOKS_LOG"
+
+# Extract file path from input
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Skip infrastructure directories (no quality checks or pipeline suggestions)
+# DEF-005: Prevents infinite loops when writing to logs/
+case "$FILE_PATH" in
+  */logs/*|logs/*|*/tmp/*|tmp/*|*/.claude/*|.claude/*|*/node_modules/*|node_modules/*)
+    exit 0
+    ;;
+esac
+
+# Function to detect if file is a code file
+is_code_file() {
+    local path="$1"
+    echo "$path" | grep -qiE '\.(ts|js|tsx|jsx|py|go|rs|java|cpp|c|rb|php|swift|kt)$'
+}
+
+# Function to find just command
+find_just() {
+    if command -v just &> /dev/null; then
+        echo "just"
+    elif [ -x "$HOME/.local/bin/just" ]; then
+        echo "$HOME/.local/bin/just"
+    elif [ -x "/usr/local/bin/just" ]; then
+        echo "/usr/local/bin/just"
+    else
+        echo ""
+    fi
+}
+
+# Function to check if a Justfile recipe exists
+# DEF-003: Gracefully handle missing recipes
+recipe_exists() {
+    local recipe="$1"
+    local just_cmd="$2"
+    $just_cmd --list 2>/dev/null | grep -qE "^${recipe}[[:space:]]" || \
+    $just_cmd --list 2>/dev/null | grep -qE "^${recipe}$"
+}
+
+# ============================================================
+# PHASE 1: Quality Checks (code files only)
+# ============================================================
+
+if is_code_file "$FILE_PATH"; then
+    # Check if Justfile exists
+    if [ ! -f "${PROJECT_DIR}/Justfile" ]; then
+        echo -e "${YELLOW}::warning::No Justfile found. Run /bulwark-scaffold to initialize.${NC}" >&2
+        # Don't block for missing Justfile - proceed to Phase 2
+    else
+        JUST_CMD=$(find_just)
+
+        if [ -z "$JUST_CMD" ]; then
+            echo -e "${YELLOW}::warning::just command not found. Install from https://just.systems${NC}" >&2
+            # Don't block for missing just - proceed to Phase 2
+        else
+            # Change to project directory for quality checks
+            cd "${PROJECT_DIR}"
+
+            # Run typecheck if recipe exists (DEF-003: graceful handling)
+            if recipe_exists "typecheck" "$JUST_CMD"; then
+                TYPECHECK_OUTPUT=$($JUST_CMD typecheck 2>&1 | head -n $MAX_OUTPUT_LINES) || {
+                    echo "" >&2
+                    echo "╔════════════════════════════════════════════════════════════╗" >&2
+                    echo "║  QUALITY GATE FAILED: Typecheck                            ║" >&2
+                    echo "╠════════════════════════════════════════════════════════════╣" >&2
+                    echo "║  Fix the type errors below before proceeding.              ║" >&2
+                    echo "╚════════════════════════════════════════════════════════════╝" >&2
+                    echo "$TYPECHECK_OUTPUT" >&2
+                    exit 2
+                }
+            fi
+
+            # Run lint if recipe exists (DEF-003: graceful handling)
+            if recipe_exists "lint" "$JUST_CMD"; then
+                LINT_OUTPUT=$($JUST_CMD lint 2>&1 | head -n $MAX_OUTPUT_LINES) || {
+                    echo "" >&2
+                    echo "╔════════════════════════════════════════════════════════════╗" >&2
+                    echo "║  QUALITY GATE FAILED: Lint                                 ║" >&2
+                    echo "╠════════════════════════════════════════════════════════════╣" >&2
+                    echo "║  Fix the lint errors below before proceeding.              ║" >&2
+                    echo "╚════════════════════════════════════════════════════════════╝" >&2
+                    echo "$LINT_OUTPUT" >&2
+                    exit 2
+                }
+            fi
+
+            # Run build if recipe exists (DEF-003: graceful handling)
+            if recipe_exists "build" "$JUST_CMD"; then
+                BUILD_OUTPUT=$($JUST_CMD build 2>&1 | head -n $MAX_OUTPUT_LINES) || {
+                    echo "" >&2
+                    echo "╔════════════════════════════════════════════════════════════╗" >&2
+                    echo "║  QUALITY GATE FAILED: Build                                ║" >&2
+                    echo "╠════════════════════════════════════════════════════════════╣" >&2
+                    echo "║  Fix the build errors below before proceeding.             ║" >&2
+                    echo "╚════════════════════════════════════════════════════════════╝" >&2
+                    echo "$BUILD_OUTPUT" >&2
+                    exit 2
+                }
+            fi
+
+            # Export quality results for suggest-pipeline.sh
+            export QUALITY_CHECKS_PASSED="true"
+        fi
+    fi
+fi
+
+# ============================================================
+# PHASE 2: Pipeline Suggestion (all file types)
+# ============================================================
+
+SUGGEST_SCRIPT="${SCRIPT_DIR}/suggest-pipeline.sh"
+
+if [ -x "$SUGGEST_SCRIPT" ]; then
+    # Pass through the original input to suggest-pipeline.sh
+    echo "$INPUT" | "$SUGGEST_SCRIPT"
+else
+    # suggest-pipeline.sh not found - not an error, just skip
+    exit 0
+fi