relay-workflow 2.0.0

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

@@ -0,0 +1,135 @@
+# Relay: Code — Resolve & Close
+
+**Sequence**: `/relay-analyze` → `/relay-plan` → `/relay-review` → *implement* → `/relay-verify` → `/relay-notebook` → **`/relay-resolve`**
+
+The work on [PHASE/ITEM from relay-ordering.md, e.g. "Phase 1A" or
+individual item "store_communities_n_plus_1"] is complete and verified.
+Close it out.
+
+0. Prerequisite check: Read the target item file(s) and verify
+   resolution readiness:
+   - If the full code pipeline was used: verify the most recent
+     ## Verification Report has verdict COMPLETE. A notebook in
+     .relay/notebooks/ matching this item is supplementary evidence
+     but does NOT substitute for a COMPLETE verification verdict.
+   - If the item was determined stale by /relay-analyze: verify the
+     ## Analysis section documents the staleness finding.
+   - If prerequisites are missing, WARN the user:
+     "This item does not appear fully verified. Run
+     **/relay-verify** (or **/relay-notebook**) first, or
+     confirm you want to resolve it as-is."
+     Wait for the user to confirm before proceeding.
+
+1. Identify all issue/feature files that were resolved in this phase:
+   - Read .relay/relay-ordering.md to find which item files are in the
+     specified phase/item
+   - If only some items in the phase were resolved, resolve only those
+     items. The remaining items stay in .relay/issues/ or .relay/features/
+     for the next ordering cycle. Specify individual items rather than
+     the whole phase (e.g., "store_communities_n_plus_1" instead of
+     "Phase 3B").
+   - For each item file, read it and confirm it was addressed by the
+     implementation:
+     - If a plan and verification exist in the item file (from the code
+       pipeline), cross-reference with the finalized plan and verification.
+     - If no plan/verification sections exist (resolved outside the
+       pipeline), scan the codebase directly to confirm the resolution —
+       identify the files changed and how the item was addressed.
+     - If the item was determined to be stale during /relay-analyze
+       (the bug/gap never existed or was already fixed before this item
+       was worked): do NOT create an implementation doc. Instead,
+       archive the item directly to .relay/archive/issues/ (or
+       .relay/archive/features/) with the banner:
+       > **ARCHIVED** — Closed as stale. [Reason]. No code changes made.
+       Skip steps 2-3 for this item (no implementation doc needed).
+
+2. For each resolved item (skip stale items — they were archived in step 1), create an implementation doc in .relay/implemented/:
+   - Filename: same as the item file (e.g., `delete_entity_not_atomic.md`
+     → implemented doc `delete_entity_not_atomic.md`)
+   - Content:
+
+     ## Summary
+
+     *Resolved: [YYYY-MM-DD]*
+
+     - What was the problem or goal (1-2 sentences)
+     - How it was resolved (approach taken)
+
+     ## Files Modified
+     - [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`
+     - Test commands that confirm the change
+
+     ## Caveats
+     - Any follow-up items, edge cases deferred, or related issues/features affected
+
+   - For feature files: update the feature file's `*Status:*` line from
+     `DESIGNED` to `IMPLEMENTED` before archiving.
+
+3. If a resolved feature was part of a brainstorm, update the brainstorm
+   file BEFORE archiving:
+   - To find the parent brainstorm: check the `*Brainstorm:*` metadata line
+     in the feature file for the relative link to the brainstorm file.
+   - Mark the feature as complete in the Feature Breakdown table.
+   - If ALL features in the brainstorm are now resolved (check the table —
+     all rows marked complete, and no unarchived sibling feature files remain
+     in .relay/features/), set the brainstorm's status to COMPLETE and archive
+     the brainstorm:
+     - Move it from .relay/features/ to .relay/archive/features/
+     - Add banner: `> **ARCHIVED** — All features resolved.`
+
+4. Archive each resolved item and its notebook:
+   - Move item from .relay/issues/[file].md (or .relay/features/[file].md) to
+     .relay/archive/issues/[file].md (or .relay/archive/features/[file].md)
+   - Add banner at the top of the archived file:
+     > **ARCHIVED** — Resolved. See [implementation doc](../../implemented/FILENAME.md)
+   - Note: if this item later regresses, do NOT unarchive it. Instead,
+     run **/relay-new-issue** to file a new issue that references this
+     archived file. The /relay-scan regression detection step surfaces
+     these cases automatically.
+   - If a matching notebook exists in .relay/notebooks/[file].ipynb, move it
+     to .relay/archive/notebooks/[file].ipynb
+
+5. Check if ANY remaining items in .relay/issues/ or .relay/features/ were
+   partially addressed or affected by this change:
+   - If an item was partially addressed, update it to reflect the new state
+   - If an item's proposed approach needs adjustment because of this change,
+     update it
+
+6. Refresh .relay/relay-config.md:
+   Since the project code has changed, check if relay-config.md is still
+   accurate. For each section:
+   - **Edge Cases**: scan the files modified in this phase. If any new
+     optional services, config options, concurrency patterns, or external
+     API call sites were added or changed, update the Edge Cases section.
+   - **Test Commands**: verify the test paths and commands still work.
+     If new test files were added or directories restructured, update.
+   - **Notebook Setup**: if imports, fixture patterns, or async behavior
+     changed, update the relevant subsection.
+   Only update sections where the changes in this phase actually affect
+   them — do not re-scan the entire codebase.
+
+7. Update .relay/relay-ordering.md:
+   For each resolved item, find it in relay-ordering.md and strike it
+   through (wrap in ~~...~~). Add a link to the implementation doc.
+   If all items in a phase are now resolved, mark the phase heading
+   with "— COMPLETE" and add a **Resolved** date line below the heading.
+   Do NOT remove the phase or its items — the history provides context.
+
+Output: Implementation docs in .relay/implemented/, archived items and
+brainstorms
+
+## Navigation
+When finished, tell the user:
+- "This phase is complete. You should commit these changes before continuing. Run **/relay-scan** to update the project status, then **/relay-order** to reprioritize. Then pick the next phase from relay-ordering.md and run **/relay-analyze**. Or run **/relay-discover** to scan for new issues."
+
+## Notes
+
+- This skill uses the same phase/item reference as /relay-analyze, so you can say "Phase 1A" consistently
+- If the phase contained multiple item files, they are all resolved and archived in one pass
+- Step 5 is important: resolving one item often changes the context for others — their proposed approaches may need updating
+- This skill works for both full-pipeline items (with plan/review/verification) and items resolved outside the pipeline — step 1 adapts based on what exists in the item file

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

@@ -0,0 +1,6 @@
+---
+name: relay-review
+description: 'Adversarial review of the implementation plan. Tries to break the plan by finding holes, edge cases, and regressions. Final gate before writing code. Use after relay-plan.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,163 @@
+# Relay: Code — Adversarial Review & Finalize
+
+**Sequence**: `/relay-analyze` → `/relay-plan` → **`/relay-review`** → *implement* → `/relay-verify` → `/relay-notebook` → `/relay-resolve`
+
+Review the implementation plan as an adversary. Your job is to find holes,
+not to confirm it's good.
+
+0. Read the target item file(s) and verify an ## Implementation Plan
+   section exists (from /relay-plan). If no plan exists, STOP and tell
+   the user: "No implementation plan found. Run **/relay-plan** first."
+
+1. For each step in the plan, attempt to break it:
+   - What happens if this step partially fails (e.g., first query succeeds,
+     second throws)?
+   - What if the code being modified has changed since the analysis?
+     Re-read each target file NOW and confirm the plan still applies.
+   - What input would cause this change to produce wrong results?
+   - What concurrent operation could race with this change?
+   - What happens at the boundary: empty input, None, zero, max-length string,
+     unicode, special characters?
+
+2. Test the plan against edge cases specific to this codebase:
+   Read the "## Edge Cases" section of .relay/relay-config.md and apply
+   every scenario listed there to the plan. These are the project-specific
+   conditions that must be considered for every change.
+
+3. Check for regression in the wider project:
+   - Read .relay/issues/, .relay/features/, .relay/implemented/, .relay/archive/issues/,
+     and .relay/archive/features/. Does the plan accidentally re-introduce any
+     previously resolved item?
+   - Does the plan change any behavior that other known items depend on?
+     (e.g., if item X's proposed approach assumes the current behavior of the
+     code this plan modifies)
+   - Run through the test files for affected modules. Would any existing
+     test break? If so, is the breakage correct (test was wrong) or a
+     regression (plan is wrong)?
+
+4. Check completeness:
+   - Does the plan handle ALL the cases described in the issue/feature file?
+   - Are there cases the issue/feature file didn't mention that the plan should cover?
+   - Does every file in the blast radius get addressed?
+   - Is there cleanup needed? (dead code removal, comment updates, etc.)
+
+5. Persist the review by APPENDING it to each relevant issue/feature file in
+   .relay/issues/ or .relay/features/, after the Implementation Plan section. Add:
+
+   ---
+
+   ## Adversarial Review
+
+   *Reviewed: [YYYY-MM-DD]*
+
+   ### Issues Found
+   - [numbered list of problems, each with severity and suggested fix]
+
+   ### Edge Cases to Handle
+   - [cases the plan needs to address]
+
+   ### Regression Risk
+   - [specific regressions identified, with mitigation]
+
+   ### Verdict
+   - APPROVED: plan is ready for implementation
+   - APPROVED WITH CHANGES: plan needs specific modifications (list them)
+   - REJECTED: plan has fundamental problems (explain, suggest alternative)
+
+   If APPROVED WITH CHANGES: update ALL plan sections above to incorporate
+   the modifications — Implementation Plan, Test Changes, Post-Implementation
+   Checks, Risks & Mitigations, and Rollback Plan. Do not append a second
+   plan — replace the existing plan sections with the revised version.
+   This becomes the implementation spec.
+
+## Navigation
+When finished, tell the user the next step based on the verdict:
+
+- If APPROVED:
+  "The plan is approved and ready for implementation.
+   Say **'implement the plan'** to begin coding.
+   After implementation is complete, run **/relay-verify** to verify."
+
+  Before implementing, APPEND the following to the issue/feature file
+  after the Adversarial Review section:
+
+  ---
+
+  ## Implementation Guidelines
+
+  *Date: [YYYY-MM-DD]*
+
+  - Follow the finalized plan step by step, in order
+  - After each step, run its VERIFY command before moving to the next
+  - Commit after each logically complete step or group of related steps
+  - If a step cannot be implemented as planned, APPEND a deviation
+    section to this file before proceeding:
+
+    ## Implementation Deviations
+
+    ### Step [N]: [title]
+    - **Planned**: [what the plan said]
+    - **Actual**: [what was done instead]
+    - **Reason**: [why the deviation was necessary]
+  - Do NOT make changes beyond what the plan specifies
+
+- If APPROVED WITH CHANGES (after updating the plan in-place):
+  Present a summary of the specific changes made to the plan.
+  Ask: "The plan has been updated with the changes above. Does this
+  look right before implementation begins?"
+  Wait for the user to confirm or request further adjustments. Once
+  confirmed, APPEND the Implementation Guidelines below to the
+  issue/feature file, then tell the user:
+  "The plan is confirmed. Say **'implement the plan'** to begin coding.
+   After implementation is complete, run **/relay-verify** to verify."
+
+  ---
+
+  ## Implementation Guidelines
+
+  *Date: [YYYY-MM-DD]*
+
+  - Follow the finalized plan step by step, in order
+  - After each step, run its VERIFY command before moving to the next
+  - Commit after each logically complete step or group of related steps
+  - If a step cannot be implemented as planned, APPEND a deviation
+    section to this file before proceeding:
+
+    ## Implementation Deviations
+
+    ### Step [N]: [title]
+    - **Planned**: [what the plan said]
+    - **Actual**: [what was done instead]
+    - **Reason**: [why the deviation was necessary]
+  - Do NOT make changes beyond what the plan specifies
+
+- If REJECTED:
+  "The plan needs rework. Run **/relay-plan** to revise the plan
+   incorporating the rejection feedback from the Adversarial Review.
+   If this is the second or subsequent rejection, consider whether the
+   approach itself is flawed — run **/relay-analyze** to reconsider
+   the fundamental approach before re-planning."
+
+- If the user disagrees with the verdict:
+  The user may override any verdict. To override, append to the
+  Adversarial Review section:
+  **User override**: [APPROVED/REJECTED] — [reason for override]
+  Then proceed according to the overridden verdict. The override
+  and its reasoning are preserved in the item file for audit.
+
+- If reviewing a multi-item phase with split verdicts (some items
+  APPROVED, some REJECTED):
+  Items with no dependencies on rejected items may proceed to
+  implementation independently. Rejected items return to /relay-plan.
+  If cross-dependencies exist between approved and rejected items,
+  all dependent items must be re-planned together.
+
+## Notes
+
+- This skill intentionally has an adversarial framing — it produces better results than "please review"
+- The "re-read each target file NOW" instruction is critical: it catches drift between planning and review
+- Edge cases in the edge cases section should be specific to this project — update them as the codebase evolves
+- If the verdict is REJECTED, go back to /relay-plan with the feedback. If repeated rejections indicate a fundamental approach problem, escalate to /relay-analyze
+- The plan is only finalized when this skill returns APPROVED, or when the user confirms an APPROVED WITH CHANGES revision
+- When APPROVED WITH CHANGES, the issue/feature file's plan is updated in-place so there is always one source of truth
+- The review is persisted in the issue/feature file so the full lifecycle (problem/requirement → plan → review → verification) lives in one place

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

@@ -0,0 +1,6 @@
+---
+name: relay-scan
+description: 'Scan the project documentation and codebase to generate relay-status.md with current state of all tracked items. Use periodically or after creating/resolving issues and features.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,103 @@
+# Relay: Scan & Status
+
+**Sequence**: **`/relay-scan`** → `/relay-order` → `/relay-analyze` → ...
+
+Scan the project documentation and codebase to produce an updated .relay/relay-status.md:
+
+1. Read every .md file in .relay/issues/ and .relay/features/
+   - Exclude brainstorm files (*_brainstorm.md) entirely — these are
+     exploration files managed by the feature workflow, not actionable
+     work items. Only individual feature files (created by /relay-design
+     with status DESIGNED) are tracked here.
+2. For each file, extract the distinct issues or features described
+3. Identify duplicates — same issue/feature described in multiple files
+   - If duplicated: consolidate into a single file. Turn the duplicate into
+     a redirect: replace its content with a link to the consolidated file
+     (e.g., `> **Merged into**: [consolidated_file.md](consolidated_file.md)`)
+     so /relay-resolve can archive both. Note the merge in relay-status.md.
+4. For each distinct item, scan the codebase to determine current status:
+   - RESOLVED: the code fully addresses the issue or implements the feature
+   - PARTIAL: some aspects addressed, others remain
+   - OUTSTANDING: not yet addressed in code
+   - Include a brief explanation of what evidence you found
+5. Cross-reference with the full docs landscape:
+   - Check .relay/implemented/ for matching implementation docs
+   - Check .relay/archive/issues/ and .relay/archive/features/ for items that
+     were previously resolved — confirm they haven't regressed
+   - If a previously archived item has regressed, flag it prominently
+6. Write .relay/relay-status.md with appropriate columns for each section.
+   Update the `*Last generated:*` date header to today's date (YYYY-MM-DD).
+7. Flag any items in issues/ or features/ that are fully RESOLVED but haven't
+   been moved to implemented/ yet — these need resolution docs created
+   (use the process in /relay-resolve)
+
+8. Detect in-progress work:
+   For every issue file (.relay/issues/*.md) and feature file
+   (.relay/features/*.md), check which pipeline sections have been appended
+   to determine the current workflow stage:
+   - Has ## Analysis but no ## Implementation Plan → stage: /relay-plan
+   - Has ## Implementation Plan but no ## Adversarial Review → stage: /relay-review
+   - Has ## Adversarial Review (APPROVED/APPROVED WITH CHANGES) and
+     ## Implementation Guidelines but no ## Verification Report → stage: implement
+   - Has ## Verification Report (verdict COMPLETE) but no notebook in
+     .relay/notebooks/ → stage: /relay-notebook
+   - Has ## Verification Report (verdict INCOMPLETE or HAS ISSUES) → stage: re-verify
+   - Has ## Adversarial Review with verdict REJECTED → stage: /relay-plan (revision)
+   - If multiple ## Adversarial Review sections exist, use the verdict
+     from the LAST one to determine stage
+   Write these under a "## In-Progress Work" section in relay-status.md:
+
+   | Item | File | Stage Reached | Next Step |
+   |------|------|--------------|-----------|
+   | ...  | ...  | ...          | Run /...  |
+
+   This section helps orient anyone returning to the project mid-pipeline.
+
+9. Detect feature pipeline in-progress work:
+   For every brainstorm file (.relay/features/*_brainstorm.md), check
+   the *Status:* line to determine the current feature stage:
+   - Status: BRAINSTORMING → stage: /relay-brainstorm (incomplete)
+   - Status: READY FOR DESIGN → stage: /relay-design (pending)
+   - Status: DESIGN COMPLETE → stage: /relay-order (features designed, not yet in code pipeline)
+   For every non-brainstorm feature file (.relay/features/*.md, excluding
+   *_brainstorm.md), check if it has a ## Analysis section:
+   - Status: DESIGNED with no ## Analysis → stage: /relay-analyze
+   Write these under the same "## In-Progress Work" section, in a
+   separate table:
+
+   ### Feature Pipeline
+
+   | Item | File | Stage | Next Step |
+   |------|------|-------|-----------|
+   | ...  | ...  | ...   | Run /...  |
+
+10. Staleness detection:
+    For every in-progress item (from steps 8 and 9), compare the most
+    recent date in the item file (*Analyzed:*, *Generated:*, *Reviewed:*,
+    or *Verified:* — whichever is latest) to the current date. If the
+    item has been in-progress for more than 7 days:
+    - Flag it as STALE in the Next Step column:
+      "STALE (last activity [date]) — re-run /relay-analyze to
+      validate before continuing"
+    Items without any dated pipeline section are not flagged (they
+    haven't entered the pipeline yet).
+
+Output: Updated .relay/relay-status.md
+
+## Navigation
+When finished, tell the user the next step based on the outcome:
+- If regressions were flagged in this scan:
+  "Regressions detected — run **/relay-new-issue** to file new issues for them. Then run **/relay-order** to prioritize the work."
+- If items are PARTIAL:
+  "Some items are partially addressed. Update their issue/feature files to document what was already done and narrow the scope to what remains. Then run **/relay-order** to prioritize."
+- Otherwise:
+  "Next: run **/relay-order** to prioritize the work."
+
+## Notes
+
+- relay-status.md is a generated artifact — it should be regenerated, not manually edited
+- Items that are RESOLVED should eventually be closed using /relay-resolve
+- The scan should check actual code, not just documentation claims
+- Brainstorm files (`*_brainstorm.md`) are excluded — they are managed by the feature workflow (/relay-brainstorm → /relay-design → /relay-cleanup) and are not actionable work items
+- If a previously archived item has regressed, flag it prominently — the Navigation section will direct the user to file new issues for regressions via /relay-new-issue
+- Step 8 reads issue and feature files (.relay/issues/*.md and .relay/features/*.md) to detect pipeline stage — it does not scan the codebase

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

@@ -0,0 +1,6 @@
+---
+name: relay-setup
+description: 'Set up the Relay workflow system for a new project. Creates directory structure, status files, and runs project-specific configuration. Use once per project.'
+---
+
+Follow the instructions in ./workflow.md.