@qball-inc/the-bulwark 1.0.0

package/skills/bulwark-scaffold/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: bulwark-scaffold
+description: Initialize Bulwark infrastructure in a project. Generates Justfile, logs directory, and optional hook configuration.
+user-invocable: true
+---
+
+# Bulwark Scaffold
+
+Initialize Bulwark infrastructure in a project by generating Justfile templates, creating the logs directory structure, and optionally configuring hooks.
+
+## Usage
+
+```
+/bulwark-scaffold [options]
+```
+
+**Options:**
+- `--force` - Overwrite existing Justfile (creates backup)
+- `--no-hooks` - Skip hook configuration (hooks are generated by default)
+- `--dry-run` - Show what would be generated without writing files
+- `--lang=<node|python|rust|generic>` - Override language detection
+
+**Examples:**
+- `/bulwark-scaffold` - Full scaffold with Justfile + logs/ + hooks
+- `/bulwark-scaffold --force` - Overwrite existing Justfile
+- `/bulwark-scaffold --no-hooks` - Skip hook configuration
+- `/bulwark-scaffold --dry-run` - Preview changes
+
+---
+
+## Execution Steps
+
+### Step 1: Parse Arguments
+
+Extract options from `$ARGUMENTS`:
+- `--force` → FORCE_OVERWRITE=true
+- `--no-hooks` → SKIP_HOOKS=true
+- `--dry-run` → DRY_RUN=true
+- `--lang=X` → LANG_OVERRIDE=X
+
+### Step 2: Detect Project Language
+
+If LANG_OVERRIDE is set, use that. Otherwise, search from current directory for manifest files:
+
+1. Check for `package.json` → **Node**
+2. Check for `pyproject.toml` OR `setup.py` → **Python**
+3. Check for `Cargo.toml` → **Rust**
+4. None found → **Generic**
+
+Store result in DETECTED_LANG variable.
+
+### Step 3: Check for `just` and Existing Justfile
+
+**Pre-flight: Verify `just` is installed.**
+
+```
+Run: command -v just
+
+IF just is NOT found:
+    Print:
+        "`just` command runner is not installed. It is required to use the generated Justfile."
+        ""
+        "Install just using one of these methods:"
+        "  curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin"
+        "  brew install just          # macOS/Linux (Homebrew)"
+        "  cargo install just         # Rust/Cargo"
+        "  npm install -g rust-just   # npm"
+        "  apt install just           # Debian/Ubuntu"
+        "  pacman -S just             # Arch"
+        ""
+        "See https://github.com/casey/just for all installation options."
+
+    Ask user: "Install just now using the install script, or skip Justfile generation?"
+    - If install: Run `curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin`
+      - If install succeeds: Continue
+      - If install fails: Print error and set SKIP_JUSTFILE=true
+    - If skip: Set SKIP_JUSTFILE=true
+```
+
+**Check for existing Justfile:**
+
+```
+IF Justfile exists AND NOT FORCE_OVERWRITE:
+    Print: "Justfile already exists. Use --force to overwrite (creates backup)."
+    Set SKIP_JUSTFILE=true
+ELSE IF Justfile exists AND FORCE_OVERWRITE:
+    Create backup: Justfile.backup-{YYYYMMDD-HHMMSS}
+    Set SKIP_JUSTFILE=false
+ELSE:
+    Set SKIP_JUSTFILE=false
+```
+
+### Step 4: Dry Run Check
+
+If DRY_RUN is true, display preview and exit:
+
+```
+## Scaffold Preview (dry-run)
+
+**Language detected:** {DETECTED_LANG} ({manifest file or "no manifest"})
+
+**Would create:**
+- Justfile (from lib/templates/justfile-{DETECTED_LANG}.just)
+- logs/
+- logs/diagnostics/
+- logs/validations/
+- logs/debug-reports/
+{IF NOT SKIP_HOOKS}
+- .claude/settings.json (hooks configuration)
+- .claude/skills/governance-protocol/SKILL.md
+- scripts/hooks/inject-protocol.sh
+- scripts/hooks/enforce-quality.sh
+- scripts/hooks/suggest-pipeline.sh
+{ENDIF}
+
+**Would update:**
+- .gitignore (add Bulwark patterns)
+
+Run without --dry-run to apply changes.
+```
+
+Then STOP execution.
+
+### Step 5: Generate Justfile
+
+If NOT SKIP_JUSTFILE:
+
+1. Locate template: `${CLAUDE_PLUGIN_ROOT}/lib/templates/justfile-{DETECTED_LANG}.just`
+   - For local development: `${CLAUDE_PROJECT_DIR}/lib/templates/justfile-{DETECTED_LANG}.just`
+2. Copy template content to `Justfile` in project root
+
+### Step 6: Create logs/ Directory Structure
+
+```bash
+mkdir -p logs/diagnostics logs/validations logs/debug-reports
+touch logs/.gitkeep logs/diagnostics/.gitkeep logs/validations/.gitkeep logs/debug-reports/.gitkeep
+```
+
+### Step 7: Update .gitignore
+
+Check if `.gitignore` exists and contains `# Bulwark logs` marker:
+- If marker exists: Skip (already configured)
+- If marker does not exist: Append the following patterns
+
+**Patterns to add:**
+```gitignore
+
+# Bulwark logs
+logs/*.yaml
+logs/*.log
+logs/diagnostics/*.yaml
+logs/validations/*.yaml
+logs/debug-reports/*.yaml
+!logs/.gitkeep
+!logs/*/.gitkeep
+```
+
+### Step 8: Generate Hook Configuration (Default)
+
+UNLESS SKIP_HOOKS is true:
+
+**Pre-flight: Check for existing Bulwark hooks to prevent duplication.**
+
+Plugin hooks (`hooks/hooks.json`) and settings hooks (`.claude/settings.json`) both fire at runtime. If hooks already exist in any location, adding them again causes double execution.
+
+**Check these locations for existing Bulwark hooks** (search for `enforce-quality` or `inject-protocol`):
+
+| Location | Scope | Notes |
+|----------|-------|-------|
+| `./hooks/hooks.json` | Project plugin | Bulwark installed as project-level plugin |
+| `~/.claude/plugins/*/hooks/hooks.json` | User plugin | Bulwark installed at user level via `/install` |
+| `.claude/settings.json` | Project settings | Previously scaffolded |
+| `.claude/settings.local.json` | Project local | User-specific project overrides |
+| `~/.claude/settings.json` | User settings | Global user hooks |
+| `~/.claude/settings.local.json` | User local | Global user overrides |
+
+```
+HOOKS_FOUND_IN = []
+
+FOR each location above:
+    IF file exists AND contains "enforce-quality" OR "inject-protocol":
+        Append location to HOOKS_FOUND_IN
+
+IF HOOKS_FOUND_IN is not empty:
+    Print: "Bulwark hooks already present in: {HOOKS_FOUND_IN}. Skipping hook generation to prevent duplication."
+    Set SKIP_HOOKS=true
+```
+
+**If no existing hooks found**, proceed with hook generation:
+
+Check if `.claude/settings.json` exists:
+- If exists: Merge hooks into existing configuration (preserve other settings)
+- If not exists: Create new file
+
+**Hook configuration to add:**
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/scripts/hooks/inject-protocol.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/scripts/hooks/enforce-quality.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Note:** SessionStart has no matcher, so it fires for all session events (start, resume, clear, compact).
+
+**Also copy required files** (only if hooks were generated above):
+1. Copy `scripts/hooks/inject-protocol.sh` to `${CLAUDE_PROJECT_DIR}/scripts/hooks/`
+2. Copy `scripts/hooks/enforce-quality.sh` to `${CLAUDE_PROJECT_DIR}/scripts/hooks/`
+3. Copy `scripts/hooks/suggest-pipeline.sh` to `${CLAUDE_PROJECT_DIR}/scripts/hooks/`
+4. Copy `skills/governance-protocol/SKILL.md` to `${CLAUDE_PROJECT_DIR}/.claude/skills/governance-protocol/SKILL.md`
+
+Create parent directories as needed (`mkdir -p`).
+
+### Step 9: Write Scaffold Log
+
+Write to `logs/scaffold-{YYYYMMDD-HHMMSS}.yaml`:
+
+```yaml
+metadata:
+  timestamp: {ISO-8601}
+  action: scaffold
+  invocation: "/bulwark-scaffold {args}"
+
+detection:
+  language: {DETECTED_LANG}
+  manifest: {manifest path or null}
+  override: {LANG_OVERRIDE or null}
+
+actions:
+  justfile:
+    action: created|skipped|overwritten
+    backup: {backup path or null}
+    template: lib/templates/justfile-{DETECTED_LANG}.just
+  logs_directory:
+    created: true
+    subdirectories: [diagnostics, validations, debug-reports]
+  gitignore:
+    action: created|updated|skipped
+    patterns_added: 7
+  hooks:
+    action: created|merged|skipped
+    path: .claude/settings.json
+    skipped_reason: {reason if skipped}
+
+summary: |
+  Scaffold complete for {DETECTED_LANG} project.
+```
+
+### Step 10: Report Results
+
+Present summary to user:
+
+```
+## Scaffold Complete
+
+**Language:** {DETECTED_LANG}
+**Justfile:** {created|skipped|overwritten (backup: path)}
+**logs/:** Created with subdirectories (diagnostics, validations, debug-reports)
+**.gitignore:** {updated|created|unchanged}
+**Hooks:** {created|merged|skipped (--no-hooks)}
+**Governance:** {installed|skipped} - Protocol injected at session start
+
+Run `just` to see available recipes:
+- `just typecheck` - Run type checker
+- `just lint` - Run linter
+- `just build` - Build project
+- `just test` - Run tests
+- `just ci` - Run all quality checks
+- `just fix` - Auto-fix issues
+```
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Cannot detect language | Print: "Could not detect language. Use --lang=node\|python\|rust\|generic" |
+| Template file missing | Print: "Template not found at {path}. Bulwark installation may be corrupted." |
+| Cannot create logs/ | Print: "Cannot create logs/ directory. Check permissions." |
+| .gitignore write fails | Print warning, continue with other operations |
+| Justfile backup fails | Print error, abort Justfile generation |
+
+---
+
+## Diagnostic Output
+
+Write diagnostic log to `logs/diagnostics/bulwark-scaffold-{timestamp}.yaml`:
+
+```yaml
+skill: bulwark-scaffold
+timestamp: {ISO-8601}
+invocation: "{full command}"
+inputs:
+  force: {true|false}
+  no_hooks: {true|false}
+  dry_run: {true|false}
+  lang_override: {value or null}
+detection:
+  language: {detected}
+  manifest_path: {path or null}
+outputs:
+  justfile_created: {true|false}
+  logs_created: {true|false}
+  gitignore_updated: {true|false}
+  hooks_configured: {true|false}
+errors: []
+```

package/skills/bulwark-statusline/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: bulwark-statusline
+description: Configure the Bulwark status line for Claude Code. Supports init, preset switching, and customization.
+user-invocable: true
+tools:
+  - Bash
+  - Read
+  - Edit
+---
+
+# Bulwark Status Line
+
+Configure the Bulwark multi-line status line for Claude Code.
+
+---
+
+## When to Use
+
+Use this skill when:
+- Setting up the Bulwark status line for the first time (`init`)
+- Switching between status line presets (`minimal`, `developer`, `cost`)
+- User asks to configure or customize the status line display
+
+---
+
+## Invocation
+
+This skill can be invoked two ways:
+
+| Method | Example |
+|--------|---------|
+| **Command** | `/bulwark-statusline minimal` |
+| **Conversational** | "Change my status line to minimal" |
+
+When invoked, **you (Claude) execute the steps** using the tools declared above (Bash, Read, Edit).
+
+---
+
+## Usage
+
+```
+/bulwark-statusline init        # Install with default (developer) preset
+/bulwark-statusline minimal     # Switch to minimal preset (1 line)
+/bulwark-statusline developer   # Switch to developer preset (3 lines)
+/bulwark-statusline cost        # Switch to cost preset (2 lines)
+```
+
+### Argument Handling
+
+The subcommand is passed via `$1`:
+
+```
+/bulwark-statusline init
+                     ^^^^
+                     $1 = "init"
+```
+
+Parse `$1` and execute the corresponding subcommand below.
+
+---
+
+## Subcommand: init
+
+Install the Bulwark status line for first-time setup.
+
+**Execute these steps:**
+
+1. **Bash**: Create config directory
+   ```bash
+   mkdir -p ~/.bulwark
+   ```
+
+2. **Bash**: Copy default config template
+   ```bash
+   cp "${CLAUDE_PROJECT_DIR}/skills/bulwark-statusline/templates/statusline-default.yaml" ~/.bulwark/statusline.yaml
+   ```
+
+3. **Spawn statusline-setup agent** to update settings.json:
+   ```
+   Task(subagent_type="statusline-setup", prompt="
+     GOAL: Add statusLine configuration to .claude/settings.json
+     TARGET: .claude/settings.json (project level)
+
+     EXACT JSON to add at top level of settings.json:
+     {
+       \"statusLine\": {
+         \"type\": \"command\",
+         \"command\": \"${CLAUDE_PROJECT_DIR}/skills/bulwark-statusline/scripts/statusline.sh\"
+       }
+     }
+
+     If .claude/settings.json does not exist, create it with just this content.
+     If it exists, merge the statusLine key into the existing JSON, preserving all other keys.
+   ")
+   ```
+
+4. **Display to user**: "Status line installed. Restart session to activate."
+
+---
+
+## Subcommand: minimal
+
+Switch to minimal preset (single line: model + gauge + tokens).
+
+**Execute these steps:**
+
+1. **Read**: `~/.bulwark/statusline.yaml`
+2. **Edit**: Change `preset:` value to `minimal`
+3. **Display to user**: "Switched to minimal preset."
+
+---
+
+## Subcommand: developer
+
+Switch to developer preset (3 lines).
+
+**Lines displayed:**
+- Line 1: Model + gauge + tokens
+- Line 2: Last modified file
+- Line 3: Git branch + pending count
+
+**Execute these steps:**
+
+1. **Read**: `~/.bulwark/statusline.yaml`
+2. **Edit**: Change `preset:` value to `developer`
+3. **Display to user**: "Switched to developer preset."
+
+---
+
+## Subcommand: cost
+
+Switch to cost preset (2 lines).
+
+**Lines displayed:**
+- Line 1: Model + gauge + tokens + cost
+- Line 2: Duration
+
+**Execute these steps:**
+
+1. **Read**: `~/.bulwark/statusline.yaml`
+2. **Edit**: Change `preset:` value to `cost`
+3. **Display to user**: "Switched to cost preset."
+
+---
+
+## File Locations
+
+| File | Purpose |
+|------|---------|
+| `~/.bulwark/statusline.yaml` | User config (presets, colors) |
+| `skills/bulwark-statusline/scripts/statusline.sh` | Main script (bundled with skill) |
+| `skills/bulwark-statusline/templates/statusline-default.yaml` | Default config template |
+
+---
+
+## Notes
+
+- Status line updates automatically on each interaction
+- Multi-line output is supported
+- Colors use RGB escape codes for exact hex values
+- Gauge and percentage colors match threshold (green/yellow/coral)

package/skills/bulwark-statusline/scripts/statusline.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# Bulwark Status Line for Claude Code
+# Displays multi-line status with context gauge, model info, and git status
+
+set -euo pipefail
+
+# === Color Definitions (RGB for exact hex colors) ===
+# Foreground: \033[38;2;R;G;Bm  Background: \033[48;2;R;G;Bm
+RESET='\033[0m'
+
+# Gauge colors
+GAUGE_LOW='\033[38;2;175;255;175m'      # #AFFFAF pastel green
+GAUGE_MID='\033[38;2;255;244;176m'      # #FFF4B0 pastel yellow
+GAUGE_HIGH='\033[38;2;255;154;150m'     # #FF9A96 pastel coral
+GAUGE_EMPTY='\033[38;2;88;88;88m'       # #585858 dim gray
+
+# Model background colors (with dark foreground for contrast)
+MODEL_FG='\033[38;2;30;30;30m'          # Dark text on pastel bg
+MODEL_OPUS='\033[48;2;196;173;237m'     # #C4ADED soft purple
+MODEL_SONNET='\033[48;2;172;213;243m'   # #ACD5F3 soft blue
+MODEL_HAIKU='\033[48;2;172;239;214m'    # #ACEFD6 soft teal
+
+# Segment colors
+LABEL='\033[38;2;138;138;138m'          # #8A8A8A medium gray
+FILE_PATH='\033[38;2;255;215;175m'      # #FFD7AF pastel peach
+GIT_BRANCH='\033[38;2;135;215;255m'     # #87D7FF pastel cyan
+
+# === Read JSON from stdin ===
+INPUT=$(cat)
+
+# === Parse JSON with jq ===
+MODEL=$(echo "$INPUT" | jq -r '.model.display_name // "Unknown"')
+PERCENT=$(echo "$INPUT" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
+CONTEXT_SIZE=$(echo "$INPUT" | jq -r '.context_window.context_window_size // 200000')
+# Calculate tokens from percentage (total_input/output_tokens includes sub-agents)
+PERCENT_RAW=$(echo "$INPUT" | jq -r '.context_window.used_percentage // 0')
+COST=$(echo "$INPUT" | jq -r '.cost.total_cost_usd // 0')
+CWD=$(echo "$INPUT" | jq -r '.workspace.current_dir // ""')
+
+# === Calculate tokens from percentage ===
+# tokens_used = (percentage / 100) * context_window_size
+TOTAL_TOKENS=$(echo "$PERCENT_RAW $CONTEXT_SIZE" | awk '{printf "%.0f", ($1 / 100) * $2}')
+
+# Format tokens (K/M suffix)
+format_tokens() {
+    local tokens=$1
+    if [ "$tokens" -ge 1000000 ]; then
+        echo "$((tokens / 1000000))M"
+    elif [ "$tokens" -ge 1000 ]; then
+        echo "$((tokens / 1000))K"
+    else
+        echo "$tokens"
+    fi
+}
+
+TOKENS_USED=$(format_tokens $TOTAL_TOKENS)
+TOKENS_MAX=$(format_tokens $CONTEXT_SIZE)
+
+# Format cost
+COST_FMT=$(printf "\$%.2f" "$COST")
+
+# === Build gauge ===
+GAUGE_WIDTH=10
+FILLED=$((PERCENT * GAUGE_WIDTH / 100))
+[ "$FILLED" -gt "$GAUGE_WIDTH" ] && FILLED=$GAUGE_WIDTH
+EMPTY=$((GAUGE_WIDTH - FILLED))
+
+# Select gauge color based on threshold
+if [ "$PERCENT" -lt 60 ]; then
+    GAUGE_COLOR="$GAUGE_LOW"
+elif [ "$PERCENT" -lt 70 ]; then
+    GAUGE_COLOR="$GAUGE_MID"
+else
+    GAUGE_COLOR="$GAUGE_HIGH"
+fi
+
+# Build gauge string
+GAUGE=""
+for ((i=0; i<FILLED; i++)); do
+    GAUGE="${GAUGE}▰"
+done
+GAUGE_EMPTY_STR=""
+for ((i=0; i<EMPTY; i++)); do
+    GAUGE_EMPTY_STR="${GAUGE_EMPTY_STR}▱"
+done
+
+# === Select model background color ===
+case "$MODEL" in
+    *Opus*|*opus*)
+        MODEL_BG="$MODEL_OPUS"
+        ;;
+    *Sonnet*|*sonnet*)
+        MODEL_BG="$MODEL_SONNET"
+        ;;
+    *Haiku*|*haiku*)
+        MODEL_BG="$MODEL_HAIKU"
+        ;;
+    *)
+        MODEL_BG="$MODEL_SONNET"  # Default to Sonnet color
+        ;;
+esac
+
+# === Get git info ===
+GIT_REPO=""
+GIT_BRANCH_NAME=""
+GIT_PENDING=0
+
+if [ -n "$CWD" ] && [ -d "$CWD" ]; then
+    cd "$CWD" 2>/dev/null || true
+    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        GIT_REPO=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "")
+        GIT_BRANCH_NAME=$(git branch --show-current 2>/dev/null || echo "")
+        GIT_PENDING=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    fi
+fi
+
+# === Get last modified file (most recent by mtime) ===
+LAST_FILE=""
+if [ -n "$CWD" ] && [ -d "$CWD" ]; then
+    cd "$CWD" 2>/dev/null || true
+    # Combine: modified tracked files + untracked files, sort by mtime
+    LAST_FILE=$( (git diff --name-only HEAD 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null) | \
+        xargs -I{} sh -c '[ -f "{}" ] && stat --format="%Y %n" "{}"' 2>/dev/null | \
+        sort -rn | head -1 | cut -d' ' -f2- || true)
+fi
+
+# === Output Lines ===
+
+# Line 1: Model + Gauge + Tokens (percentage matches gauge color)
+echo -e "${MODEL_BG}${MODEL_FG} ${MODEL} ${RESET}  ${GAUGE_COLOR}${GAUGE}${RESET}${GAUGE_EMPTY}${GAUGE_EMPTY_STR}${RESET} ${GAUGE_COLOR}${PERCENT}%${RESET} (${TOKENS_USED}/${TOKENS_MAX})"
+
+# Line 2: Last file (if available)
+if [ -n "$LAST_FILE" ]; then
+    echo -e "${LABEL}Last file:${RESET} ${FILE_PATH}${LAST_FILE}${RESET}"
+fi
+
+# Line 3: Git info (if available)
+if [ -n "$GIT_REPO" ] && [ -n "$GIT_BRANCH_NAME" ]; then
+    PENDING_TEXT=""
+    if [ "$GIT_PENDING" -gt 0 ]; then
+        PENDING_TEXT=" ${LABEL}(${GIT_PENDING} files pending)${RESET}"
+    fi
+    echo -e "${LABEL}Git:${RESET} ${GIT_BRANCH}${GIT_REPO}/${GIT_BRANCH_NAME}${RESET}${PENDING_TEXT}"
+fi