@dug-21/unimatrix 0.5.5

package/skills/store-pattern/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: "store-pattern"
+description: "Store a reusable implementation pattern in Unimatrix. Use when you discover a gotcha, trap, or reusable solution that future agents should know."
+---
+
+# Store Pattern — Implementation Knowledge
+
+## What This Skill Does
+
+Stores a reusable pattern in Unimatrix. Patterns capture implementation gotchas, traps, and solutions — knowledge invisible in source code that you only learn by hitting it. They surface in future `/query-patterns` results so the next agent doesn't repeat the discovery.
+
+**Use when:** you discover something that compiles but breaks at runtime, a non-obvious integration requirement, a crate-specific trap, or a reusable solution to a recurring problem.
+
+---
+
+## Pattern vs Lesson vs Procedure
+
+| Type | When to use | Example |
+|------|------------|---------|
+| **Pattern** (`/store-pattern`) | Reusable solution or gotcha applicable regardless of failure context | "Don't hold lock_conn() across await — deadlocks under concurrent requests" |
+| **Lesson** (`/store-lesson`) | Triggered by a specific failure; takeaway is preventive | "Gate 3b failed because rust-dev didn't read ADR before implementing" |
+| **Procedure** (`/store-procedure`) | Ordered steps to accomplish a task | "How to add a new MCP tool: step 1, 2, 3..." |
+
+**Decision rule:** If the knowledge was triggered by a specific failure and the takeaway is "don't do X," use `/store-lesson`. If the knowledge is a reusable solution applicable regardless of failure context — "when doing X, use approach Y because Z" — use `/store-pattern`.
+
+---
+
+## How to Store
+
+### Step 1: Check for existing patterns in the same area
+
+```
+mcp__unimatrix__context_search(
+  query: "{what the pattern is about}",
+  category: "pattern",
+  k: 3
+)
+```
+
+If a matching pattern already exists, go to Step 2b (supersede) instead of creating a duplicate.
+
+### Step 2a: Store NEW pattern (no prior exists)
+
+Assemble the content from three required fields:
+
+- **What**: The pattern in one sentence (max 200 chars). What to do or not do.
+- **Why**: What goes wrong without it (min 10 chars). The consequence that makes this worth knowing.
+- **Scope**: Where it applies — crate name, module, or context.
+
+```
+mcp__unimatrix__context_store(
+  title: "{concise what statement}",
+  content: "What: {what}\nWhy: {why}\nScope: {scope}",
+  topic: "{crate name or module — e.g., 'unimatrix-store'}",
+  category: "pattern",
+  tags: ["{domain}", "{feature_cycle if known}"],
+  agent_id: "{your role name, e.g. uni-rust-dev}"
+)
+```
+
+### Step 2b: Supersede EXISTING pattern (prior exists but is incomplete or outdated)
+
+```
+mcp__unimatrix__context_correct(
+  original_id: {old entry ID},
+  content: "What: {updated what}\nWhy: {updated why}\nScope: {updated scope}",
+  reason: "Updated: {what changed and why}"
+)
+```
+
+This deprecates the old pattern and creates a corrected version with a supersession chain.
+
+---
+
+## Quality Rules
+
+**Reject if:**
+- `why` is missing or under 10 characters — no motivation, no value
+- `what` exceeds 200 characters — not concise enough
+- Content is API documentation, not a gotcha — "Store has a lock_conn() method" is docs, not a pattern
+
+**Good patterns:**
+```
+What: Don't hold lock_conn() across await points
+Why: Deadlocks under concurrent MCP requests — the Store mutex is not async-aware
+Scope: unimatrix-store, any async caller
+```
+
+```
+What: Use #[serde(default)] on all new EntryRecord fields
+Why: Existing serialized records lack the field; deserialization panics without default
+Scope: unimatrix-core EntryRecord, any schema evolution
+```
+
+**Bad patterns:**
+```
+What: I used Arc::clone for shared ownership
+Why: It works
+```
+(No gotcha. No consequence. This is just Rust basics.)
+
+---
+
+## Tagging Conventions
+
+| Tag type | Examples |
+|----------|----------|
+| Crate | `store`, `server`, `vector`, `core`, `embed`, `engine` |
+| Domain | `async`, `serialization`, `migration`, `mcp`, `confidence` |
+| Feature cycle | `vnc-009`, `crt-005` (for retro traceability) |
+
+---
+
+## Who Stores Patterns
+
+| Agent | When |
+|-------|------|
+| uni-rust-dev | Implementation gotchas discovered while coding |
+| uni-tester | Test infrastructure patterns, fixture usage discoveries |
+| uni-risk-strategist | Risk patterns that recur across features |
+| uni-researcher | Technical landscape patterns from problem space exploration |
+| uni-vision-guardian | Recurring alignment variance patterns across features |
+| uni-validator | Quality patterns (cross-feature, not gate-specific) |
+| Retrospective agents | Patterns extracted from shipped feature analysis |

package/skills/store-procedure/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: "store-procedure"
+description: "Store or update a technical procedure (how-to) in Unimatrix. Use during retrospectives when a technique has evolved or been discovered."
+---
+
+# Store Procedure — Technical How-To Knowledge
+
+## What This Skill Does
+
+Stores a step-by-step technical procedure in Unimatrix. Procedures describe HOW to accomplish specific tasks in this project. They evolve as the project evolves.
+
+**Use during retrospectives** — not while implementing. Procedures are extracted from evidence, not guessed mid-session.
+
+---
+
+## Procedure vs Convention vs Pattern
+
+| Type | What it is | Example |
+|------|-----------|---------|
+| **Procedure** | Ordered steps to accomplish a task | "How to add a new MCP tool: step 1, 2, 3..." |
+| **Convention** | A rule or standard | "No .unwrap() in non-test code" |
+| **Pattern** | A reusable solution to a recurring problem | "Fresh context for unbiased review" |
+
+If it has **numbered steps**, it's a procedure. If it's a **rule**, it's a convention. If it's a **when/why/how solution**, it's a pattern.
+
+---
+
+## How to Store a New Procedure
+
+### Step 1: Check for existing procedure
+
+```
+mcp__unimatrix__context_search(
+  query: "{what the procedure covers}",
+  category: "procedure",
+  k: 3
+)
+```
+
+If an existing procedure covers the same task, use Step 2 (Update) instead.
+
+### Step 2a: Store NEW procedure
+
+```
+mcp__unimatrix__context_store(
+  title: "How to {task description}",
+  content: "{step-by-step content}",
+  topic: "{crate or area — e.g., 'unimatrix-server'}",
+  category: "procedure",
+  tags: ["{domain}", "{consuming-roles}"],
+  agent_id: "{your role name, e.g. uni-architect}"
+)
+```
+
+### Step 2b: UPDATE existing procedure (supersedes old version)
+
+```
+mcp__unimatrix__context_correct(
+  original_id: {old entry ID},
+  content: "{updated step-by-step content}",
+  reason: "Updated: {what changed and why}"
+)
+```
+
+This deprecates the old entry and creates a new one with a supersession chain. Agents querying later will get the latest version.
+
+---
+
+## Content Format
+
+Procedures should be **concise and actionable** (200-500 chars):
+
+```
+How to add a new MCP tool:
+1. Add validate_{tool}_params fn in validation.rs (pure, no I/O)
+2. Add format_{tool}_success fn in response.rs (summary + markdown + json)
+3. Add handler block in tools.rs match arm
+4. Add AuditEvent variant in audit.rs
+5. Add tool schema in server registration
+6. Add integration test in product/test/infra-001/
+```
+
+NOT:
+```
+When you want to add a new MCP tool to the server, you should first consider
+the validation requirements. The validation module in validation.rs contains
+pure functions that validate input parameters...
+```
+
+---
+
+## Tagging Conventions
+
+| Tag type | Examples |
+|----------|----------|
+| Crate/area | `server`, `store`, `vector`, `core`, `embed` |
+| Consuming roles | `rust-dev`, `pseudocode`, `architect` |
+| Domain | `mcp-tool`, `schema`, `testing`, `integration` |
+
+Always include at least one consuming-role tag so `/query-patterns` can filter by who needs it.
+
+---
+
+## When to Store vs When to Skip
+
+**Store when:**
+- A multi-step technique was used across 2+ features
+- An existing procedure was wrong and needed correction
+- A developer had to figure out steps that should have been documented
+
+**Skip when:**
+- The technique was used once and may not recur
+- The steps are obvious to any Rust developer (not project-specific)
+- The procedure is workflow choreography (that stays in coordinator agent defs)

package/skills/uni-git/SKILL.md

@@ -0,0 +1,117 @@
+# uni-git — Git Conventions for Unimatrix
+
+## Branch-First Workflow
+
+All workflows produce PRs. No workflow commits directly to main.
+
+### Branch Naming
+
+| Context | Pattern | Example | Creator |
+|---------|---------|---------|---------|
+| Feature (design + delivery) | `feature/{phase}-{NNN}` | `feature/crt-009` | uni-scrum-master (Session 1 creates, Session 2 continues) |
+| Bug fix | `bugfix/{issue}-{desc}` | `bugfix/52-embed-retry` | uni-scrum-master (bugfix session) |
+| Ad-hoc docs/config | `docs/{short-desc}` | `docs/update-vision` | Human or primary agent |
+| Workflow/process | `workflow/{desc}` | `workflow/base-002` | Human or primary agent |
+
+### Branch Lifecycle
+
+```bash
+# Session 1 (Design): create feature branch, commit artifacts, open DRAFT PR
+git checkout -b feature/{phase}-{NNN}
+git add <files> && git commit -m "design: {description} (#{issue})"
+git push -u origin feature/{phase}-{NNN}
+gh pr create --draft --title "[{feature-id}] {title}" --body "..."
+
+# Session 2 (Implementation): continue on same branch, convert draft to ready
+git checkout feature/{phase}-{NNN}  # if not already on it
+git add <files> && git commit -m "{prefix}: {description} (#{issue})"
+git push -u origin feature/{phase}-{NNN}
+gh pr ready {pr-number}  # convert draft → ready for review
+
+# After merge: branch auto-deletes (repo setting enabled)
+```
+
+## Commit Format
+
+```
+{prefix}: {description} (#{issue})
+```
+
+| Prefix | When |
+|--------|------|
+| `design:` | Design docs (Session 1) |
+| `pseudocode:` | Stage 3a artifacts |
+| `impl({component}):` | Component implementation |
+| `test:` | Test execution |
+| `fix({gate}):` | Gate rework |
+| `fix:` | Bug fix |
+| `docs:` | Standalone documentation changes |
+
+## PR Merge Strategy
+
+**Rebase-only** (`gh pr merge --rebase`). Squash acceptable for single-commit PRs. Merge commits are disabled at repo level.
+
+## PR Template
+
+```bash
+gh pr create \
+  --title "[{feature-id}] {short description}" \
+  --body "$(cat <<'EOF'
+## Summary
+Implements {feature-id} per approved design.
+
+## Source Documents
+- Architecture: product/features/{id}/architecture/ARCHITECTURE.md
+- Specification: product/features/{id}/specification/SPECIFICATION.md
+- Risk Strategy: product/features/{id}/RISK-TEST-STRATEGY.md
+
+## Gate Results
+- Gate 3a (Design Review): PASS
+- Gate 3b (Code Review): PASS
+- Gate 3c (Risk Validation): PASS
+
+## GH Issue
+Closes #{N}
+EOF
+)"
+```
+
+## Worktree Isolation
+
+Coordinators use Claude Code's native `isolation: "worktree"` parameter when spawning worker agents. Claude Code automatically creates worktrees at `.claude/worktrees/agent-{id}/` and cleans up afterward.
+
+**Coordinator responsibilities:**
+- Spawn agents with `isolation: "worktree"` for parallel workstreams
+- Clean up **worker** worktrees after their code is committed to the feature branch (after each gate pass)
+- Do NOT remove the session's own worktree — it must persist until PR merge
+- If removal fails (dirty state): warn human, do NOT force-remove
+
+**Mandatory cleanup after each gate pass:**
+```bash
+# Remove worker worktrees whose code has been committed
+git worktree remove .claude/worktrees/{agent-id}/ 2>/dev/null
+# Prune stale entries
+git worktree prune
+```
+
+Each worktree contains a full `target/` build directory (~1-2GB). Failing to clean up causes disk exhaustion during parallel development.
+
+**Stale worktree recovery:** `git worktree prune` removes entries for deleted directories. Human can `git worktree remove --force` if needed.
+
+## Build Artifact Isolation
+
+| Binary | Location | Used by |
+|--------|----------|---------|
+| Installed | `~/.local/bin/unimatrix-server` | Hooks, MCP server |
+| Build artifact | `target/release/unimatrix-server` | Integration tests |
+
+- `cargo build --release` in a worktree does NOT affect `~/.local/bin/` or other worktrees (each worktree has its own `target/`)
+- To update the installed binary: `cargo install --path crates/unimatrix-server`
+- Integration tests in worktrees: set `UNIMATRIX_BINARY` to the worktree's own `target/release/unimatrix-server`
+
+## Rules
+
+- Never force-push to main
+- Never commit `.env`, credentials, or build artifacts
+- Never skip pre-commit hooks (`--no-verify`)
+- Feature branches auto-delete after merge

package/skills/uni-init/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: "uni-init"
+description: "Initialize Unimatrix in a repository: append knowledge block to CLAUDE.md and produce agent orientation recommendations."
+---
+
+# /uni-init — Repository Initialization
+
+## Prerequisites
+
+Before running this skill:
+
+1. **Skill files installed**: Both `uni-init/SKILL.md` and `uni-seed/SKILL.md` must be present in `.claude/skills/` in the target repository.
+2. **MCP server wired** (for `/uni-seed`): The Unimatrix MCP server (`unimatrix-server`) must be running and configured in your Claude Code `settings.json`. This skill (`/uni-init`) does not require MCP, but `/uni-seed` does.
+
+If you need to install the Unimatrix server or wire MCP, consult the installation documentation.
+
+---
+
+## What This Skill Does
+
+Sets up Unimatrix awareness in a repository by:
+1. Checking if Unimatrix is already initialized (idempotency guard)
+2. Scanning agent definitions for orientation gaps (read-only)
+3. Appending a self-contained Unimatrix knowledge block to CLAUDE.md
+
+---
+
+## Arguments
+
+- **No arguments**: Run the full initialization (sentinel check, agent scan, CLAUDE.md append).
+- **`--dry-run`**: Print what would happen without modifying any files.
+
+---
+
+## Execution Steps
+
+Follow these phases in strict order. Do not skip or reorder.
+
+### Phase 1: Pre-flight — Idempotency Check
+
+**Check for `--dry-run` argument first.** If the user invoked `/uni-init --dry-run`, set dry-run mode. In dry-run mode, no files will be created or modified — only terminal output.
+
+1. Check if `CLAUDE.md` exists in the repository root.
+
+2. **If CLAUDE.md exists**, read the entire file and search for this exact sentinel string:
+   ```
+   <!-- uni-init v1: DO NOT REMOVE THIS LINE -->
+   ```
+
+3. **Head-check fallback for large files**: If `CLAUDE.md` has more than 200 lines, also explicitly read the last 30 lines of the file and check for the sentinel there. This catches cases where the sentinel is at the end of a large file.
+
+4. **If the sentinel is found** (in either check): Print the following and stop immediately. Do not proceed to Phase 2 or Phase 3.
+   ```
+   Already initialized. Unimatrix block found in CLAUDE.md.
+   ```
+
+5. **If CLAUDE.md does not exist**: Note this — CLAUDE.md will be created in Phase 3. Continue to Phase 2.
+
+6. **If CLAUDE.md exists but sentinel is not found**: Continue to Phase 2.
+
+---
+
+### Phase 2: Agent Scan (Read-Only)
+
+This phase produces a terminal-only recommendation report. **Do not write any files. Do not modify any agent files.**
+
+1. Glob for agent definition files: `.claude/agents/**/*.md`
+
+2. **If no agent files are found**: Print the following and continue to Phase 3.
+   ```
+   No agent files found at .claude/agents/. Skipping agent scan.
+   ```
+
+3. **For each agent file found**, read its content and check for the presence of these three patterns:
+
+   - **context_briefing**: Does the file contain `context_briefing`? (This indicates the agent calls the Unimatrix briefing tool at session start.)
+   - **Outcome reporting**: Does the file contain `/uni-record-outcome` or reference `context_store` with `category: "outcome"`? (This indicates the agent records session outcomes.)
+   - **uni-\* skill reference**: Does the file contain any reference to `uni-` prefixed skills (e.g., `/uni-init`, `/uni-seed`)?
+
+4. **Print the Agent Orientation Report** to the terminal:
+
+   ```
+   Agent Orientation Report
+   ========================
+   Agent                          | Missing                          | Suggested Addition
+   -------------------------------|----------------------------------|------------------------------------------
+   ```
+
+   For each agent file, print a row:
+   - **Agent**: the filename (without path prefix)
+   - **Missing**: which of the three patterns are absent
+   - **Suggested Addition**: concrete, skill-level recommendation. Examples:
+     - Missing context_briefing: "Add orientation section: call context_briefing at session start for relevant knowledge"
+     - Missing outcome reporting: "Add session end: invoke /uni-record-outcome to capture what was learned"
+     - Missing uni-* skills: "Reference /uni-init and /uni-seed for onboarding new repos"
+     - All present: "fully wired" / "none"
+
+5. **If all agents have all three patterns**: Print after the table:
+   ```
+   All agents fully wired.
+   ```
+
+---
+
+### Phase 3: CLAUDE.md Append
+
+**If in dry-run mode**: Print the following, then print the full Unimatrix block content below, and stop. Do not create or modify any files.
+```
+DRY RUN -- the following block would be appended to CLAUDE.md:
+```
+Print the block, then:
+```
+No files were modified.
+```
+
+**If NOT in dry-run mode**:
+
+The exact block to append is:
+
+```markdown
+
+<!-- uni-init v1: DO NOT REMOVE THIS LINE -->
+## Unimatrix
+
+Knowledge engine (MCP server). Makes agent expertise searchable, trustworthy, and self-improving.
+
+### Available Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| `/uni-init` | First-time setup: wire CLAUDE.md and get agent recommendations |
+| `/uni-seed` | Populate Unimatrix with foundational repo knowledge |
+
+### Knowledge Categories
+
+| Category | What Goes Here |
+|----------|---------------|
+| `decision` | Architectural decisions (ADRs) — use `/uni-store-adr` |
+| `pattern` | Reusable implementation patterns — use `/uni-store-pattern` |
+| `procedure` | Step-by-step workflows — use `/uni-store-procedure` |
+| `convention` | Project-wide coding/process standards |
+| `lesson-learned` | Post-failure takeaways — use `/uni-store-lesson` |
+
+### When to Invoke
+
+- Before implementing anything new → search knowledge base
+- After each architectural decision → store ADR
+- After each shipped feature → run retrospective
+- When a technique evolves → update procedure
+<!-- end uni-init v1 -->
+```
+
+**If CLAUDE.md exists**: Append the block to the end of the existing file. Use Edit/append semantics — do NOT overwrite the file. Preserve all existing content. Add a blank line before the block if the file does not already end with a blank line.
+
+**If CLAUDE.md does not exist**: Create CLAUDE.md with the block as its only content (without the leading blank line).
+
+After writing, confirm:
+```
+Unimatrix block appended to CLAUDE.md.
+```
+Or if created:
+```
+Created CLAUDE.md with Unimatrix block.
+```
+
+Finally, print:
+```
+Initialization complete. Run /uni-seed next to populate the knowledge base.
+```

package/skills/uni-knowledge-lookup/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: "uni-knowledge-lookup"
+description: "Deterministic lookup of Unimatrix knowledge by exact filters. Use when you know what you want — a specific feature, category, entry ID, or status."
+---
+
+# Knowledge Lookup — Deterministic Query Against Unimatrix
+
+## What This Skill Does
+
+Retrieves Unimatrix entries by exact filters — topic, category, tags, status, or entry ID. Returns all matching entries without semantic ranking. Use when you know precisely what you're looking for.
+
+**Use this when you KNOW what you want** — a specific feature's ADRs, entries with a particular status, or a known entry by ID.
+
+---
+
+## How to Look Up
+
+Call the `mcp__unimatrix__context_lookup` MCP tool:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `topic` | No* | Exact feature ID match (e.g., `"nxs-001"`) |
+| `category` | No* | Exact category match (e.g., `"decision"`) |
+| `tags` | No* | All specified tags must match |
+| `status` | No | `"active"` (default), `"deprecated"`, `"proposed"` |
+| `id` | No* | Specific entry ID (returns exactly one entry) |
+| `limit` | No | Max results (default: 10) |
+| `format` | No | `"summary"` (default), `"markdown"` (full content), `"json"` |
+| `agent_id` | No | Your role name (e.g. `uni-architect`) |
+
+*At least one filter parameter is required (topic, category, tags, or id).
+
+### Examples
+
+**Get all ADRs for a specific feature:**
+```
+mcp__unimatrix__context_lookup(topic: "nxs-002", category: "decision")
+```
+
+**Get a specific entry by ID (full content):**
+```
+mcp__unimatrix__context_lookup(id: 42, format: "markdown")
+```
+
+**Find all deprecated decisions:**
+```
+mcp__unimatrix__context_lookup(category: "decision", status: "deprecated")
+```
+
+**Find entries tagged with a specific domain:**
+```
+mcp__unimatrix__context_lookup(category: "decision", tags: ["adr", "serialization"])
+```
+
+**Get all knowledge for a feature (any category):**
+```
+mcp__unimatrix__context_lookup(topic: "vnc-001")
+```
+
+---
+
+## Single Entry Retrieval
+
+If you already have an entry ID (from a prior search or lookup result), use `context_get` for direct retrieval:
+
+```
+mcp__unimatrix__context_get(id: 42, format: "markdown")
+```
+
+This is faster than a lookup with an ID filter and always returns full content.
+
+---
+
+## When to Use This vs /uni-knowledge-search
+
+| Use `/uni-knowledge-lookup` when | Use `/uni-knowledge-search` when |
+|------------------------------|------------------------------|
+| You know the exact feature/category | Exploring a concept |
+| "Give me all ADRs for nxs-002" | "What do we know about X?" |
+| Retrieving a specific entry by ID | Finding related decisions |
+| Filtering by exact status or tags | Discovering unknown patterns |
+| Checking what exists before storing | Broad exploration |
+
+---
+
+## Common Workflows
+
+**Before writing a new ADR (architect):**
+```
+1. mcp__unimatrix__context_lookup(topic: "{feature-id}", category: "decision")
+   → See what ADRs already exist for this feature
+2. mcp__unimatrix__context_lookup(category: "decision", tags: ["adr", "{domain}"])
+   → See ADRs across features in the same domain
+```
+
+**Before implementing a component (developer):**
+```
+1. mcp__unimatrix__context_lookup(topic: "{feature-id}", category: "decision", format: "markdown")
+   → Read all architectural decisions for this feature
+```
+
+**Checking for deprecated knowledge:**
+```
+mcp__unimatrix__context_lookup(category: "decision", status: "deprecated", topic: "{feature-id}")
+→ See what decisions have been superseded
+```
+
+---
+
+## When You Find Stale or Wrong Knowledge
+
+Lookup may surface entries that are outdated or incorrect. Fix them:
+
+| Situation | Action |
+|-----------|--------|
+| Entry is **wrong** | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` — supersedes with chain link |
+| Entry is **outdated** | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
+| Entry is **suspicious** | `mcp__unimatrix__context_quarantine(id: {id}, reason: "{concern}")` — Admin only |
+
+Every agent shares responsibility for knowledge quality. Don't leave wrong entries for the next agent to trip over.