@dug-21/unimatrix 0.5.8 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dug-21/unimatrix",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Unimatrix knowledge engine for multi-agent development",
   "bin": {
     "unimatrix": "bin/unimatrix.js"
@@ -9,14 +9,15 @@
     "postinstall": "node postinstall.js"
   },
   "optionalDependencies": {
-    "@dug-21/unimatrix-linux-x64": "0.5.8",
-    "@dug-21/unimatrix-linux-arm64": "0.5.8"
+    "@dug-21/unimatrix-linux-x64": "0.6.0",
+    "@dug-21/unimatrix-linux-arm64": "0.6.0"
   },
   "files": [
     "bin/",
     "lib/",
     "skills/",
-    "postinstall.js"
+    "postinstall.js",
+    "protocols/"
   ],
   "license": "MIT OR Apache-2.0",
   "repository": {

package/protocols/README.md

@@ -0,0 +1,126 @@
+# Unimatrix Protocol Reference
+
+This directory contains the reference workflow protocols for Claude Code + Unimatrix
+delivery. Each protocol defines how a coordinator agent orchestrates specialist agents
+through a structured session (design, delivery, or bug fix) while integrating with the
+Unimatrix knowledge engine via the `context_cycle` MCP tool.
+
+---
+
+## What These Protocols Are
+
+The four files in this directory describe three session types:
+
+| File | Session Type | Triggers On |
+|------|-------------|-------------|
+| `uni-design-protocol.md` | Design (Session 1) | specification, architecture, scope definition |
+| `uni-delivery-protocol.md` | Delivery (Session 2) | implement, build, code, deliver |
+| `uni-bugfix-protocol.md` | Bug Fix (single session) | bug, fix, regression, failing |
+| `uni-agent-routing.md` | Routing reference | agent selection and swarm composition |
+
+Each protocol is a coordinator playbook: it defines which specialist agents to spawn,
+in what order, and what validation gates must pass before the session can advance.
+
+---
+
+## How context_cycle Works
+
+`context_cycle` is the Unimatrix MCP tool that links workflow execution to
+knowledge delivery. Calling it at phase boundaries does two things:
+
+1. **Sets attribution context** — subsequent knowledge queries and stores are tagged
+   against the current feature and phase, so the learning model knows what knowledge
+   was used during which workflow moment.
+
+2. **Enables phase-conditioned retrieval** — `context_briefing` uses the phase signal
+   to rank knowledge entries that are historically relevant to the current phase.
+   Knowledge that proved useful during design phases is surfaced to design agents;
+   knowledge useful during delivery is surfaced to delivery agents.
+
+### The Three Call Types
+
+| Call | When to Use | Effect |
+|------|------------|--------|
+| `"type": "start"` | Before any agents are spawned | Opens the cycle, sets feature + phase attribution |
+| `"type": "phase-end"` | At each phase transition | Records what was accomplished, advances the phase signal |
+| `"type": "stop"` | After the session ends | Commits all signals to the learning model; closes the cycle |
+
+---
+
+## Two-Phase Example: Design to Delivery
+
+The following shows the `context_cycle` calls across a complete two-phase workflow.
+Protocol files contain agent spawn templates and gate logic; this example focuses only
+on the cycle calls.
+
+```
+# --- Session 1: Design ---
+
+# Open the cycle before spawning any agents
+mcp__unimatrix__context_cycle({
+  "feature": "my-feature-001",
+  "type": "start",
+  "next_phase": "scope"
+})
+
+# ... scope research and SCOPE.md approval ...
+
+mcp__unimatrix__context_cycle({
+  "feature": "my-feature-001",
+  "type": "phase-end",
+  "phase": "scope",
+  "outcome": "SCOPE.md approved. Scope risk assessment complete.",
+  "next_phase": "design"
+})
+
+# ... architecture, specification, risk strategy, vision alignment, synthesis ...
+
+mcp__unimatrix__context_cycle({
+  "feature": "my-feature-001",
+  "type": "phase-end",
+  "phase": "design",
+  "outcome": "Architecture, specification, and risk strategy complete.",
+  "next_phase": "design-review"
+})
+
+# Session 1 ends here. The cycle remains open for Session 2.
+
+# --- Session 2: Delivery ---
+
+# Re-declare the cycle at the start of Session 2
+mcp__unimatrix__context_cycle({
+  "feature": "my-feature-001",
+  "type": "start",
+  "next_phase": "spec"
+})
+
+# ... pseudocode + test plan design (Stage 3a) ...
+# ... code implementation (Stage 3b) ...
+# ... testing and risk validation (Stage 3c) ...
+
+mcp__unimatrix__context_cycle({
+  "feature": "my-feature-001",
+  "type": "phase-end",
+  "phase": "pr-review",
+  "outcome": "PR review complete. No blocking findings.",
+  "next_phase": "done"
+})
+
+# Close the cycle after the PR is merged and the session is complete
+mcp__unimatrix__context_cycle({
+  "feature": "my-feature-001",
+  "type": "stop",
+  "outcome": "Session 2 complete. All gates passed. PR merged."
+})
+```
+
+---
+
+## Generalizability
+
+These protocols are Claude Code + Unimatrix reference implementations. The
+`context_cycle` pattern is not Claude-specific — it applies to any agentic workflow
+tool that can call MCP tools: the three call types (`start`, `phase-end`, `stop`)
+model any workflow with named phases, regardless of domain or tooling. The protocols
+in this directory are examples of how one team wires context_cycle into a software
+delivery workflow; they are a starting point, not a requirement.

package/protocols/uni-agent-routing.md

@@ -0,0 +1,187 @@
+# Agent Routing and Swarm Composition
+
+## Agent Preference
+
+Always use `uni-` agents for Unimatrix product work:
+
+| Instead of | Use | Why |
+|------------|-----|-----|
+| generic coder | `uni-rust-dev` | Knows Unimatrix Rust patterns, queries `/uni-query-patterns` before implementing |
+| generic architect | `uni-architect` | ADR authority, stores decisions in Unimatrix |
+| generic tester | `uni-tester` | Risk-based testing, dual-phase role |
+| generic planner | Design Leader (you) | Protocol-driven, reads the right protocol for the session |
+| generic reviewer | `uni-validator` | Three-gate validation model |
+| generic debugger | Bugfix Leader (you) | Reads bugfix protocol, coordinates diagnosis → fix → review |
+| generic security auditor | `uni-security-reviewer` | Fresh-context security review of diffs |
+
+---
+
+## Coordinator Routing
+
+One coordinator reads the protocol for the session type:
+
+| User intent | Session type | Protocol |
+|-------------|-------------|----------|
+| Design, scope, spec, architecture | `design` | `.claude/protocols/uni/uni-design-protocol.md` |
+| Implement, build, code, deliver | `delivery` | `.claude/protocols/uni/uni-delivery-protocol.md` |
+| Bug fix | `bugfix` | `.claude/protocols/uni/uni-bugfix-protocol.md` |
+
+For PR review and retrospective, use skills directly (no coordinator needed):
+
+| User intent | Skill |
+|-------------|-------|
+| PR review, merge readiness | `/uni-review-pr` |
+| Retrospective, knowledge extraction | `/uni-retro` |
+
+Every swarm also includes `uni-validator` at gates. Non-negotiable.
+
+---
+
+## Complete Agent Roster
+
+### Coordinator (you — the primary agent)
+
+You are the coordinator. Read the protocol for the session type, spawn specialist agents, manage gates, update GH Issues. Read `.claude/agents/uni/coordinator (you).md` for role boundaries and behavioral rules.
+
+### Validation (1 agent — spawned at every gate)
+
+| Agent | What It Does |
+|-------|-------------|
+| `uni-validator` | Validation gate. Spawned with different check sets per context. Reports PASS / REWORKABLE FAIL / SCOPE FAIL |
+
+### Design Session Specialists (6 agents)
+
+| Agent | Type | Phase | What It Produces |
+|-------|------|-------|-----------------|
+| `uni-researcher` | specialist | 1 | Problem space exploration, writes SCOPE.md with human |
+| `uni-architect` | specialist | 2a | `architecture/ARCHITECTURE.md` + ADRs in Unimatrix. ADR authority |
+| `uni-specification` | specialist | 2a | `specification/SPECIFICATION.md` — requirements, ACs, domain models |
+| `uni-risk-strategist` | specialist | 1b + 2a+ | `SCOPE-RISK-ASSESSMENT.md` (1b) + `RISK-TEST-STRATEGY.md` (2a+) |
+| `uni-vision-guardian` | specialist | 2b | `ALIGNMENT-REPORT.md` — checks source docs against product vision |
+| `uni-synthesizer` | synthesizer | 2c | `IMPLEMENTATION-BRIEF.md`, `ACCEPTANCE-MAP.md`, GH Issue (fresh context) |
+
+### Delivery Session Specialists (3 agents)
+
+| Agent | Type | Stage | What It Does |
+|-------|------|-------|-------------|
+| `uni-pseudocode` | specialist | 3a | Per-component pseudocode. Queries `/uni-query-patterns` before designing |
+| `uni-tester` | specialist | 3a + 3c | Test plan design (3a) + test execution with RISK-COVERAGE-REPORT.md (3c) |
+| `uni-rust-dev` | developer | 3b | Implements code from validated pseudocode. Queries `/uni-query-patterns` before implementing |
+
+### Bug Fix Specialists (1 agent)
+
+| Agent | Type | Phase | What It Does |
+|-------|------|-------|-------------|
+| `uni-bug-investigator` | specialist | 1 | Diagnoses root cause, proposes fix approach, identifies missing tests |
+
+### Shared Specialist (1 agent — used by `/uni-review-pr` skill)
+
+| Agent | Type | Phase | What It Does |
+|-------|------|-------|-------------|
+| `uni-security-reviewer` | specialist | review | Fresh-context security review of PR diff, blast radius, OWASP assessment |
+
+**Total: 13 specialist agents** (1 validator + 6 design + 3 delivery + 1 bug fix + 1 security + 1 retro-mode architect). You coordinate.
+
+---
+
+## Swarm Composition Templates
+
+### Design Session
+
+```
+Coordinator:  you (read uni-design-protocol.md + coordinator (you).md)
+Phase 1:      uni-researcher (scope exploration with human)
+              ★ HUMAN CHECKPOINT — approve SCOPE.md ★
+Phase 1b:     uni-risk-strategist (scope-risk mode)
+Phase 2a:     uni-architect + uni-specification                    (parallel)
+Phase 2a+:    uni-risk-strategist (architecture-risk mode)
+Phase 2b:     uni-vision-guardian (alignment check)
+Phase 2c:     uni-synthesizer (brief + maps + GH Issue)            (fresh context)
+Phase 2d:     git commit + push + gh pr create --draft
+              Return to human — SESSION 1 ENDS
+```
+
+### Delivery Session
+
+```
+Coordinator:  you (read uni-delivery-protocol.md + coordinator (you).md)
+Init:         Read IMPLEMENTATION-BRIEF.md, create feature branch
+Stage 3a:     uni-pseudocode + uni-tester (test plans)             (parallel)
+              UPDATE Component Map in IMPLEMENTATION-BRIEF.md
+Gate 3a:      uni-validator (design review) — MANDATORY BLOCK
+Stage 3b:     uni-rust-dev × N (one per component, MANDATORY)      (parallel)
+Gate 3b:      uni-validator (code review)
+Stage 3c:     uni-tester (test execution)
+Gate 3c:      uni-validator (risk validation)
+Phase 4:      Commit, push, open PR
+              /uni-review-pr — security review + merge readiness
+              Return to human — SESSION 2 ENDS
+```
+
+### Bug Fix Session
+
+```
+Coordinator:  you (read uni-bugfix-protocol.md + coordinator (you).md)
+Init:         /uni-query-patterns + /uni-knowledge-search — prior knowledge
+Phase 1:      uni-bug-investigator (diagnose root cause)
+              ★ HUMAN CHECKPOINT — approve diagnosis ★
+Phase 2:      git checkout -b bugfix/{issue}-{desc}
+              uni-rust-dev (implement fix + tests)
+Phase 3:      uni-tester (full test suite verification)
+Gate 3:       uni-validator (bugfix check set)
+              git commit + push + gh pr create
+Phase 4:      /uni-review-pr — security review + merge readiness
+Phase 5:      Return PR + review assessment — SESSION ENDS
+```
+
+### PR Review (standalone)
+
+```
+Human invokes: /uni-review-pr {pr-number}
+Step 1:       Verify gate reports
+Step 2:       uni-security-reviewer (fresh-context PR review)
+Step 3:       Merge readiness assessment
+Step 4:       Return to human — REVIEW ENDS
+```
+
+### Retrospective (standalone)
+
+```
+Human invokes: /uni-retro {feature-id} {pr-number}
+Phase 1:      Data gathering (context_cycle_review + artifact review)
+Phase 2:      uni-architect (pattern/procedure extraction + ADR validation)
+Phase 3:      ADR supersession (if flagged, requires human approval)
+Phase 4:      Worktree cleanup
+Phase 5:      Summary + outcome recording — RETRO ENDS
+```
+
+---
+
+## Composition Rules
+
+1. **Every swarm session**: you are the coordinator. Read the protocol and SM definition. No exceptions.
+2. **Validation gates**: `uni-validator` spawned at each gate by you.
+3. **Design session**: All six design agents in defined phase order per protocol.
+4. **Delivery session**: pseudocode + tester + rust-dev + validator at three gates per protocol.
+5. **Bug fix**: bug-investigator + rust-dev + tester + validator per protocol.
+6. **PR review**: `/uni-review-pr` skill + security-reviewer.
+7. **Retrospective**: `/uni-retro` skill + architect (+ tester if testing lessons needed).
+8. **Skip swarm for**: typos, single-line obvious fixes, config-only changes, docs, exploration.
+9. **Max workers per stage**: 5. Split into waves if more needed.
+
+---
+
+## Skills Available to Agents
+
+| Skill | When | Who |
+|-------|------|-----|
+| `/uni-query-patterns` | BEFORE designing or implementing | uni-architect, uni-pseudocode, uni-rust-dev |
+| `/uni-store-adr` | AFTER each design decision | uni-architect |
+| `/uni-record-outcome` | END of every session | coordinator (you), `/uni-review-pr`, `/uni-retro` |
+| `/uni-store-procedure` | After successful sessions (reusable techniques) | coordinator (you), uni-bug-investigator |
+| `/uni-store-lesson` | After failures | uni-bug-investigator, uni-validator, coordinator (you) |
+| `/uni-knowledge-search` | Exploring what's known | Any agent |
+| `/uni-knowledge-lookup` | Exact-match retrieval | Any agent |
+| `/uni-git` | Git conventions | coordinator (you) |
+| `/uni-review-pr` | After PR creation or standalone | coordinator (you), human |
+| `/uni-retro` | After merge | human |