@dug-21/unimatrix 0.5.5

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

@@ -0,0 +1,113 @@
+---
+name: "uni-knowledge-search"
+description: "Semantic search across Unimatrix knowledge. Use when exploring a topic, looking for related decisions, patterns, or conventions."
+---
+
+# Knowledge Search — Semantic Query Against Unimatrix
+
+## What This Skill Does
+
+Searches Unimatrix for knowledge entries using natural language. Returns results ranked by semantic similarity. Use when you need to explore what's known about a concept, find related decisions, or discover relevant patterns.
+
+**Use this when you DON'T know exactly what you're looking for** — you have a concept or question, not a specific entry.
+
+---
+
+## How to Search
+
+Call the `mcp__unimatrix__context_search` MCP tool:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `query` | Yes | Natural language search query |
+| `category` | No | Filter to a specific category |
+| `topic` | No | Filter to a specific feature ID |
+| `tags` | No | Filter by tags (all must match) |
+| `k` | No | Max results (default: 5) |
+| `format` | No | `"summary"` (default), `"markdown"` (full content), `"json"` |
+| `agent_id` | No | Your role name (e.g. `uni-architect`) |
+
+### Examples
+
+**Find ADRs about error handling across all features:**
+```
+mcp__unimatrix__context_search(query: "error handling strategy", category: "decision")
+```
+
+**Find anything related to MCP transport:**
+```
+mcp__unimatrix__context_search(query: "MCP transport stdio protocol")
+```
+
+**Find conventions about testing in a specific feature:**
+```
+mcp__unimatrix__context_search(query: "test patterns integration", topic: "nxs-001")
+```
+
+**Get full content instead of summaries:**
+```
+mcp__unimatrix__context_search(query: "serialization approach", format: "markdown")
+```
+
+---
+
+## Available Categories
+
+| Category | Contains |
+|----------|----------|
+| `decision` | Architectural Decision Records (ADRs) |
+| `convention` | Coding and process conventions |
+| `pattern` | Reusable implementation patterns |
+| `procedure` | Step-by-step processes |
+| `outcome` | Results and outcomes |
+| `lesson-learned` | Retrospectives and process learnings |
+| `reference` | General reference material |
+| `duties` | Role duties for context briefing |
+
+Omit `category` to search across all categories.
+
+---
+
+## Interpreting Results
+
+**Summary format** (default): Returns title, topic, category, tags, and a brief content preview for each match. Use this for scanning and triage.
+
+**Markdown format**: Returns full content for each match. Use this when you need the complete text of matching entries.
+
+**JSON format**: Returns structured data. Use for programmatic processing.
+
+---
+
+## When to Use This vs /uni-knowledge-lookup
+
+| Use `/uni-knowledge-search` when | Use `/uni-knowledge-lookup` when |
+|------------------------------|------------------------------|
+| Exploring a concept | You know the exact feature/category |
+| "What do we know about X?" | "Give me all ADRs for nxs-002" |
+| Finding related decisions | Retrieving a specific entry by ID |
+| Discovering patterns you didn't know existed | Filtering by exact status or tags |
+
+---
+
+## Getting Full Content
+
+Search returns summaries by default. To read the full content of a specific result:
+
+1. Note the entry ID from search results
+2. Call `mcp__unimatrix__context_get(id: {entry_id}, format: "markdown")` for the full text
+
+Or pass `format: "markdown"` directly to search if you want full content for all results.
+
+---
+
+## When You Find Stale or Wrong Knowledge
+
+Search may surface entries that are outdated or incorrect. Don't ignore them — fix the knowledge base:
+
+| Situation | Action |
+|-----------|--------|
+| Entry is **wrong** — contains incorrect information | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` — supersedes with chain link |
+| Entry is **outdated** — no longer relevant | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why it no longer applies}")` |
+| Entry is **suspicious** — may be poisoned or invalid | `mcp__unimatrix__context_quarantine(id: {id}, reason: "{concern}")` — Admin only |
+
+Correcting knowledge is as important as storing it. Every agent shares responsibility for knowledge quality.

package/skills/uni-query-patterns/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: "uni-query-patterns"
+description: "Query Unimatrix for component patterns, procedures, and conventions before designing or implementing. Use BEFORE writing pseudocode or code."
+---
+
+# Query Patterns — Find How Things Are Done Here
+
+## What This Skill Does
+
+Searches Unimatrix for established patterns, procedures, and conventions relevant to the work you're about to do. Returns actionable guidance on how similar work was done before.
+
+**Use BEFORE designing or implementing** — not after.
+
+---
+
+## When to Use
+
+| Situation | Query approach |
+|-----------|---------------|
+| Designing a new MCP tool | Search for component patterns in `unimatrix-server` |
+| Adding a new table to redb | Search for procedures in `unimatrix-store` |
+| Writing integration tests | Search for testing conventions |
+| Implementing any component | Search for patterns in the affected crate |
+
+---
+
+## How to Query
+
+### Step 1: Search by crate/area
+
+```
+mcp__unimatrix__context_search(
+  query: "{what you're building — e.g., 'MCP tool handler'}",
+  category: "pattern",
+  k: 5
+)
+```
+
+### Step 2: Also check conventions for the area
+
+```
+mcp__unimatrix__context_search(
+  query: "{area — e.g., 'server tool pipeline'}",
+  category: "convention",
+  k: 5
+)
+```
+
+### Step 3: Check for procedures (step-by-step techniques)
+
+```
+mcp__unimatrix__context_search(
+  query: "{task — e.g., 'adding a new MCP tool'}",
+  category: "procedure",
+  k: 3
+)
+```
+
+### Step 4: Check for relevant ADRs
+
+```
+mcp__unimatrix__context_lookup(
+  topic: "{feature-id}",
+  category: "decision"
+)
+```
+
+---
+
+## Interpreting Results
+
+**Patterns** tell you the reusable structure. Follow them unless your component has a good reason to deviate. If you deviate, note why in your pseudocode or code comments.
+
+**Procedures** tell you the steps. Follow them in order. If a step is wrong or missing, note it — the retrospective will update the procedure.
+
+**Conventions** tell you the rules. Follow them always. No deviations.
+
+**ADRs** tell you what was decided and why. Respect the decision. If it seems wrong for your case, flag it to the coordinator — don't silently override.
+
+---
+
+## If Nothing Is Found
+
+No results means either:
+1. This is genuinely new work with no prior patterns — proceed with your best design
+2. Patterns exist but aren't stored yet — check the codebase directly for similar code
+
+In either case, your work may establish a NEW pattern that the retrospective will extract.
+
+---
+
+## When You Find Stale or Wrong Knowledge
+
+Query results may include entries that are outdated or incorrect. Fix them before they mislead the next agent:
+
+| Situation | Action |
+|-----------|--------|
+| Pattern/procedure is **wrong** | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` |
+| Pattern/procedure is **outdated** | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
+| Convention no longer applies | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
+
+If you correct or deprecate an entry during your session, mention it in your return to the coordinator so it can be noted in the outcome.
+
+---
+
+## What NOT to Do
+
+- Do NOT store patterns during this query phase — that's the retrospective's job
+- Do NOT ignore results because "my approach is better" — patterns represent accumulated project wisdom
+- Do NOT query for workflow choreography — that's in your coordinator, not Unimatrix

package/skills/uni-record-outcome/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: "uni-record-outcome"
+description: "Record a feature or bugfix outcome in Unimatrix. Use at the end of every session (design, delivery, bugfix, retrospective)."
+---
+
+# Record Outcome — Session Completion Record
+
+## What This Skill Does
+
+Stores a structured outcome record in Unimatrix. Outcomes enable the retrospective pipeline to analyze what shipped, how it went, and detect cross-feature patterns.
+
+**Use at the END of every session** — design, delivery, bugfix, or retrospective.
+
+---
+
+## How to Record
+
+Call `mcp__unimatrix__context_store` with these parameters:
+
+| Parameter | Value |
+|-----------|-------|
+| `category` | `"outcome"` |
+| `topic` | `"{feature-id}"` (e.g., `"col-011"`) |
+| `feature_cycle` | `"{feature-id}"` |
+| `tags` | Structured tags (see below) |
+| `content` | What happened — artifacts, results, key facts |
+| `agent_id` | Your role name (e.g. `uni-architect`) |
+
+### Required Tags
+
+Tags use `key:value` format. Include ALL applicable:
+
+| Tag | Values | Required |
+|-----|--------|----------|
+| `type:{x}` | `feature`, `bugfix`, `incident`, `process`, `session` | Yes |
+| `phase:{x}` | `research`, `design`, `implementation`, `testing`, `validation` | Yes |
+| `result:{x}` | `pass`, `fail`, `rework`, `skip` | Yes |
+| `gate:{x}` | `3a`, `3b`, `3c` | Only for delivery (last gate passed) |
+
+### Examples
+
+**Design session complete:**
+```
+mcp__unimatrix__context_store(
+  category: "outcome",
+  topic: "col-011",
+  feature_cycle: "col-011",
+  tags: ["type:feature", "phase:design", "result:pass"],
+  content: "Session 1 complete. 9 artifacts produced. GH Issue #65.
+    ADR entries: #250, #251. 3 scope risks identified (SR-01 through SR-03)."
+)
+```
+
+**Implementation session complete:**
+```
+mcp__unimatrix__context_store(
+  category: "outcome",
+  topic: "col-011",
+  feature_cycle: "col-011",
+  tags: ["type:feature", "phase:implementation", "result:pass", "gate:3c"],
+  content: "Session 2 complete. All 3 gates passed. PR #70.
+    12 unit tests, 4 integration tests added. No rework needed."
+)
+```
+
+**Bugfix complete:**
+```
+mcp__unimatrix__context_store(
+  category: "outcome",
+  topic: "col-011",
+  feature_cycle: "col-011",
+  tags: ["type:bugfix", "phase:implementation", "result:pass"],
+  content: "Bug fix shipped. Root cause: off-by-one in confidence calculation.
+    PR #72. 2 tests added. No rework."
+)
+```
+
+---
+
+## Content Guidelines
+
+Keep content to 100-300 characters. Include:
+- What shipped (artifact count, PR number)
+- Key metrics (test count, gate results, rework count)
+- Notable facts (ADR IDs, risk count, scope changes)
+
+Do NOT include full artifact lists or file paths — those are in the feature directory.
+
+---
+
+## Self-Verification
+
+After calling `context_store`, verify:
+- Response confirms entry stored (returns entry ID)
+- Tags follow the `key:value` format exactly
+- `feature_cycle` matches the feature ID

package/skills/uni-release/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: "uni-release"
+description: "Version bump, changelog generation, tag, and push to trigger the release pipeline."
+---
+
+# /uni-release — Create a Unimatrix Release
+
+## Inputs
+
+From the invoker:
+- Bump level: `major`, `minor`, or `patch` — OR an explicit semver string (e.g. `0.7.0`).
+
+If no bump level is provided, ask the user before proceeding.
+
+---
+
+## Pre-flight Checks
+
+1. Ensure the worktree is clean (no uncommitted changes):
+   ```bash
+   git status --porcelain
+   ```
+   If output is non-empty, stop with: **"Clean worktree required for release. Commit or stash changes first."**
+
+2. Ensure you are on a branch that can be pushed (typically `main` or a release branch).
+
+---
+
+## Step 1: Read Current Version
+
+Read `[workspace.package] version` from the root `Cargo.toml`:
+
+```bash
+grep -m1 'version' Cargo.toml | head -1
+```
+
+Look inside the `[workspace.package]` section for the `version = "X.Y.Z"` line. Parse the current version string.
+
+---
+
+## Step 2: Compute New Version
+
+- **If bump level** (`major` / `minor` / `patch`):
+  - Parse current version as `MAJOR.MINOR.PATCH`.
+  - `patch` -> `MAJOR.MINOR.(PATCH+1)`
+  - `minor` -> `MAJOR.(MINOR+1).0`
+  - `major` -> `(MAJOR+1).0.0`
+
+- **If explicit version string**:
+  - Validate it matches `X.Y.Z` where X, Y, Z are non-negative integers.
+  - Validate it is strictly greater than the current version.
+  - If invalid, stop with a diagnostic error.
+
+Check that the git tag `v{new_version}` does not already exist:
+```bash
+git tag -l "v{new_version}"
+```
+If it exists, stop with: **"Tag v{new_version} already exists."**
+
+---
+
+## Step 3: Update Root Cargo.toml
+
+Edit the `[workspace.package]` section in the root `Cargo.toml`:
+- Change `version = "{old_version}"` to `version = "{new_version}"`.
+
+All 9 workspace crates use `version.workspace = true` and inherit automatically.
+
+---
+
+## Step 4: Update npm package.json Files
+
+Update these files with the new version:
+
+1. **`packages/unimatrix/package.json`**:
+   - Set `"version"` to `"{new_version}"`.
+   - Set `"optionalDependencies"."@dug-21/unimatrix-linux-x64"` to `"{new_version}"`.
+   - Set `"optionalDependencies"."@dug-21/unimatrix-linux-arm64"` to `"{new_version}"`.
+
+2. **`packages/unimatrix-linux-x64/package.json`**:
+   - Set `"version"` to `"{new_version}"`.
+
+3. **`packages/unimatrix-linux-arm64/package.json`**:
+   - Set `"version"` to `"{new_version}"`.
+
+---
+
+## Step 5: Generate CHANGELOG.md
+
+1. Find the previous release tag:
+   ```bash
+   git describe --tags --abbrev=0 --match "v*" 2>/dev/null
+   ```
+   If no prior tag exists, use the first commit as the range start.
+
+2. Collect conventional commits in the range `{previous_tag}..HEAD`:
+   ```bash
+   git log {previous_tag}..HEAD --format="%H %s"
+   ```
+
+3. Classify each commit:
+   - Starts with `feat:` or `feat(` -> **Features** (strip prefix for display).
+   - Starts with `fix:` or `fix(` -> **Fixes** (strip prefix for display).
+   - Contains `BREAKING CHANGE` in the body OR has `!:` in the subject -> **Breaking Changes**.
+   - All other prefixes (`docs:`, `test:`, `chore:`, etc.) -> skip.
+
+4. Build the new changelog section:
+   ```
+   ## [{new_version}] - {YYYY-MM-DD}
+
+   ### Breaking Changes
+   - {message}
+
+   ### Features
+   - {message}
+
+   ### Fixes
+   - {message}
+   ```
+   Omit any section that has zero entries. Use today's date.
+
+5. If `CHANGELOG.md` does not exist, create it with this header:
+   ```
+   # Changelog
+
+   All notable changes to Unimatrix are documented here.
+   Format based on [Keep a Changelog](https://keepachangelog.com/).
+   ```
+
+6. **Prepend** the new section after the header (before any existing release sections).
+
+---
+
+## Step 6: Verify Build
+
+Run a build check to confirm the version change does not break compilation:
+```bash
+cargo check --workspace
+```
+If this fails, stop with: **"Build check failed after version update. Review changes before releasing."**
+
+---
+
+## Step 7: Create Release Commit
+
+Stage only the release-related files:
+```bash
+git add Cargo.toml packages/unimatrix/package.json packages/unimatrix-linux-x64/package.json packages/unimatrix-linux-arm64/package.json CHANGELOG.md
+```
+
+Commit with the release message:
+```bash
+git commit -m "release: v{new_version}"
+```
+
+---
+
+## Step 8: Create Git Tag
+
+```bash
+git tag "v{new_version}"
+```
+
+---
+
+## Step 9: Push Commit and Tag
+
+```bash
+git push origin HEAD
+git push origin "v{new_version}"
+```
+
+The tag push triggers the release pipeline defined in `.github/workflows/uni-release.yml`.
+
+---
+
+## Step 10: Print Summary
+
+```
+Release v{new_version} complete.
+
+Version: {old_version} -> {new_version}
+
+Files modified:
+  - Cargo.toml (workspace version)
+  - packages/unimatrix/package.json
+  - packages/unimatrix-linux-x64/package.json
+  - packages/unimatrix-linux-arm64/package.json
+  - CHANGELOG.md
+
+Git:
+  - Commit: release: v{new_version}
+  - Tag: v{new_version}
+  - Pushed to origin
+
+CI pipeline: https://github.com/anthropic/unimatrix/actions
+```
+
+---
+
+## Error Reference
+
+| Condition | Action |
+|-----------|--------|
+| No bump level or version provided | Ask the user to specify one |
+| Invalid explicit version (not semver) | Stop with diagnostic |
+| New version <= current version | Stop: "New version must be greater than {current}" |
+| Git tag already exists | Stop: "Tag v{version} already exists" |
+| Uncommitted changes in worktree | Stop: "Clean worktree required for release" |
+| `cargo check` fails | Stop: "Build check failed, review changes" |