relay-workflow 2.0.0

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

@@ -0,0 +1,6 @@
+---
+name: relay-analyze
+description: 'Analyze and validate an item before implementation. Checks if the problem still exists, identifies root cause, and maps blast radius. Use as the first step when starting work on an item from relay-ordering.md.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,108 @@
+# Relay: Code — Analyze & Validate
+
+**Sequence**: **`/relay-analyze`** → `/relay-plan` → `/relay-review` → *implement* → `/relay-verify` → `/relay-notebook` → `/relay-resolve`
+
+I want to work on [PHASE/ITEM from relay-ordering.md, e.g. "Phase 1A"].
+
+Before writing any code, analyze and validate:
+
+1. Read .relay/relay-ordering.md to understand the target item(s) and their
+   context within the broader work sequence
+2. Read the full project landscape — current, archived, and implemented:
+   a. Read EVERY file in .relay/issues/ and .relay/features/ — not just the
+      target. You need the full picture of known problems and planned work
+      so your changes don't conflict with or ignore related items.
+   b. Read .relay/archive/issues/ and .relay/archive/features/ to understand
+      what was previously resolved and how. This prevents re-introducing
+      old bugs or duplicating past work.
+   c. Read .relay/implemented/ to understand the approaches taken for past
+      work — patterns, trade-offs, and caveats documented there may directly
+      affect your current work.
+   Summarize the relevant connections across all directories.
+3. Read the actual source files cited in the target item(s). The codebase may
+   have changed since the item was written. Verify:
+   - Does the bug/gap/requirement still exist at the cited line numbers?
+   - Has the code been refactored, moved, or partially addressed?
+   - Are the proposed implementation steps still valid?
+   If the item is stale, say so and recommend archiving or updating.
+   If the item is PARTIAL (some aspects already addressed outside the
+   pipeline): document what was already done, narrow the scope to what
+   remains, and proceed with analysis of the remaining work only.
+4. Root cause / requirements analysis — ask: are we addressing a symptom or
+   the real problem?
+   - Trace the problem upstream: what creates the bad state? (For features:
+     what creates the need?)
+   - Trace it downstream: what consumes the output? How will it change?
+   - Is there a deeper architectural issue that would make this change fragile?
+   - Are any OTHER items in .relay/issues/ or .relay/features/ caused by the
+     same root cause or motivated by the same need?
+     If so, should they be addressed together?
+   - Was this root cause previously addressed (check .relay/archive/issues/,
+     .relay/archive/features/, and .relay/implemented/)? If so, did the previous
+     work regress, or is this a different manifestation of the same
+     underlying problem?
+5. Blast radius mapping — for every proposed change, identify:
+   - Direct callers (who calls this function/method?)
+   - Indirect consumers (who uses the output downstream?)
+   - Test coverage (which tests exercise this path? which don't?)
+   - Config surface (does this change interact with any config options?)
+   - Related items (does this change affect any other known issue or feature,
+     positively or negatively?)
+   - Past work at risk (does this change touch code that was modified by a
+     previous change in .relay/implemented/? Could it undo or destabilize
+     that work?)
+6. Produce a structured analysis covering: validation, root cause,
+   blast radius, and approach. See step 7 for the exact format to persist.
+
+Do NOT write code yet. Do NOT create a plan yet. Just analyze.
+
+7. Persist the analysis by APPENDING it to each relevant issue/feature file in
+   .relay/issues/ or .relay/features/. Add a horizontal rule separator, then
+   append the structured analysis:
+
+   ---
+
+   ## Analysis
+
+   *Analyzed: [YYYY-MM-DD]*
+
+   ### Validation
+   - Problem/requirement still exists: YES/NO (with current line numbers if shifted)
+   - Proposed approach still valid: YES/NO/NEEDS ADJUSTMENT
+
+   ### Root Cause
+   - What creates the bad state / what drives the requirement
+   - Whether this is a symptom of something deeper
+   - Related issues/features that share the same root cause or motivation
+
+   ### Blast Radius
+   - Files affected (with function names)
+   - Callers and consumers
+   - Test coverage status
+   - Config interactions
+   - Cross-item interactions (current .relay/issues/ and .relay/features/)
+   - Past work regression risk (.relay/archive/ + .relay/implemented/)
+
+   ### Approach
+   - Recommended approach (may differ from the issue/feature file's proposal)
+   - Alternatives considered and why they were rejected
+   - Open questions or decisions needed before implementation
+
+Output: Updated issue/feature file(s) in .relay/issues/ or .relay/features/ with analysis appended
+
+## Navigation
+When finished, tell the user the next step based on the outcome:
+- If the item is stale (the bug/gap no longer exists in the code, was already addressed outside the pipeline, or the requirement is no longer valid):
+  "This item is stale. Run **/relay-resolve** to archive it as a stale close-out. Then run **/relay-scan** to refresh project status."
+- Otherwise:
+  "Next: run **/relay-plan** to create the implementation plan."
+
+## Notes
+
+- The analysis is persisted in the issue/feature file so it survives across conversations and is available to /relay-plan
+- This skill forces validation before planning — catching stale items and wrong approaches early
+- The "read all items" step is critical: it prevents changes that conflict with other known problems or planned features
+- Reading archive/ and implemented/ provides historical context — knowing what was already tried, what approaches worked, and what caveats were noted prevents repeating mistakes and protects past work from regression
+- If the analysis reveals the item is stale, the right action is to update/archive the issue/feature file, not proceed with implementation
+- If multiple items share a root cause, consider proposing a combined approach
+- If past work is at risk of regression, call it out explicitly in the Blast Radius section

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

@@ -0,0 +1,6 @@
+---
+name: relay-brainstorm
+description: 'Interactive brainstorming session for a new feature idea. Explores approaches, trade-offs, and produces a brainstorm file. Use when you have a feature idea to explore.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,114 @@
+# Relay: Feature — Brainstorm & Explore
+
+**Sequence**: **`/relay-brainstorm`** → `/relay-design` → `/relay-scan` → `/relay-order` → `/relay-analyze` → `/relay-plan` → `/relay-review` → *implement* → `/relay-verify` → `/relay-notebook` → `/relay-resolve`
+
+I want to explore a feature idea: [DESCRIPTION]
+
+Guide me through brainstorming this feature interactively.
+
+1. Understand the idea:
+   - Ask clarifying questions about what I'm trying to achieve
+   - Don't assume scope — let me define it through conversation
+   - Identify the core problem or opportunity this feature addresses
+
+2. Explore the codebase for context:
+   - What existing code, patterns, and abstractions are relevant?
+   - What architectural constraints exist that shape what's possible?
+   - Check for related work across the full docs landscape:
+     - .relay/features/ — is something similar already planned?
+     - .relay/issues/ — are there known issues this feature would affect?
+     - .relay/implemented/ — has something similar been built before?
+     - .relay/archive/features/ and .relay/archive/issues/ — was this
+       previously attempted, designed, or rejected?
+   - What would this feature interact with in the current codebase?
+
+3. Identify implementation approaches:
+   - Present 2-3 distinct approaches with trade-offs
+   - For each: how it fits the current architecture, complexity,
+     what it enables, what it limits
+   - Surface constraints I might not know about
+   - Ask me which direction resonates
+
+4. As the conversation progresses, manage the brainstorm file explicitly:
+   - Ask before CREATING the file for the first time:
+     "Should I create the brainstorm file with what we have so far?"
+   - Once the file exists, update it as decisions land — record each
+     decision when it is settled without asking each time.
+   - Ask before STRUCTURAL changes: adding or removing a feature from
+     the Feature Breakdown table, changing the Development Order, or
+     updating the brainstorm status. Example:
+     "We've landed on [feature X] as a separate feature — should I add
+     it to the breakdown table?"
+   Do NOT silently accumulate decisions and batch them — record each
+   decision as it is settled, not at the end.
+
+5. Create and maintain a brainstorm file in .relay/features/:
+   - Naming: [topic]_brainstorm.md (e.g., rls_brainstorm.md)
+   - This is a LIVING DOCUMENT — update it throughout the conversation
+     as decisions are made, not just at the end.
+   - Structure:
+
+     # Feature Brainstorm: [Topic]
+
+     *Created: [YYYY-MM-DD]*
+     *Status: BRAINSTORMING*
+     (Lifecycle: BRAINSTORMING → READY FOR DESIGN → DESIGN COMPLETE → COMPLETE)
+
+     ## Goal
+     [What we're trying to achieve — refined through conversation]
+
+     ## Context
+     [Relevant codebase patterns, constraints, existing code discovered]
+
+     ## Approaches Considered
+     ### Approach A: [name]
+     - Description, trade-offs, verdict (selected/rejected + why)
+     ### Approach B: [name]
+     - Description, trade-offs, verdict (selected/rejected + why)
+
+     ## Decisions Made
+     - [numbered list of decisions with rationale, accumulated as we go]
+
+     ## Feature Breakdown
+
+     [If this brainstorm produces multiple features, list ALL of them
+      here as an accumulation. If it produces a single feature, this
+      table has one row.]
+
+     | # | Feature File | Description | Suggested Order | Dependencies |
+     |---|-------------|-------------|-----------------|--------------|
+     | 1 | `[name].md` | ...         | Build first     | None         |
+     | 2 | `[name].md` | ...         | Build second    | Depends on 1 |
+
+     ## Development Order
+     [Recommended order with rationale. This is advisory —
+      /relay-order makes the final project-wide call,
+      but this captures the intra-feature dependencies.]
+
+     ## Open Questions
+     [Anything unresolved that /relay-design needs to address]
+
+6. When brainstorming feels complete:
+   - Update the brainstorm file status to READY FOR DESIGN
+   - Confirm the feature breakdown and proposed file names with the user
+   - Confirm the suggested development order with the user
+
+Do NOT design implementation details yet — that's /relay-design.
+Do NOT create individual feature files — only the brainstorm file.
+Focus on WHAT and WHY, not HOW.
+
+## Navigation
+When brainstorming is complete, tell the user:
+- "Next: run **/relay-design** to design each feature in detail."
+
+## Notes
+
+- This is intentionally interactive — ask questions, don't monologue
+- The brainstorm file is updated throughout the conversation as decisions are made, not dumped at the end
+- Ask before the first creation; once the file exists, update routine decisions freely. Ask before structural changes (new Feature Breakdown entry, Development Order changes, status transitions)
+- Only ONE brainstorm file is created, even for multi-feature ideas — it accumulates all the areas/namespaces
+- The Feature Breakdown table is the handoff contract to /relay-design — it names the files and describes what each one covers. /relay-design will create the individual feature files listed in the table.
+- Suggested development order is recorded so /relay-design and eventually /relay-order can use it
+- If the idea is simple (one feature, obvious approach), this phase can be brief
+- If the idea is complex (architectural decisions, multiple features), this phase may take several rounds
+- If the brainstorm reveals this is actually a bug/gap rather than a feature, pivot to /relay-new-issue

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

@@ -0,0 +1,6 @@
+---
+name: relay-cleanup
+description: 'Archive abandoned brainstorm files in .relay/features/. Use periodically to clean up brainstorms that were started but never completed through relay-design.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,53 @@
+# Relay: Feature — Cleanup Abandoned Brainstorms
+
+**Sequence**: **`/relay-cleanup`** (standalone utility)
+
+Clean up orphaned brainstorm files in .relay/features/.
+
+This utility handles brainstorm files that were started but abandoned.
+Brainstorms with status DESIGN COMPLETE or COMPLETE are managed by the
+main workflow (/relay-resolve archives COMPLETE brainstorms automatically).
+
+1. Read every *_brainstorm.md file in .relay/features/.
+
+2. For each brainstorm file, check its status:
+   - COMPLETE — should already have been archived by /relay-resolve.
+     If found here, archive it (see step 3) with banner:
+     > **ARCHIVED** — All features resolved.
+   - DESIGN COMPLETE — features may still be in progress. Check the
+     Feature Breakdown table: if ALL listed feature files have been
+     archived (exist in .relay/archive/features/ but not in .relay/features/),
+     this brainstorm was missed by /relay-resolve. Treat it like COMPLETE
+     and archive it with banner:
+     > **ARCHIVED** — All features resolved.
+     If some features are still active in .relay/features/, leave it alone.
+   - READY FOR DESIGN — this brainstorm is waiting for /relay-design.
+     Ask the user: "Brainstorm [filename] has status READY FOR DESIGN.
+     Should I archive it, or leave it for /relay-design?"
+   - BRAINSTORMING — this brainstorm was started but never completed.
+     Ask the user: "Brainstorm [filename] has status BRAINSTORMING
+     (incomplete). Should I archive it?"
+
+3. For each brainstorm the user wants archived:
+   - Move it from .relay/features/[file].md to .relay/archive/features/[file].md
+   - Add the appropriate banner at the top based on status:
+     - COMPLETE: `> **ARCHIVED** — All features resolved.`
+     - READY FOR DESIGN: `> **ARCHIVED** — Abandoned. Was ready for design but not progressed.`
+     - BRAINSTORMING: `> **ARCHIVED** — Abandoned. Brainstorming was not completed.`
+   - If any individual feature files in .relay/features/ reference this
+     brainstorm (check the *Brainstorm:* metadata line), warn the user
+     that orphaned feature files exist and ask how to handle them.
+
+4. Report what was archived and what was left in place.
+
+## Navigation
+When finished, tell the user:
+- "Cleanup complete. Run **/relay-scan** if you want to refresh the project status."
+
+## Notes
+
+- This is a utility skill — run it when brainstorm files accumulate
+- COMPLETE brainstorms are normally archived by /relay-resolve — this skill is a fallback if one was missed
+- DESIGN COMPLETE brainstorms are left alone — their features are in the code pipeline
+- Always ask the user before archiving BRAINSTORMING and READY FOR DESIGN files — they may be intentionally paused, not abandoned
+- If a brainstorm has associated feature files that were already created by /relay-design, those feature files are independent and should NOT be archived just because the brainstorm is

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

@@ -0,0 +1,6 @@
+---
+name: relay-design
+description: 'Design features from a brainstorm file into detailed specs. Creates individual feature files with architecture, interfaces, and data flow. Use after relay-brainstorm produces a READY FOR DESIGN brainstorm.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,108 @@
+# Relay: Feature — Design & Specify
+
+**Sequence**: `/relay-brainstorm` → **`/relay-design`** → `/relay-scan` → `/relay-order` → `/relay-analyze` → `/relay-plan` → `/relay-review` → *implement* → `/relay-verify` → `/relay-notebook` → `/relay-resolve`
+
+Design the features from the brainstorm file.
+
+A brainstorm file (*_brainstorm.md with status READY FOR DESIGN) must exist
+in .relay/features/ before running this skill. If none exists, tell the user
+to run **/relay-brainstorm** first.
+
+1. Read the brainstorm file in .relay/features/:
+   - Find all *_brainstorm.md files with status READY FOR DESIGN
+   - If multiple brainstorm files have status READY FOR DESIGN, list
+     them and ask the user which one to design first. Process one
+     brainstorm per invocation.
+   - Read it for the Feature Breakdown table, decisions, development
+     order, and open questions
+
+2. For each feature listed in the Feature Breakdown, in the suggested
+   development order:
+
+   a. Deep-dive into the codebase:
+      - Read the specific files, modules, and interfaces this feature touches
+      - Understand the existing patterns and abstractions it must fit into
+      - Check .relay/issues/ for known problems that interact with this feature
+      - Check .relay/implemented/ and .relay/archive/ for past work that's relevant
+      - Identify what's new code vs modifications to existing code
+
+   b. Design the feature iteratively with the user:
+      - Present the proposed architecture: components, data flow, interfaces
+      - Highlight decisions that need user input
+      - Ask: "Does this design match what you had in mind?"
+      - Adjust based on feedback before committing to the file
+
+   c. Create the individual feature file in .relay/features/:
+      - Use the filename specified in the brainstorm's Feature Breakdown
+      - Structure:
+
+        # 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]*
+        *Status: DESIGNED*
+
+        ## Summary
+        [1-2 sentence description of what this feature does]
+
+        ## Motivation
+        [Why this feature is needed — from the brainstorm decisions]
+
+        ## Design
+
+        ### Architecture
+        [Components, how they fit into the existing codebase]
+
+        ### Interfaces
+        [New or modified APIs, function signatures, data structures]
+
+        ### Data Flow
+        [How data moves through the feature]
+
+        ### Integration Points
+        [Where this connects to existing code — specific files and functions]
+
+        ## Affected Files
+        - [list of files that need creation or modification]
+
+        ## Dependencies
+        - [Other features or issues that must be completed first]
+        - Brainstorm: [link to brainstorm file]
+        - Related features: [links to sibling feature files from same brainstorm]
+
+        ## Development Order
+        [Position in the sequence from the brainstorm, with rationale.
+         e.g., "2 of 3 — requires [feature_1].md to be implemented first
+         because it depends on the interfaces defined there."]
+
+        ## Open Questions
+        [Anything deferred or needing resolution during implementation]
+
+   d. After creating each feature file, explicitly ask the user:
+      - "Does this design look right before I move to the next feature?"
+      - If changes are needed, update the file before proceeding
+
+3. After all feature files are created:
+   - Set the brainstorm file's status to DESIGN COMPLETE
+   - Update the Feature Breakdown table with links to the created files
+   - Summarize what was created and the development order
+
+Do NOT update relay-status.md or relay-ordering.md — that is the
+responsibility of the prepare skills.
+Do NOT create implementation plans — that is /relay-plan's job.
+
+## Navigation
+When finished, tell the user:
+- "Next: run **/relay-scan** to update project status, then **/relay-order** to integrate these into the backlog. Then run **/relay-analyze** to begin implementation."
+
+## Notes
+
+- Each feature file is self-contained but links back to the brainstorm for context and links to sibling features
+- The design should be detailed enough for /relay-plan to create an implementation plan from it
+- Development order is recorded in each file, but /relay-order makes the final project-wide prioritization
+- If designing reveals the brainstorm's breakdown was wrong (features should be split or merged differently), update the brainstorm file and confirm with the user before proceeding
+- For simple single-feature brainstorms, this phase creates one file and is brief
+- For multi-feature brainstorms, iterate through each feature in the suggested order — earlier designs inform later ones
+- If the design reveals new issues or conflicts with existing code, note them in the feature file's Open Questions section — do not create issue files mid-design

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

@@ -0,0 +1,6 @@
+---
+name: relay-discover
+description: 'Scan the codebase to discover bugs, gaps, inconsistencies, and technical debt. Creates issue files in .relay/issues/. Use periodically or after significant code changes.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,56 @@
+# Relay: Discover Issues
+
+**Sequence**: **`/relay-discover`** → `/relay-scan` → `/relay-order` → `/relay-analyze` → ...
+
+Scan the codebase to discover issues. For each issue found, create a
+new .md file in .relay/issues/.
+
+1. Read the full docs landscape to understand what's already known:
+   - .relay/issues/ — currently tracked problems
+   - .relay/features/ — planned work
+   - .relay/implemented/ — completed work and how it was done
+   - .relay/archive/issues/ — previously resolved issues
+   - .relay/archive/features/ — previously resolved features
+   Do NOT re-report anything that is already documented, previously
+   resolved, or archived. If an archived issue has regressed, reference
+   the archive file and explain what changed.
+2. Read .relay/relay-status.md (if it exists) for current tracked items
+3. Scan the codebase systematically. Look for:
+   - Bugs: logic errors, unhandled edge cases, broken code paths
+   - Gaps: missing functionality referenced in docs, specs, or PRDs but not implemented
+   - Inconsistencies: mismatches between schema and code, API docs vs actual signatures
+   - Dead code: unused imports, unreachable branches, stale config options
+   - Security: injection risks, missing validation, unsafe defaults
+   - Performance: N+1 queries, unbounded loops, missing indexes
+   - Test gaps: untested critical paths, assertions that don't verify behavior
+   - Error handling: swallowed exceptions, missing error paths, unhelpful messages
+4. For each distinct issue found:
+   a. Check .relay/issues/ — skip if already documented
+   b. Check .relay/features/ — if a feature file with the same name or topic
+      exists, note the overlap and use a distinct filename that clarifies this
+      is an issue (e.g., prefix with the specific problem)
+   c. Create .relay/issues/[descriptive_name].md with:
+      - *Created: [YYYY-MM-DD]*
+      - Title and severity (P0 critical / P1 high / P2 medium / P3 low)
+      - Problem statement: what's wrong 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
+Focus on real, actionable issues. Do not report style preferences,
+minor naming quibbles, or hypothetical problems that require unlikely inputs.
+
+Output: New issue files in .relay/issues/
+
+## Navigation
+When finished, tell the user:
+- "Next: run **/relay-scan** to update project status, then **/relay-order** to prioritize the work."
+
+## Scoping Variants
+
+To narrow the scan, the user can append one of these:
+
+- **Scope to a module**: `Focus your scan on src/search/ and src/extraction/`
+- **Scope to a concern**: `Focus on security issues only`
+- **Scope to recent changes**: `Focus on files changed in the last 5 commits (use git diff)`
+- **Depth**: `Do a deep scan — read every function body` vs `Do a quick scan — focus on public API and integration points`

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

@@ -0,0 +1,6 @@
+---
+name: relay-help
+description: 'Navigate the Relay workflow. Analyzes current project state, helps you decide what to do, and routes you to the right skill. Use when you need guidance, want to file something but are not sure if it is an issue or feature, or say what should I do next.'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1,165 @@
+# Relay: Help & Navigation
+
+Analyze the user's intent and current project state, then guide them to the right skill.
+
+## Execution
+
+### Step 0 — Parse user input
+
+The user may invoke this skill in several ways:
+
+**With a description** (intent-based):
+```
+/relay-help I want to add authentication
+/relay-help The search API is returning duplicates
+/relay-help What should I do next?
+/relay-help I found a bug in the parser
+```
+
+**Without a description** (state-based):
+```
+/relay-help
+```
+
+If the user provided a description, go to **Step 1 (Intent routing)**.
+If no description, skip to **Step 2 (Setup check)**.
+
+---
+
+### Step 1 — Intent routing
+
+The user described what they want. Classify their intent and route them:
+
+**a) They describe a problem, bug, or gap** (something broken, missing, wrong):
+→ "This sounds like an issue. Run **/relay-new-issue** to file it:
+   `/relay-new-issue [their description]`
+   The skill will investigate, confirm it's an issue, and create the file. If it turns out to be a feature, it will redirect you to **/relay-brainstorm**."
+
+**b) They describe a feature, enhancement, or new capability** (something to build):
+→ "This sounds like a feature. Run **/relay-brainstorm** to explore it:
+   `/relay-brainstorm [their description]`
+   The skill will ask clarifying questions and help you design it interactively."
+
+**c) They're unsure or it's ambiguous** (could be either):
+→ "Not sure if this is a bug or a feature? Run **/relay-new-issue** — it will investigate the codebase, determine whether it's an issue or a feature, and route you accordingly. Features get redirected to **/relay-brainstorm** automatically."
+
+**d) They want to scan for problems** ("find issues", "what's broken", "audit"):
+→ "Run **/relay-discover** to systematically scan the codebase for bugs, gaps, and issues."
+
+**e) They want to continue or resume work** ("what's next", "where was I", "continue"):
+→ Skip to **Step 2** and proceed with state-based detection.
+
+**f) They ask about Relay itself** ("how does relay work", "what skills are available"):
+→ Show the **Available Relay Skills** table and **Workflow Paths** section below. Explain that Relay has three entry points: scan for issues, file a specific item, or brainstorm a feature — and all paths lead through the same code pipeline.
+
+After routing, also mention the current project state if relevant (e.g., "You also have 2 items in progress — run `/relay-help` without a description to see their status").
+
+---
+
+### Step 2 — Check if Relay is set up
+
+- Look for `.relay/` directory. If it doesn't exist, tell the user:
+  "Relay is not set up in this project. Run **/relay-setup** to initialize."
+  Stop here.
+
+### Step 3 — Read current state
+
+- Read `.relay/version.md` (if it exists) for installed version info
+- Read `.relay/relay-status.md` (if it exists) for item counts, in-progress work, and staleness flags
+- Read `.relay/relay-ordering.md` (if it exists) for the current work plan
+- Check `.relay/issues/` and `.relay/features/` for active items
+- Check `.relay/notebooks/` for in-progress notebooks
+
+### Step 4 — Detect where the user is in the workflow
+
+**No items at all** (empty issues/ and features/):
+→ "Your project has no tracked items yet. What would you like to do?
+   - **/relay-discover** — scan the codebase for bugs, gaps, and issues
+   - **/relay-new-issue** — file a specific bug or gap you already know about
+   - **/relay-brainstorm** — explore a new feature idea
+   Tell me what you're thinking and I'll point you to the right skill."
+
+**Items exist but no relay-status.md or it's stale (>1 day old)**:
+→ "Your status file needs refreshing. Run **/relay-scan** to update, then **/relay-order** to prioritize."
+
+**Items exist with up-to-date status but no relay-ordering.md**:
+→ "Status is current but work isn't prioritized. Run **/relay-order** to create the work plan."
+
+**Ordering exists with outstanding phases**:
+Check if any items are in-progress (have pipeline sections appended):
+- If in-progress items found, recommend resuming from their current stage.
+  Check sections in the item file to determine stage (check in this order —
+  later conditions take precedence over earlier ones):
+  - Has ## Analysis but no ## Implementation Plan → "Resume with **/relay-plan** on [item]"
+  - Has ## Implementation Plan but no ## Adversarial Review → "Resume with **/relay-review** on [item]"
+  - Has ## Adversarial Review with verdict REJECTED → "Plan was rejected. Resume with **/relay-plan** on [item] to revise"
+  - Has ## Adversarial Review (APPROVED/APPROVED WITH CHANGES) but no ## Implementation Guidelines → "Ready to implement [item]. Say **'implement the plan'**"
+  - Has ## Implementation Guidelines but no ## Verification Report → "Implementation may be done. Resume with **/relay-verify** on [item]"
+  - Has ## Verification Report with verdict INCOMPLETE or HAS ISSUES → "Verification found issues. Resume with **/relay-verify** on [item]"
+  - Has ## Verification Report with verdict COMPLETE but no notebook in .relay/notebooks/ → "Resume with **/relay-notebook** on [item]"
+  - Has matching notebook in .relay/notebooks/ → "Ready to close out. Run **/relay-resolve** on [item]"
+- If no in-progress items, recommend starting the next phase:
+  → "Next up: [Phase X] from relay-ordering.md. Run **/relay-analyze** to begin."
+- Always add: "You can also file new items anytime with **/relay-new-issue** or **/relay-brainstorm**."
+
+**All phases complete**:
+→ "All planned work is complete! Options:
+   - **/relay-discover** — scan for new issues
+   - **/relay-brainstorm** — explore new features
+   - **/relay-new-issue** — file a specific bug or gap
+   - **/relay-scan** — refresh status to confirm everything is clean"
+
+**Feature pipeline in progress**:
+- Brainstorm with status BRAINSTORMING → "Continue brainstorming with **/relay-brainstorm**"
+- Brainstorm with status READY FOR DESIGN → "Design the features with **/relay-design**"
+- Features DESIGNED but not in ordering → "Run **/relay-scan** then **/relay-order** to integrate features into the work plan"
+- Brainstorms with BRAINSTORMING or READY FOR DESIGN that are older than 7 days → also mention: "You have stale brainstorms. Run **/relay-cleanup** to archive abandoned ones."
+
+### Step 5 — Present recommendations
+
+- Show the current state summary (items count, what's in progress)
+- Recommend the specific next action with the skill command
+- If multiple paths are available, list them with brief explanations
+- If the user seems unsure, ask what they're trying to accomplish
+
+## Available Relay Skills
+
+| Skill | Purpose |
+|-------|---------|
+| **/relay-setup** | Initialize Relay in a new project |
+| **/relay-discover** | Scan codebase for bugs, gaps, issues |
+| **/relay-new-issue** | File a specific bug or gap |
+| **/relay-brainstorm** | Explore a new feature idea |
+| **/relay-design** | Design features from brainstorm |
+| **/relay-cleanup** | Archive abandoned brainstorms |
+| **/relay-scan** | Update project status |
+| **/relay-order** | Prioritize work |
+| **/relay-analyze** | Validate item before implementation |
+| **/relay-plan** | Create implementation plan |
+| **/relay-review** | Adversarial review of plan |
+| **/relay-verify** | Verify implementation |
+| **/relay-notebook** | Create verification notebook |
+| **/relay-resolve** | Close out and archive completed work |
+
+## Workflow Paths
+
+```
+Specific issue  →  /relay-new-issue  →  /relay-scan → /relay-order → /relay-analyze → ... → /relay-resolve
+Systematic scan →  /relay-discover   →  /relay-scan → /relay-order → /relay-analyze → ... → /relay-resolve
+Feature idea    →  /relay-brainstorm → /relay-design → /relay-scan → /relay-order → /relay-analyze → ... → /relay-resolve
+```
+
+## Code Pipeline
+
+```
+/relay-analyze → /relay-plan → /relay-review → implement → /relay-verify → /relay-notebook → /relay-resolve
+```
+
+## Notes
+
+- This skill reads .relay/ state files but does not modify them
+- If relay-status.md exists, use its dates and in-progress tables rather than re-scanning the codebase
+- When multiple paths are available, present all options but highlight the recommended one
+- Run each Relay skill in a fresh conversation for best results
+- When the user provides a description, prioritize intent routing (Step 1) over state detection (Step 4)
+- /relay-new-issue is the universal entry point for uncertain items — it investigates and redirects features automatically

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

@@ -0,0 +1,6 @@
+---
+name: relay-new-issue
+description: 'File a specific bug or gap as an issue. Redirects features to relay-brainstorm. Use when you have identified a specific problem to document.'
+---
+
+Follow the instructions in ./workflow.md.