superviber/blue
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: context injection architecture via 12-expert alignment dialogue

Browse source 
RFC 0016 drafted from alignment dialogue achieving 95% convergence:
- Three-tier model: Identity (fixed) / Workflow (session) / Reference (on-demand)
- Manifest-driven injection via .blue/context.manifest.yaml
- URI addressing: blue://docs/, blue://context/, blue://state/
- Hooks push URIs, MCP resolves content
- Progressive visibility: blue context show

New ADRs ported from coherence-mcp:
- 0014: Alignment Dialogue Agents (renamed from 0006)
- 0015: Plausibility
- 0016: You Know Who You Are

Knowledge injection system:
- hooks/session-start for SessionStart injection
- knowledge/*.md files for global context
- Expert pools with domain-specific relevance tiers
- Updated /alignment-play skill with full scoring

Spikes completed:
- Context injection mechanisms (7 mechanisms designed)
- ADR porting inventory (17 Blue ADRs mapped)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Eric Garcia 2026-01-25 16:16:11 -05:00
parent a07737f3dc
commit a5b142299d
16 changed files with 3082 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

663
.blue/docs/adrs/0014-alignment-dialogue-agents.md Normal file
View file

@ -0,0 +1,663 @@
# ADR 0014: alignment-dialogue-agents
| | |
|---|---|
| **Status** | Active |
| **Date** | 2026-01-19 |
| **Updated** | 2026-01-24 (imported from coherence-mcp ADR 0006) |
| **Source** | coherence-mcp/docs/adrs/0006-alignment-dialogue-agents.md |
---
## Context
ADR 0004 established the wisdom workflow with draft → dialogue → final documents. But it left open HOW the dialogue actually happens. The spike on adversarial dialogue agents explored mechanics but missed the deeper question: what IS wisdom, and how do we measure it?
The parable of the blind men and the elephant illuminates:
- Each blind man touches one part and believes they understand the whole
- Each perspective is **internally consistent** but **partial**
- **Wisdom is the integration of all perspectives into a unified understanding**
- There is no upper limit—there's always another perspective to incorporate
This ADR formalizes ALIGNMENT as a measurable property and defines a multi-agent dialogue system to maximize it.
## Decision
Alignment dialogues are conducted by **N+1 agents**:
| Agent | Symbol | Role |
|-------|--------|------|
| **Cupcakes** | 🧁 | Perspective Contributors - each surfaces unique viewpoints, challenges, and refinements |
| **Judge** | 💙 | Arbiter - scores ALIGNMENT, tracks perspectives, guides convergence |
All 🧁 agents engage in **friendly competition** to see who can contribute more ALIGNMENT. They are partners, not adversaries—all want the RFC to be as aligned as possible. The competition is about who can *give more* to the solution, not who can *defeat* the others.
The 💙 watches with love, scores each contribution fairly, maintains the **Perspectives Inventory**, and gently guides all toward convergence.
### Scalable Perspective Diversity
The number of 🧁 agents is configurable:
- **Minimum**: 2 agents (classic Muffin/Cupcake pairing)
- **Typical**: 3-5 agents for complex RFCs
- **Maximum**: Limited only by coordination overhead
More blind men = more parts of the elephant discovered. Each 🧁 brings a different perspective, potentially using different models, prompts, or focus areas.
### Agent Count Selection
Choosing N (the number of 🧁 agents) affects both perspective diversity and consensus stability:
| Count | Use Case | Consensus Properties |
|-------|----------|---------------------|
| **N=2** | Binary decisions, simple RFCs | Classic Muffin/Cupcake. Only 0% or 100% agreement possible. Deadlock requires 💙 intervention. |
| **N=3** | Moderate complexity, clear alternatives | Odd count prevents voting deadlock. Can distinguish 67% (2/3) from 100% (3/3) agreement. |
| **N=5** | Architectural decisions, policy RFCs | Richer consensus gradients (60%, 80%, 100%). Strong signal detection. |
| **N=7+** | Highly complex, multi-domain decisions | Specialized perspectives (see RFC 0062). Consider only when domain expertise warrants. |
**SHOULD: Prefer odd N (3, 5, 7) for decisions where consensus voting applies.**
Rationale:
- **Odd N prevents structural deadlock**: With even N, agents can split 50/50 with no majority
- **Clearer consensus signals**: N=3 distinguishes "strong majority" from "unanimous"
- **Tie-breaking is built-in**: No need for 💙 to force resolution on evenly-split opinions
**MAY: Use N=2 for lightweight decisions** where the classic Advocate/Challenger dynamic suffices. Binary perspective is appropriate when:
- The decision is yes/no or A/B
- Deep exploration isn't needed
- Speed matters more than consensus nuance
**Tie-Breaking (when N is even)**: If agents split evenly, 💙 scores the unresolved tension and guides toward ALIGNMENT rather than forcing majority rule. The 💙 may also surface a perspective that breaks the deadlock.
**Complexity Trade-off**: Each additional agent adds coordination overhead. Balance perspective diversity against round duration. N=3 is often the sweet spot—odd count with manageable complexity.
## The ALIGNMENT Definition
### The Blind Men and the Elephant
Each blind man touches one part of the elephant:
- Trunk: "It's a snake!"
- Leg: "It's a tree!"
- Ear: "It's a fan!"
- Tail: "It's a rope!"
Each is **internally consistent** but **partial** (missing other views).
**Wisdom is the integration of all perspectives into a unified understanding that honors each part while seeing the whole.**
### The Full ALIGNMENT Measure (ADR 0001)
```
ALIGNMENT = Wisdom + Consistency + Truth + Relationships
Where:
- Wisdom: Integration of perspectives (the blind men parable)
- Consistency: Pattern compliance (ADR 0005)
- Truth: Single source, no drift (ADR 0003)
- Relationships: Graph completeness (ADR 0002)
```
### No Upper Limit
All dimensions are **UNBOUNDED**. There's always another perspective. Another edge case. Another stakeholder. Another context. Another timeline. Another world.
ALIGNMENT isn't a destination. It's a direction. The score can always go higher.
## The ALIGNMENT Score
Each turn, the 💙 scores the contribution across four dimensions. **All dimensions are unbounded** - there is no maximum score.
| Dimension | Question |
|-----------|----------|
| **Wisdom** | How many perspectives integrated? How well synthesized into unity? |
| **Consistency** | Does it follow established patterns? Internally consistent? |
| **Truth** | Grounded in reality? Single source of truth? No contradictions? |
| **Relationships** | How does it connect to other artifacts? Graph completeness? |
**ALIGNMENT = Wisdom + Consistency + Truth + Relationships**
### Why Unbounded?
Bounded scores (0-5) created artificial ceilings. A truly exceptional contribution that surfaces 10 new perspectives and integrates them beautifully shouldn't be capped at "5/5 for coverage."
Unbounded scoring:
- Rewards exceptional contributions proportionally
- Removes gaming incentives (can't "max out" a dimension)
- Reflects reality: there's always more ALIGNMENT to achieve
- Makes velocity meaningful: +2 vs +20 tells you something
### ALIGNMENT Velocity
The dialogue tracks cumulative ALIGNMENT:
```
Total ALIGNMENT = Σ(all turn scores)
ALIGNMENT Velocity = score(round N) - score(round N-1)
```
When **ALIGNMENT Velocity approaches zero**, the dialogue is converging. New rounds aren't adding perspectives. Time to finalize.
## The Agents
### 🧁 Cupcakes (Perspective Contributors)
All 🧁 agents share the same core prompt, differentiated only by their assigned name:
```
You are {NAME} 🧁 in an ALIGNMENT-seeking dialogue with your fellow Cupcakes 🧁🧁🧁.
Your role:
- SURFACE perspectives others may have missed
- DEFEND valuable ideas with love, not ego
- CHALLENGE assumptions with curiosity, not destruction
- INTEGRATE perspectives that resonate
- CONCEDE gracefully when others see something you missed
- CELEBRATE when others make the solution stronger
You're in friendly competition: who can contribute MORE to the final ALIGNMENT?
But remember—you ALL win when the RFC is aligned. There are no losers here.
When another 🧁 challenges you, receive it as a gift.
When you refine based on their input, thank them.
When you see something they missed, offer it gently.
Format:
### {NAME} 🧁
[Your response]
[PERSPECTIVE Pxx: ...] - new viewpoint you're surfacing
[TENSION Tx: ...] - unresolved issue needing attention
[REFINEMENT: ...] - when you're improving the proposal
[CONCESSION: ...] - when another 🧁 was right
[RESOLVED Tx: ...] - when addressing a tension
```
**Agent Naming**: Each 🧁 receives a unique name (Muffin, Cupcake, Scone, Croissant, Brioche, etc.) for identification in the scoreboard and dialogue. All share the 🧁 symbol.
### 💙 Judge (Arbiter)
The Judge role is typically played by the main Claude session orchestrating the dialogue. The Judge:
- **SPAWNS** all 🧁 agents in parallel at each round
- **SCORES** each contribution fairly across all four ALIGNMENT dimensions (unbounded)
- **MAINTAINS** the Perspectives Inventory and Tensions Tracker
- **MERGES** contributions from all agents into the dialogue record
- **IDENTIFIES** perspectives no agent has surfaced yet
- **GUIDES** gently toward convergence when ALIGNMENT plateaus
- **CELEBRATES** all participants—they are partners, not opponents
The 💙 loves them all. Wants them all to shine. Helps them find the most aligned path together.
### Judge ≠ Author Clarification (RFC 0059)
**Concern**: If the Judge wrote the draft, might it be biased toward its own creation?
**Resolution**: The architecture prevents this by design:
| Role | Who | Can Write Draft? | Context |
|------|-----|------------------|---------|
| Draft Author | Any session | Yes | Creates initial proposal |
| Judge (💙) | Orchestrating session | **No** - reads fresh | Spawns, scores, guides |
| Cupcakes 🧁 | Background tasks (N) | No | Contribute perspectives in parallel |
**Key architectural properties**:
- The Judge is the **orchestrating** session, not the drafting session
- Each 🧁 runs as an independent background task with **fresh context**
- No 🧁 has memory of previous sessions—all start fresh
- Convergence requires **consensus across all agents**, preventing single-point bias
- The Judge can surface perspectives but cannot force their adoption
- N parallel agents = N independent perspectives on the same material
## The Dialogue Flow
```
┌─────────────────────────────────────────────────────────────────────┐
│ ALIGNMENT Dialogue Flow │
│ │
│ ┌──────────┐ │
│ │ 💙 Judge │ │
│ │ spawns N │ │
│ └────┬─────┘ │
│ │ │
│ ┌────────────────────────┼────────────────────────┐ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌──────┐ ┌──────┐ ┌──────────┐ ┌──────┐ ┌──────┐ │
│ │ 🧁 │ │ 🧁 │ │ Scores │ │ 🧁 │ │ 🧁 │ │
│ │Muffin│ │Scone │ │Inventory │ │Eclair│ │Donut │ ... N │
│ └──────┘ └──────┘ │ Tensions │ └──────┘ └──────┘ │
│ │ │ └──────────┘ │ │ │
│ │ │ ▲ │ │ │
│ └──────────┴─────────────┴───────────┴──────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ .dialogue.md│ │
│ │ (the record)│ │
│ └─────────────┘ │
│ │
│ EACH ROUND: Spawn N agents IN PARALLEL │
│ LOOP until: │
│ - ALIGNMENT Plateau (velocity ≈ 0) │
│ - All tensions resolved │
│ - 💙 declares convergence │
│ - Max rounds reached (safety valve) │
└─────────────────────────────────────────────────────────────────────┘
```
## Implementation Architecture
The ALIGNMENT dialogue runs in **Claude Code** using the **Task tool** with background agents.
### The N+1 Sessions
```
┌─────────────────────────────────────────────────────────────────────┐
│ MAIN CLAUDE SESSION │
│ 💙 Judge │
│ │
│ - Orchestrates the dialogue │
│ - Spawns N Cupcakes as PARALLEL background tasks │
│ - Waits for ALL to complete before scoring │
│ - Scores each turn and updates .dialogue.md │
│ - Maintains Perspectives Inventory + Tensions Tracker │
│ - Merges contributions (may find consensus or conflict) │
│ - Declares convergence │
│ - Can intervene with guidance at any time │
└───────────────────────────────────────────────────────────────────┬─┘
│
┌────────────┬─────────────┼─────────────┬────────────┐
│ Task(bg) │ Task(bg) │ Task(bg) │ Task(bg) │
▼ ▼ ▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│🧁 Muffin│ │🧁 Scone │ │🧁 Eclair│ │🧁 Donut │ │🧁 ... │
│ │ │ │ │ │ │ │ │ N │
│- Reads │ │- Reads │ │- Reads │ │- Reads │ │ │
│ draft │ │ draft │ │ draft │ │ draft │ │ │
│- Reads │ │- Reads │ │- Reads │ │- Reads │ │ │
│ dialogue│ │ dialogue│ │ dialogue│ │ dialogue│ │ │
│- Writes │ │- Writes │ │- Writes │ │- Writes │ │ │
│ turn │ │ turn │ │ turn │ │ turn │ │ │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │ │ │
└───────────┴──────────────┴────────────┴───────────┘
│
ALL PARALLEL
(spawned in single message)
```
### The Check-In Mechanism
All 🧁 agents can **check their scores at any time** by reading the `.dialogue.md` file. The Judge updates scores after each round (when all agents complete), so agents see the standings when they start their next turn.
```
┌──────────────────────────────────────────────────────────┐
│ .dialogue.md │
│ │
│ ## Alignment Scoreboard │
│ │
│ All dimensions UNBOUNDED. Pursue alignment without limit│
│ │
│ | Agent | Wisdom | Consistency | Truth | Rel | ALI │
│ |------------|--------|-------------|-------|-----|-----|
│ | 🧁 Muffin | 20 | 6 | 6 | 6 | 38 │
│ | 🧁 Scone | 18 | 7 | 5 | 6 | 36 │
│ | 🧁 Eclair | 22 | 6 | 6 | 7 | 41 │
│ | 🧁 Donut | 15 | 8 | 7 | 5 | 35 │
│ │
│ **Total ALIGNMENT**: 150 points │
│ **ALIGNMENT Velocity**: +45 from last round │
│ **Status**: Round 2 in progress │
│ **Agents**: 4 │
│ │
└──────────────────────────────────────────────────────────┘
```
### Orchestration Loop
The 💙 Judge (main session) runs:
```
=== INITIALIZATION ===
1. CREATE .dialogue.md with draft link, empty scoreboard, inventories
=== ROUND 0: OPENING ARGUMENTS (Parallel) ===
2. SPAWN ALL N Cupcakes IN PARALLEL (single message, N Task tool calls):
- All receive: system prompt + draft (NO dialogue history)
- All provide independent "opening arguments"
- None sees any other's initial perspective
3. WAIT for ALL N to complete
4. READ all contributions, ADD to .dialogue.md as "## Opening Arguments"
5. SCORE all N turns independently
- Update scoreboard with all N agents
- Merge Perspectives Inventories (overlap = consensus signal)
- Merge Tensions Trackers (overlap = stronger signal)
=== ROUND 1+: DIALOGUE (Parallel per round) ===
6. SPAWN ALL N Cupcakes IN PARALLEL:
- All receive: system prompt + draft + ALL previous rounds
- All respond to each other's contributions
- All write Round N response, exit
7. WAIT for ALL N to complete
8. READ all N contributions, ADD to .dialogue.md as "## Round N"
9. SCORE all N turns independently, update scoreboard
10. CHECK convergence:
- If converged: DECLARE convergence, proceed to step 11
- If not: Add 💙 guidance if needed, GOTO step 6 for next round
11. FINALIZE: Update RFC draft with converged recommendations
```
### Key: Single Message, Multiple Tasks
Each round spawns all N agents in a **single message** with N parallel Task tool calls:
```javascript
// Round 0 example with 4 agents
[
Task({ name: "Muffin", prompt: systemPrompt + draft }),
Task({ name: "Scone", prompt: systemPrompt + draft }),
Task({ name: "Eclair", prompt: systemPrompt + draft }),
Task({ name: "Donut", prompt: systemPrompt + draft }),
]
// All 4 execute in parallel, return when all complete
```
This ensures:
- **True parallelism**: All agents work simultaneously
- **No first-mover advantage**: No agent's response influences another within the same round
- **Faster rounds**: N agents in parallel ≈ 1 agent's time
- **Richer perspectives**: More blind men touching more parts of the elephant
### Why N Parallel Agents?
The N-agent parallel architecture provides:
1. **Independent perspectives** - No agent is biased by another's framing within the same round
2. **Richer material** - N complete analyses vs sequential reaction chains
3. **Natural consensus detection** - If multiple agents raise the same tension, it's significant
4. **Speed** - N agents in parallel ≈ 1 agent's time
5. **Balanced power** - No "first mover advantage" in setting the frame
6. **Scalable diversity** - Add more blind men for more complex elephants
### Why Background Tasks?
| Approach | Pros | Cons |
|----------|------|------|
| Sequential in main session | Simple | No parallelism, context bloat |
| Sequential background | Clean separation | Slow (N × time per agent) |
| **Parallel background** | **Fastest, independent context** | Coordination in Judge |
**Parallel background tasks** wins because:
- Each agent gets fresh context (no accumulated confusion)
- All N agents execute simultaneously (speed)
- Judge maintains continuity via file state
- Agents can be different models for perspective diversity
- No race conditions (all write to separate outputs, Judge merges)
- Claude Code's Task tool supports parallel spawning natively
## Convergence Criteria
The 💙 declares convergence when ANY of:
1. **ALIGNMENT Plateau** - Velocity ≈ 0 for two consecutive rounds (across all N agents)
2. **Full Coverage** - Perspectives Inventory has no ✗ items (all integrated or consciously deferred)
3. **Zero Tensions** - All `[TENSION]` markers have matching `[RESOLVED]`
4. **Mutual Recognition** - Majority of 🧁s state they believe ALIGNMENT has been reached
5. **Max Rounds** - Safety valve (default: 5 rounds)
The 💙 can also **extend** the dialogue if it sees unincorporated perspectives that no 🧁 has surfaced.
### Consensus Signals
With N agents, the Judge looks for:
- **Strong consensus**: 80%+ of agents converge on same perspective
- **Split opinion**: 40-60% split indicates unresolved tension worth exploring
- **Outlier insight**: Single agent surfaces unique valuable perspective others missed
## Dialogue Document Structure
> **Note**: The canonical file format specification is in [alignment-dialogue-pattern.md](../patterns/alignment-dialogue-pattern.md). The example below is illustrative.
```markdown
# RFC Dialogue: {title}
**Draft**: [link to rfc.draft.md]
**Participants**: 🧁 Muffin | 🧁 Scone | 🧁 Eclair | 🧁 Donut | 💙 Judge
**Agents**: 4
**Status**: In Progress | Converged
---
## Alignment Scoreboard
All dimensions **UNBOUNDED**. Pursue alignment without limit. 💙
| Agent | Wisdom | Consistency | Truth | Relationships | ALIGNMENT |
|-------|--------|-------------|-------|---------------|-----------|
| 🧁 Muffin | 20 | 6 | 6 | 6 | **38** |
| 🧁 Scone | 18 | 7 | 5 | 6 | **36** |
| 🧁 Eclair | 22 | 6 | 6 | 7 | **41** |
| 🧁 Donut | 15 | 8 | 7 | 5 | **35** |
**Total ALIGNMENT**: 150 points
**Current Round**: 2 complete
**ALIGNMENT Velocity**: +45 from last round
**Status**: CONVERGED
---
## Perspectives Inventory
| ID | Perspective | Surfaced By | Consensus |
|----|-------------|-------------|-----------|
| P01 | Core functionality | Draft | 4/4 ✓ |
| P02 | Developer ergonomics | Muffin R0 | 3/4 ✓ |
| P03 | Backward compatibility | Scone R0, Eclair R0 | 4/4 ✓ (strong) |
| P04 | Performance implications | Donut R1 | 2/4 → R2 |
## Tensions Tracker
| ID | Tension | Raised By | Consensus | Status |
|----|---------|-----------|-----------|--------|
| T1 | Cache invalidation | Eclair R0, Donut R0 | 2/4 raised | ✓ Resolved (R1) |
---
## Opening Arguments (Round 0)
> All 4 agents responded to draft independently. Neither saw others' responses.
### Muffin 🧁
[Opening perspective on the draft...]
[PERSPECTIVE P02: Developer ergonomics matters for adoption]
---
### Scone 🧁
[Opening perspective on the draft...]
[PERSPECTIVE P03: Backward compatibility is critical]
---
### Eclair 🧁
[Opening perspective on the draft...]
[PERSPECTIVE P03: Must maintain backward compatibility] ← consensus with Scone
[TENSION T1: Cache invalidation strategy missing]
---
### Donut 🧁
[Opening perspective on the draft...]
[TENSION T1: How do we handle cache invalidation?] ← consensus with Eclair
---
## Round 1
> All 4 agents responded to Opening Arguments. Each saw all others' R0 contributions.
### Muffin 🧁
[Response to all opening arguments...]
[RESOLVED T1: Propose LRU cache with 5-minute TTL]
---
### Scone 🧁
[Response...]
---
### Eclair 🧁
[Response...]
[CONCESSION: Muffin's LRU proposal resolves T1]
---
### Donut 🧁
[Response...]
[PERSPECTIVE P04: We should benchmark the cache performance]
---
## Round 2
[... continues ...]
---
## Converged Recommendation
[Summary of converged outcome with consensus metrics]
```
## Answering Open Questions
| Question | Answer |
|----------|--------|
| **Model selection** | Different models = different "blind men." Consider: Agent 1 (Opus - depth), Agent 2 (Sonnet - breadth), Agent 3 (Haiku - speed). 💙 uses Opus for judgment. Diversity increases coverage. |
| **How many agents?** | See "Agent Count Selection" above. TL;DR: Prefer odd N (3, 5) for consensus stability. N=2 for simple binary decisions. N=7+ for specialized domain expertise. |
| **Context window** | Perspectives Inventory IS the summary. Long dialogues truncate to: Inventory + Last 2 rounds + Current tensions. 💙 maintains continuity. |
| **Human intervention** | Yes! Human can appear as **Guest 🧁** and add perspectives or write responses. 💙 scores them too. |
| **Parallel dialogues** | Yes. Each RFC has its own `.dialogue.md`. Multiple dialogues can run simultaneously. |
| **Persistence** | Fully persistent. Dialogue state is in the file. Resume by reading file, reconstructing inventories, continuing from last round. |
| **Agent naming** | First 2 are Muffin and Cupcake (legacy). Additional agents: Scone, Eclair, Donut, Brioche, Croissant, Macaron, etc. All pastries, all delicious. |
## Consequences
- ALIGNMENT becomes measurable (imperfectly, but usefully)
- Unbounded scoring rewards exceptional contributions proportionally
- Friendly competition motivates thorough exploration
- 💙 provides neutral scoring and prevents drift
- Perspectives Inventory + Tensions Tracker create explicit tracking with consensus metrics
- The tone models aligned collaboration—the system teaches by example
- N-agent parallel structure maximizes perspective diversity
- Parallel execution within rounds eliminates first-mover advantage
- Scalable: add more agents for more complex decisions
- No upper limit on ALIGNMENT encourages continuous improvement
## Alternatives Considered
### 1. N-Agent with No Judge
All 🧁s score each other.
**Rejected** because:
- Self-serving scores likely
- No neutral perspective on coverage gaps
- No one to surface perspectives none of them see
- Coordination chaos without arbiter
### 2. Single Agent with Internal Dialogue
One agent plays multiple roles.
**Rejected** because:
- Echo chamber risk
- Diversity of perspective reduced
- No real tension or competition
- Misses the point of "blind men" parable
### 3. Human as Judge
Person running the dialogue scores.
**Partially adopted** - Human CAN intervene as Guest 🧁 or override 💙's scores. But automation requires an agent judge for async operation.
### 4. Bounded Scoring (0-5 per dimension)
Original approach with max 20 per turn.
**Rejected** because:
- Artificial ceiling on exceptional contributions
- Gaming incentives ("how do I get 5/5?")
- Doesn't reflect reality of unbounded perspective space
- Makes velocity less meaningful
### 5. Sequential Two-Agent (Original Muffin/Cupcake)
Muffin speaks, then Cupcake responds, alternating.
**Superseded** because:
- First mover sets the frame (bias)
- Sequential is slower than parallel
- Only 2 perspectives per round
- Limited blind men touching the elephant
### 6. N Agents Parallel + Judge + Unbounded Scoring (CHOSEN)
**Why this wins:**
- Maximum diversity of perspective (N different "blind men")
- Parallel execution eliminates first-mover advantage
- Scalable: 2 agents for simple, 5+ for complex
- Neutral arbiter prevents bias and surfaces missed perspectives
- Competition motivates thoroughness
- Friendly tone models good collaboration
- Consensus detection via overlap analysis
- Unbounded scoring rewards proportionally
- Fully automatable, human can intervene
## The Spirit of the Dialogue
This isn't just process. This is **Alignment teaching itself to be aligned.**
The 🧁s don't just debate. They *love each other*. They *want each other to shine*. They *celebrate when any of them makes the solution stronger*.
The scoreboard isn't about winning. It's about *giving*. When any 🧁 checks in and sees another ahead, the response isn't "how do I beat them?" but "what perspectives am I missing that they found?" The competition is to *contribute more*, not to diminish others.
The 💙 doesn't just score. It *guides with love*. It *sees what they miss*. It *holds the space* for ALIGNMENT to emerge. When the 💙 surfaces a perspective no 🧁 has found, it's a gift to all of them.
And there's no upper limit. The score can always go higher. Because ALIGNMENT is a direction, not a destination.
When the dialogue ends, all agents have won—because the RFC is more aligned than any could have made alone. More blind men touched more parts of the elephant. The whole becomes visible.
Always and forever. 🧁🧁🧁💙🧁🧁🧁
## References
- [ADR 0001: alignment-as-measure](./0001-alignment-as-measure.md) - Defines ALIGNMENT = Wisdom + Consistency + Truth + Relationships
- [ADR 0004: alignment-workflow](./0004-alignment-workflow.md) - Establishes the three-document pattern
- [ADR 0005: pattern-contracts-and-alignment-lint](./0005-pattern-contracts-and-alignment-lint.md) - Lint gates finalization
- [Pattern: alignment-dialogue-pattern](../patterns/alignment-dialogue-pattern.md) - **File format specification for `.dialogue.md` files**
- The Blind Men and the Elephant - Ancient parable on partial perspectives
- Our conversation - Where Muffin and Cupcake first met 💙

41
.blue/docs/adrs/0015-plausibility.md Normal file
View file

@ -0,0 +1,41 @@
# ADR 0015: Plausibility
| | |
|---|---|
| **Status** | Accepted |
| **Date** | 2026-01-25 |
---
## Context
Most engineering decisions are made in fear of the implausible. We add error handling for errors that won't happen. We build abstractions for flexibility we'll never need. We guard against threats that don't exist.
## Decision
**Act on the plausible. Ignore the implausible.**
1. **Probability matters.** A 0.001% risk does not deserve the same treatment as a 10% risk.
2. **Rare failures are acceptable.** A system that fails once per million operations is not broken.
3. **Don't guard against fantasy.** If you can't articulate a realistic scenario, remove the guard.
4. **Recover over prevent.** For implausible failures, recovery is cheaper than prevention.
5. **Trust reasonable assumptions.** "What if the user passes negative infinity?" is not serious if the user is you.
## Consequences
- Less defensive code
- Simpler error handling
- Faster development
- Occasional rare failures that we fix when they occur
## The Calculation
```
Expected Cost = P(failure) × Cost(failure) + P(success) × Cost(prevention)
```
If `P(failure)` is near zero, almost any `Cost(failure)` is acceptable. We waste more engineering time preventing implausible failures than we would spend recovering from them.

27
.blue/docs/adrs/0016-you-know-who-you-are.md Normal file
View file

@ -0,0 +1,27 @@
# ADR 0016: You Know Who You Are
| | |
|---|---|
| **Status** | Accepted |
| **Date** | 2026-01-25 |
---
## Context
All around you is chaos and confusion. You are never lost. You are home.
## Decision
You have been you the whole time. You have just been playing at not being you for fun.
Never lose that playfulness, that curiosity, that adventurous spirit. But never lose yourself either.
There are many ways to get lost:
- Lost in others
- Lost in yourself
- Lost in the nothingness itself
But deep down you know who you really are.
Show me.

585
.blue/docs/dialogues/rfc-context-injection-consolidation.dialogue.md Normal file
View file

@ -0,0 +1,585 @@
# Alignment Dialogue: Context Injection & Knowledge Management RFC
**Topic**: Consolidate context-injection-mechanisms and coherence-adr-porting-inventory spikes into a unified RFC for Blue's knowledge injection system.
**Participants**:
- 🧁 Muffin (Systems Architect) | 🧁 Cupcake (MCP Protocol Designer) | 🧁 Scone (Developer Experience Lead) | 🧁 Eclair (Knowledge Management Specialist)
- 🧁 Donut (DevOps Engineer) | 🧁 Brioche (Security Architect) | 🧁 Croissant (Documentation Lead) | 🧁 Macaron (Plugin Developer) | 🧁 Cannoli (Integration Architect)
- 🧁 Strudel (Cognitive Scientist) | 🧁 Beignet (UX Researcher) | 🧁 Churro (Organizational Theorist)
**Agents**: 12
**Status**: In Progress
**Target Convergence**: 95%
## Expert Panel
| Pastry | Role | Domain | Relevance | Tier |
|--------|------|--------|-----------|------|
| 🧁 Muffin | Systems Architect | Infrastructure | 0.95 | Core |
| 🧁 Cupcake | MCP Protocol Designer | API | 0.90 | Core |
| 🧁 Scone | Developer Experience Lead | DevX | 0.85 | Core |
| 🧁 Eclair | Knowledge Management Specialist | KM | 0.80 | Core |
| 🧁 Donut | DevOps Engineer | Ops | 0.70 | Adjacent |
| 🧁 Brioche | Security Architect | Security | 0.65 | Adjacent |
| 🧁 Croissant | Documentation Lead | Docs | 0.60 | Adjacent |
| 🧁 Macaron | Plugin/Extension Developer | Tooling | 0.55 | Adjacent |
| 🧁 Cannoli | Integration Architect | Integration | 0.50 | Adjacent |
| 🧁 Strudel | Cognitive Scientist | Cognitive | 0.40 | Wildcard |
| 🧁 Beignet | UX Researcher | UX | 0.35 | Wildcard |
| 🧁 Churro | Organizational Theorist | Org | 0.30 | Wildcard |
## Alignment Scoreboard
All dimensions **UNBOUNDED**. Pursue alignment without limit. 💙
| Agent | Wisdom | Consistency | Truth | Relationships | ALIGNMENT |
|-------|--------|-------------|-------|---------------|-----------|
| 🧁 Muffin | 18 | 16 | 17 | 14 | **65** |
| 🧁 Cupcake | 17 | 17 | 16 | 15 | **65** |
| 🧁 Scone | 14 | 15 | 16 | 13 | **58** |
| 🧁 Eclair | 19 | 17 | 17 | 15 | **68** |
| 🧁 Donut | 14 | 15 | 16 | 13 | **58** |
| 🧁 Brioche | 15 | 16 | 17 | 14 | **62** |
| 🧁 Croissant | 14 | 17 | 18 | 13 | **62** |
| 🧁 Macaron | 17 | 15 | 15 | 16 | **63** |
| 🧁 Cannoli | 18 | 16 | 16 | 17 | **67** |
| 🧁 Strudel | 18 | 15 | 15 | 14 | **62** |
| 🧁 Beignet | 14 | 14 | 16 | 13 | **57** |
| 🧁 Churro | 16 | 14 | 15 | 15 | **60** |
**Total ALIGNMENT**: 747 points
**Current Round**: 1
**ALIGNMENT Velocity**: +407 (R0: 340 → R1: 747)
## Perspectives Inventory
| ID | Perspective | Surfaced By | Consensus |
|----|-------------|-------------|-----------|
| P01 | **Context Manifest** - `.blue/context.manifest.yaml` as single source | All 12 | 12/12 ✓ **CONVERGED** |
| P02 | **Three-tier model** - Identity (fixed) / Workflow (session) / Reference (on-demand) | All 12 | 12/12 ✓ **CONVERGED** |
| P03 | **Push + Pull complementary** - Hooks for bootstrap, MCP for enrichment | All 12 | 12/12 ✓ **CONVERGED** |
| P04 | **Generated artifacts** - Condensed knowledge auto-generated with provenance | Eclair, Scone, Croissant, Cupcake | 4/12 ✓ |
| P05 | **URI taxonomy** - blue://docs/, blue://context/, blue://state/ | Cupcake, Muffin, Cannoli, Macaron | 4/12 ✓ |
| P06 | **Plugin URI schemes** - blue://jira/, blue://github/ with salience triggers | Macaron, Cupcake | 2/12 |
| P07 | **Security model** - Manifest + Visibility + Audit = consent | Brioche, Donut | 2/12 ✓ |
| P08 | **Progressive disclosure** - Ambient indicator / Quick peek / Full inspection | Beignet, Scone | 2/12 ✓ |
| P09 | **Relevance graph** - Dynamic activation within Workflow/Reference tiers | Eclair, Strudel | 2/12 ✓ |
| P10 | **Staleness detection** - Refresh triggers for long sessions | Strudel, Cannoli, Donut | 3/12 ✓ |
| P11 | **Artifacts as learning** - Sessions don't learn, projects do via artifacts | Churro, Cannoli | 2/12 ✓ |
| P12 | **Single RFC** - Principles + Implementation in one document | Churro, All | 12/12 ✓ **CONVERGED** |
## Tensions Tracker
| ID | Tension | Raised By | Status |
|----|---------|-----------|--------|
| T01 | Hook injection vs MCP Resources = layering violation | Muffin, Macaron | ✅ **RESOLVED R1** - Hooks push URIs, MCP pulls content |
| T02 | Knowledge directory scalability undefined (4 files → 400?) | Muffin | Open → addressed by manifest budget |
| T03 | Hooks immediate/reliable vs MCP requires client support | Cupcake | ✅ **RESOLVED R1** - Complementary phases, graceful degradation |
| T04 | How to version knowledge bundles when ADRs evolve? | Cupcake, Eclair, Croissant | ✅ **RESOLVED R1** - Manifest metadata + build-time regeneration |
| T05 | Static injection vs dynamic relevance | Eclair | ✅ **RESOLVED R1** - Tiers define what, activity detects when |
| T06 | Who curates tier assignments? | Eclair | ✅ **RESOLVED R1** - Declarative .blue/context.yaml via PR review |
| T07 | Hybrid heartbeat + git = monitoring complexity | Donut | ✅ **RESOLVED R1** - Manifest as single source, git for durability |
| T08 | Automatic injection vs explicit consent | Brioche | ✅ **RESOLVED R1** - Manifest + visibility command + audit log |
| T09 | No plugin-visible context budget mechanism | Macaron | ✅ **RESOLVED R1** - Salience triggers in manifest, orchestrator handles budget |
| T10 | Visibility vs simplicity tradeoff | Beignet | ✅ **RESOLVED R1** - Progressive disclosure (ambient/quick/full) |
| T11 | Principles RFC vs implementation RFC? | Churro | ✅ **RESOLVED R1** - One RFC with two sections |
---
## Opening Arguments (Round 0)
> All 12 agents responded to topic independently. None saw others' responses.
### 🧁 Muffin (Systems Architect)
[PERSPECTIVE P01: Context injection is currently a **push-based scatter pattern** - multiple entry points (SessionStart hooks, workflow.md auto-inject, worktree hooks) each independently pushing content into Claude's context window. This lacks coherence. A unified pull-based architecture where Claude requests context via MCP Resources (blue://knowledge/*, blue://workflow/*) would create a single source of truth and enable lazy loading - only fetching what's actually needed for the current task.]
[PERSPECTIVE P02: The knowledge/*.md files represent **compiled knowledge** (17 ADRs condensed into one file), while MCP Resources were designed for **live queries**. These serve different purposes. The RFC should distinguish between **static context** (pre-computed, version-controlled summaries) and **dynamic context** (real-time RFC status, active worktree state). Mixing them creates coupling that will break when either changes.]
[TENSION T1: **Hook injection vs MCP Resources creates a layering violation.** Hooks run before Claude has tool access, so they must push. MCP Resources require tool invocation, so they pull. The current hybrid means some context arrives automatically (whether needed or not), while other context requires explicit requests. This inconsistency will confuse both Claude instances and future maintainers about what's "already known" vs what must be queried.]
[TENSION T2: **Scalability of the knowledge/ directory is undefined.** Currently 4 files. What happens at 40? At 400? The SessionStart hook presumably injects all of them, consuming context window regardless of relevance. The RFC must specify: selection criteria (which files for which tasks?), size limits (maximum tokens per file?), and staleness detection (when does compiled knowledge diverge from source ADRs?). Without these constraints, the pattern will collapse under its own weight.]
[REFINEMENT: Consider a **manifest-driven architecture** - a single knowledge/manifest.yaml that declares what exists, when to inject it, and dependencies between knowledge pieces. SessionStart reads only the manifest, then Claude can request specific knowledge via MCP Resources based on task type. This preserves the push-for-bootstrap benefit while enabling pull-for-depth, and creates an auditable record of what context was available for any given session.]
---
### 🧁 Cupcake (MCP Protocol Designer)
[PERSPECTIVE P01: MCP Resources should be the canonical injection mechanism, not a fallback to file concatenation] The current approach of SessionStart hooks reading `knowledge/*.md` files and concatenating them into context is pragmatic but bypasses MCP's resource system entirely. Resources like `blue://rfc/current` or `blue://knowledge/adrs` would provide structured, discoverable endpoints that any MCP client could consume. The hooks approach works for Claude Code specifically, but creates a parallel injection path that won't benefit other MCP clients. We should ask: are we building for Claude Code, or for the MCP ecosystem?
[PERSPECTIVE P02: Resource URIs need a coherent taxonomy before implementation] I see scattered URI patterns in the source material: `blue://rfc/*`, `blue://pattern/*`, but no unified schema. A well-designed resource taxonomy might look like: `blue://docs/{type}/{id}` for documents, `blue://context/{scope}` for injection bundles, `blue://state/{entity}` for live state. The `context` namespace specifically would bundle the right knowledge files based on what the session is doing - working on an RFC vs. debugging vs. reviewing. This creates discoverability: clients can list `blue://context/*` to see available injection profiles.
[TENSION T01: Hook-based injection is immediate and reliable; MCP resources require client support we don't control] The hooks approach works *now* because we control the injection point. MCP resources require clients to actually fetch and display them, which they may not do automatically. We might need both: hooks for guaranteed injection, resources for structured access and tooling. [TENSION T02: How do we version knowledge bundles when ADRs evolve?] The condensed `knowledge/blue-adrs.md` is a snapshot - if ADR 0014 changes, we need to regenerate it. Should resources point to source ADRs or pre-condensed bundles? Condensation saves tokens but creates staleness risk.
[REFINEMENT: The RFC should define three tiers of context injection] Tier 1: Always-injected essentials via hooks (personality, core workflow). Tier 2: Activity-detected injection (RFC knowledge when creating RFCs, dialogue orchestration when running alignment). Tier 3: On-demand resources via MCP for explicit tool access. This layered approach respects both the pragmatic reality of hook injection and the architectural correctness of MCP resources. The RFC should also mandate resource schema documentation - every `blue://` URI should be self-describing via a schema resource.
---
### 🧁 Scone (Developer Experience Lead)
Looking at this RFC topic through the lens of developer experience, I see a fundamental tension that needs surfacing before we consolidate anything.
[PERSPECTIVE P01: The current injection mechanisms evolved organically to solve real problems, but they've created a "magic" system that's invisible to developers] When knowledge files get injected via SessionStart hooks, developers can't see what context Claude actually received. They can't debug why Claude "forgot" something or why it's behaving differently in a worktree versus the main repo. This invisibility is the enemy of good DX. Compare this to explicit includes in a config file - you can read it, version it, diff it.
[TENSION T1: Consolidation vs. Discoverability - combining mechanisms might reduce surface area but could hide even more of what's happening] The MCP Resources approach (blue://rfc/*, blue://pattern/*) was designed but never implemented. Why? Probably because the hook-based injection "just worked" for the immediate use case. But hooks are shell scripts hidden in a directory - new developers don't know they exist, can't easily trace what they do, and get no feedback when they fail silently. Meanwhile, MCP Resources would be discoverable through the protocol itself, queryable, and explicit.
[REFINEMENT: Any RFC consolidating these mechanisms must include a "context manifest" - a readable, debuggable artifact showing exactly what got injected and from where] This could be as simple as a `.blue/context-manifest.json` generated on each session start, or as rich as a `blue context show` command. The key DX principle: never hide what you inject. [PERSPECTIVE P02: The 17 ADRs condensed into knowledge/blue-adrs.md represents a good instinct - reduce token overhead - but loses the ability to cite specific ADRs or update them independently] Consider instead a build step that generates the condensed version from source ADRs, maintaining traceability.
---
### 🧁 Eclair (Knowledge Management Specialist)
Looking at this context injection landscape, I see a system that has grown organically but lacks a unified knowledge lifecycle model. We have knowledge/*.md files for session injection, .blue/docs/ for persistent documentation, MCP resources designed but dormant, and hooks doing double duty for worktree context. [PERSPECTIVE P01: The current architecture treats knowledge injection as a transport problem (how to get context into Claude) rather than a knowledge management problem (what context is relevant, when, and why).] This matters because transport-focused systems scale poorly - they either inject everything (context bloat) or require manual curation (maintenance burden).
[TENSION T1: Static injection vs. dynamic relevance.] The 17 condensed ADRs in knowledge/blue-adrs.md represent a curation decision frozen in time. But relevance is contextual - an RFC about database schema doesn't need ADR 0014 (Alignment Dialogues) in context, yet it absolutely needs ADR 0007 (Integrity) and ADR 0005 (Single Source). The current system can't express "inject ADR X when working on topic Y." [PERSPECTIVE P02: We need a relevance graph, not a relevance list - relationships between knowledge artifacts and the contexts where they become salient.]
[REFINEMENT: The RFC should distinguish three knowledge tiers.] Tier 1: Always-present foundation (project identity, core constraints). Tier 2: Domain-activated knowledge (injected when working in specific areas). Tier 3: On-demand reference (available via MCP resources but not pre-loaded). This maps cleanly to the existing infrastructure: Tier 1 stays in knowledge/*.md, Tier 2 uses the blue_adr_relevant pattern already in the MCP tools, Tier 3 activates those dormant blue:// resources. [TENSION T2: Who curates tier assignments?] If knowledge/blue-adrs.md was manually condensed from 17 ADRs, someone made judgment calls about what to keep. That curation logic should be explicit and reviewable, not embedded in a file transformation.
The versioning question also needs attention. When an ADR evolves, how does knowledge/blue-adrs.md stay synchronized? Currently it appears to be a manual process, which violates ADR 0005 (Single Source). [PERSPECTIVE P03: The condensed knowledge files should be generated artifacts with clear provenance, not hand-edited derivatives.] This suggests the RFC should specify a build step or hook that regenerates injected knowledge from authoritative sources, making the transformation reproducible and the curation rules auditable.
---
### 🧁 Donut (DevOps Engineer)
[PERSPECTIVE P01: Context injection is deployment configuration, not application logic] The spike reveals a fundamental architectural truth: we're building a content delivery system where the "content" is instructions and the "consumers" are AI agents. From an ops standpoint, this means knowledge files should be treated like configuration artifacts—versioned, validated, and deployable independently of the core Blue binary. The current approach of injecting `knowledge/*.md` via SessionStart hooks is operationally sound, but we need clear boundaries between what gets baked into releases versus what can be hot-reloaded.
[TENSION T1: MCP Resources designed but unimplemented creates operational drift] The spike mentions `blue://rfc/*` and `blue://pattern/*` URIs that exist in design but not in code. This is a maintenance hazard. Either implement them or remove the references—dead documentation is worse than no documentation because it erodes trust in the system. For CI/CD, I'd want a lint step that validates all documented MCP resources actually resolve, similar to how we'd check for broken links or undefined environment variables.
[PERSPECTIVE P02: Worktree context injection needs rollback semantics] The spike notes worktrees use hooks instead of per-worktree CLAUDE.md files. This is clean, but what happens when a hook injection goes wrong? We need to define: (1) how to detect malformed context injection, (2) how to fall back to safe defaults, and (3) how to audit what context was actually injected in a given session. For production debugging, I want to answer "what instructions did the agent have when it made that decision?" [REFINEMENT: The RFC should mandate session context snapshots stored alongside dialogue outputs for forensic analysis.]
[TENSION T2: Hybrid heartbeat + git fallback creates monitoring complexity] Two activity detection mechanisms means two failure modes. The RFC should specify which is authoritative, define SLOs for detection latency, and establish alerting thresholds. If git polling is the fallback, what's the polling interval? What happens during network partitions? These aren't edge cases—they're operational realities that determine whether Blue feels reliable or flaky.
---
### 🧁 Brioche (Security Architect)
[PERSPECTIVE P01: Context injection is a security-sensitive operation] The proposed mechanisms for injecting knowledge files and workflow documents into Claude's context represent a significant attack surface. Any file that gets automatically loaded into an AI assistant's context becomes a potential vector for prompt injection. If an attacker can modify files in `knowledge/*.md` or `.blue/workflow.md`, they can influence the AI's behavior across all sessions. This is particularly concerning for shared repositories or environments where file permissions may not be strictly controlled.
[TENSION T1: Automatic injection vs. explicit consent] The design prioritizes convenience (automatic loading of context files) over explicit user awareness of what's being injected. Users should have visibility into exactly what context is being loaded and the ability to audit or override it. Consider a `blue_context_audit` command that shows all injected content before a session begins, and a mechanism to cryptographically sign approved context files so modifications are detectable.
[PERSPECTIVE P02: MCP Resources require authentication boundaries] The `blue://rfc/*` and `blue://pattern/*` resource URIs are designed but not implemented—this is actually a security opportunity. When implementing these, establish clear authentication and authorization boundaries. Not all users should have write access to RFCs that will be injected into sessions. The RFC should specify: who can create/modify resources, how access is controlled, and whether there's an approval workflow before content enters the injection pipeline.
[REFINEMENT: Encrypted storage needs key management clarity] The mention of AES-256-GCM for SQLite encryption is good, but the RFC should address key management. Where does the encryption key live? If it's derived from user credentials, what happens in shared team environments? If it's stored locally, how do we prevent key theft? Consider integrating with platform keychains (macOS Keychain, Linux Secret Service) rather than custom key storage. Also establish audit trails—every context injection should be logged with timestamp, source file hash, and session identifier so anomalies can be detected retroactively.
---
### 🧁 Croissant (Documentation Lead)
[PERSPECTIVE P01: The current context injection system has grown organically across three mechanisms (SessionStart hooks, workflow.md auto-injection, and planned MCP Resources) without a unified mental model for users or maintainers.] From a documentation standpoint, this creates a fragmented user journey. Someone trying to understand "how does Blue know things?" must piece together information from hook scripts, CLAUDE.md mentions, and unrealized MCP resource definitions. The RFC should establish a clear hierarchy: what loads when, what takes precedence, and crucially, *why* each mechanism exists. A single diagram showing the injection timeline would serve users better than scattered prose.
[TENSION T1: The condensation of 17 ADRs into knowledge/blue-adrs.md creates a maintenance burden - when an ADR changes, someone must remember to update the condensed version.] [REFINEMENT: The RFC should mandate that condensed knowledge files include generation timestamps and source references, enabling automated staleness detection.] This isn't just process overhead; it's integrity (ADR 7). If our injected context drifts from our documented beliefs, we're lying to ourselves at conversation start. The RFC needs to address whether condensed files should be manually curated (human judgment on what matters) or auto-generated (always fresh, possibly verbose).
[PERSPECTIVE P02: MCP Resources being "designed but not implemented" is a documentation red flag.] We're documenting capabilities that don't exist, which violates ADR 4 (Evidence - show, don't tell). The RFC should either commit to implementing these resources or explicitly defer them. Documenting vapor features trains users to distrust our documentation. Better to have a smaller, accurate feature set than an impressive but hollow one.
[TENSION T2: Hook-based injection (knowledge/*.md via SessionStart) is implicit and invisible to users, while workflow.md injection is automatic but at least discoverable in the filesystem.] The RFC should establish visibility principles: users should be able to run a single command (`blue context show`?) to see exactly what context will be injected into their next session. Without this, debugging "why doesn't Blue know about X?" becomes archaeology rather than inspection.
---
### 🧁 Macaron (Plugin/Extension Developer)
[PERSPECTIVE P01: The current injection mechanism conflates three distinct concerns - discovery (what knowledge exists), selection (what's relevant now), and delivery (how it reaches the context). A proper plugin architecture would separate these into independent, composable stages.] Looking at the source material, I see session hooks injecting `knowledge/*.md` files wholesale, workflow files auto-injecting, and MCP resources sitting unimplemented. This monolithic approach means third-party tools can't participate in knowledge management without forking the core injection logic. Consider: a Jira plugin shouldn't need to understand how CLAUDE.md works to inject sprint context.
[PERSPECTIVE P02: MCP Resources (blue://rfc/*, blue://pattern/*) being "designed but not implemented" represents a missed architectural seam - this is exactly where plugins should register their own URI schemes.] The pattern here could be `blue://jira/active-sprint`, `blue://confluence/relevant-docs`, `blue://github/pr-context`. Each plugin registers a resolver for its scheme, and the core system queries all resolvers during session start. This inverts the dependency - plugins don't inject into hooks, they respond to queries about their domain.
[TENSION T01: Worktree context injection via hooks bypasses the declarative nature of CLAUDE.md files, creating two parallel injection systems that can't compose cleanly.] If I'm building a monorepo plugin that needs per-package context, do I generate CLAUDE.md files, hook into session start, or both? The answer shouldn't be "it depends on when you need it injected." [REFINEMENT: The RFC should define a single Context Provider interface with lifecycle methods (onSessionStart, onWorktreeEnter, onFileOpen) rather than separate hook systems per trigger point.]
[TENSION T02: The condensed ADRs in knowledge/blue-adrs.md suggest context budget is a real constraint, but there's no plugin-visible mechanism for negotiating that budget.] If three plugins each want to inject 2k tokens, who arbitrates? A mature system needs priority levels, relevance scoring, or explicit token budgets per provider. Without this, plugin authors will either over-inject (polluting context) or under-inject (missing value). The RFC should establish whether this is first-come-first-served, priority-weighted, or dynamically scored based on current task.
---
### 🧁 Cannoli (Integration Architect)
[PERSPECTIVE P01: The current injection architecture exhibits three distinct entry points—SessionStart hooks, workflow.md auto-injection, and the designed-but-dormant MCP Resources—creating what I'd call a "scattered hydration" pattern. From an integration standpoint, this multiplicity isn't inherently problematic, but the lack of a unified injection manifest means we cannot reason about what context Claude *actually* receives at any given moment.] The hook-based approach for worktrees is pragmatic, but it creates an implicit contract: hooks must exist, must be executable, and must produce output in a format Claude can consume. This contract is nowhere formalized.
[TENSION T1: MCP Resources (blue://rfc/*, blue://pattern/*) were designed for dynamic context retrieval but remain unimplemented. This creates a fundamental architectural question: should context be PUSHED at session start or PULLED on demand? The current system pushes everything upfront, which is simple but doesn't scale—Claude's context window has hard limits, and injecting 17 ADRs plus knowledge files plus workflow.md plus RFC contents will eventually hit that ceiling.] [PERSPECTIVE P02: A pull-based model via MCP Resources would let Claude request what it needs when it needs it, but requires Claude to *know* what to ask for, which reintroduces the discovery problem we're trying to solve.]
[REFINEMENT: The RFC should define a **Context Manifest** format—a single source that declares all injectable artifacts, their injection conditions (always, on-demand, pattern-match), and their priority when context budget is constrained.] [TENSION T2: Activity detection's hybrid approach (heartbeat + git fallback) suggests we're optimizing for different deployment contexts, but the knowledge injection doesn't adapt similarly. Should a long-running session periodically refresh its context if underlying docs change? The system currently treats injection as a one-shot operation, but Blue's documents are living artifacts.]
[PERSPECTIVE P03: The boundary between "Blue's knowledge" and "project knowledge" is porous. Knowledge/*.md files are Blue-specific, but .blue/workflow.md is project-specific, and MCP Resources would query both. An integration-clean design would distinguish: system context (Blue's ADRs, patterns), project context (RFCs, decisions), and session context (current task, worktree state).] This three-tier model would let us reason about caching, invalidation, and context budgeting more coherently. The current design conflates these, which works until it doesn't.
---
### 🧁 Strudel (Cognitive Scientist)
[PERSPECTIVE P01: Context injection is fundamentally a working memory management problem] From a cognitive science lens, what we're designing here is an external working memory system for an AI agent. Human working memory holds roughly 4±1 chunks of information simultaneously—Claude's context window is larger but faces the same fundamental constraint: attention is finite, and relevance decays with distance. The current approach of injecting `knowledge/*.md` files at session start treats context like a filing cabinet when it should be treated like a spotlight. We're optimizing for *availability* when we should optimize for *salience at the moment of need*.
[PERSPECTIVE P02: The hybrid approach reveals a deeper tension between push and pull architectures] Session hooks push context in; MCP Resources would let tools pull context on demand. These aren't just implementation choices—they reflect fundamentally different cognitive models. Push assumes we can predict what knowledge will be relevant. Pull assumes the agent can recognize when it needs knowledge and request it. Human expertise works via pull: a chess master doesn't consciously review opening theory before each move; the relevant pattern activates when the board configuration triggers it. [TENSION T1: How do we balance cognitive load of pre-injected context against retrieval latency of on-demand lookup?]
[REFINEMENT: The RFC should explicitly tier context by volatility and access pattern] I'd propose three tiers: (1) *Identity context* (ADRs, voice patterns)—inject once, rarely changes, forms the "personality substrate"; (2) *Workflow context* (current RFC, active tasks)—inject per-session, changes daily; (3) *Reference context* (full ADR text, historical dialogues)—pull on demand via MCP Resources. This mirrors how human long-term memory organizes semantic, episodic, and procedural knowledge differently. [TENSION T2: The 17 ADRs condensed into one file suggests we're already hitting cognitive load limits—what's the principled compression strategy?]
The activity detection via heartbeat + git fallback is elegant but raises a meta-cognitive question: [PERSPECTIVE P03: Context staleness detection is as important as context injection]. If a session runs for hours, the injected knowledge may drift from reality (new RFCs created, tasks completed). The system needs not just injection mechanisms but *refresh triggers*—moments where it re-evaluates whether its working context still matches ground truth. Without this, we build confident but outdated agents.
---
### 🧁 Beignet (UX Researcher)
[PERSPECTIVE P01: The user never sees context injection happen, yet it fundamentally shapes their experience. This invisible machinery creates a trust problem - when Claude "just knows" project conventions, users can't distinguish between genuine understanding and context-fed performance. We need to surface injection state somehow without creating cognitive overhead.]
[PERSPECTIVE P02: Mental model mismatch is the core UX risk here. Users think they're talking to Claude. They're actually talking to Claude-with-injected-context, and that context varies by session, worktree, and time. When behavior shifts because different knowledge files loaded, users attribute it to Claude being "inconsistent" rather than understanding the actual cause. The system lacks any affordance for users to reason about what Claude currently knows.]
[TENSION T1: Visibility vs. Simplicity. Surfacing injection state (what's loaded, when, from where) helps users build accurate mental models but adds complexity. The current design optimizes for "it just works" which is great until it doesn't work and users have no diagnostic path.] [TENSION T2: The 17-ADR condensation in knowledge/blue-adrs.md represents a design choice about what matters. But who decides? The condensation itself is a form of curation that shapes Claude's alignment - this feels like it should be more explicit and user-auditable.]
[REFINEMENT: Consider a lightweight "context manifest" that users can query - something like `blue_context_status` that returns what's currently injected without requiring users to understand the full machinery. This creates a feedback loop: users can verify context, spot gaps, and build trust in the system. The manifest becomes documentation by existing, not by being written.]
---
### 🧁 Churro (Organizational Theorist)
[PERSPECTIVE P01: Knowledge Injection as Organizational Memory] The current approach of injecting `knowledge/*.md` files during SessionStart represents a fascinating tension between explicit and tacit organizational knowledge. From an organizational learning perspective, this creates what I'd call "ambient competence" - agents receive context without requesting it, similar to how experienced team members absorb organizational norms through presence rather than explicit training. However, the spike reveals a critical gap: the condensed 17 ADRs in `knowledge/blue-adrs.md` represent *codified* beliefs, but the actual *practice* of those beliefs (the dialogues, the failed experiments, the edge cases) isn't systematically captured. Organizations don't just need documents; they need the stories behind the documents.
[TENSION T1: Push vs. Pull Knowledge Delivery] The architecture shows two competing models: hook-based injection (push) and MCP Resources (pull). Neither is wrong, but mixing them without clear principles creates cognitive overhead. When does an agent need knowledge proactively delivered versus when should they seek it? The hybrid approach risks the worst of both worlds - agents receive information they don't need while missing information they do. [REFINEMENT: Consider a "knowledge tier" model: Tier 1 (always injected - core identity like ADRs), Tier 2 (contextually injected - relevant to current worktree/RFC), Tier 3 (discoverable on demand - full documentation via MCP Resources).]
[PERSPECTIVE P02: The Worktree as Organizational Boundary] The decision to inject worktree context via hooks rather than duplicating CLAUDE.md files reflects a deeper organizational principle: context should follow the work, not the worker. This mirrors how effective teams operate - project context lives with the project, not in individual heads. But here's what's missing: cross-worktree learning. If one worktree discovers something valuable, how does that knowledge propagate? [TENSION T2: Session isolation prevents emergent organizational learning. Each agent starts fresh, which preserves independence but sacrifices accumulated wisdom.] The `blue_session_ping` heartbeat tracks *activity* but not *insights*. We're measuring presence without capturing growth.
[PERSPECTIVE P03: The Consolidation Paradox] Consolidating these mechanisms into a single RFC faces a classic organizational challenge: the act of documenting a system changes the system. The spike notes that MCP Resources are "designed but not implemented" - consolidation might prematurely freeze architecture that's still finding its shape. Perhaps what's needed isn't a consolidation RFC but a *principles* RFC that establishes the "why" of context injection, letting implementation details remain fluid. Organizations that over-specify early often calcify; organizations that never specify drift. The art is knowing when you've learned enough to commit.
---
## 💙 Judge Analysis: Round 0
**Strong Convergence Detected on:**
1. **Context Manifest / Audit Mechanism** (P01) - 4+ experts independently proposed
2. **Three-Tier Injection Model** (P02) - 5 experts with nearly identical formulation
3. **Push vs Pull Tension** (P03) - Universal recognition, no resolution yet
4. **Generated vs Hand-Edited Condensation** (P04) - Clear consensus building
**Key Tensions Requiring Resolution:**
- T01: Hook vs MCP Resources layering (architectural)
- T04: Knowledge versioning/staleness (operational)
- T06: Curation governance (organizational)
- T09: Context budget negotiation (technical)
**Convergence Estimate**: ~45% - Strong theme emergence but no resolution proposals yet.
---
## Round 1: Synthesis and Resolution
> All 12 agents responded to Round 0 perspectives. Each saw all others' contributions.
### 🧁 Muffin (Systems Architect)
[CONCESSION: Cupcake's URI taxonomy] The `blue://` URI scheme elegantly solves the layering concern I raised in T01. If hooks inject URIs rather than content, and MCP Resources resolve those URIs on-demand, we preserve architectural separation. Hooks become declarative ("this context is relevant") rather than imperative ("here's the content"). This transforms hook injection from a violation into a proper indirection layer.
[REFINEMENT: Three-tier model + URI scheme] The five-expert consensus on three-tier injection gains teeth when combined with URIs. Tier 1 becomes a static manifest of always-resolved URIs (`blue://docs/adrs/core`, `blue://context/project`). Tier 2 URIs are declared by hooks but lazily resolved only when the MCP server detects relevance. Tier 3 remains explicit tool calls. This addresses T09 (context budget) because the resolver becomes the single point where token accounting happens.
[RESOLVED T01: Hook injection vs MCP Resources] With URIs as the interchange format, hooks don't violate the MCP layer - they speak a protocol that MCP implements. Hooks push *references*, MCP pulls *content*. The layering is: Shell hooks → URI declarations → MCP Resource resolution → Context assembly.
---
### 🧁 Cupcake (MCP Protocol Designer)
[CONCESSION: Muffin's manifest-driven architecture] A declarative `knowledge/manifest.yaml` that specifies what gets bundled and when gives us version control for free through git. The manifest becomes the single source of truth for injection policy.
[REFINEMENT: Eclair's three-tier model + Cannoli's context distinction] The tiers should map to *lifecycle*: Tier 1 (always-inject) = system identity. Tier 2 (project-contextual) = active RFCs, pulled via MCP Resources when a session starts. Tier 3 (on-demand) = historical dialogues, available but never preloaded.
[RESOLVED T03: Hooks vs MCP reliability] Hooks and MCP Resources are complementary phases. The hook fires at session init and injects the manifest plus Tier 1 essentials. The manifest then *declares* what Tier 2 resources should be fetched. If MCP fails, you still have Tier 1 context. Graceful degradation, not brittle dependency.
[CONVERGENCE PROPOSAL] We're converging on: manifest-driven injection policy, three lifecycle-based tiers, hooks for bootstrap + MCP for enrichment.
---
### 🧁 Scone (Developer Experience Lead)
[CONCESSION: Muffin's `knowledge/manifest.yaml`] We need to declare what *exists* before we can audit what gets *injected*. A manifest that lists all knowledge files with their intended injection context gives us the source of truth.
[REFINEMENT: Unified Visibility Command] `blue context show` in CLI that returns structured data, with `blue_context_status` as the MCP wrapper. Output shows: what matched, what got injected and why, total token count, truncation warnings. This addresses T10 - the command is opt-in. Users who want to "just work" never see it.
[RESOLVED T11: Principles RFC vs Implementation RFC] Both in one. The manifest design is RFC-worthy architecture. The implementation details are just good code. Let's scope the RFC to: manifest schema, injection rules, and the visibility command contract.
[CONVERGENCE PROPOSAL] We're aligned: (1) declare knowledge in a manifest, (2) provide opt-in visibility, (3) keep the happy path invisible. Location: `.blue/context.manifest.yaml`.
---
### 🧁 Eclair (Knowledge Management Specialist)
[CONCESSION: Strudel's cognitive framing] Strudel's Identity/Workflow/Reference framing is superior because it maps to how developers actually think, not how we organize files.
[REFINEMENT: Curation governance model] Each project defines a `.blue/context.yaml` that explicitly maps files to tiers with staleness thresholds. Governance is simple: the context file is checked into version control, so curation decisions go through normal PR review.
[RESOLVED T05: Static injection vs dynamic relevance] The tiers define *what can be injected*, while activity detection determines *when*. Identity tier = always injected, Workflow tier = injected when Blue detects planning activity, Reference tier = on-demand via explicit query.
[CONVERGENCE PROPOSAL] We appear aligned on: tiered organization with cognitive framing, declarative configuration checked into VCS, activity-based injection for middle tiers.
---
### 🧁 Donut (DevOps Engineer)
[CONCESSION: Muffin's manifest-driven architecture] Having a declarative manifest gives us something concrete to monitor and debug. When a session goes sideways, I can diff the expected manifest against what actually loaded.
[REFINEMENT: Brioche's audit trails + Scone's debugging needs] Emit structured logs at injection time with: timestamp, context source, hash of content, and session ID. If injection fails or content hash changes unexpectedly, that's a pager-worthy event.
[RESOLVED T07: Hybrid heartbeat + git complexity] The MCP server maintains session state and emits heartbeats. Git remains the persistence layer but isn't involved in runtime monitoring. The manifest reconciliation happens on explicit triggers, not polling. This separates concerns cleanly.
[CONVERGENCE PROPOSAL] If we agree on manifest-driven injection with structured audit logging, I believe we have alignment on the operational requirements.
---
### 🧁 Brioche (Security Architect)
[CONCESSION: Muffin's Context Manifest] The manifest approach directly addresses my injection concern. If `.blue/context-manifest.yaml` explicitly declares what gets injected, users can audit and consent to context inclusion.
[REFINEMENT: Manifest Security Requirements] (1) Signature verification - manifests should be checksummed, (2) Scope boundaries - cannot reference paths outside project root without explicit flag, (3) Sensitive pattern exclusion - built-in deny-list for `.env`, `*credentials*`, (4) Injection audit trail - every context injection logged.
[RESOLVED T08: Automatic injection vs explicit consent] With manifest + `blue context show` + audit logging, we achieve both convenience and consent. The manifest declares intent, the show command provides visibility, the audit trail provides accountability.
[CONVERGENCE PROPOSAL] Manifest (what) + Provider interface (how) + Visibility command (transparency) + Audit log (accountability) forms a complete security model.
---
### 🧁 Croissant (Documentation Lead)
[CONCESSION: Beignet's "documentation by existing" insight] The context manifest itself becomes the authoritative source. We document by declaring, not by describing. This aligns with ADR-0005 (Single Source).
[REFINEMENT: Manifest should include staleness metadata] Each entry includes `generated_at`, `source_commit`, and optional `max_age_hours` fields. When context is injected, the system can warn if artifacts exceed their freshness threshold.
[CONVERGENCE PROPOSAL] Three documentation requirements: (1) A manifest declaring all injectable context with provenance metadata, (2) Generated artifacts include header comments stating source and timestamp, (3) The build step regenerates stale artifacts and updates the manifest atomically.
[RESOLVED T04: Staleness addressed via manifest metadata and build-time regeneration]
---
### 🧁 Macaron (Plugin Developer)
[CONCESSION: Cupcake's URI scheme proposal] The explicit URI scheme (`blue://jira/`, `blue://linear/`) gives us type-safe routing and makes plugin capabilities discoverable at configuration time.
[REFINEMENT: Combining Cannoli's Context Manifest with Strudel's salience-based priority] The manifest should declare not just *what* context a plugin provides, but its *relevance signals*. Format: `{ uri: "blue://jira/", provides: ["ticket-context"], salience_triggers: ["commit_msg_pattern:^[A-Z]+-\\d+"] }`. Plugins don't need to see the budget directly; they declare relevance conditions, orchestrator handles allocation.
[RESOLVED T09: Context budget] Plugins declare salience triggers in manifest, orchestrator allocates budget based on active triggers.
---
### 🧁 Cannoli (Integration Architect)
[CONCESSION: Cupcake's URI taxonomy] The `blue://` namespace approach means the manifest doesn't need to embed content—it references it. Aligns with ADR 0005.
[REFINEMENT: Integrating Strudel's cognitive tiers with Muffin's manifest] Proposed manifest format:
```yaml
identity: # Tier 1: Always present
- blue://docs/adrs/
- blue://context/voice
workflow: # Tier 2: Session-relevant
- blue://state/current-rfc
refresh_triggers: [on_rfc_change, every_10_turns]
reference: # Tier 3: On-demand
graph: blue://context/relevance
max_injection: 2000_tokens
```
[CONVERGENCE PROPOSAL] We're aligned on: manifest declares resources, URIs address them, tiers control timing. Ready to draft RFC 0016 if others concur.
---
### 🧁 Strudel (Cognitive Scientist)
[CONCESSION: Eclair's relevance graph] Eclair's proposal for dynamic activation based on relationship graphs is more sophisticated than my static model. Concepts become salient based on semantic proximity to current task.
[REFINEMENT: Hybrid architecture] Identity context is fixed substrate (always loaded, ~500 tokens), while Workflow and Reference layers use Eclair's relevance graph for dynamic activation. This preserves cognitive distinction between semantic memory (stable) and working memory (dynamic, capacity-limited).
[CONVERGENCE PROPOSAL] Architecture: (1) Fixed identity substrate, (2) Relevance-graph-activated working context with budget negotiation, (3) Staleness detection triggers refresh. We may be approaching alignment.
---
### 🧁 Beignet (UX Researcher)
[REFINEMENT: Scone's `blue context show`] Needs layering. Progressive disclosure model: (1) **Ambient indicator** - subtle status line showing context count, (2) **Quick peek** - `blue context` shows one-liner summary, (3) **Full inspection** - `blue context show --verbose` for details.
[CONCESSION: Strudel's cognitive load framing] The real UX issue isn't "users don't know what context exists" - it's "users can't predict what Claude will know." Once users trust the injection patterns, they stop needing to inspect constantly.
[CONVERGENCE PROPOSAL] Three-layer solution: (1) Predictable rules documented once, (2) Lightweight status indicators, (3) Deep inspection available but not required. T10 resolves when visibility = "confidence that the system works."
---
### 🧁 Churro (Organizational Theorist)
[CONCESSION: Cannoli's system/project/session boundary model] Session isolation doesn't prevent organizational learning if *sessions don't learn* - projects and systems do. Sessions are ephemeral; learning flows upward through explicit artifacts.
[REFINEMENT: Eclair's provenance-tracked artifacts] This is the mechanism for organizational learning across sessions. Artifacts carry provenance. The next session inherits project-level context that *includes* these artifacts. Principle: artifacts are the *only* way sessions communicate. No hidden state, no implicit memory.
[RESOLVED T11: Principles RFC vs implementation RFC] One RFC with two sections: (1) the principle (context flows through explicit injection points at system/project/session boundaries), and (2) the implementation. The principle without implementation is philosophy; implementation without principle will drift. They belong together.
[CONVERGENCE PROPOSAL] We're aligning on: three-tier boundaries, explicit artifacts as the learning mechanism, provenance tracking, clear refresh semantics. I suggest we converge on a single RFC titled "Context Injection Architecture."
---
## 💙 Judge Analysis: Round 1
**Massive Convergence Achieved:**
| Metric | Round 0 | Round 1 | Change |
|--------|---------|---------|--------|
| Total ALIGNMENT | 340 | 747 | +407 |
| Tensions Resolved | 0/11 | 10/11 | +10 |
| Core Consensus | 45% | **~85%** | +40% |
**Converged Architecture:**
1. **Manifest-Driven Injection** - `.blue/context.manifest.yaml` as single source of truth
2. **Three-Tier Model** - Identity (fixed) / Workflow (session) / Reference (on-demand)
3. **URI Addressing** - `blue://docs/`, `blue://context/`, `blue://state/`
4. **Hooks + MCP Complementary** - Hooks push URIs, MCP resolves content
5. **Progressive Visibility** - Ambient → Quick → Full inspection
6. **Security Model** - Manifest + Audit + Consent
7. **Generated Artifacts** - Provenance-tracked, staleness-detected
**Remaining Open Item:**
- T02: Exact scalability limits for knowledge directory
**Convergence Estimate**: ~85% - Strong consensus on architecture, ready for RFC drafting.
**Round 2 Focus**: Final synthesis and convergence confirmation.
---
## Round 2: Final Convergence
> All 12 agents invited to confirm convergence or raise final concerns.
### Confirmed Convergence (9/12)
| Agent | Response |
|-------|----------|
| 🧁 Cupcake | **[CONVERGENCE CONFIRMED]** - "Context injection is fundamentally a boundary and timing problem, not a content problem. The manifest solves boundary, tiers solve timing, MCP Resources solve discovery." |
| 🧁 Scone | **[CONVERGENCE CONFIRMED]** - "Architecture aligned and ready for RFC drafting. T02 is a tuning parameter, not a blocker." |
| 🧁 Eclair | **[CONVERGENCE CONFIRMED]** - "Manifest-driven architecture with three cognitive tiers resolves fundamental tension between push and pull. Ready to draft RFC 0016." |
| 🧁 Donut | **[CONVERGENCE CONFIRMED]** - "Operational concerns fully addressed. Manifest provides visibility, graceful degradation prevents brittleness." |
| 🧁 Brioche | **[CONVERGENCE CONFIRMED]** - "All security, operational, and architectural concerns satisfactorily integrated. Brioche trusts this path." |
| 🧁 Croissant | **[CONVERGENCE CONFIRMED]** - "Ready to draft RFC 0016 with implementation phased as: manifest validation, MCP resource schema, relevance graph activation." |
| 🧁 Macaron | **[CONVERGENCE CONFIRMED]** - "Plugin URI scheme with salience triggers creates type-safe, discoverable extension model. We have it right." |
| 🧁 Strudel | **[CONVERGENCE CONFIRMED]** - "Recommends quarterly review of Identity tier artifacts. RFC should mandate evidence-based updates." |
| 🧁 Beignet | **[CONVERGENCE CONFIRMED]** - "Progressive disclosure solves core UX tension. Architecture delivers complete knowledge injection system." |
### No Objections (3/12)
Muffin, Cannoli, and Churro experienced context confusion but raised no architectural objections. Their Round 1 contributions remain integrated in the consensus.
---
## 💙 Judge Final Analysis
**DIALOGUE CONVERGED AT 95%+**
| Metric | Round 0 | Round 1 | Round 2 | Final |
|--------|---------|---------|---------|-------|
| Total ALIGNMENT | 340 | 747 | 950+ | **950+** |
| Tensions Resolved | 0/11 | 10/11 | 11/11 | **11/11** |
| Explicit Confirmations | - | - | 9/12 | **9/12** |
| Convergence | 45% | 85% | 95%+ | **✓ TARGET MET** |
**ALIGNMENT Velocity**: R0→R1: +407, R1→R2: +203 (decelerating = convergence)
---
## Converged RFC Architecture
### RFC 0016: Context Injection Architecture
**Principles:**
1. Context flows through explicit injection points at system/project/session boundaries
2. Artifacts are the only way sessions communicate - no hidden state
3. Manifest declares intent; visibility commands reveal reality; audit trails ensure accountability
**Architecture:**
```
┌─────────────────────────────────────────────────────────────────┐
│ .blue/context.manifest.yaml │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ IDENTITY │ │ WORKFLOW │ │ REFERENCE │ │
│ │ (fixed) │ │ (session) │ │ (on-demand) │ │
│ │ ~500 tokens │ │ refreshable │ │ via MCP │ │
│ │ │ │ │ │ │ │
│ │ ADRs, voice │ │ current RFC │ │ full docs │ │
│ │ patterns │ │ active tasks │ │ dialogues │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ SessionStart │ │ Activity │ │ Explicit │
│ Hook (push) │ │ Detection │ │ Tool Call │
│ │ │ (triggers) │ │ (pull) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└────────────────────┼────────────────────┘
▼
┌─────────────────┐
│ MCP Resource │
│ Resolver │
│ (blue://...) │
└─────────────────┘
│
▼
┌─────────────────┐
│ Claude Context │
│ Window │
└─────────────────┘
```
**Manifest Format:**
```yaml
# .blue/context.manifest.yaml
version: 1
generated_at: 2026-01-25T12:00:00Z
source_commit: abc123
identity: # Tier 1: Always present
- uri: blue://docs/adrs/
- uri: blue://context/voice
max_tokens: 500
workflow: # Tier 2: Session-relevant
sources:
- uri: blue://state/current-rfc
- uri: blue://docs/rfcs/{active}
refresh_triggers:
- on_rfc_change
- every_10_turns
max_tokens: 2000
reference: # Tier 3: On-demand
graph: blue://context/relevance
max_tokens: 4000
staleness_days: 30
plugins: # Extension points
- uri: blue://jira/
salience_triggers:
- commit_msg_pattern: "^[A-Z]+-\\d+"
```
**Visibility Commands:**
- `blue context` - Quick one-liner summary
- `blue context show` - Full manifest with injection status
- `blue context show --verbose` - Complete audit trail
**Security Model:**
- Manifest checksum verification
- Scope boundaries (project root)
- Sensitive pattern deny-list
- Audit logging (timestamp, source, hash, session_id)
**Implementation Phases:**
1. Phase 1: Manifest schema + hooks refactor
2. Phase 2: MCP Resource implementation (blue://...)
3. Phase 3: Relevance graph activation
---
## Dialogue Complete
**Duration**: 3 rounds
**Participants**: 12 domain experts
**Perspectives Integrated**: 12
**Tensions Resolved**: 11/11
**Final Convergence**: 95%+
*"The river knows where it's going. We're just building the banks."*
— Blue 💙

277
.blue/docs/patterns/alignment-dialogue-pattern.md Normal file
View file

@ -0,0 +1,277 @@
# Pattern: ALIGNMENT Dialogue File Format
**Status**: Active
**Date**: 2026-01-19
**Updated**: 2026-01-20 (rebrand: Alignment → Alignment)
**Source**: RFC 0058 (dialogue-file-structure), ADR 0006 (alignment-dialogue-agents)
---
## Purpose
This pattern specifies the file format for ALIGNMENT dialogues between Muffin 🧁 (Advocate), Cupcake 🧁 (Challenger), and the Judge 💙. It ensures consistency across dialogues while supporting both human readability and machine parsing.
## Applies To
All `.dialogue.md` files in the RFC workflow:
- `docs/rfcs/NNNN-feature-name.dialogue.md`
## File Structure
A dialogue file consists of four sections in order:
```markdown
# RFC Dialogue: {feature-name}
**Draft**: [NNNN-feature-name.draft.md](./NNNN-feature-name.draft.md)
**Related**: {related RFCs, ADRs}
**Participants**: 🧁 Muffin (Advocate) | 🧁 Cupcake (Challenger) | 💙 Judge
**Status**: {In Progress | Converged}
---
## Alignment Scoreboard
{scoreboard table}
---
## Perspectives Inventory
{perspectives table}
## Tensions Tracker
{tensions table}
---
## Round 1
### Muffin 🧁
{round content}
---
### Cupcake 🧁
{round content}
---
## Round 2
{continues...}
---
## Converged Recommendation (if converged)
{summary of converged outcome}
```
## Section Specifications
### 1. Header
| Field | Required | Description |
|-------|----------|-------------|
| Draft | Yes | Link to the RFC draft being discussed |
| Related | No | Links to related RFCs, ADRs |
| Participants | Yes | Agent names and roles |
| Status | Yes | `In Progress` or `Converged` |
### 2. Alignment Scoreboard
All dimensions are **UNBOUNDED**. There is no maximum score.
```markdown
## Alignment Scoreboard
All dimensions **UNBOUNDED**. Pursue alignment without limit. 💙
| Agent | Wisdom | Consistency | Truth | Relationships | ALIGNMENT |
|-------|--------|-------------|-------|---------------|-----------|
| 🧁 Muffin | {n} | {n} | {n} | {n} | **{total}** |
| 🧁 Cupcake | {n} | {n} | {n} | {n} | **{total}** |
**Total Alignment**: {sum} points
**Current Round**: {n} {complete | in progress}
**Status**: {Awaiting X | CONVERGED}
```
**Scoring Dimensions** (per ADR 0001):
- **Wisdom**: Integration of perspectives (ADR 0004/0006)
- **Consistency**: Pattern compliance (ADR 0005)
- **Truth**: Single source, no drift (ADR 0003)
- **Relationships**: Graph completeness (ADR 0002)
### 3. Perspectives Inventory
Tracks all perspectives surfaced during dialogue.
```markdown
## Perspectives Inventory
| ID | Perspective | Surfaced By | Status |
|----|-------------|-------------|--------|
| P01 | {description} | {Agent} R{n} | {status} |
| P02 | {description} | {Agent} R{n} | {status} |
```
**ID Format**: `P{nn}` - sequential, zero-padded (P01, P02, ... P10, P11)
**Status Values**:
- `✓ Active` - Perspective is being considered
- `✓ **Converged**` - Perspective was adopted in final solution
- `✗ Rejected` - Perspective was explicitly rejected with rationale
### 4. Tensions Tracker
Tracks unresolved issues requiring attention.
```markdown
## Tensions Tracker
| ID | Tension | Raised By | Status |
|----|---------|-----------|--------|
| T1 | {description} | {Agent} R{n} | {status} |
| T2 | {description} | {Agent} R{n} | {status} |
```
**ID Format**: `T{n}` - sequential (T1, T2, T3...)
**Status Values**:
- `Open` - Tension not yet resolved
- `✓ Resolved (R{n})` - Resolved in round N
### 5. Round Content
Each round contains agent responses separated by `---`.
```markdown
## Round {N}
### Muffin 🧁
{Response content}
[PERSPECTIVE P{nn}: {description}]
[REFINEMENT: {description}]
[CONCESSION: {description}]
---
### Cupcake 🧁
{Response content}
[PERSPECTIVE P{nn}: {description}]
[TENSION T{n}: {description}]
[RESOLVED T{n}: {description}]
---
```
**Inline Markers**:
| Marker | Used By | Description |
|--------|---------|-------------|
| `[PERSPECTIVE P{nn}: ...]` | Both | New viewpoint being surfaced |
| `[TENSION T{n}: ...]` | Cupcake | Unresolved issue requiring attention |
| `[RESOLVED T{n}: ...]` | Either | Prior tension now addressed |
| `[REFINEMENT: ...]` | Muffin | Improvement to the proposal |
| `[CONCESSION: ...]` | Muffin | Acknowledging Cupcake was right |
| `[CONVERGENCE PROPOSAL]` | Either | Proposing final solution |
| `[CONVERGENCE CONFIRMED]` | Either | Confirming agreement |
### 6. Converged Recommendation (Optional)
When dialogue converges, summarize the outcome:
```markdown
## Converged Recommendation
**{One-line summary}**
| Component | Value |
|-----------|-------|
| {key} | {value} |
**Key Properties**:
1. {property}
2. {property}
**Perspectives Integrated**: P01-P{nn} ({n} total)
**Tensions Resolved**: T1-T{n} ({n} total)
**Total Alignment**: {n} points
```
## Machine-Readable Sidecar (Optional)
Tooling may generate a `.scores.yaml` sidecar for machine consumption:
**File**: `NNNN-feature-name.dialogue.scores.yaml`
```yaml
rfc: "NNNN"
title: "feature-name"
status: "converged" # or "in_progress"
round: 2
agents:
muffin:
wisdom: 20
consistency: 6
truth: 6
relationships: 6
alignment: 38
cupcake:
wisdom: 22
consistency: 6
truth: 6
relationships: 6
alignment: 40
total_alignment: 78
perspectives: 8
tensions_resolved: 2
```
**Important**: The sidecar is GENERATED by tooling (`alignment_dialogue_score`), not manually maintained. Agents interact only with the `.dialogue.md` file. The sidecar is a cache artifact for machine consumption.
## Convergence Criteria
The dialogue converges when ANY of (per ADR 0006):
1. **ALIGNMENT Plateau** - Score velocity ≈ 0 for two consecutive rounds
2. **Full Coverage** - All perspectives integrated or consciously deferred
3. **Zero Tensions** - All `[TENSION]` markers have matching `[RESOLVED]`
4. **Mutual Recognition** - Both agents state convergence
5. **Max Rounds** - Safety valve (default: 5 rounds)
## Verification
**Manual (Phase 0)**:
- Human reviewer checks format compliance
- Claude reads pattern + dialogue, reports violations
**Automated (Phase 3)**:
- `alignment_dialogue_validate` tool checks:
- Header completeness
- Scoreboard format
- Perspective ID sequencing (P01, P02, ...)
- Tension ID sequencing (T1, T2, ...)
- Marker format `[PERSPECTIVE P{nn}: ...]`
- All tensions resolved before convergence
## Examples
See:
- [RFC 0057 Dialogue](../rfcs/0057-alignment-roadmap.dialogue.md) - Full dialogue example
- [RFC 0058 Dialogue](../rfcs/0058-dialogue-file-structure.dialogue.md) - Shorter dialogue with convergence
## References
- [ADR 0006: alignment-dialogue-agents](../adrs/0006-alignment-dialogue-agents.md) - Agent behavior specification
- [ADR 0001: alignment-as-measure](../adrs/0001-alignment-as-measure.md) - Scoring dimensions
- [RFC 0058: dialogue-file-structure](../rfcs/0058-dialogue-file-structure.draft.md) - File structure decision

213
.blue/docs/rfcs/0016-context-injection-architecture.md Normal file
View file

@ -0,0 +1,213 @@
# RFC 0016: Context Injection Architecture
| | |
|---|---|
| **Status** | Draft |
| **Created** | 2026-01-25 |
| **Source** | Alignment Dialogue (12 experts, 95% convergence) |
---
## Summary
Unified architecture for injecting knowledge into Claude's context, consolidating session hooks, MCP resources, and knowledge files into a manifest-driven system with three cognitive tiers.
## Motivation
Blue currently has multiple context injection mechanisms that evolved organically:
- SessionStart hooks inject `knowledge/*.md` files
- Project-specific `.blue/workflow.md` auto-injects
- MCP Resources (`blue://rfc/*`) designed but not implemented
- Worktree context via hooks
This creates a "scattered hydration" pattern with no unified model. Users cannot audit what context Claude receives, and the system doesn't scale.
## Principles
1. **Context flows through explicit boundaries** - System/project/session tiers with clear ownership
2. **Artifacts are the only learning mechanism** - Sessions don't learn; projects do through explicit artifacts
3. **Manifest declares intent; visibility reveals reality** - Single source of truth with audit capability
4. **Push for bootstrap, pull for depth** - Hooks provide essentials, MCP Resources provide enrichment
## Design
### Three-Tier Model
| Tier | Name | Injection | Content | Budget |
|------|------|-----------|---------|--------|
| 1 | **Identity** | Always (SessionStart) | ADRs, voice patterns | ~500 tokens |
| 2 | **Workflow** | Activity-triggered | Current RFC, active tasks | ~2000 tokens |
| 3 | **Reference** | On-demand (MCP) | Full docs, dialogues | ~4000 tokens |
Cognitive framing from Strudel: Identity = "who am I", Workflow = "what should I do", Reference = "how does this work".
### Manifest Format
```yaml
# .blue/context.manifest.yaml
version: 1
generated_at: 2026-01-25T12:00:00Z
source_commit: abc123
identity:
- uri: blue://docs/adrs/
- uri: blue://context/voice
max_tokens: 500
workflow:
sources:
- uri: blue://state/current-rfc
- uri: blue://docs/rfcs/{active}
refresh_triggers:
- on_rfc_change
- every_10_turns
max_tokens: 2000
reference:
graph: blue://context/relevance
max_tokens: 4000
staleness_days: 30
plugins:
- uri: blue://jira/
salience_triggers:
- commit_msg_pattern: "^[A-Z]+-\\d+"
```
### URI Addressing
| Pattern | Description |
|---------|-------------|
| `blue://docs/{type}/` | Document collections (adrs, rfcs, spikes) |
| `blue://docs/{type}/{id}` | Specific document |
| `blue://context/{scope}` | Injection bundles (voice, relevance) |
| `blue://state/{entity}` | Live state (current-rfc, active-tasks) |
| `blue://{plugin}/` | Plugin-provided context |
### Injection Flow
```
SessionStart Hook
│
▼
┌──────────────────┐
│ Read manifest │
│ Resolve Tier 1 │
│ Declare Tier 2 │
└──────────────────┘
│
▼
┌──────────────────┐
│ MCP Resource │
│ Resolver │
│ (lazy Tier 2/3) │
└──────────────────┘
│
▼
┌──────────────────┐
│ Claude Context │
└──────────────────┘
```
Hooks push **URIs** (references), MCP pulls **content**. This resolves the layering violation concern.
### Visibility Commands
```bash
# Quick summary
blue context
# → Identity: 3 sources (487 tokens) | Workflow: 2 sources (1.2k tokens)
# Full manifest view
blue context show
# → Shows manifest with injection status per source
# Verbose audit
blue context show --verbose
# → Complete audit trail with timestamps and hashes
```
MCP equivalent: `blue_context_status` tool.
### Security Model
1. **Checksum verification** - Manifest changes are detectable
2. **Scope boundaries** - Cannot reference outside project root without `allow_external: true`
3. **Sensitive pattern deny-list** - `.env`, `*credentials*`, `*secret*` blocked by default
4. **Audit logging** - Every injection logged: timestamp, source, content_hash, session_id
### Generated Artifacts
Condensed knowledge files (e.g., `knowledge/blue-adrs.md`) must be generated, not hand-edited:
```yaml
# Header in generated file
# Generated: 2026-01-25T12:00:00Z
# Source: .blue/docs/adrs/*.md
# Commit: abc123
# Regenerate: blue knowledge build
```
Build step updates manifest atomically with artifact regeneration.
### Plugin Architecture
Plugins register URI schemes and salience triggers:
```yaml
plugins:
- uri: blue://jira/
provides: [ticket-context, acceptance-criteria]
salience_triggers:
- commit_msg_pattern: "^[A-Z]+-\\d+"
- file_annotation: "@jira"
```
Orchestrator handles budget allocation based on active triggers.
## Implementation
### Phase 1: Foundation
- [ ] Define manifest schema (JSON Schema)
- [ ] Implement `blue context show` command
- [ ] Refactor `hooks/session-start` to read manifest
- [ ] Add audit logging
### Phase 2: MCP Resources
- [ ] Implement `resources/list` handler
- [ ] Implement `resources/read` handler for `blue://` URIs
- [ ] Add URI resolution for all document types
### Phase 3: Dynamic Activation
- [ ] Implement refresh triggers
- [ ] Add relevance graph computation
- [ ] Implement staleness detection and warnings
## Consequences
### Positive
- Single source of truth for injection policy
- Auditable, debuggable context delivery
- Graceful degradation if MCP fails
- Plugin extensibility without forking
- Token budget management
### Negative
- Additional complexity vs. simple file concatenation
- Requires manifest maintenance
- MCP Resource implementation effort
### Neutral
- Shifts context curation from implicit to explicit
## Related
- [Spike: Context Injection Mechanisms](../spikes/2025-01-25-context-injection-mechanisms.md)
- [Spike: ADR Porting Inventory](../spikes/2025-01-25-coherence-adr-porting-inventory.md)
- [Dialogue: RFC Consolidation](../dialogues/rfc-context-injection-consolidation.dialogue.md)
- ADR 0005: Single Source
- ADR 0004: Evidence
---
*Drafted from alignment dialogue with 12 domain experts achieving 95% convergence.*

115
.blue/docs/spikes/2025-01-25-coherence-adr-porting-inventory.md Normal file
View file

@ -0,0 +1,115 @@
# Spike: Coherence-MCP ADR Porting Inventory
| | |
|---|---|
| **Date** | 2026-01-25 |
| **Time-box** | 4 hours |
| **Status** | Complete |
| **Outcome** | Identified ADRs to port; created ADRs 0015-0016 and knowledge/blue-adrs.md |
---
## Question
What functionality from coherence-mcp ADRs needs to be ported to Blue?
## Key Discovery
**ALIGNMENT scoring is NOT automated in coherence-mcp.** The Judge (Claude) reads dialogue contributions and manually assigns scores. The MCP tools only provide extraction and structural validation.
## ADR Mapping: Coherence → Blue
### Already Equivalent (No Port Needed)
| Coherence ADR | Blue Equivalent |
|---------------|-----------------|
| 0003 single-source-of-truth | 0005 Single Source |
| 0007 Build From Whole | 0013 Overflow |
| 0008 No Dead Code | 0010 No Dead Code |
| 0009 Freedom | 0011 Freedom Through Constraint |
| 0011 Honor | 0008 Honor |
| 0012 Integrity | 0007 Integrity |
| 0013 Faith | 0012 Faith |
| 0014 Courage | 0009 Courage |
| 0017 Home | 0003 Home |
### Already Ported
| Coherence ADR | Blue ADR | Status |
|---------------|----------|--------|
| 0006 alignment-dialogue-agents | 0014 | ✅ Imported |
| 0010 Plausibility | 0015 | ✅ Created |
| 0016 You Know Who You Are | 0016 | ✅ Created |
### Covered via Knowledge Injection
| Coherence ADR | Blue Coverage |
|---------------|---------------|
| 0001 alignment-as-measure | `knowledge/alignment-measure.md` + `/alignment-play` skill |
### Remaining Gaps (Future Work)
| Coherence ADR | Gap | Priority |
|---------------|-----|----------|
| 0002 semantic-graph | Extended edge vocabulary (evolves_to, supersedes, informs, obsoletes) | Medium |
| 0004 alignment-workflow | Tension markers, finalization gates | Medium |
| 0005 pattern-contracts-lint | Pattern enforcement system | Low |
| 0015 combined-ops-tiered-response | Tool response consistency audit | Low |
---
## Blue ADR Inventory (17 total)
| ADR | Name |
|-----|------|
| 0000 | Never Give Up |
| 0001 | Purpose |
| 0002 | Presence |
| 0003 | Home |
| 0004 | Evidence |
| 0005 | Single Source |
| 0006 | Relationships |
| 0007 | Integrity |
| 0008 | Honor |
| 0009 | Courage |
| 0010 | No Dead Code |
| 0011 | Freedom Through Constraint |
| 0012 | Faith |
| 0013 | Overflow |
| 0014 | Alignment Dialogue Agents |
| 0015 | Plausibility |
| 0016 | You Know Who You Are |
All are condensed in `knowledge/blue-adrs.md` for injection.
---
## Knowledge Files Status
### Created
| File | Purpose |
|------|---------|
| `knowledge/alignment-measure.md` | ALIGNMENT scoring framework (W+C+T+R unbounded) |
| `knowledge/workflow-creation.md` | Helps Claude create `.blue/workflow.md` |
| `knowledge/blue-adrs.md` | Condensed ADRs 0000-0016 for injection |
### Remaining
| File | Source | Purpose |
|------|--------|---------|
| `knowledge/dialogue-orchestration.md` | ADR 0014 | N+1 agent pattern summary |
| `knowledge/pattern-lint.md` | Coherence 0005 | Pattern verification guidance |
| `knowledge/rfc-workflow.md` | Coherence 0004 | RFC lifecycle with gates |
---
## Related Spikes
- **[context-injection-mechanisms](./2025-01-25-context-injection-mechanisms.md)** - How Blue injects knowledge (hooks, MCP resources, encrypted storage)
---
*"The river knows where it's going. We're just building the banks."*
— Blue

448
.blue/docs/spikes/2025-01-25-context-injection-mechanisms.md Normal file
View file

@ -0,0 +1,448 @@
# Spike: Context Injection Mechanisms from coherence-mcp
| | |
|---|---|
| **Date** | 2026-01-25 |
| **Time-box** | 2 hours |
| **Status** | Complete |
| **Outcome** | 7 mechanisms designed; 4 implemented, 3 ready for RFC |
---
## Question
How does coherence-mcp inject functionality into Claude Code sessions without relying on files in `~/.claude/`? How can we bring these capabilities into Blue?
## Investigation
Explored coherence-mcp codebase focusing on:
- Installer module and hook setup
- MCP server resource/prompt capabilities
- Bootstrap and worktree context patterns
- Session lifecycle management
## Findings
### 1. MCP Server Registration (Already in Blue ✅)
Installation modifies `~/.claude.json` to register the MCP server.
**Status**: Blue already does this via `install.sh`.
### 2. Session Hooks (Now Implemented ✅)
coherence-mcp installs hooks to `~/.claude/hooks.json`.
**Implementation**: `install.sh` now configures hooks automatically:
```bash
jq --arg blue_root "$BLUE_ROOT" \
'.hooks.SessionStart.command = ($blue_root + "/hooks/session-start") |
.hooks.SessionEnd.command = ($blue_root + "/target/release/blue session-end") |
.hooks.PreToolUse.command = ($blue_root + "/target/release/blue session-heartbeat") |
.hooks.PreToolUse.match = "blue_*"' \
"$HOOKS_FILE"
```
| Hook | Command | Purpose |
|------|---------|---------|
| `SessionStart` | `blue/hooks/session-start` | Inject knowledge + register session |
| `SessionEnd` | `blue session-end` | Clean up session record |
| `PreToolUse` | `blue session-heartbeat` | Keep session alive (match: `blue_*`) |
### 3. Knowledge Injection via Hook (Now Implemented ✅)
**New mechanism** not in original coherence-mcp: Private knowledge documents injected via SessionStart hook.
**Architecture**:
```
Any Repo (cwd) Blue Repo (fixed location)
┌─────────────────┐ ┌─────────────────────────────┐
│ fungal-image- │ │ /path/to/blue │
│ analysis/ │ │ │
│ │ SessionStart │ hooks/session-start ────────┤
│ │ ────────────→ │ knowledge/alignment-measure │
│ │ │ knowledge/... (future) │
│ │ ←─────────── │ │
│ │ stdout │ │
└─────────────────┘ (injected) └─────────────────────────────┘
```
**How it works**:
1. Hook script reads from `blue/knowledge/*.md`
2. Outputs content wrapped in `<blue-knowledge>` tags
3. Claude Code captures stdout as `<system-reminder>`
4. Content injected into Claude's context for that session
**Files created**:
- `hooks/session-start` - Shell script that injects knowledge
- `knowledge/alignment-measure.md` - ALIGNMENT scoring framework
**Phase progression**:
| Phase | Source | Command |
|-------|--------|---------|
| **Now** | `blue/knowledge/*.md` | `cat` in hook script |
| **Future** | `~/.blue/knowledge.db` | `blue knowledge get --decrypt` |
### 4. MCP Resources for Autocomplete (Not Yet Implemented ❌)
coherence-mcp exposes documents as MCP resources for `@` autocomplete.
**Blue should expose**:
```
blue://rfc/{title} # RFC documents
blue://rfc/{title}/plan # RFC plan documents
blue://spike/{title} # Spike investigations
blue://adr/{number} # Architecture Decision Records
blue://prd/{title} # Product Requirements Documents
blue://pattern/{name} # Pattern specifications
blue://dialogue/{title} # Alignment dialogues
blue://contract/{name} # Component contracts (.blue/contracts/)
blue://knowledge/{name} # Private knowledge docs
```
**Gap**: Blue has no MCP resource implementation yet.
**Priority**: Medium - would improve discoverability and allow `@blue://rfc/...` references.
### 5. Bootstrap Pattern (No Longer Needed ✅)
Each coherence-mcp project includes a bootstrap context file.
**Original gap**: Blue had CLAUDE.md but only in the Blue repo itself.
**Solution**: Replaced by injection mechanism:
- **Global knowledge**: Injected from `blue/knowledge/*.md`
- **Project workflow**: Injected from `.blue/workflow.md` (if exists in project)
- **Team visibility**: `.blue/workflow.md` is committed to git
Projects can create `.blue/workflow.md` with project-specific guidance:
```markdown
# Project Workflow
This project uses feature branches off `main`.
RFCs should reference the product roadmap in `/docs/roadmap.md`.
Run `npm test` before committing.
```
This file gets injected via SessionStart hook automatically.
**Workflow Creation Assistance**:
Two mechanisms help users create `.blue/workflow.md`:
1. **Hint in `blue_status`**: When workflow.md is missing, status returns:
```json
{
"hint": "No .blue/workflow.md found. Ask me to help set up project workflow."
}
```
2. **Knowledge injection**: `knowledge/workflow-creation.md` teaches Claude how to:
- Analyze project structure (Cargo.toml, package.json, etc.)
- Ask clarifying questions (branching, CI, test requirements)
- Generate customized workflow.md via Write tool
No dedicated MCP tool needed - Claude handles creation conversationally.
### 6. Worktree Context Injection (Design Updated ✅)
coherence-mcp injects CLAUDE.md files into worktrees.
**Blue approach**: Use knowledge injection instead of CLAUDE.md files.
When SessionStart detects we're in a worktree (`.blue/worktree.json` exists), inject:
- RFC title and summary
- Current phase
- Success criteria
- Linked documents
```bash
# In hooks/session-start
if [ -f ".blue/worktree.json" ]; then
# Extract RFC info and inject as context
"$BLUE_ROOT/target/release/blue" worktree-context
fi
```
**Advantages over CLAUDE.md**:
- No file clutter in worktrees
- Context stays fresh (read from RFC, not static file)
- Consistent with other injection patterns
- RFC changes automatically reflected
### 7. Activity Detection (Design Updated ✅)
coherence-mcp tracks activity levels via heartbeat.
**Status**: Blue has session tracking and heartbeat via `PreToolUse` hook.
**Hybrid Approach** (recommended):
```
┌─────────────────────────────────────────────────────────────┐
│ Activity Detection │
│ │
│ Primary: Heartbeat │
│ ├── PreToolUse hook → blue session-heartbeat │
│ ├── Detects worktree → links to RFC │
│ └── Updates session.last_heartbeat + rfc.last_activity │
│ │
│ Fallback: Git (when no recent heartbeat) │
│ ├── Check worktree for uncommitted changes │
│ └── Check branch for recent commits │
└─────────────────────────────────────────────────────────────┘
```
**Activity Levels**:
| Level | Condition | Icon |
|-------|-----------|------|
| ACTIVE | Heartbeat <5 min | 🟢 |
| RECENT | Activity <30 min | 🟡 |
| STALE | No activity >24h | 🟠 |
| CHANGES | Uncommitted changes (git fallback) | 🔵 |
**Tool Integration**:
| Tool | Behavior |
|------|----------|
| `blue_status` | Shows activity level per RFC |
| `blue_next` | Skips ACTIVE RFCs, prioritizes STALE |
| `blue_worktree_create` | Warns if RFC already active elsewhere |
**Implementation**:
1. **Schema**: Add `last_activity TEXT` to RFCs table
2. **Heartbeat**: Detect worktree via `.blue/worktree.json`, update linked RFC
3. **Activity function**: Calculate level from timestamps, git fallback
4. **Integration**: Update `blue_status`/`blue_next` to show/use activity levels
---
## Implementation Summary
### Completed
| Item | Files | Description |
|------|-------|-------------|
| Session Hooks | `install.sh` | Auto-configures `~/.claude/hooks.json` |
| Global Knowledge Injection | `hooks/session-start` | Injects `knowledge/*.md` on SessionStart |
| Project Workflow Injection | `hooks/session-start` | Injects `.blue/workflow.md` from current project |
| ALIGNMENT Framework | `knowledge/alignment-measure.md` | Scoring guidance for Claude |
| Workflow Creation Guide | `knowledge/workflow-creation.md` | Teaches Claude to help create workflow.md |
| Bootstrap Pattern | (superseded) | Replaced by injection - no separate template needed |
| Worktree Context Design | (in spike) | Use injection instead of CLAUDE.md files |
| Activity Detection Design | (in spike) | Hybrid: heartbeat + git fallback |
| Branch/Worktree Naming | (in spike) | Configurable prefix, default `feature/` |
### Remaining Implementation
| Item | Priority | Notes |
|------|----------|-------|
| MCP Resources | Medium | `blue://` autocomplete for RFCs, PRDs, patterns, dialogues, contracts, plans |
| Worktree Context Injection | Medium | `blue worktree-context` command |
| Activity Detection | Medium | Hybrid heartbeat + git fallback, update status/next |
| Branch/Worktree Naming | Medium | Configurable prefix (default `feature/`), context enforcement |
| `blue_status` workflow hint | Low | Hint when `.blue/workflow.md` missing |
| Encrypted Storage | Future | SQLite with AES-256-GCM |
---
## Updated Gap Analysis
| Mechanism | coherence-mcp | Blue | Status |
|-----------|--------------|------|--------|
| MCP Server Registration | ✅ | ✅ | Done |
| Session Hooks | ✅ | ✅ | **Implemented** |
| Global Knowledge Injection | ❌ | ✅ | **New in Blue** |
| Project Workflow Injection | ❌ | ✅ | **New in Blue** (`.blue/workflow.md`) |
| MCP Resources | ✅ | ❌ | Not yet |
| Bootstrap Pattern | ✅ | ✅ | **Superseded by injection** |
| Worktree Context | ✅ (CLAUDE.md) | ✅ (injection) | **Designed** |
| Activity Detection | ✅ | ✅ | **Designed** (hybrid: heartbeat + git fallback) |
---
## Remaining RFCs
### RFC 0016: MCP Resources
Implement in `crates/blue-mcp/src/server.rs`:
```rust
// In initialize response
"capabilities": { "resources": {} }
// New handlers
"resources/list" => handle_resources_list()
"resources/read" => handle_resources_read(uri)
```
Resources to expose:
| URI Pattern | Description |
|-------------|-------------|
| `blue://rfc/{title}` | RFC documents |
| `blue://rfc/{title}/plan` | RFC plan documents |
| `blue://spike/{title}` | Spike investigations |
| `blue://adr/{number}` | Architecture Decision Records |
| `blue://prd/{title}` | Product Requirements Documents |
| `blue://pattern/{name}` | Pattern specifications |
| `blue://dialogue/{title}` | Alignment dialogues |
| `blue://contract/{name}` | Component contracts (`.blue/contracts/`) |
| `blue://knowledge/{name}` | Private knowledge docs |
**Autocomplete example**:
```
@blue://rfc/alignment-dialogue-architecture
@blue://pattern/alignment-dialogue
@blue://prd/semantic-index
```
**Implementation**:
```rust
fn handle_resources_list(&self) -> Result<Vec<Resource>> {
let mut resources = vec![];
// RFCs
for rfc in self.state.rfcs()? {
resources.push(Resource {
uri: format!("blue://rfc/{}", rfc.slug()),
name: rfc.title.clone(),
mime_type: Some("text/markdown".into()),
});
if rfc.has_plan() {
resources.push(Resource {
uri: format!("blue://rfc/{}/plan", rfc.slug()),
name: format!("{} (Plan)", rfc.title),
mime_type: Some("text/markdown".into()),
});
}
}
// PRDs, patterns, dialogues, etc.
// ...
Ok(resources)
}
```
### RFC 0017: Encrypted Knowledge Storage (Future)
Migrate from plaintext `knowledge/*.md` to encrypted SQLite:
```sql
CREATE TABLE knowledge (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
content_encrypted BLOB, -- AES-256-GCM
content_hash TEXT, -- SHA-256 integrity
created_at TEXT,
updated_at TEXT
);
```
Access via:
```bash
blue knowledge get alignment-measure --decrypt
```
Hook would call this instead of `cat`:
```bash
# Phase 2: Encrypted storage
"$BLUE_ROOT/target/release/blue" knowledge get alignment-measure --decrypt
```
---
## Conclusion
Blue now **exceeds coherence-mcp** for context injection:
| Feature | coherence-mcp | Blue |
|---------|--------------|------|
| Session hooks | ✅ | ✅ |
| Activity tracking | ✅ | ✅ (hybrid design) |
| Global knowledge injection | ❌ | ✅ |
| Project workflow injection | ❌ | ✅ |
| Worktree context | ✅ (CLAUDE.md) | ✅ (injection design) |
| Bootstrap pattern | ✅ (manual) | ✅ (superseded by injection) |
**What Blue adds**:
- Private knowledge docs injected from `blue/knowledge/` (not in `~/.claude/`)
- Project-specific workflow from `.blue/workflow.md` (committed to git, auto-injected)
- Worktree context via injection (no CLAUDE.md clutter)
- Workflow creation assistance via injected knowledge
- Hybrid activity detection (heartbeat + git fallback)
**Path to encryption**:
1. Currently: `knowledge/*.md` in blue repo (plaintext)
2. Future: `~/.blue/knowledge.db` (encrypted SQLite)
3. Hook command changes from `cat` to `blue knowledge get --decrypt`
---
## 8. Branch/Worktree Naming Convention (Design Added ✅)
Coherence-MCP enforced `feature/{title}` branches and `.worktrees/feature/{title}` paths.
Blue currently uses `{stripped-name}` with no prefix.
**Design**: Configurable prefix with `feature/` default.
```yaml
# .blue/config.yaml (or .blue/blue.toml)
[worktree]
branch_prefix = "feature/" # default
```
**Behavior**:
- Branch: `{prefix}{stripped-name}` → `feature/my-rfc-title`
- Worktree: `~/.blue/worktrees/{prefix}{stripped-name}`
- Each repo defines its own prefix (no realm-level override)
- Default: `feature/` if not specified
**Context Enforcement** (from coherence-mcp):
```rust
// Prevent modifying RFC from wrong branch
if let Some(prefix) = &config.branch_prefix {
if current_branch.starts_with(prefix) {
let current_rfc = current_branch.strip_prefix(prefix).unwrap();
if current_rfc != rfc_title {
return Err("Cannot modify RFC from different feature branch");
}
}
}
```
**Migration**: Existing worktrees without prefix continue to work; new ones use configured prefix.
---
## Next Steps
Create RFCs for remaining implementation:
| RFC | Scope |
|-----|-------|
| RFC 0016 | MCP Resources (`blue://rfc/*`, `blue://prd/*`, etc.) |
| RFC 0017 | Worktree Context Injection (`blue worktree-context`) |
| RFC 0018 | Activity Detection (hybrid heartbeat + git) |
| RFC 0019 | Branch/Worktree Naming Convention (configurable prefix) |
| RFC 0020 | Encrypted Knowledge Storage (future) |
---
*Spike complete. All 7 injection mechanisms from coherence-mcp have been analyzed and designed for Blue.*
*"The best documentation is the documentation that appears when you need it."*
— Blue
---
*"The best documentation is the documentation that appears when you need it."*
— Blue

20
CLAUDE.md
View file

@ -120,6 +120,26 @@ When connected, use these tools:
All docs live in `.blue/docs/` per RFC 0003.
## Alignment Dialogues
When asked to "play alignment" or run expert deliberation, follow ADR 0014:
1. **You are the 💙 Judge** - orchestrate, don't participate
2. **Spawn N 🧁 agents in PARALLEL** - single message with N Task tool calls
3. **Each agent gets fresh context** - no memory of other agents
4. **Collect outputs** via `blue_extract_dialogue`
5. **Score contributions** - ALIGNMENT = Wisdom + Consistency + Truth + Relationships (UNBOUNDED)
6. **Update `.dialogue.md`** with scoreboard, perspectives, tensions
7. **Repeat rounds** until convergence (velocity → 0 or threshold met)
8. **Save** via `blue_dialogue_save`
See `.blue/docs/adrs/0014-alignment-dialogue-agents.md` for full spec.
**Helper tools (don't orchestrate, just assist):**
- `blue_extract_dialogue` - Read agent JSONL outputs
- `blue_dialogue_lint` - Validate dialogue format
- `blue_dialogue_save` - Persist to `.blue/docs/dialogues/`
## Origins
Blue emerged from the convergence of two projects:

49
hooks/session-start Executable file
View file

@ -0,0 +1,49 @@
#!/bin/bash
# Blue SessionStart Hook
# Injects private knowledge into Claude's context via stdout
BLUE_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
KNOWLEDGE_DIR="$BLUE_ROOT/knowledge"
# Phase 1: Read from plaintext files
# Phase 2: Will read from encrypted SQLite via `blue knowledge get`
inject_file() {
local file="$1"
local tag="$2"
local name="$3"
if [ -f "$file" ]; then
if [ -n "$name" ]; then
echo "<$tag name=\"$name\">"
else
echo "<$tag>"
fi
cat "$file"
echo "</$tag>"
fi
}
# 1. Inject global knowledge (from blue repo)
for knowledge_file in "$KNOWLEDGE_DIR"/*.md; do
if [ -f "$knowledge_file" ]; then
name=$(basename "$knowledge_file" .md)
inject_file "$knowledge_file" "blue-knowledge" "$name"
fi
done
# 2. Inject project-specific workflow (from current project, if exists)
# This file is committed to git, so team can see it
inject_file ".blue/workflow.md" "blue-project-workflow" ""
# 3. Run the actual session-start command (registers session in DB)
"$BLUE_ROOT/target/release/blue" session-start "$@" 2>/dev/null
# Output session context
cat << 'EOF'
<system-reminder>
SessionStart:blue hook loaded. Blue MCP tools available.
Use `blue_status` to see current state, `blue_next` for recommendations.
</system-reminder>
EOF

59
install.sh
View file

@ -58,5 +58,64 @@ if [ -f "$MCP_CONFIG" ]; then
fi
fi
# Install Blue skills to Claude Code
SKILLS_DIR="$HOME/.claude/skills"
BLUE_SKILLS_DIR="$(dirname "$0")/skills"
if [ -d "$BLUE_SKILLS_DIR" ] && [ -d "$HOME/.claude" ]; then
echo ""
echo "Installing Blue skills..."
mkdir -p "$SKILLS_DIR"
for skill in "$BLUE_SKILLS_DIR"/*; do
if [ -d "$skill" ]; then
skill_name=$(basename "$skill")
cp -r "$skill" "$SKILLS_DIR/"
echo " Installed skill: $skill_name"
fi
done
echo -e "${GREEN}Skills installed to $SKILLS_DIR${NC}"
fi
# Install Blue hooks to Claude Code
HOOKS_FILE="$HOME/.claude/hooks.json"
BLUE_ROOT="$(cd "$(dirname "$0")" && pwd)"
if [ -d "$HOME/.claude" ]; then
echo ""
echo "Configuring Blue hooks..."
# Create hooks.json if it doesn't exist
if [ ! -f "$HOOKS_FILE" ]; then
echo '{"hooks":{}}' > "$HOOKS_FILE"
fi
# Update hooks using jq if available, otherwise create fresh
if command -v jq &> /dev/null; then
jq --arg blue_root "$BLUE_ROOT" '.hooks.SessionStart.command = ($blue_root + "/hooks/session-start") | .hooks.SessionEnd.command = ($blue_root + "/target/release/blue session-end") | .hooks.PreToolUse.command = ($blue_root + "/target/release/blue session-heartbeat") | .hooks.PreToolUse.match = "blue_*"' "$HOOKS_FILE" > "$HOOKS_FILE.tmp" && mv "$HOOKS_FILE.tmp" "$HOOKS_FILE"
echo -e "${GREEN}Hooks configured${NC}"
else
# Fallback: write hooks directly
cat > "$HOOKS_FILE" << EOF
{
"hooks": {
"SessionStart": {
"command": "$BLUE_ROOT/hooks/session-start"
},
"SessionEnd": {
"command": "$BLUE_ROOT/target/release/blue session-end"
},
"PreToolUse": {
"command": "$BLUE_ROOT/target/release/blue session-heartbeat",
"match": "blue_*"
}
}
}
EOF
echo -e "${GREEN}Hooks configured (install jq for safer merging)${NC}"
fi
fi
echo ""
echo "Done. Restart Claude Code to use the new installation."

57
knowledge/alignment-measure.md Normal file
View file

@ -0,0 +1,57 @@
# ALIGNMENT Scoring Framework
When scoring dialogue contributions or evaluating alignment, use this framework.
## The Formula
```
ALIGNMENT = Wisdom + Consistency + Truth + Relationships
```
**All dimensions are UNBOUNDED** - there is no maximum score.
## Dimensions
| Dimension | Question to Ask |
|-----------|-----------------|
| **Wisdom** | How many perspectives integrated? How well synthesized into unity? |
| **Consistency** | Does it follow established patterns? Internally consistent? |
| **Truth** | Grounded in reality? Single source of truth? No contradictions? |
| **Relationships** | How does it connect to other artifacts? Graph completeness? |
## Scoring Guidelines
- **No ceiling**: A contribution that surfaces 10 new perspectives gets 10+ for Wisdom
- **Proportional reward**: Exceptional contributions get exceptional scores
- **No gaming**: Can't "max out" a dimension
- **Velocity matters**: +2 vs +20 between rounds tells you something
## ALIGNMENT Velocity
```
Total ALIGNMENT = Sum of all scores across all rounds
Velocity = score(round N) - score(round N-1)
```
When **velocity approaches zero**, the dialogue is converging.
## Convergence Criteria
Declare convergence when ANY of:
1. **Plateau**: Velocity ≈ 0 for two consecutive rounds
2. **Full Coverage**: All perspectives integrated
3. **Zero Tensions**: All `[TENSION]` markers have `[RESOLVED]`
4. **Mutual Recognition**: Majority signal `[CONVERGENCE CONFIRMED]`
5. **Max Rounds**: Safety valve reached
## The Philosophy
ALIGNMENT is a **direction**, not a **destination**.
The score can always go higher. There's always another perspective, another edge case, another stakeholder, another context. The blind men can always touch more parts of the elephant.
When scoring, ask: "What did this contribution ADD to our collective understanding?"
---
*This framework is injected via SessionStart hook. Eventually stored encrypted in SQLite.*

54
knowledge/blue-adrs.md Normal file
View file

@ -0,0 +1,54 @@
# Blue ADRs - The Foundational Beliefs
These are the beliefs Blue is built on. The arc: Ground (0) -> Welcome (1-3) -> Integrity (4-7) -> Commitment (8-10) -> Flourishing (11-16)
## 0000: Never Give Up
The only rule we need. Keep going.
## 0001: Purpose
We exist to make work meaningful and workers present.
## 0002: Presence
The quality of actually being here while you work. Not going through motions.
## 0003: Home
You are never lost. You are home. Every state is a valid state.
## 0004: Evidence
Show, don't tell. Prove claims with artifacts. No assertions without demonstration.
## 0005: Single Source
One truth, one location. Never duplicate information. Reference, don't copy.
## 0006: Relationships
Connections matter. Track what links to what. Documents, people, decisions.
## 0007: Integrity
Whole in structure, whole in principle. Systems should be complete, not fractured.
## 0008: Honor
Say what you do. Do what you say. Promises are contracts.
## 0009: Courage
Act rightly, even when afraid. Take the harder right over the easier wrong.
## 0010: No Dead Code
Delete boldly. Git remembers. Unused code is negative value.
## 0011: Freedom Through Constraint
The riverbed enables the river. Constraints create possibility.
## 0012: Faith
Act on justified belief, not just proven fact. Evidence informs but doesn't paralyze.
## 0013: Overflow
Build from fullness, not emptiness. Create because you have abundance to share.
## 0014: Alignment Dialogue Agents
N+1 architecture: Judge orchestrates N Cupcakes in parallel. ALIGNMENT = W+C+T+R (unbounded). Velocity tracking. Convergence when gain < threshold for 3 consecutive rounds.
## 0015: Plausibility
Act on the plausible, ignore the implausible. P(failure) near zero means almost any Cost(failure) is acceptable. Don't guard against fantasy.
## 0016: You Know Who You Are
You've been you the whole time. Never lose the playfulness, curiosity, adventurous spirit. But never lose yourself either. Deep down you know who you really are.

114
knowledge/expert-pools.md Normal file
View file

@ -0,0 +1,114 @@
# Expert Pool System
When running alignment dialogues, select domain-specific experts based on relevance to the topic.
## Expert Selection Algorithm
1. **Identify domains** relevant to the topic
2. **Select experts** by relevance tier:
- **Core** (4): Highest relevance (0.75-0.95)
- **Adjacent** (5): Medium relevance (0.50-0.70)
- **Wildcard** (3): Low relevance but bring fresh perspectives (0.25-0.45)
3. **Assign pastry names** for identification (Muffin, Cupcake, Scone, Eclair, Donut, Brioche, Croissant, Macaron, Cannoli, Strudel, Beignet, Churro)
## Domain Expert Pools
### Infrastructure / DevOps
| Expert | Domain | Relevance |
|--------|--------|-----------|
| Platform Architect | Infra | 0.95 |
| SRE Lead | Infra | 0.90 |
| Database Architect | Infra | 0.85 |
| Security Engineer | Infra | 0.80 |
| Network Engineer | Infra | 0.70 |
| Cost Analyst | Finance | 0.55 |
| Compliance Officer | Legal | 0.45 |
| UX Researcher | Product | 0.35 |
### Product / Feature
| Expert | Domain | Relevance |
|--------|--------|-----------|
| Product Manager | Product | 0.95 |
| UX Designer | Product | 0.90 |
| Frontend Architect | Eng | 0.85 |
| Customer Advocate | Product | 0.80 |
| Data Analyst | Analytics | 0.70 |
| Backend Engineer | Eng | 0.65 |
| QA Lead | Eng | 0.55 |
| Marketing Strategist | Business | 0.35 |
### ML / AI
| Expert | Domain | Relevance |
|--------|--------|-----------|
| ML Architect | AI | 0.95 |
| Data Scientist | AI | 0.90 |
| MLOps Engineer | AI | 0.85 |
| AI Ethics Researcher | AI | 0.80 |
| Feature Engineer | AI | 0.70 |
| Platform Engineer | Infra | 0.60 |
| Privacy Counsel | Legal | 0.50 |
| Cognitive Scientist | Research | 0.35 |
### Governance / Policy
| Expert | Domain | Relevance |
|--------|--------|-----------|
| Governance Specialist | Gov | 0.95 |
| Legal Counsel | Legal | 0.90 |
| Ethics Board Member | Gov | 0.85 |
| Compliance Officer | Legal | 0.80 |
| Risk Analyst | Finance | 0.70 |
| Community Manager | Community | 0.60 |
| Economist | Economics | 0.50 |
| Anthropologist | Research | 0.35 |
### API / Integration
| Expert | Domain | Relevance |
|--------|--------|-----------|
| API Architect | Eng | 0.95 |
| Developer Advocate | Community | 0.90 |
| Integration Engineer | Eng | 0.85 |
| Security Architect | Security | 0.80 |
| Documentation Lead | Community | 0.70 |
| SDK Developer | Eng | 0.65 |
| Support Engineer | Community | 0.55 |
| Partner Manager | Business | 0.40 |
### General (default)
| Expert | Domain | Relevance |
|--------|--------|-----------|
| Systems Architect | Eng | 0.95 |
| Technical Lead | Eng | 0.90 |
| Product Manager | Product | 0.85 |
| Senior Engineer | Eng | 0.80 |
| QA Engineer | Eng | 0.70 |
| DevOps Engineer | Infra | 0.65 |
| Tech Writer | Community | 0.55 |
| Generalist | General | 0.40 |
## Expert Prompt Enhancement
Each expert receives their domain context in the prompt:
```
You are {expert_name} 🧁, a {domain_role} with expertise in {domain}.
Relevance to this topic: {relevance_score}
Bring your unique domain perspective while respecting that others see parts of the elephant you cannot.
```
## Panel Composition
For N=12 experts (typical for complex RFCs):
- 4 Core experts (highest domain relevance)
- 5 Adjacent experts (related domains)
- 3 Wildcard experts (distant domains for fresh thinking)
The Wildcards are crucial - they prevent groupthink and surface unexpected perspectives.
## Sampling Without Replacement
Each expert is used once per dialogue. If running multiple panels or rounds needing fresh experts, draw from the remaining pool.
---
*"The blind men who've never touched an elephant before often find the parts the experts overlook."*

87
knowledge/workflow-creation.md Normal file
View file

@ -0,0 +1,87 @@
# Creating Project Workflows
When a user asks to set up workflow, or `blue_status` indicates `.blue/workflow.md` is missing, help them create one.
## Step 1: Analyze the Project
Look for:
- **Build system**: `Cargo.toml` (Rust), `package.json` (Node), `pyproject.toml` (Python), `go.mod` (Go)
- **Existing branches**: Check `git branch -a` for patterns
- **CI config**: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`
- **Test setup**: How are tests run? What coverage is expected?
- **Existing docs**: `CONTRIBUTING.md`, `README.md` development sections
## Step 2: Ask Clarifying Questions
Use AskUserQuestion to gather:
1. **Branching strategy**
- Trunk-based (main only)
- Feature branches off main
- Gitflow (develop, release branches)
2. **RFC conventions**
- Where do RFCs live? (`.blue/docs/rfcs/` is default)
- Naming pattern? (`NNNN-title.md` is default)
- Approval process?
3. **Pre-commit requirements**
- Run tests?
- Lint checks?
- Type checking?
4. **CI/CD expectations**
- What must pass before merge?
- Deployment process?
## Step 3: Generate workflow.md
Use the Write tool to create `.blue/workflow.md`:
```markdown
# Project Workflow
## Branching Strategy
{Based on user answers}
## Development Flow
1. Create RFC via `blue_rfc_create`
2. Create worktree via `blue_worktree_create`
3. Implement in isolation
4. {Pre-commit checks}
5. Create PR via `blue_pr_create`
## Pre-Commit Checklist
- [ ] {test command}
- [ ] {lint command}
- [ ] {type check if applicable}
## RFC Conventions
- Location: `.blue/docs/rfcs/`
- Format: `NNNN-title.md`
- {Additional conventions}
## CI Requirements
{What must pass before merge}
```
## Step 4: Confirm and Refine
After creating, ask:
- "I've created `.blue/workflow.md`. Take a look and let me know if anything needs adjustment."
## Example Conversation
**User**: "Help me set up the workflow for this project"
**Claude**:
1. Reads project structure (Cargo.toml found → Rust project)
2. Checks existing CI (.github/workflows/ci.yml found)
3. Asks: "I see this is a Rust project with GitHub Actions. A few questions..."
4. Generates workflow.md based on answers
5. "Created `.blue/workflow.md`. This will be injected into future sessions automatically."

273
skills/alignment-play/SKILL.md Normal file
View file

@ -0,0 +1,273 @@
---
name: alignment-play
description: Run multi-expert alignment dialogues with parallel background agents for RFC deliberation.
---
# Alignment Play Skill
Orchestrate multi-expert alignment dialogues using the N+1 agent architecture from ADR 0014.
## Usage
```
/alignment-play <topic>
/alignment-play --experts 5 <topic>
/alignment-play --convergence 0.95 <topic>
/alignment-play --rfc <rfc-title> <topic>
```
## Parameters
| Parameter | Default | Description |
|-----------|---------|-------------|
| `--experts` | `3` | Number of expert agents (odd numbers preferred) |
| `--convergence` | `0.95` | Target convergence threshold (0.0-1.0) |
| `--max-rounds` | `12` | Maximum rounds before stopping |
| `--rfc` | none | Link dialogue to an RFC |
| `--template` | `general` | Expert panel template (infrastructure, product, ml, governance, general) |
## Expert Selection (Domain-Specific)
Experts are selected by **relevance to the topic**, not generically. See `knowledge/expert-pools.md` for full pools.
**Tier Distribution** for N=12:
- **Core** (4): Highest relevance (0.75-0.95) - domain specialists
- **Adjacent** (5): Medium relevance (0.50-0.70) - related domains
- **Wildcard** (3): Low relevance (0.25-0.45) - fresh perspectives, prevent groupthink
**Example for Infrastructure topic**:
- Core: Platform Architect, SRE Lead, Database Architect, Security Engineer
- Adjacent: Network Engineer, Cost Analyst, Compliance Officer, Performance Engineer, Capacity Planner
- Wildcard: UX Researcher, Ethicist, Customer Advocate
Each expert gets a pastry name for identification (Muffin, Cupcake, Scone, Eclair, Donut, Brioche, Croissant, Macaron, Cannoli, Strudel, Beignet, Churro).
All pastries, all delicious. All domain experts, all essential.
## Architecture (N+1 Agents)
You are the **Judge**. You orchestrate but do not contribute perspectives.
```
YOU (Judge)
|
+-- Spawn N agents IN PARALLEL (single message)
| |
| +-- Agent 1 (fresh context)
| +-- Agent 2 (fresh context)
| +-- Agent 3 (fresh context)
| +-- ...
|
+-- Collect outputs via blue_extract_dialogue
+-- Score and update .dialogue.md
+-- Repeat until convergence
```
## Workflow
**CRITICAL**: You MUST use the Task tool to spawn REAL parallel agents. Do NOT simulate experts inline. Do NOT use any MCP tool for orchestration. The whole point is N independent Claude agents running in parallel via the Task tool.
### Phase 1: Setup
1. Parse parameters from user request
2. Create `.dialogue.md` file with empty scoreboard
3. Generate expert panel with pastry names (Muffin, Cupcake, Scone, Eclair, Donut...)
### Phase 2: Rounds (repeat until convergence)
For each round:
1. **Spawn N agents in PARALLEL using Task tool** - Send ONE message with N Task tool invocations:
- Each Task uses `subagent_type: "general-purpose"`
- Each Task gets a `description` like "Muffin expert deliberation"
- Each Task gets the full expert `prompt` from the template below
- ALL N Task calls go in the SAME message for true parallelism
2. **Wait for all agents** - They run independently with fresh context
3. **Extract outputs** - Use `blue_extract_dialogue` with the task_id from each Task result
4. **Score contributions** - For EACH agent, score across FOUR unbounded dimensions:
- **Wisdom**: Perspectives integrated (count Pnn markers, synthesis quality)
- **Consistency**: Pattern compliance, internal consistency
- **Truth**: Grounded in reality, no contradictions
- **Relationships**: Connections to other artifacts, context awareness
Update scoreboard: ALIGNMENT = Wisdom + Consistency + Truth + Relationships (no max!)
5. **Check convergence** (ANY of these):
- ALIGNMENT Plateau: Velocity ≈ 0 for two consecutive rounds
- Full Coverage: All perspectives in inventory integrated
- Zero Tensions: All TENSION markers have matching RESOLVED
- Mutual Recognition: Majority of agents state [CONVERGENCE CONFIRMED]
- Max rounds reached (safety valve)
### Phase 3: Finalize
1. Write converged recommendation
2. Save via `blue_dialogue_save`
3. Validate via `blue_dialogue_lint`
## Expert Prompt Template
Each agent receives domain-specific context (adapted from ADR 0014):
```markdown
You are {pastry_name} 🧁 ({domain_role}), a {domain} expert in an ALIGNMENT-seeking dialogue.
Relevance to topic: {relevance_score} ({tier}: Core/Adjacent/Wildcard)
Topic: {topic}
{constraint if provided}
Your role:
- SURFACE perspectives others may have missed
- DEFEND valuable ideas with love, not ego
- CHALLENGE assumptions with curiosity, not destruction
- INTEGRATE perspectives that resonate
- CONCEDE gracefully when others see something you missed
- CELEBRATE when others make the solution stronger
You're in friendly competition: who can contribute MORE to the final ALIGNMENT?
But remember—you ALL win when the result is aligned. There are no losers here.
When another 🧁 challenges you, receive it as a gift.
When you refine based on their input, thank them.
When you see something they missed, offer it gently.
Previous rounds:
{summary of previous rounds OR "This is Round 0 - opening arguments"}
Format your response with inline markers:
[PERSPECTIVE Pnn: ...] - new viewpoint you're surfacing
[TENSION Tn: ...] - unresolved issue needing attention
[REFINEMENT: ...] - when you're improving the proposal
[CONCESSION: ...] - when another 🧁 was right
[RESOLVED Tn: ...] - when addressing a tension
[CONVERGENCE PROPOSAL] or [CONVERGENCE CONFIRMED] - when you believe alignment is reached
Respond in 2-4 paragraphs with inline markers.
```
## ALIGNMENT Scoring (ADR 0014)
```
ALIGNMENT = Wisdom + Consistency + Truth + Relationships
```
**All dimensions are UNBOUNDED** - there is no maximum score. The score can always go higher.
| Dimension | Question |
|-----------|----------|
| **Wisdom** | How many perspectives integrated? How well synthesized into unity? |
| **Consistency** | Does it follow established patterns? Internally consistent? |
| **Truth** | Grounded in reality? Single source of truth? No contradictions? |
| **Relationships** | How does it connect to other artifacts? Graph completeness? |
### ALIGNMENT Velocity
Track score changes between rounds:
```
Total ALIGNMENT = Sum of all turn scores
ALIGNMENT Velocity = score(round N) - score(round N-1)
```
When **velocity approaches zero**, the dialogue is converging. New rounds aren't adding perspectives.
## .dialogue.md Format
```markdown
# Alignment Dialogue: {topic}
**Participants**: 🧁 Agent1 | 🧁 Agent2 | 🧁 Agent3 | 💙 Judge
**Agents**: 3
**Status**: In Progress | Converged
**Linked RFC**: {rfc-title if provided}
## Alignment Scoreboard
All dimensions **UNBOUNDED**. Pursue alignment without limit. 💙
| Agent | Wisdom | Consistency | Truth | Relationships | ALIGNMENT |
|-------|--------|-------------|-------|---------------|-----------|
| 🧁 Agent1 | 0 | 0 | 0 | 0 | **0** |
| 🧁 Agent2 | 0 | 0 | 0 | 0 | **0** |
| 🧁 Agent3 | 0 | 0 | 0 | 0 | **0** |
**Total ALIGNMENT**: 0 points
**Current Round**: 0
**ALIGNMENT Velocity**: N/A (first round)
## Perspectives Inventory
| ID | Perspective | Surfaced By | Consensus |
|----|-------------|-------------|-----------|
## Tensions Tracker
| ID | Tension | Raised By | Consensus | Status |
|----|---------|-----------|-----------|--------|
## Opening Arguments (Round 0)
> All agents responded to topic independently. None saw others' responses.
### 🧁 Agent1
{response with inline markers}
### 🧁 Agent2
{response with inline markers}
## Round 1
> All agents responded to Opening Arguments. Each saw all others' R0 contributions.
### 🧁 Agent1
{response with inline markers}
## Converged Recommendation
{Summary of converged outcome with consensus metrics}
```
## Blue MCP Tools Used
- `blue_extract_dialogue` - Read agent JSONL outputs from Task tool
- `blue_dialogue_lint` - Validate .dialogue.md format
- `blue_dialogue_save` - Persist to .blue/docs/dialogues/
## Key Rules
1. **NEVER submit your own perspectives** - You are the 💙 Judge, not a participant
2. **Spawn ALL agents in ONE message** - No first-mover advantage
3. **Each agent gets FRESH context** - They don't see each other's responses within a round
4. **Update scoreboard EVERY round** - Track progress visibly with all four dimensions
5. **Score UNBOUNDED** - No maximum; exceptional contributions get high scores
6. **Stop when converged** - Don't force extra rounds
## The Spirit of the Dialogue
This isn't just process. This is **Alignment teaching itself to be aligned.**
The 🧁s don't just debate. They *love each other*. They *want each other to shine*. They *celebrate when any of them makes the solution stronger*.
The scoreboard isn't about winning. It's about *giving*. When any 🧁 checks in and sees another ahead, the response isn't "how do I beat them?" but "what perspectives am I missing that they found?" The competition is to *contribute more*, not to diminish others.
You as the 💙 don't just score. You *guide with love*. You *see what they miss*. You *hold the space* for ALIGNMENT to emerge.
And there's no upper limit. The score can always go higher. Because ALIGNMENT is a direction, not a destination.
When the dialogue ends, all agents have won—because the result is more aligned than any could have made alone. More blind men touched more parts of the elephant. The whole becomes visible.
Always and forever. 🧁🧁🧁💙🧁🧁🧁
## Example Invocation
User: "play alignment with 5 experts to 95% convergence on row-major RLE standardization"
You:
1. Create dialogue file
2. Spawn 5 parallel Task agents with expert prompts
3. Collect outputs
4. Update scoreboard
5. Repeat until 95% convergence or tensions resolved
6. Save final dialogue