Adds unified installation management for Claude Code integration:
blue install - Install hooks, skills, MCP server
blue uninstall - Remove Blue from Claude Code
blue doctor - Check installation health
Components managed:
- Hooks: session-start.sh (PATH), guard-write.sh (guard)
- Skills: Symlinks to ~/.claude/skills/
- MCP Server: Configuration in ~/.claude.json
Features:
- --hooks-only, --skills-only, --mcp-only flags
- --force to overwrite existing files
- Managed files tagged with "# Managed by: blue install"
- Idempotent - safe to run repeatedly
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Now covers unified `blue install` that manages:
- Hooks (SessionStart + PreToolUse)
- Skills (symlinks to ~/.claude/skills/)
- MCP Server (configuration in ~/.claude.json)
Also adds `blue uninstall` and `blue doctor` for health checks.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Proposes `blue hooks` subcommand for managing Claude Code hooks:
blue hooks install - Install all Blue hooks
blue hooks uninstall - Remove Blue hooks
blue hooks status - Show current hook status
blue hooks check - Verify hooks work correctly
Benefits: one-command setup, portable, idempotent, reversible.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added SessionStart hook that adds $CLAUDE_PROJECT_DIR/target/release
to PATH via CLAUDE_ENV_FILE. This makes `blue` available by name in
all subsequent hooks.
- .claude/hooks/session-start.sh: Sets PATH on session start
- .claude/hooks/guard-write.sh: Now uses `blue` instead of full path
- .claude/settings.json: Added SessionStart hook
Requires Claude Code restart to take effect.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Problem: Claude Code hooks run in minimal environment without PATH.
Commands by name hang; only full paths work.
Solution: Use $CLAUDE_PROJECT_DIR for portable binary resolution:
"$CLAUDE_PROJECT_DIR/target/release/blue" guard --path="$FILE_PATH"
This is documented Claude Code behavior - hooks don't inherit shell
initialization for security reasons.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Guard now runs synchronously before tokio runtime initialization:
- Added maybe_handle_guard_sync() pre-main check
- Added run_guard_sync() with full guard logic
- Added is_in_allowlist_sync() and is_source_code_path_sync()
- main() now checks for guard before calling tokio_main()
This eliminates tokio overhead for guard invocations and provides
correct architecture (pre-init gates don't depend on post-init infra).
Note: PATH-based command lookup still hangs in Claude Code's hook
environment - this is a Claude Code issue, not Blue. The hook still
requires full binary path as workaround.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Emerged from alignment dialogue with 5 experts (unanimous convergence).
Problem: guard command runs async within tokio::main, causing hangs
when invoked from Claude Code hooks.
Solution: Run guard synchronously before tokio runtime initialization.
Pre-init gates should not depend on post-init infrastructure.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The original hook syntax `blue guard --path="$TOOL_INPUT:file_path"`
didn't work - Claude Code doesn't support that variable interpolation.
Created guard-write.sh that:
- Reads JSON from stdin using jq (Claude Code's recommended pattern)
- Extracts file_path from tool_input
- Calls blue guard with full path to target/release binary
- Closes stdin with </dev/null to prevent hanging
The full binary path is a workaround for an issue where PATH-based
command lookup hangs in Claude Code's hook subprocess environment.
A proper fix (making guard synchronous before tokio::main) is tracked
in RFC 0049.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Git worktree names are stored in .git/worktrees/<name> and cannot
contain slashes. The code was using branch names like "feature/slug"
or "rfc/name" as worktree names, which git2 rejects silently.
Now the worktree name is derived from the path's directory name (the
slug), which is always a simple identifier without slashes.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extends lint.rs with Mermaid block validation:
- Neutral theme declaration check (Error, auto-fixable)
- Custom fill color detection (Error, requires manual fix)
- LR flow >3 leaf nodes warning (Advisory)
- Leaf node counting algorithm (excludes subgraphs/style/comments)
Adds 15 test cases covering all lint scenarios.
Also fixes dialogue.rs test assertions to match template text.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Establishes mandatory standards for Mermaid diagrams in Blue documents:
- Neutral theme required for dark/light mode compatibility
- Leaf node counting for LR flow warnings (>3 nodes)
- Plain text for architecture labels (no emoji color injection)
- Shape semantics advisory for new diagrams
- Auto-fix for theme declaration only (colors require manual review)
Includes alignment dialogue with 10/10 tensions resolved across 3 rounds.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add plan_cache table to base SCHEMA so fresh databases have it
(was only created via migration, causing "no such table" errors)
- Change worktree branch naming from `{title}` to `feature/{slug}`
- Add slugify() to handle titles with spaces like "Minimal Job Submission"
- Update cleanup handler to use same naming convention
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add 'resolved' outcome for spikes where a fix is applied during investigation.
Requires fix_summary parameter describing what was fixed. File renames to .resolved.md.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The Judge spawned expert agents with run_in_background: true, which caused
the Judge's turn to end immediately after spawning. Users had to manually
type "proceed" to resume scoring and convergence. Removing the flag keeps
parallel execution (multiple Task calls in one message) while blocking
until all agents return summaries, so the Judge auto-proceeds through
rounds without intervention.
Also includes RFC 0033 round-scoped file architecture updates: coerce_bool
for MCP string booleans, mandatory agent return summaries, token budget
documentation, and write-artifacts workflow step.
Spike: alignment-dialogue-halts-after-expert-completion
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace JSONL extraction pipeline with direct file writes: alignment-expert
agents write perspectives to /tmp/blue-dialogue/{slug}/round-{n}/{name}.md,
and the Judge reads those files directly after Task completion.
Changes:
- alignment-expert.md: add Write tool
- dialogue.rs: create output_dir, pass to build_judge_protocol
- Add name_lowercase field to agent JSON for filename generation
- Add WRITE YOUR OUTPUT section to agent prompt template
- Update Judge instructions with mkdir + Read tool workflow
- Add output_dir to returned protocol JSON
- New test: test_build_judge_protocol_output_paths
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Every document filename now mirrors its lifecycle state with a status
suffix (e.g., .draft.md, .wip.md, .accepted.md). No more bare .md for
tracked document types. Also renamed all from_str methods to parse to
avoid FromStr trait confusion, introduced StagingDeploymentParams struct,
and fixed all 19 clippy warnings across the codebase.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix "Round 0" → "Round 1" for opening arguments in alignment dialogues
- Convert spike titles to kebab-case for consistent filenames
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Alignment dialogues now use custom `alignment-expert` subagents with
max_turns: 10, tool restrictions (Read/Grep/Glob), and hard 400-word
output limits. Judge protocol injects as prose via RFC 0023. Moved
Blue voice patterns from CLAUDE.md to MCP server instructions field
for cross-repo portability.
Includes RFCs 0017-0026, spikes, and alignment dialogues from
2026-01-25/26 sessions.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Separate mcp_root from cwd so tool-arg overrides don't clobber the
session-level root from initialize. Fallback chain matches RFC spec:
cwd → mcp_root → walk tree → fail with guidance. Error messages now
include attempted paths and actionable fix suggestions. Added --debug
flag to MCP server for file-based DEBUG logging.
Phase 2 finding: Claude Code v2.1.19 declares roots capability but
sends no roots array. Walk-up is the primary detection path.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add slug-based document lookup so kebab-case queries ("filesystem-authority")
match titles ("Filesystem Authority") via deslugification. Implement
next_number_with_fs() that scans both DB and filesystem directory, taking
max(db, fs) + 1 to prevent numbering collisions when files exist outside
the index. Update all 7 callers across MCP handlers. Add blue.db to
.gitignore since it is a derived index. Includes 9 new tests covering
slug matching, filesystem-aware numbering, and collision regression.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Plan files (.plan.md) are now the authoritative source for RFC task
tracking, with SQLite as a derived cache rebuilt on read.
Changes:
- Add plan.rs with PlanFile parsing/generation
- Add schema v7 migration for plan_cache table
- Modify handle_rfc_plan to write .plan.md files
- Modify handle_rfc_task_complete to update .plan.md
- Implement rebuild-on-read for stale cache detection
- Add RFC header validation (table vs inline format)
- Extend blue_lint with headers check and --fix support
Also includes spike investigating Claude Code task integration.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace redundant closures with function references
- Use next_back() instead of last() for DoubleEndedIterator
- Fix test_parse_index_response_invalid to use actually invalid YAML
(previous test string was valid YAML - a plain string with braces)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- RFC 0014: Workflow Enforcement Parity - conversational hints over JSON
- RFC 0015: Cert-Manager with Let's Encrypt for TLS on K3s cluster
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
RFC 0012 was implemented with Option B (MCP orchestrates via Ollama)
instead of Option A (Claude orchestrates via Task tool). This caused:
- No parallel agents spawned
- Fake Ollama responses instead of real deliberation
- Inline JSON instead of .dialogue.md files
Fix by removing blue_alignment_play tool entirely. Claude now
orchestrates alignment dialogues directly using Task tool per ADR 0014.
Also:
- Add pub mod resources for RFC 0016/0017 (was missing)
- Update lib.rs threading for spawn_blocking
- Add .blue/worktrees/ to gitignore
- Update database schema
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
After creating a worktree, detect the project type and suggest
the appropriate install command:
- Node.js: bun/pnpm/yarn/npm based on lock file
- Python: uv/poetry/pip based on lock file
- Rust: cargo build
- Go: go mod download
- Generic: Makefile
Custom scripts/setup-worktree.sh takes precedence over auto-detection.
Ported from coherence-mcp.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add blue_alignment_play MCP tool for multi-expert deliberation:
- Core alignment module with Expert, Round, ExpertResponse types
- Panel templates: Infrastructure, Product, ML, Governance, General
- Ollama integration for running expert rounds until convergence
- Dialogue markdown generation with SQLite tracking
- RFC linking support
Also removes dead code (ADR 0010: No Dead Code).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Completes RFC 0013 git forge integration:
- Add BlueConfig struct for .blue/config.yaml persistence
- Add detect_forge_type_cached() and create_forge_cached() functions
that cache detected forge type to avoid repeated API probing
- Update handle_pr_merge to use native forge API instead of gh CLI
- Add force parameter for skipping precondition checks when gh unavailable
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add forge module with Forge trait for unified PR operations
- Implement GitHubForge with REST API client
- Implement ForgejoForge with REST API client (works with Gitea too)
- Add git URL parsing to extract host, owner, repo from remotes
- Add auto-detection of forge type from remote URLs
- Update blue_pr_create to use native forge API instead of gh CLI
- Support GITHUB_TOKEN and FORGEJO_TOKEN environment variables
The forge abstraction allows Blue to create PRs on both GitHub and
Forgejo/Gitea instances without requiring external CLI tools.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Update blue_worktree_create description with workflow context
- Fix blue_next to use MCP tool syntax instead of CLI syntax
- Update generate_hint() to name tools explicitly
- Add next_action field when RFC status becomes accepted
- Add warning when RFC goes in-progress without worktree
- Update pr_create and rfc_complete descriptions with workflow context
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The stop_sequences contained "```" which caused the model to stop
immediately after outputting "```yaml", truncating the entire response.
Also wrap blocking indexer operations in spawn_blocking to avoid
runtime conflicts with reqwest::blocking::Client.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements the AI-powered indexing component of RFC 0010:
- Add indexer module with LlmProvider abstraction
- Integrate qwen2.5:3b via Ollama for local file analysis
- Extract summaries, relationships, and symbols from source files
- Support partial indexing for files >1000 lines
- Wire indexer to all CLI index commands (--all, --diff, --file, --refresh)
The indexer generates structured YAML output with:
- One-sentence file summaries
- Relationship descriptions for semantic search
- Symbol-level indexing with line numbers
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds the foundation for AI-maintained semantic file indexing:
Schema (v4 migration):
- file_index table with summary, relationships, prompt_version
- symbol_index table with name, kind, line numbers, description
- FTS5 virtual tables for full-text search
CLI commands (blue index):
- --all: Bootstrap full index
- --diff: Index staged files (for pre-commit hook)
- --file: Single file indexing
- --refresh: Re-index stale entries
- --install-hook: Install git pre-commit hook
- status: Show index freshness
MCP tools:
- blue_index_status: Get index stats
- blue_index_search: FTS5 search across files/symbols
- blue_index_impact: Analyze change blast radius
- blue_index_file: Store AI-generated index data
- blue_index_realm: List all indexed files
Remaining work: Ollama integration for actual AI indexing.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Spike investigation into AI-maintained semantic indexing for realms.
12-expert dialogue refined through 6 rounds to 96% alignment.
Key decisions:
- Storage: SQLite + FTS5, relationships stored at index time
- Triggers: Git pre-commit hook on diff, --all for bootstrap
- Model: Qwen2.5:3b via Ollama (speed/quality sweet spot)
- Granularity: Symbol-level with line numbers
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
