relay-workflow 2.0.0

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

@@ -0,0 +1,296 @@
+# Relay: Setup Workflow
+
+Set up the Relay workflow system for this project.
+
+## Phase 1 — Create structure and files
+
+Create the following directory structure:
+  .relay/
+  .relay/issues/
+  .relay/features/
+  .relay/implemented/
+  .relay/notebooks/
+  .relay/archive/
+  .relay/archive/issues/
+  .relay/archive/features/
+  .relay/archive/notebooks/
+
+### Version file
+
+**File: .relay/version.md**
+
+Create this file to track the installed Relay version:
+
+# Relay Version
+
+*Do not edit manually — this file is created by /relay-setup and updated by the installer.*
+
+## Installed
+
+| Field | Value |
+|-------|-------|
+| **Version** | 2.0.0 |
+| **Installed** | [YYYY-MM-DD] |
+| **Source** | https://github.com/momobits/Relay |
+| **Format** | skills |
+
+## Changelog
+
+### 2.0.0 — 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
+- `.relay/` is now data-only (issues, features, status, config, archives)
+
+### 1.0.0 — Prompt-based workflow
+- Initial release with 14 prompt files in `.relay/prompts/`
+- Workflow driven by `@.relay/prompts/*.md` file references
+
+## Skills Manifest
+
+| Skill | File | Purpose |
+|-------|------|---------|
+| /relay-setup | .claude/skills/relay-setup/ | Initialize Relay in a project |
+| /relay-scan | .claude/skills/relay-scan/ | Generate relay-status.md |
+| /relay-order | .claude/skills/relay-order/ | Prioritize work ordering |
+| /relay-discover | .claude/skills/relay-discover/ | Scan codebase for issues |
+| /relay-new-issue | .claude/skills/relay-new-issue/ | File a specific bug or gap |
+| /relay-brainstorm | .claude/skills/relay-brainstorm/ | Explore feature ideas |
+| /relay-design | .claude/skills/relay-design/ | Design features from brainstorm |
+| /relay-cleanup | .claude/skills/relay-cleanup/ | Archive stale brainstorms |
+| /relay-analyze | .claude/skills/relay-analyze/ | Validate before implementation |
+| /relay-plan | .claude/skills/relay-plan/ | Create implementation plan |
+| /relay-review | .claude/skills/relay-review/ | Adversarial review of plan |
+| /relay-verify | .claude/skills/relay-verify/ | Verify implementation |
+| /relay-notebook | .claude/skills/relay-notebook/ | Verification notebook |
+| /relay-resolve | .claude/skills/relay-resolve/ | Close out and archive |
+| /relay-help | .claude/skills/relay-help/ | Navigation guidance |
+
+### Status files
+
+Create these initial status files:
+
+**File: .relay/relay-status.md**
+
+# Project Status
+
+*Last generated: [YYYY-MM-DD]*
+
+> This file is generated by running /relay-scan. Do not edit manually.
+
+---
+
+## Summary
+
+| Category | Outstanding | Resolved | Total |
+|----------|-------------|----------|-------|
+| Issues (issues/) | 0 | 0 | 0 |
+| Features (features/) | 0 | 0 | 0 |
+| Implemented (implemented/) | — | 0 | 0 |
+
+---
+
+## Active Issues — .relay/issues/
+
+No active issues. Run /relay-discover to scan the codebase.
+
+---
+
+## Active Features — .relay/features/
+
+No active features.
+
+---
+
+## Implemented — .relay/implemented/
+
+None yet.
+
+**File: .relay/relay-ordering.md**
+
+# Relay Ordering
+
+*Last generated: [YYYY-MM-DD]*
+
+> This file is generated by /relay-order and updated by /relay-resolve. Regenerated from scratch when /relay-order runs.
+
+---
+
+No outstanding items. Run the discovery skills first to populate .relay/issues/ and .relay/features/.
+
+**File: .relay/relay-config.md**
+
+Create this file with the template structure below. Content will be
+populated in Phase 2.
+
+# Relay Config
+
+*Created: [YYYY-MM-DD] by /relay-setup. Update manually as the project evolves.*
+
+> Project-specific settings used by the relay workflow at runtime.
+> Read by: /relay-review (edge cases), /relay-verify (test commands),
+> /relay-notebook (notebook setup).
+
+---
+
+## Edge Cases
+
+*Used by: /relay-review step 2 — apply every scenario below to the plan*
+
+### Optional Services / Feature Flags
+<!-- Populated by Phase 2 scan -->
+
+### Config Boundaries
+<!-- Populated by Phase 2 scan -->
+
+### Concurrency
+<!-- Populated by Phase 2 scan -->
+
+### LLM / External API Failures
+<!-- Populated by Phase 2 scan -->
+
+### Data Boundaries
+<!-- Populated by Phase 2 scan -->
+
+---
+
+## Test Commands
+
+*Used by: /relay-verify step 4 — select commands based on what was changed*
+
+### When to use each
+<!-- Populated by Phase 2 scan -->
+
+---
+
+## Notebook Setup
+
+*Used by: /relay-notebook — use these patterns verbatim when creating notebooks*
+
+### Imports
+<!-- Populated by Phase 2 scan -->
+
+### Standard Fixtures
+<!-- Populated by Phase 2 scan -->
+
+### Cleanup Pattern
+<!-- Populated by Phase 2 scan -->
+
+### Async Pattern
+<!-- Populated by Phase 2 scan -->
+
+---
+
+## Scoping Paths
+
+*Used by: /relay-discover — scope patterns for this project*
+
+<!-- Populated by Phase 2 scan -->
+
+### Relay readme
+
+Fetch the latest Relay readme from the canonical source and write it to
+`.relay/relay-readme.md`:
+
+```
+curl -sL https://raw.githubusercontent.com/momobits/Relay/main/README.md \
+  -o .relay/relay-readme.md
+```
+
+If the fetch fails (no internet, URL changed, etc.), tell the user:
+"Could not fetch relay-readme.md from GitHub. Download it manually from
+https://github.com/momobits/Relay and save it as .relay/relay-readme.md."
+
+## Phase 2 — Project scan and customization
+
+After creating all files, scan the project codebase to populate
+.relay/relay-config.md with project-specific configuration. For each
+section below, scan the codebase first, then ask the user to confirm or
+adjust before writing. If the user is unsure about any section, use the
+scan results as the default.
+
+relay-config.md is the single source of truth for project-specific
+workflow settings. It is populated once at setup and maintained manually
+as the project evolves (/relay-resolve also refreshes it after each
+resolved phase). The skills /relay-review, /relay-verify, and
+/relay-notebook read from it at runtime.
+
+1. **Edge cases → relay-config.md "## Edge Cases" section**:
+   Do a deep scan of the project for: optional integrations (feature-flagged
+   or conditionally-imported services), external service dependencies, config
+   options that change behavior, caching layers, database backends, async
+   concurrency patterns, and LLM/external API call sites.
+
+   For each edge case, produce a specific, actionable entry — not just "What
+   if X is disabled?" but the full scenario including: what code path it hits,
+   what the guard condition looks like (cite the file and pattern), and what
+   failure mode to verify the plan handles. Group entries by category.
+
+   Present the full list to the user for confirmation, then write it to the
+   Edge Cases section of .relay/relay-config.md.
+
+2. **Regression check commands → relay-config.md "## Test Commands" section**:
+   Scan the project for test frameworks, test directory structure, module
+   layout, and any special env vars or fixtures required to run tests.
+
+   Produce a complete, runnable command reference — not placeholders. Include:
+   - The exact command to run all unit tests
+   - The exact command to run all integration tests
+   - Targeted variants using actual directory/module paths discovered (not
+     `[relevant_test_files]` — use real paths like `tests/unit/test_storage/`)
+   - Import-check commands for each top-level module
+   - Any environment variables or setup steps required before running tests
+   - Which command set to use under which conditions (e.g., "run integration
+     tests when the change touches storage or API layers")
+
+   Present the commands to the user for confirmation, then write to the
+   Test Commands section of .relay/relay-config.md.
+
+3. **Notebook patterns → relay-config.md "## Notebook Setup" section**:
+   Do a deep scan of the project's public API, connection/teardown patterns,
+   async frameworks, test fixture conventions, and test data used in existing
+   tests. Produce complete, copy-paste-ready code for each subsection:
+
+   **Imports**: The full import block a notebook needs.
+   **Standard Fixtures**: Complete working code for isolated test fixtures.
+   **Cleanup Pattern**: Complete teardown code in the correct order.
+   **Async Pattern**: Document the exact async behavior for notebooks.
+
+   Present to the user for confirmation, then write to the Notebook Setup
+   section of .relay/relay-config.md.
+
+4. **Scoping examples for /relay-discover**:
+   Scan the project for its main module/package structure. Add a
+   "## Scoping Paths" section to .relay/relay-config.md listing the
+   discovered module paths the user can use when running /relay-discover.
+   Example format:
+   - Full scan: `/relay-discover`
+   - Module scope: `/relay-discover Focus on src/storage/ and src/api/`
+   - Concern scope: `/relay-discover Focus on security issues only`
+   Present to the user for confirmation, then write to relay-config.md.
+
+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.
+
+## Navigation
+When setup is complete, tell the user:
+- "Setup complete. Next steps:
+   1. Run **/relay-discover** to scan the codebase for issues
+   2. Run **/relay-scan** to generate relay-status.md
+   3. Run **/relay-order** to prioritize the work
+   4. Run **/relay-analyze** to start working on the highest-priority item
+   Or run **/relay-brainstorm** to explore a new feature idea."
+
+## Notes
+
+- Status files (relay-status.md, relay-ordering.md) are generated artifacts — they get real content after running the prepare skills
+- relay-config.md is populated during Phase 2 and maintained manually + refreshed by /relay-resolve after each resolved phase
+- The Relay skills (/relay-discover, /relay-scan, /relay-order, /relay-analyze, etc.) must be present in .claude/skills/ for the workflow to function

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

@@ -0,0 +1,6 @@
+---
+name: relay-verify
+description: 'Verify implementation against the finalized plan. Checks diffs, completeness, correctness, and runs regression tests. Use after code changes are implemented.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,100 @@
+# Relay: Code — Verify Implementation
+
+**Sequence**: `/relay-analyze` → `/relay-plan` → `/relay-review` → *implement* → **`/relay-verify`** → `/relay-notebook` → `/relay-resolve`
+
+The implementation is complete. Verify it against the finalized plan.
+
+0. Read the target item file(s) and verify an ## Adversarial Review section
+   exists with verdict APPROVED or APPROVED WITH CHANGES (from /relay-review).
+   If no approved review exists, STOP and tell the user:
+   "No approved review found. Run **/relay-review** first."
+
+1. Diff check — for each step in the plan:
+   - Read the modified file and confirm the change matches the plan
+   - If the implementation deviated from the plan, is the deviation justified?
+     Check the ## Implementation Deviations section (if present) —
+     deviations documented there with a reason are justified. Also check
+     Verification Fixes from a previous verification pass.
+   - If the implementation deviated but NO ## Implementation Deviations
+     section exists, flag the deviation as undocumented in the
+     Verification Report's Issues Found section.
+   - Check that no unplanned changes were introduced (scope creep, drive-by
+     refactors, unnecessary additions)
+
+2. Completeness check:
+   - Were ALL steps in the plan implemented? List any that were skipped.
+   - Were ALL test changes made? Run the affected tests and report results.
+   - Were ALL files in the blast radius addressed?
+   - Are there TODO comments or placeholder code left behind?
+
+3. Correctness check — re-read each modified function in full:
+   - Does the logic flow correctly end-to-end?
+   - Are error paths handled?
+   - Are edge cases from the review (/relay-review) covered?
+   - Is the code consistent with surrounding patterns and style?
+   - Are there any off-by-one errors, incorrect variable names, or
+     copy-paste mistakes?
+
+4. Regression check:
+   Read the "## Test Commands" section of .relay/relay-config.md and run
+   the commands listed there for the affected modules. Select the
+   appropriate commands based on what the change touches (unit, integration,
+   import check, etc.).
+
+5. Persist the verification by APPENDING it to each relevant issue/feature
+   file in .relay/issues/ or .relay/features/, after the Implementation
+   Guidelines section (or after the Adversarial Review section if no
+   Implementation Guidelines exist). Add:
+
+   ---
+
+   ## Verification Report
+
+   *Verified: [YYYY-MM-DD]*
+
+   ### Implementation Status
+   | Step | Planned | Implemented | Correct |
+   |------|---------|-------------|---------|
+   | 1    | ...     | YES/NO      | YES/NO  |
+   | 2    | ...     | YES/NO      | YES/NO  |
+
+   ### Test Results
+   - [test output summary]
+
+   ### Issues Found
+   - [any discrepancies, bugs, or gaps discovered during verification]
+
+   ### Verification Fixes
+   [If INCOMPLETE or HAS ISSUES: for each issue found, document:]
+   - **Problem**: what was wrong
+   - **Fix**: what was changed to resolve it
+   - **Files modified**: additional files changed beyond the original plan
+   - **Risk**: any new regression risk from the fix
+   - **Rollback**: how to revert this specific verification fix
+
+   ### Verdict
+   - COMPLETE: all changes verified, tests pass, no issues
+   - INCOMPLETE: [list what's missing]
+   - HAS ISSUES: [list problems that need fixing]
+
+   If INCOMPLETE or HAS ISSUES, fix the problems, update the Verification
+   Fixes section above with what was done, then re-run this verification.
+   On re-verification, APPEND a new Verification Report section (do not
+   replace the previous one — the history of verification passes is
+   valuable). The issue/feature file should always reflect the final state.
+
+## Navigation
+When finished, tell the user the next step based on the verdict:
+- If COMPLETE:
+  "Next: run **/relay-notebook** to create and run the verification notebook." (The user may choose to skip to **/relay-resolve** — do not skip on their behalf.)
+- If INCOMPLETE or HAS ISSUES:
+  "Issues were found and fixed. Say **'re-verify'** to re-run verification, or run **/relay-verify** again."
+
+## Notes
+
+- This is not a rubber stamp — it should actively look for mistakes in the implementation
+- "Read the modified function in full" means the whole function, not just the diff
+- Running actual tests is required, not optional
+- If issues are found, fix them and run this skill again — don't skip to the notebook
+- The verification report is persisted in the issue/feature file so the full lifecycle lives in one place
+- If verification finds issues that require additional code changes, those changes get their own mini plan/rollback in the Verification Fixes section — this ensures nothing is done without a revert path

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Momo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.