relay-workflow 2.0.0 → 2.0.2

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

@@ -39,9 +39,7 @@ to run **/relay-brainstorm** first.
         # Feature: [Title]
 
         *Created: [YYYY-MM-DD]*
-        *Brainstorm: [link to brainstorm file — include both paths:
-         Active: .relay/features/[topic]_brainstorm.md
-         Archived: .relay/archive/features/[topic]_brainstorm.md]*
+        *Brainstorm: [[topic]_brainstorm.md]([topic]_brainstorm.md)*
         *Status: DESIGNED*
 
         ## Summary

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

@@ -19,30 +19,51 @@ verdict is not COMPLETE, STOP and tell the user:
 Before creating the notebook, verify the notebook execution dependencies
 are available:
 
-1. Check if `nbclient`, `nbformat`, and `nbconvert` are importable:
+1. Determine the correct Python command for this platform:
+   - If a virtual environment exists (`.venv/`, `venv/`): use its Python
+     directly (e.g., `.venv/Scripts/python` on Windows, `.venv/bin/python`
+     on Linux/macOS)
+   - Otherwise: try `python3` first, fall back to `python`
+   Use whichever works for ALL subsequent Python/pip commands in this skill.
+
+   Check if `nbclient`, `nbformat`, and `nbconvert` are importable:
    ```
-   python3 -c "import nbclient, nbformat, nbconvert"
+   <python> -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__}'"
+   <python> -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`
+   `<python> -m pip install --upgrade ipython ipykernel`
 
-2. If all checks pass, proceed to Part A.
+2. Register the virtual environment as a Jupyter kernel so notebooks
+   can find it (both for programmatic execution and IDE use):
+   ```
+   <python> -m ipykernel install --user --name=<project> --display-name="<project> (.venv)"
+   ```
+   Where `<project>` is the project directory name (basename of the
+   working directory, e.g., `mnemos2`, `my-app`). If no venv exists
+   (system Python), skip this step — the default `python3` kernel works.
+
+   Verify the kernel is registered:
+   ```
+   <python> -m jupyter kernelspec list
+   ```
+
+3. If all checks pass (deps importable + kernel registered), proceed to Part A.
 
-3. If they are NOT available:
+4. If deps 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.
+      `<python> -m pip install nbclient nbformat nbconvert ipython ipykernel`, 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`,
+      notebook dependencies into the system Python? (Or create a
+      venv first with `<python> -m venv .venv`)"
+      If the user approves, run `<python> -m pip install nbclient nbformat nbconvert ipython ipykernel`,
       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
@@ -55,18 +76,36 @@ 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`
 
+Kernel metadata: Set the notebook's `kernelspec` to the kernel registered
+in Part 0 step 2. In the notebook JSON metadata:
+```json
+"kernelspec": {
+  "name": "<project>",
+  "display_name": "<project> (.venv)",
+  "language": "python"
+}
+```
+If no venv was registered (system Python), use `"name": "python3"` instead.
+This ensures both programmatic execution and IDE opening use the correct
+Python environment.
+
 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):
+   - Reference to the item file using **relative paths from the notebook's
+     directory** (NOT project-root paths). Because `.relay/` mirrors its own
+     structure under `.relay/archive/`, the relative path `../issues/` or
+     `../features/` works both before and after archival:
      ```
-     **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))
+     **Item file**: [FILENAME.md](../issues/FILENAME.md) or [FILENAME.md](../features/FILENAME.md)
      ```
+     Explanation: notebooks live in `.relay/notebooks/`, so `../issues/`
+     resolves to `.relay/issues/`. After archival, notebooks are in
+     `.relay/archive/notebooks/`, so `../issues/` resolves to
+     `.relay/archive/issues/`. Same relative path, correct in both locations.
    - Prerequisites (database, env vars, install steps)
 
 2. SETUP CELL:
@@ -157,6 +196,15 @@ For each issue/feature file in the phase:
 
 ## Part B — Run, Validate, and Iterate
 
+**Execution method**: Execute the notebook **in-place** so cell outputs are
+persisted in the source `.ipynb` file. Use one of these approaches:
+- **Preferred**: `<python> -m jupyter nbconvert --to notebook --execute --inplace <notebook>.ipynb`
+- **Alternative**: Use `nbclient` programmatically — load with `nbformat.read()`,
+  execute with `nbclient.NotebookClient(...).execute()`, write back with
+  `nbformat.write()` to the **same file path**.
+- **NEVER** use `--output-dir` pointing to a temp directory — this discards
+  outputs from the source notebook.
+
 After creating the notebook, execute every cell sequentially. For each cell
 that errors or produces a FAIL:
 
@@ -184,8 +232,7 @@ that errors or produces a FAIL:
         - 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)
+        # KNOWN ISSUE: see ../issues/[new_issue_name].md
         ```
       → Continue to the next cell.
 
@@ -255,7 +302,7 @@ When finished, tell the user:
 
 - 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
+- The header cell uses relative paths (`../issues/` or `../features/`) so links work both before archival (from `.relay/notebooks/`) and after (from `.relay/archive/notebooks/`) without any path updates needed
 - 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)

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

@@ -59,9 +59,11 @@ Close it out.
      - [list of files changed, with brief description of each change]
 
      ## Verification
-     - Link to verification notebook (if created), include both paths:
-       - Active: `.relay/notebooks/[file].ipynb`
-       - Archived: `.relay/archive/notebooks/[file].ipynb`
+     - Link to verification notebook (if created) using relative path:
+       `[notebook](../notebooks/[file].ipynb)` (before archival)
+       or `[notebook](../archive/notebooks/[file].ipynb)` (after archival)
+       Since implementation docs never move, use the archived path as the
+       permanent link: `[notebook](../archive/notebooks/[file].ipynb)`
      - Test commands that confirm the change
 
      ## Caveats

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

@@ -29,14 +29,14 @@ Create this file to track the installed Relay version:
 
 | Field | Value |
 |-------|-------|
-| **Version** | 2.0.0 |
+| **Version** | 2.0.2 |
 | **Installed** | [YYYY-MM-DD] |
 | **Source** | https://github.com/momobits/Relay |
 | **Format** | skills |
 
 ## Changelog
 
-### 2.0.0 — Skills-based workflow
+### 2.0.2 — Skills-based workflow
 - Converted 14 prompts to Claude Code skills plus new `/relay-help` navigation skill (15 total)
 - Added `/relay-help` navigation skill
 - Skills are auto-discovered — no more `@file.md` references
@@ -271,14 +271,25 @@ resolved phase). The skills /relay-review, /relay-verify, and
 
 5. **Python environment for verification notebooks**:
    Verification notebooks (/relay-notebook) require Python 3 and
-   the packages `nbclient`, `nbformat`, and `nbconvert` to execute.
-   Set these up now so notebooks work when you reach the code pipeline:
-
-   a. Check if Python 3 is available.
-   b. Check for an existing virtual environment.
-   c. Install notebook dependencies.
-   d. Confirm the install succeeded.
-   e. Ask if the user wants these added to the project's dev dependencies.
+   the packages `nbclient`, `nbformat`, `nbconvert`, `ipython`, and
+   `ipykernel` to execute. Set these up now so notebooks work when
+   you reach the code pipeline:
+
+   a. Determine the correct Python command for this platform:
+      - If a virtual environment exists (`.venv/`, `venv/`): use its
+        Python directly (e.g., `.venv/Scripts/python` on Windows,
+        `.venv/bin/python` on Linux/macOS)
+      - Otherwise: try `python3` first, fall back to `python`
+      Use whichever works for ALL subsequent Python/pip commands.
+   b. Check if Python 3 is available using the resolved command.
+   c. Check for an existing virtual environment.
+   d. Install all notebook dependencies:
+      `<python> -m pip install nbclient nbformat nbconvert ipython ipykernel`
+   e. Register the venv as a Jupyter kernel (skip if no venv):
+      `<python> -m ipykernel install --user --name=<project> --display-name="<project> (.venv)"`
+      Where `<project>` is the project directory name.
+   f. Confirm the install succeeded (import all five packages).
+   g. Ask if the user wants these added to the project's dev dependencies.
 
 ## Navigation
 When setup is complete, tell the user:

package/README.md

@@ -48,7 +48,7 @@ Every AI session reads this documentation before acting. Every session writes ba
 ```bash
 # Install with npx (recommended)
 cd your-project
-npx relay-workflow install
+npx relay-workflow@latest install
 ```
 
 Or install manually:
@@ -130,6 +130,12 @@ All paths converge on the same **code pipeline** for implementation, ensuring ev
 
 ## Skill Reference
 
+### Setup
+
+| Skill | Purpose |
+|-------|---------|
+| **/relay-setup** | Initialize Relay in a new project. Creates `.relay/` directory, status files, and scans the project for customizations. |
+
 ### Prepare — Project status and maintenance
 
 | Skill | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-workflow",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Persistent memory for AI coding workflows — Claude Code skills that give agents memory of what was built, what broke, and what's next",
   "main": "tools/cli.js",
   "bin": {

package/tools/cli.js

@@ -3,7 +3,7 @@
 const fs = require("fs");
 const path = require("path");
 
-const VERSION = "2.0.0";
+const VERSION = "2.0.2";
 const SKILLS_DIR = ".claude/skills";
 
 const RELAY_SKILLS = [