relay-workflow 2.0.0

package/.claude/skills/relay-new-issue/workflow.md

@@ -0,0 +1,90 @@
+# Relay: Create Issue
+
+**Sequence**: **`/relay-new-issue`** → `/relay-scan` → `/relay-order` → `/relay-analyze` → `/relay-plan` → `/relay-review` → *implement* → `/relay-verify` → `/relay-notebook` → `/relay-resolve`
+
+## How to invoke
+
+There are two usage patterns:
+
+**In-context** — you're already investigating the codebase and find something:
+```
+/relay-new-issue The batch processor silently drops episodes when the connection pool is exhausted.
+```
+
+**Cross-chat handoff** — you found something in another conversation and want to file it. Paste the relevant context so the AI can investigate from a cold start:
+```
+/relay-new-issue
+
+Context from another session:
+While testing voice ingestion, the extraction pipeline threw a
+KeyError on `coherence_facts` when the LLM returned an empty list
+instead of a dict. The error was in pipeline.py around line 340.
+The episode was silently marked as complete despite the failure.
+
+Create an issue for this.
+```
+
+---
+
+Analyze the following and create a documentation file.
+
+Topic: [DESCRIPTION — what you found, what you want filed]
+
+Context (if from another session):
+[Paste error messages, observations, file paths, or conversation
+ excerpts that describe the finding. If invoking in-context, this
+ section can be omitted.]
+
+1. Investigate the topic in the codebase — read relevant files, understand
+   the current state. If context is provided from another session, use it
+   as a starting point but verify everything against the actual code.
+
+2. Determine if this is an issue (bug, shortcoming, gap) or a feature
+   (new capability, enhancement). If it's a feature, STOP — do not
+   create a file. Skip to the Navigation section and direct the user
+   to /relay-brainstorm.
+
+3. Check the full docs landscape for existing coverage:
+   - .relay/issues/ — is this already tracked?
+   - .relay/features/ — is this already planned?
+   - .relay/implemented/ — was this already addressed?
+   - .relay/archive/issues/ and .relay/archive/features/ — was this
+     previously resolved or attempted?
+   If a matching file exists, update it rather than creating a duplicate.
+   If an archived issue has regressed, create a new issue that references
+   the archive file.
+
+4. Write the analysis to:
+   - .relay/issues/[descriptive_name].md if it's an issue
+   - If step 2 determined this is a feature (new capability, enhancement),
+     do NOT create a file — skip to the Navigation section and direct the
+     user to /relay-brainstorm. All features go through the brainstorm
+     → design pipeline to ensure they get proper *Status: DESIGNED*
+     metadata and are tracked by the prepare skills (/relay-scan and /relay-order).
+
+5. Include:
+   - *Created: [YYYY-MM-DD]*
+   - Title and severity (P0 critical / P1 high / P2 medium / P3 low)
+   - Problem statement: what's wrong or what's needed, and why it matters
+   - Current state: exact file paths, line numbers, code snippets
+   - Impact: what breaks, what's degraded, who's affected
+   - Proposed fix: concrete remediation steps
+   - Affected files: list of files that need changes
+
+Output: New issue doc in .relay/issues/, or redirect to /relay-brainstorm
+
+## Navigation
+When finished, tell the user the next step based on the outcome:
+- If the topic is a feature (no file was created):
+  "This is a feature. Run **/relay-brainstorm** to explore and design it."
+- If an issue file was created:
+  "Next: run **/relay-scan** to update project status, then **/relay-order** to prioritize the work."
+
+## Notes
+
+- Replace `[DESCRIPTION]` with what you want analyzed — be as specific as possible
+- Always check for existing docs first to avoid duplication
+- Use descriptive filenames: `fuzzy_matching_gaps.md` not `issue_42.md`
+- This skill does NOT update relay-status.md or relay-ordering.md — that is the responsibility of /relay-scan and /relay-order
+- For cross-chat handoffs: include enough context that the AI can reproduce the finding without the original conversation
+- All features (small or large) are redirected to /relay-brainstorm — only issues are filed directly by this skill

package/.claude/skills/relay-notebook/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: relay-notebook
+description: 'Create and run a Jupyter verification notebook that exercises the real project API end-to-end. Use after relay-verify confirms implementation is complete.'
+---
+
+Follow the instructions in ./workflow.md.

package/.claude/skills/relay-notebook/workflow.md

@@ -0,0 +1,264 @@
+# Relay: Code — Create & Validate Verification Notebook
+
+**Sequence**: `/relay-analyze` → `/relay-plan` → `/relay-review` → *implement* → `/relay-verify` → **`/relay-notebook`** → `/relay-resolve`
+
+Create a verification notebook for each implemented and verified issue/feature
+file in this phase, then RUN every cell and iterate until all cells pass.
+
+## Prerequisites Check
+
+Before proceeding, read the target item file(s) and verify the **most
+recent** ## Verification Report section has verdict COMPLETE (from
+/relay-verify). Note: there may be multiple Verification Report sections
+if re-verification occurred — check the last one. If missing or the last
+verdict is not COMPLETE, STOP and tell the user:
+"No completed verification found. Run **/relay-verify** first."
+
+## Part 0 — Environment Check
+
+Before creating the notebook, verify the notebook execution dependencies
+are available:
+
+1. Check if `nbclient`, `nbformat`, and `nbconvert` are importable:
+   ```
+   python3 -c "import nbclient, nbformat, nbconvert"
+   ```
+   Also check that IPython 7+ is available (required for top-level
+   `await` directly in notebook cells):
+   ```
+   python3 -c "import IPython; v=tuple(int(x) for x in IPython.__version__.split('.')[:2]); assert v>=(7,0), f'IPython 7+ required for top-level await, found {IPython.__version__}'"
+   ```
+   If the IPython check fails, upgrade before proceeding:
+   `pip install --upgrade ipython ipykernel`
+
+2. If all checks pass, proceed to Part A.
+
+3. If they are NOT available:
+   a. Look for an existing virtual environment (`.venv/`, `venv/`, or
+      check if already running inside one via `sys.prefix != sys.base_prefix`).
+   b. If a venv exists: activate it and run
+      `pip install nbclient nbformat nbconvert`, then proceed to Part A.
+   c. If no venv exists but Python 3 is available: ask the user before
+      installing globally: "No virtual environment found. Install
+      nbclient/nbformat/nbconvert into the system Python? (Or create a
+      venv first with `python3 -m venv .venv`)"
+      If the user approves, run `pip install nbclient nbformat nbconvert`,
+      then proceed to Part A.
+   d. If Python 3 is not available: tell the user
+      "Python 3 is required for verification notebooks. Install Python 3
+      and re-run this step." Do NOT proceed — this is a blocker.
+
+## Part A — Create the Notebook
+
+Location: .relay/notebooks/
+Naming: Use the SAME name as the issue/feature file, but with .ipynb
+extension instead of .md.
+  e.g., `delete_entity_not_atomic.md` → `delete_entity_not_atomic.ipynb`
+
+For each issue/feature file in the phase:
+
+1. HEADER CELL (markdown):
+   - Title: `# [Item Title]: Verification`
+   - Brief description of what was changed and what this notebook tests
+   - Table of what changed (before/after, or list of changes)
+   - Reference to the item file (use repo-root-relative paths so links
+     work both before and after the notebook is archived):
+     ```
+     **Item file**: [.relay/issues/FILENAME.md](.relay/issues/FILENAME.md) or [.relay/features/FILENAME.md](.relay/features/FILENAME.md)
+     (after resolution: [.relay/archive/issues/FILENAME.md](.relay/archive/issues/FILENAME.md) or [.relay/archive/features/FILENAME.md](.relay/archive/features/FILENAME.md))
+     ```
+   - Prerequisites (database, env vars, install steps)
+
+2. SETUP CELL:
+   - Read the "### Imports" section of .relay/relay-config.md and use it
+     as the import block for this cell
+   - Create connection
+   - Create isolated test fixtures (unique user, project, namespace with uuid tag)
+   - Set up pass/fail tracking:
+     ```python
+     passed, failed = [], []
+
+     # Use record() when you already have a boolean condition to check.
+     # Example: record('entity exists', entity is not None)
+     def record(name, condition, detail=''):
+         if condition:
+             passed.append(name)
+             print(f'  PASS: {name}')
+         else:
+             failed.append(name)
+             print(f'  FAIL: {name} -- {detail}')
+
+     # Use run_test() when your test is a callable that might throw
+     # an exception. It catches errors and records them as failures.
+     # Example: await run_test('ingest works', lambda: m.ingest(ns_id, text))
+     async def run_test(name, fn):
+         """Wrapper that catches exceptions and records them as failures."""
+         try:
+             result = fn()
+             if asyncio.iscoroutine(result):
+                 result = await result
+             if isinstance(result, bool):
+                 record(name, result)
+             elif result is None:
+                 record(name, True)  # No return = completed without error
+             else:
+                 record(name, bool(result), f'returned falsy: {result!r}' if not result else '')
+         except Exception as e:
+             record(name, False, str(e))
+     ```
+
+**CRITICAL — Integration, not simulation**: The notebook MUST exercise the
+   project's real code — import the actual modules, connect to real backends,
+   call the public API, and verify observable behavior end-to-end. Do NOT
+   reimplement or simulate the fixed logic locally in the notebook. If a
+   notebook can run without the project's dependencies (database, services,
+   etc.), it is a unit test duplicate, not a verification notebook. Unit tests
+   already cover isolated logic — this step validates the fix works in the
+   integrated system.
+
+3. SEED DATA: Ingest realistic test content that exercises the changed code path.
+   Read the "### Standard Fixtures" section of .relay/relay-config.md for
+   the project's standard test content and domain conventions. Use those
+   unless the specific change requires different data.
+
+4. CORE VERIFICATION (one section per aspect of the change):
+   - Each section has a markdown header explaining what it tests
+   - Each test uses `record()` for pass/fail tracking
+   - Tests should verify BEHAVIOR, not implementation details
+   - Include the specific scenario that was broken/missing before the change
+
+5. EDGE CASES:
+   - Empty input, None values, boundary conditions
+   - The specific edge cases identified during the review (/relay-review)
+
+6. REGRESSION CHECKS:
+   - Verify that related functionality still works after the change
+   - If the change touches extraction: verify search still works
+   - If the change touches storage: verify ingest/search/export still work
+   - If the change touches API: verify public API equivalents still work
+
+7. SUMMARY CELL:
+   ```python
+   print(f'RESULTS: {len(passed)} passed, {len(failed)} failed')
+   if failed:
+       print('\nFailed:')
+       for name in failed:
+           print(f'  FAIL: {name}')
+   else:
+       print('All tests passed!')
+   ```
+
+8. CLEANUP CELL:
+   - Delete any test fixtures created in the SETUP CELL (users, projects,
+     namespaces, test data) to prevent test artifacts from accumulating
+   - Close connections and release resources
+   - Read the "### Cleanup Pattern" section of .relay/relay-config.md and
+     use it as the basis for this cell's teardown code.
+
+## Part B — Run, Validate, and Iterate
+
+After creating the notebook, execute every cell sequentially. For each cell
+that errors or produces a FAIL:
+
+1. DIAGNOSE the failure. Classify it as one of three types:
+
+   a) NOTEBOOK CODE ISSUE — the cell code itself is wrong (typo, wrong API
+      call, incorrect assertion, missing await, etc.)
+      → Fix the cell code directly and re-run. No item file update needed.
+
+   b) PROJECT CODE ISSUE — RELATED to the current change. The implementation
+      is incomplete, has a bug, or introduced a regression in the code path
+      that was just changed.
+      → Append a Post-Implementation Fix to the item file (see below).
+      → Implement the fix in the project code.
+      → Re-run the failing cell.
+
+   c) PROJECT CODE ISSUE — UNRELATED to the current change. A pre-existing
+      bug that the notebook happened to expose.
+      → Flag this to the user. Do NOT fix it inline.
+      → Invoke **/relay-new-issue** to create a new issue file. Provide
+        the notebook context:
+        - Currently working on: [item file being verified]
+        - Notebook: [notebook file]
+        - Failing cell: [cell description]
+        - Error: [the actual error]
+      → In the notebook, mark the cell with a comment:
+        ```python
+        # KNOWN ISSUE: see .relay/issues/[new_issue_name].md
+        # (after resolution: .relay/archive/issues/[new_issue_name].md)
+        ```
+      → Continue to the next cell.
+
+2. For type (b) — RELATED project code issues:
+
+   Append to the item file in .relay/issues/ or .relay/features/ (do NOT replace
+   existing sections — these are additive):
+
+   ---
+
+   ## Post-Implementation Fix #[N]
+
+   *Date: [YYYY-MM-DD]*
+   *Found during: notebook cell [cell description]*
+
+   ### Problem
+   - What failed and what the error/unexpected behavior was
+   - Root cause: what the original implementation missed or got wrong
+
+   ### Plan
+   - Specific code changes to fix this
+   - Files to modify
+
+   ### Rollback
+   - How to revert just this post-implementation fix
+   - Whether reverting this also requires reverting the original change
+
+   After documenting, implement the fix, then re-run the failing cell.
+   If the fix introduces further failures, repeat this process as
+   Post-Implementation Fix #[N+1].
+
+3. Keep iterating until:
+   - All cells pass, OR
+   - All remaining failures are type (c) unrelated issues with
+     `# KNOWN ISSUE` comments
+
+4. Once stable, update the notebook's summary cell output to reflect
+   the final pass/fail state.
+
+Output: Validated notebook(s) in .relay/notebooks/, updated item file(s)
+if post-implementation fixes were needed
+
+## Navigation
+When finished, tell the user:
+- "Next: run **/relay-resolve** to close out and archive."
+
+## Guidelines
+
+- Read the "### Async Pattern" section of .relay/relay-config.md for
+  project-specific async, logging flush, and timing requirements
+- Use `uuid.uuid4().hex[:8]` tags for test isolation
+- Prefer `record()` assertions over bare `assert` — record() shows all
+  results at the end, assert stops at first failure
+- Keep test content short but realistic — enough to trigger the code path
+- Do NOT test implementation details (internal method calls, log messages) —
+  test observable behavior (return values, stored data, search results)
+- Every cell must produce visible output (print statements, record() calls)
+  so the user can review what happened during execution
+- Build high-quality verification cells that thoroughly test the fix/feature
+  in the context of the actual project — not toy examples
+- Log intermediate state (e.g., print entity counts, show query results)
+  so failures are diagnosable from the notebook output alone
+- Run every cell and verify the output before considering the notebook done —
+  a notebook with untested cells is incomplete
+
+## Notes
+
+- Notebooks live in `.relay/notebooks/`, NOT in the project root `notebooks/` directory
+- Notebook filename matches the issue/feature filename (`.md` → `.ipynb`) for traceability
+- The header cell includes both the active and archived path so the link works before and after resolution
+- When /relay-resolve archives the item, it also archives the notebook to `.relay/archive/notebooks/`
+- Every notebook should be self-contained: create its own fixtures, don't depend on other notebooks
+- If a phase has multiple item files, create one notebook per item file (not one giant notebook)
+- Post-Implementation Fixes are numbered sequentially (#1, #2, #3...) and never replace each other — this preserves the full history of what went wrong and how it was addressed
+- If a post-implementation fix is large or complex enough to warrant full analysis, escalate: tell the user to re-run /relay-analyze → /relay-plan → /relay-review for it instead of handling inline
+- For type (c) unrelated issues: /relay-new-issue handles the issue filing — provide the notebook context so it can investigate from a cold start

package/.claude/skills/relay-order/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: relay-order
+description: 'Generate prioritized work ordering in relay-ordering.md. Analyzes dependencies, severity, and complexity to produce phased implementation plan. Use after relay-scan updates status.'
+---
+
+Follow the instructions in ./workflow.md.

package/.claude/skills/relay-order/workflow.md

@@ -0,0 +1,51 @@
+# Relay: Generate Solution Ordering
+
+**Sequence**: `/relay-scan` → **`/relay-order`** → `/relay-analyze` → ...
+
+Generate a solution ordering for all outstanding work:
+
+0. Read the "*Last generated:*" date in .relay/relay-status.md. If it
+   is more than 1 day old, WARN the user: "relay-status.md was generated
+   on [date] — consider running **/relay-scan** first to refresh before
+   ordering." Wait for the user to confirm before proceeding.
+
+1. Read .relay/relay-status.md for current item status
+2. Read the full content of every OUTSTANDING and PARTIAL item
+   (files in .relay/issues/ and .relay/features/)
+   - Exclude brainstorm files (*_brainstorm.md) — these are managed by
+     the feature workflow, not actionable work items. Only individual
+     feature files (created by /relay-design) are ordered here.
+3. Check for intra-feature dependencies:
+   - Read the Development Order and Dependencies sections in individual
+     feature files — these record which features depend on others and
+     link back to their brainstorm for context
+   - Respect these intra-feature orderings: keep related features grouped
+     and sequenced as specified unless a cross-cutting dependency overrides
+4. Analyze cross-item dependencies (does resolving X require Y first?)
+5. Consider: severity/priority, complexity, blast radius, quick wins
+6. Update the `*Last generated:*` date header to today's date (YYYY-MM-DD).
+   Produce an ordered implementation plan in .relay/relay-ordering.md with:
+   - Phases (groups of items that can be done together)
+   - For each item: ID, title, file link, estimated complexity, dependencies
+   - Rationale for the ordering
+   - If a phase contains related features (sharing the same brainstorm
+     link), note their intended build order from the feature files
+7. Keep RESOLVED items in the phases where they were originally placed,
+   struck through with a link to their implementation doc. This preserves
+   phase history and context. Only create new ordering entries for
+   OUTSTANDING and PARTIAL items. Fully completed phases should be marked
+   with "— COMPLETE" in their heading.
+
+Output: Updated .relay/relay-ordering.md
+
+## Navigation
+When finished, tell the user:
+- "Next: run **/relay-analyze** and specify which phase/item to work on from relay-ordering.md."
+
+## Notes
+
+- relay-ordering.md is a generated artifact — regenerate it when the backlog changes
+- The ordering should consider both issues (bugs/gaps) and features (new capabilities)
+- Dependencies matter: e.g., a feature may require an issue to be resolved first
+- Feature files from /relay-design carry explicit Development Order metadata — use it
+- Brainstorm files are excluded — feature files carry their own Development Order and Dependencies metadata from /relay-design

package/.claude/skills/relay-plan/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: relay-plan
+description: 'Create a detailed, step-by-step implementation plan with risk mitigation. Use after relay-analyze has validated the item and mapped the blast radius.'
+---
+
+Follow the instructions in ./workflow.md.

package/.claude/skills/relay-plan/workflow.md

@@ -0,0 +1,133 @@
+# Relay: Code — Implementation Plan
+
+**Sequence**: `/relay-analyze` → **`/relay-plan`** → `/relay-review` → *implement* → `/relay-verify` → `/relay-notebook` → `/relay-resolve`
+
+Based on the analysis, create a detailed implementation plan.
+
+0. Read the target item file(s) and verify an ## Analysis section exists
+   (from /relay-analyze). If no analysis exists, STOP and tell the user:
+   "No analysis found in the item file. Run **/relay-analyze** first."
+
+   Freshness check: read the *Analyzed:* date in the Analysis section.
+   If the analysis is more than 7 days old, WARN the user:
+   "Analysis was done on [date] — the codebase may have changed since then.
+   Consider re-running **/relay-analyze** to revalidate before planning."
+   Wait for the user to confirm before proceeding.
+
+If an Adversarial Review section exists in the issue/feature file with
+verdict REJECTED (from a previous /relay-review), read it first and
+incorporate the rejection feedback into this revised plan. Address every
+issue raised in the review.
+
+All dates in this workflow use YYYY-MM-DD format.
+
+Requirements for the plan:
+
+1. Break the change into atomic, independently-verifiable steps. Each step should:
+   - Change as few files as possible (ideally one)
+   - Be testable in isolation (you could run tests after just this step)
+   - Not leave the codebase in a broken state if you stop here
+   Order steps so that each builds on the last without breaking what came before.
+
+2. For each step, specify:
+   - WHAT: exact file, function, and line range to change
+   - HOW: the specific code change (pseudocode or actual code)
+   - WHY: what this step accomplishes and how it connects to the root cause / requirement
+   - RISK: what could go wrong, what regression could this introduce
+   - VERIFY: how to confirm this step worked (test command, manual check, etc.)
+   - ROLLBACK: if this step causes problems, how to revert safely
+
+3. Cross-check every step against the blast radius from the analysis:
+   - For each caller/consumer identified: does this step change their behavior?
+   - If yes: is the behavior change correct? Do their tests still pass?
+   - For each related item: does this step interact with it?
+
+4. Identify test changes needed:
+   - Existing tests that need updating (mock changes, new assertions, etc.)
+   - New tests that should be added to cover the change
+   - Integration/regression tests to run after all steps complete
+
+5. Consider the full breadth of this change:
+   - Does this change any public API behavior?
+   - Does it change any stored data format?
+   - Does it affect performance characteristics?
+   - Does it interact with configuration options?
+   - Could it affect existing deployments during upgrade?
+
+6. Stress-test every assumption:
+   - Re-read each affected function body. Don't rely on memory or the
+     issue/feature description — verify the actual code matches your mental model.
+   - For each "this is safe because X" claim, verify X is actually true.
+   - For each "callers do Y", grep to confirm all callers actually do Y.
+   - Run multiple passes over the plan: does step 3 invalidate step 1?
+     Does the final state match what you intended?
+
+7. Persist the plan in each relevant issue/feature file in .relay/issues/ or
+   .relay/features/. If an Implementation Plan section already exists (from a
+   previous rejected plan), REPLACE it with the revised plan — do not append
+   a second copy. If no plan exists yet, APPEND after the Analysis section.
+   Add a horizontal rule separator, then these sections:
+
+   ---
+
+   ## Implementation Plan
+
+   *Generated: [YYYY-MM-DD]*
+
+   ### Step 1: [title]
+   **File**: path/to/file.py
+   **Change**: [description]
+   **Code**: [specific change]
+   **Why**: [what this step accomplishes and how it connects to the root cause]
+   **Risk**: [what could break]
+   **Verify**: [how to check]
+   **Rollback**: [how to revert]
+
+   ### Step 2: [title]
+   ...
+
+   ## Test Changes
+   - [list of test file changes]
+
+   ## Post-Implementation Checks
+   - [ordered list of verification commands]
+
+   ## Risks & Mitigations
+   - [consolidated risk register]
+
+   ## Rollback Plan
+   - If the change is purely code (no DB migrations, no config changes,
+     no stored data format changes), the rollback plan is a single line:
+     `git revert <actual-commit-hash>` — fill in the real commit hash
+     after implementation, not a placeholder.
+   - If the change involves DB migrations, config changes, or stored
+     data format changes: include ordered revert steps for each
+     (migration reversal commands, config restoration, data cleanup).
+
+   If the phase spans multiple item files, append the relevant steps to
+   each file (each item file gets only the steps that apply to it, plus
+   the shared rollback plan). Each file must cross-reference the other
+   item files in the phase with links and a note about execution order
+   (e.g., "This plan depends on steps in [other_item.md](../issues/other_item.md)
+   being completed first").
+
+   If the plan spans multiple item files and was REJECTED, the Adversarial
+   Review will be in each affected file. Read the review from ALL affected
+   files and coordinate the revised plan across them — ensure cross-file
+   dependencies are addressed together.
+
+Output: Updated issue/feature file(s) in .relay/issues/ or .relay/features/ with plan persisted
+
+## Navigation
+When finished, tell the user:
+- "Next: run **/relay-review** for adversarial review of the plan."
+
+## Notes
+
+- The plan is persisted in the issue/feature file so it survives across conversations and is archived with the item when resolved
+- The step-by-step decomposition is key: it allows incremental implementation with verification at each stage
+- "Stress-test every assumption" means re-reading the actual code, not relying on the issue/feature description
+- The plan should be detailed enough that someone unfamiliar with the codebase could execute it
+- If the analysis revealed related items that should be addressed together, the plan should include steps for all of them
+- On a revision cycle (after REJECTED), the plan replaces the previous version in-place — never two Implementation Plan sections in one file
+- If the plan is later revised (e.g., after /relay-review returns APPROVED WITH CHANGES), update the plan in the issue/feature file — don't append a second copy

package/.claude/skills/relay-resolve/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: relay-resolve
+description: 'Close out and archive completed work. Creates implementation docs, archives resolved items, and updates ordering. Use after relay-notebook or relay-verify.'
+---
+
+Follow the instructions in ./workflow.md.