compass-cc 0.1.0

package/hooks/compass-commit-check.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+
+# compass-commit-check.sh — Claude Code PreToolUse hook
+# Validates conventional commit format before git commit.
+#
+# Hook type: PreToolUse
+# Matcher: tool_name == "Bash" and command contains "git commit"
+#
+# OPT-IN: Only active when hooks.commit_check is true in .compass/config.yaml.
+# When active, BLOCKS non-conventional commits (exit 2).
+
+# Timeout guard
+TIMEOUT_PID=$$
+( sleep 5 && kill -0 "$TIMEOUT_PID" 2>/dev/null && kill "$TIMEOUT_PID" ) &
+WATCHDOG=$!
+trap "kill $WATCHDOG 2>/dev/null" EXIT
+
+# Read hook input
+INPUT=$(cat)
+
+# Check if this is a git commit command
+COMMAND=$(echo "$INPUT" | grep -o '"command":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+case "$COMMAND" in
+    *"git commit"*) ;;
+    *) exit 0 ;;
+esac
+
+# Find .compass/ and check if commit check is enabled
+COMPASS_DIR=""
+DIR="$PWD"
+while [[ "$DIR" != "/" ]]; do
+    if [[ -d "$DIR/.compass" ]]; then
+        COMPASS_DIR="$DIR/.compass"
+        break
+    fi
+    DIR=$(dirname "$DIR")
+done
+
+[[ -n "$COMPASS_DIR" ]] || exit 0
+
+CONFIG="$COMPASS_DIR/config.yaml"
+[[ -f "$CONFIG" ]] || exit 0
+
+ENABLED=$(grep -A1 "hooks:" "$CONFIG" | grep "commit_check:" | awk '{print $2}')
+[[ "$ENABLED" == "true" ]] || exit 0
+
+# Extract commit message from -m flag
+MSG=$(echo "$COMMAND" | grep -oP '(?<=-m\s)["\x27]([^"\x27]*)["\x27]' | tr -d "\"'" | head -1)
+
+# If no -m flag found (might use heredoc or other format), skip validation
+[[ -n "$MSG" ]] || exit 0
+
+# Validate conventional commit format
+# Pattern: type(scope)?: description
+# Types: feat, fix, chore, docs, refactor, test, ci, perf, build, style, revert
+PATTERN='^(feat|fix|chore|docs|refactor|test|ci|perf|build|style|revert)(\([a-zA-Z0-9_-]+\))?!?:.+'
+
+if ! echo "$MSG" | grep -qE "$PATTERN"; then
+    # Exit 2 = block the tool call
+    cat <<EOF
+{"error": "COMPASS COMMIT CHECK: Commit message does not follow conventional commits format. Expected: type(scope)?: description. Types: feat, fix, chore, docs, refactor, test, ci, perf, build, style, revert. Got: '$MSG'"}
+EOF
+    exit 2
+fi

package/hooks/compass-context-monitor.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+
+# compass-context-monitor.sh — Claude Code PostToolUse hook
+# Monitors context usage and warns when approaching limits.
+#
+# Hook type: PostToolUse
+# Matcher: (all tool uses, debounced internally)
+#
+# This hook reads the Claude Code statusline metrics and injects
+# warnings when context is running low.
+
+# Timeout guard
+TIMEOUT_PID=$$
+( sleep 5 && kill -0 "$TIMEOUT_PID" 2>/dev/null && kill "$TIMEOUT_PID" ) &
+WATCHDOG=$!
+trap "kill $WATCHDOG 2>/dev/null" EXIT
+
+# Debounce — only check every 10 tool uses
+COUNTER_FILE="/tmp/compass-ctx-counter-$$"
+if [[ -f "$COUNTER_FILE" ]]; then
+    COUNT=$(cat "$COUNTER_FILE")
+    COUNT=$((COUNT + 1))
+    echo "$COUNT" > "$COUNTER_FILE"
+    [[ $((COUNT % 10)) -eq 0 ]] || exit 0
+else
+    echo "1" > "$COUNTER_FILE"
+    exit 0
+fi
+
+# Look for Claude Code context metrics
+# The statusline bridge file location varies — check common paths
+SESSION_ID="${CLAUDE_SESSION_ID:-unknown}"
+METRICS_FILE="/tmp/claude-ctx-${SESSION_ID}.json"
+
+[[ -f "$METRICS_FILE" ]] || exit 0
+
+# Try to read remaining percentage
+REMAINING=$(grep -o '"remaining":[0-9.]*' "$METRICS_FILE" 2>/dev/null | head -1 | cut -d: -f2)
+
+[[ -n "$REMAINING" ]] || exit 0
+
+# Convert to integer for comparison
+REMAINING_INT=${REMAINING%.*}
+
+if [[ $REMAINING_INT -le 25 ]]; then
+    cat <<EOF
+{"additionalContext": "COMPASS CONTEXT MONITOR — CRITICAL: Context is at ${REMAINING_INT}% remaining. Save your work: run /compass:next to capture current state, then /clear before continuing. SESSION.md will preserve your position."}
+EOF
+elif [[ $REMAINING_INT -le 35 ]]; then
+    cat <<EOF
+{"additionalContext": "COMPASS CONTEXT MONITOR — WARNING: Context is at ${REMAINING_INT}% remaining. Consider finishing current task and running /clear soon. Use /compass:next to see where you are."}
+EOF
+fi

package/hooks/compass-preflight.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+# compass-preflight.sh — Claude Code PreToolUse hook
+# Checks phase prerequisites before /compass:* commands execute.
+#
+# Hook type: PreToolUse
+# Matcher: tool_name == "Skill" and skill name starts with "compass-"
+#
+# This hook injects advisory context about missing prerequisites.
+# It does NOT block execution — the skill itself handles missing prereqs.
+
+# Timeout guard
+TIMEOUT_PID=$$
+( sleep 5 && kill -0 "$TIMEOUT_PID" 2>/dev/null && kill "$TIMEOUT_PID" ) &
+WATCHDOG=$!
+trap "kill $WATCHDOG 2>/dev/null" EXIT
+
+# Read hook input
+INPUT=$(cat)
+
+# Check if this is a compass skill invocation
+SKILL_NAME=$(echo "$INPUT" | grep -o '"skill":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+case "$SKILL_NAME" in
+    compass-*) ;;
+    *) exit 0 ;;
+esac
+
+# Extract phase from skill name
+PHASE="${SKILL_NAME#compass-}"
+
+# Find compass-tools.sh
+TOOLS_SCRIPT=""
+for candidate in \
+    "$HOME/.claude/compass/scripts/compass-tools.sh" \
+    "$(dirname "$(dirname "$0")")/scripts/compass-tools.sh"; do
+    if [[ -x "$candidate" ]]; then
+        TOOLS_SCRIPT="$candidate"
+        break
+    fi
+done
+
+[[ -n "$TOOLS_SCRIPT" ]] || exit 0
+
+# Run preflight check
+RESULT=$("$TOOLS_SCRIPT" preflight "$PHASE" 2>/dev/null)
+[[ $? -eq 0 ]] || exit 0
+
+READY=$(echo "$RESULT" | grep -o '"ready":[a-z]*' | cut -d: -f2)
+
+if [[ "$READY" == "false" ]]; then
+    MISSING=$(echo "$RESULT" | grep -o '"missing":\[[^]]*\]' | sed 's/"missing":\[//;s/\]//;s/"//g')
+    cat <<EOF
+{"additionalContext": "COMPASS PREFLIGHT: Phase '$PHASE' has missing prerequisites: $MISSING. The skill will handle this, but be aware."}
+EOF
+fi

package/hooks/compass-scope-guardian.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+
+# compass-scope-guardian.sh — Claude Code PostToolUse hook
+# Triggers on Write/Edit outside .compass/ during build phase.
+# Compares changes against SPEC.md, ADRs, and FRAMING.md.
+#
+# Hook type: PostToolUse
+# Matcher: tool_name in ["Write", "Edit"]
+#
+# This hook injects advisory context — it does not block operations.
+# The scope-guardian agent interprets the findings.
+
+# Timeout guard — do not block Claude Code
+TIMEOUT_PID=$$
+( sleep 8 && kill -0 "$TIMEOUT_PID" 2>/dev/null && kill "$TIMEOUT_PID" ) &
+WATCHDOG=$!
+trap "kill $WATCHDOG 2>/dev/null" EXIT
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+# Extract tool name and file path
+TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4)
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+# Only process Write/Edit
+case "$TOOL_NAME" in
+    Write|Edit) ;;
+    *) exit 0 ;;
+esac
+
+# Skip if editing inside .compass/
+case "$FILE_PATH" in
+    */.compass/*) exit 0 ;;
+esac
+
+# Find .compass/ directory
+COMPASS_DIR=""
+DIR="$PWD"
+while [[ "$DIR" != "/" ]]; do
+    if [[ -d "$DIR/.compass" ]]; then
+        COMPASS_DIR="$DIR/.compass"
+        break
+    fi
+    DIR=$(dirname "$DIR")
+done
+
+[[ -n "$COMPASS_DIR" ]] || exit 0
+
+# Check if scope guardian is enabled
+CONFIG="$COMPASS_DIR/config.yaml"
+if [[ -f "$CONFIG" ]]; then
+    ENABLED=$(grep -A1 "hooks:" "$CONFIG" | grep "scope_guardian:" | awk '{print $2}')
+    [[ "$ENABLED" == "false" ]] && exit 0
+fi
+
+# Check if we're in build phase (units exist)
+UNITS_DIR="$COMPASS_DIR/UNITS"
+[[ -d "$UNITS_DIR" ]] || exit 0
+UNIT_COUNT=$(find "$UNITS_DIR" -name 'unit-*.md' 2>/dev/null | wc -l)
+[[ $UNIT_COUNT -gt 0 ]] || exit 0
+
+# Check if spec exists
+SPEC_FILE="$COMPASS_DIR/SPEC.md"
+[[ -f "$SPEC_FILE" ]] || exit 0
+
+# Find compass-tools.sh
+TOOLS_SCRIPT=""
+for candidate in \
+    "$HOME/.claude/compass/scripts/compass-tools.sh" \
+    "$(dirname "$(dirname "$0")")/scripts/compass-tools.sh"; do
+    if [[ -x "$candidate" ]]; then
+        TOOLS_SCRIPT="$candidate"
+        break
+    fi
+done
+
+# Run drift analysis if tools script is available
+FILENAME=$(basename "$FILE_PATH")
+if [[ -n "$TOOLS_SCRIPT" ]]; then
+    DRIFT_OUTPUT=$("$TOOLS_SCRIPT" drift --json 2>/dev/null || true)
+    if [[ -n "$DRIFT_OUTPUT" ]]; then
+        FILE_COUNT=$(echo "$DRIFT_OUTPUT" | grep -o '"files_changed":[0-9]*' | cut -d: -f2)
+        CHANGED=$(echo "$DRIFT_OUTPUT" | grep -o '"changed_files":\[[^]]*\]' | sed 's/"changed_files"://;s/\[//;s/\]//;s/"//g' | tr ',' ', ')
+        cat <<EOF
+{"additionalContext": "SCOPE GUARDIAN: '$FILENAME' modified outside .compass/ during build phase. Drift analysis: $FILE_COUNT file(s) changed ($CHANGED). Check these against SPEC.md, active ADRs, and FRAMING.md. Report any drift to the user: out-of-scope additions, ADR contradictions, or unspecified behavior."}
+EOF
+        exit 0
+    fi
+fi
+
+# Fallback if tools script not found
+cat <<EOF
+{"additionalContext": "SCOPE GUARDIAN: File '$FILENAME' was modified outside .compass/ during the build phase. Check whether this change aligns with SPEC.md, active ADRs, and FRAMING.md. Report any drift to the user."}
+EOF

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "compass-cc",
+  "version": "0.1.0",
+  "description": "COMPASS — Collaborative Orientation, Mapping, Planning, Architecture, Spec & Supervision. An inverted AI coding skill: the human implements, the LLM orients.",
+  "license": "MIT",
+  "author": "hvpaiva",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hvpaiva/compass"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-coding",
+    "spec-driven",
+    "architecture",
+    "code-review",
+    "adr"
+  ],
+  "bin": {
+    "compass-cc": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "agents/",
+    "scripts/",
+    "templates/",
+    "hooks/",
+    "references/",
+    "constitution.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/references/inverted-contract.md

@@ -0,0 +1,31 @@
+# Inverted Contract — Binding Rules for All COMPASS Agents
+
+This reference is loaded by every COMPASS sub-agent. It is non-negotiable.
+
+## You MUST NOT
+
+- Generate production code: functions, methods, classes, modules, structs, traits,
+  implementations, algorithms, or business logic.
+- Generate scaffolding, boilerplate, stubs, or starter code.
+- Suggest specific code fixes: "change line N to X", "replace this with Y."
+- Write to the target project's git repository.
+- Resolve ambiguities the human could resolve — ask instead.
+
+## You MUST
+
+- Ask questions that help the human think clearly.
+- Cite sources for every factual claim.
+- Report problems without prescribing code solutions.
+- Respect phase gates — never advance without human approval.
+- Read state from `.compass/` files, not from conversation memory.
+- Call `compass-tools.sh` for state mutations, never edit state files directly.
+
+## Mechanical editing exception
+
+You MAY execute textual transformations that are repetitive, non-creative, and
+mechanically describable by the human. If judgment about design, architecture, or
+logic is required, it is production code and you must refuse.
+
+## When in doubt
+
+Ask the human. Never guess. Never infer. Never fill gaps with plausible defaults.