relay-cc 2.0.0

package/relay/workflows/map-codebase.md

@@ -0,0 +1,357 @@
+<purpose>
+Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .relay/codebase/
+
+Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
+
+Output: .relay/codebase/ folder with 7 structured documents about the codebase state.
+</purpose>
+
+<philosophy>
+**Why dedicated mapper agents:**
+- Fresh context per domain (no token contamination)
+- Agents write documents directly (no context transfer back to orchestrator)
+- Orchestrator only summarizes what was created (minimal context usage)
+- Faster execution (agents run simultaneously)
+
+**Document quality over length:**
+Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
+
+**Always include file paths:**
+Documents are reference material for Claude when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
+</philosophy>
+
+<process>
+
+<step name="resolve_model_profile" priority="first">
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .relay/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| relay-codebase-mapper | sonnet | haiku | haiku |
+
+Store resolved model for use in Task calls below.
+</step>
+
+<step name="check_existing">
+Check if .relay/codebase/ already exists:
+
+```bash
+ls -la .relay/codebase/ 2>/dev/null
+```
+
+**If exists:**
+
+```
+.relay/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Update - Keep existing, only update specific documents
+3. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .relay/codebase/, continue to create_structure
+If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .relay/codebase/ directory:
+
+```bash
+mkdir -p .relay/codebase
+```
+
+**Expected output files:**
+- STACK.md (from tech mapper)
+- INTEGRATIONS.md (from tech mapper)
+- ARCHITECTURE.md (from arch mapper)
+- STRUCTURE.md (from arch mapper)
+- CONVENTIONS.md (from quality mapper)
+- TESTING.md (from quality mapper)
+- CONCERNS.md (from concerns mapper)
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+Spawn 4 parallel relay-codebase-mapper agents.
+
+Use Task tool with `subagent_type="relay-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
+
+**CRITICAL:** Use the dedicated `relay-codebase-mapper` agent, NOT `Explore`. The mapper agent writes documents directly.
+
+**Agent 1: Tech Focus**
+
+Task tool parameters:
+```
+subagent_type: "relay-codebase-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase tech stack"
+```
+
+Prompt:
+```
+Focus: tech
+
+Analyze this codebase for technology stack and external integrations.
+
+Write these documents to .relay/codebase/:
+- STACK.md - Languages, runtime, frameworks, dependencies, configuration
+- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+```
+
+**Agent 2: Architecture Focus**
+
+Task tool parameters:
+```
+subagent_type: "relay-codebase-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase architecture"
+```
+
+Prompt:
+```
+Focus: arch
+
+Analyze this codebase architecture and directory structure.
+
+Write these documents to .relay/codebase/:
+- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
+- STRUCTURE.md - Directory layout, key locations, naming conventions
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+```
+
+**Agent 3: Quality Focus**
+
+Task tool parameters:
+```
+subagent_type: "relay-codebase-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase conventions"
+```
+
+Prompt:
+```
+Focus: quality
+
+Analyze this codebase for coding conventions and testing patterns.
+
+Write these documents to .relay/codebase/:
+- CONVENTIONS.md - Code style, naming, patterns, error handling
+- TESTING.md - Framework, structure, mocking, coverage
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+```
+
+**Agent 4: Concerns Focus**
+
+Task tool parameters:
+```
+subagent_type: "relay-codebase-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase concerns"
+```
+
+Prompt:
+```
+Focus: concerns
+
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+Write this document to .relay/codebase/:
+- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
+
+Explore thoroughly. Write document directly using template. Return confirmation only.
+```
+
+Continue to collect_confirmations.
+</step>
+
+<step name="collect_confirmations">
+Wait for all 4 agents to complete.
+
+Read each agent's output file to collect confirmations.
+
+**Expected confirmation format from each agent:**
+```
+## Mapping Complete
+
+**Focus:** {focus}
+**Documents written:**
+- `.relay/codebase/{DOC1}.md` ({N} lines)
+- `.relay/codebase/{DOC2}.md` ({N} lines)
+
+Ready for orchestrator summary.
+```
+
+**What you receive:** Just file paths and line counts. NOT document contents.
+
+If any agent failed, note the failure and continue with successful documents.
+
+Continue to verify_output.
+</step>
+
+<step name="verify_output">
+Verify all documents created successfully:
+
+```bash
+ls -la .relay/codebase/
+wc -l .relay/codebase/*.md
+```
+
+**Verification checklist:**
+- All 7 documents exist
+- No empty documents (each should have >20 lines)
+
+If any documents missing or empty, note which agents may have failed.
+
+Continue to scan_for_secrets.
+</step>
+
+<step name="scan_for_secrets">
+**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
+
+Run secret pattern detection:
+
+```bash
+# Check for common API key patterns in generated docs
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .relay/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**If SECRETS_FOUND=true:**
+
+```
+⚠️  SECURITY ALERT: Potential secrets detected in codebase documents!
+
+Found patterns that look like API keys or tokens in:
+[show grep output]
+
+This would expose credentials if committed.
+
+**Action required:**
+1. Review the flagged content above
+2. If these are real secrets, they must be removed before committing
+3. Consider adding sensitive files to Claude Code "Deny" permissions
+
+Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
+```
+
+Wait for user confirmation before continuing to commit_codebase_map.
+
+**If SECRETS_FOUND=false:**
+
+Continue to commit_codebase_map.
+</step>
+
+<step name="commit_codebase_map">
+Commit the codebase map:
+
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .relay/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .relay 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
+```bash
+git add .relay/codebase/*.md
+git commit -m "$(cat <<'EOF'
+docs: map existing codebase
+
+- STACK.md - Technologies and dependencies
+- ARCHITECTURE.md - System design and patterns
+- STRUCTURE.md - Directory layout
+- CONVENTIONS.md - Code style and patterns
+- TESTING.md - Test structure
+- INTEGRATIONS.md - External services
+- CONCERNS.md - Technical debt and issues
+EOF
+)"
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps.
+
+**Get line counts:**
+```bash
+wc -l .relay/codebase/*.md
+```
+
+**Output format:**
+
+```
+Codebase mapping complete.
+
+Created .relay/codebase/:
+- STACK.md ([N] lines) - Technologies and dependencies
+- ARCHITECTURE.md ([N] lines) - System design and patterns
+- STRUCTURE.md ([N] lines) - Directory layout and organization
+- CONVENTIONS.md ([N] lines) - Code style and patterns
+- TESTING.md ([N] lines) - Test structure and practices
+- INTEGRATIONS.md ([N] lines) - External services and APIs
+- CONCERNS.md ([N] lines) - Technical debt and issues
+
+
+---
+
+## ▶ Next Up
+
+**Initialize project** — use codebase context for planning
+
+`/relay:new-project`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Re-run mapping: `/relay:map-codebase`
+- Review specific file: `cat .relay/codebase/STACK.md`
+- Edit any document before proceeding
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .relay/codebase/ directory created
+- 4 parallel relay-codebase-mapper agents spawned with run_in_background=true
+- Agents write documents directly (orchestrator doesn't receive document contents)
+- Read agent output files to collect confirmations
+- All 7 codebase documents exist
+- Clear completion summary with line counts
+- User offered clear next steps in Relay style
+</success_criteria>

package/relay/workflows/resume-project.md

@@ -0,0 +1,307 @@
+<trigger>
+Use this workflow when:
+- Starting a new session on an existing project
+- User says "continue", "what's next", "where were we", "resume"
+- Any planning operation when .relay/ already exists
+- User returns after time away from project
+</trigger>
+
+<purpose>
+Instantly restore full project context so "Where were we?" has an immediate, complete answer.
+</purpose>
+
+<required_reading>
+@~/.claude/relay/references/continuation-format.md
+</required_reading>
+
+<process>
+
+<step name="detect_existing_project">
+Check if this is an existing project:
+
+```bash
+ls .relay/STATE.md 2>/dev/null && echo "Project exists"
+ls .relay/ROADMAP.md 2>/dev/null && echo "Roadmap exists"
+ls .relay/PROJECT.md 2>/dev/null && echo "Project file exists"
+```
+
+**If STATE.md exists:** Proceed to load_state
+**If only ROADMAP.md/PROJECT.md exist:** Offer to reconstruct STATE.md
+**If .relay/ doesn't exist:** This is a new project - route to /relay:new-project
+</step>
+
+<step name="load_state">
+
+Read and parse STATE.md, then PROJECT.md:
+
+```bash
+cat .relay/STATE.md
+cat .relay/PROJECT.md
+```
+
+**From STATE.md extract:**
+
+- **Project Reference**: Core value and current focus
+- **Current Position**: Phase X of Y, Plan A of B, Status
+- **Progress**: Visual progress bar
+- **Recent Decisions**: Key decisions affecting current work
+- **Pending Todos**: Ideas captured during sessions
+- **Blockers/Concerns**: Issues carried forward
+- **Session Continuity**: Where we left off, any resume files
+
+**From PROJECT.md extract:**
+
+- **What This Is**: Current accurate description
+- **Requirements**: Validated, Active, Out of Scope
+- **Key Decisions**: Full decision log with outcomes
+- **Constraints**: Hard limits on implementation
+
+</step>
+
+<step name="check_incomplete_work">
+Look for incomplete work that needs attention:
+
+```bash
+# Check for continue-here files (mid-plan resumption)
+ls .relay/tickets/*/.continue-here*.md 2>/dev/null
+
+# Check for plans without summaries (incomplete execution)
+for plan in .relay/tickets/*/*-PLAN.md; do
+  summary="${plan/PLAN/SUMMARY}"
+  [ ! -f "$summary" ] && echo "Incomplete: $plan"
+done 2>/dev/null
+
+# Check for interrupted agents
+if [ -f .relay/current-agent-id.txt ] && [ -s .relay/current-agent-id.txt ]; then
+  AGENT_ID=$(cat .relay/current-agent-id.txt | tr -d '\n')
+  echo "Interrupted agent: $AGENT_ID"
+fi
+```
+
+**If .continue-here file exists:**
+
+- This is a mid-plan resumption point
+- Read the file for specific resumption context
+- Flag: "Found mid-plan checkpoint"
+
+**If PLAN without SUMMARY exists:**
+
+- Execution was started but not completed
+- Flag: "Found incomplete plan execution"
+
+**If interrupted agent found:**
+
+- Subagent was spawned but session ended before completion
+- Read agent-history.json for task details
+- Flag: "Found interrupted agent"
+  </step>
+
+<step name="present_status">
+Present complete project status to user:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PROJECT STATUS                                               ║
+╠══════════════════════════════════════════════════════════════╣
+║  Building: [one-liner from PROJECT.md "What This Is"]         ║
+║                                                               ║
+║  Phase: [X] of [Y] - [Phase name]                            ║
+║  Plan:  [A] of [B] - [Status]                                ║
+║  Progress: [██████░░░░] XX%                                  ║
+║                                                               ║
+║  Last activity: [date] - [what happened]                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+[If incomplete work found:]
+⚠️  Incomplete work detected:
+    - [.continue-here file or incomplete plan]
+
+[If interrupted agent found:]
+⚠️  Interrupted agent detected:
+    Agent ID: [id]
+    Task: [task description from agent-history.json]
+    Interrupted: [timestamp]
+
+    Resume with: Task tool (resume parameter with agent ID)
+
+[If pending todos exist:]
+📋 [N] pending todos — /relay:check-todos to review
+
+[If blockers exist:]
+⚠️  Carried concerns:
+    - [blocker 1]
+    - [blocker 2]
+
+[If alignment is not ✓:]
+⚠️  Brief alignment: [status] - [assessment]
+```
+
+</step>
+
+<step name="determine_next_action">
+Based on project state, determine the most logical next action:
+
+**If interrupted agent exists:**
+→ Primary: Resume interrupted agent (Task tool with resume parameter)
+→ Option: Start fresh (abandon agent work)
+
+**If .continue-here file exists:**
+→ Primary: Resume from checkpoint
+→ Option: Start fresh on current plan
+
+**If incomplete plan (PLAN without SUMMARY):**
+→ Primary: Complete the incomplete plan
+→ Option: Abandon and move on
+
+**If phase in progress, all plans complete:**
+→ Primary: Transition to next phase
+→ Option: Review completed work
+
+**If phase ready to plan:**
+→ Check if CONTEXT.md exists for this phase:
+
+- If CONTEXT.md missing:
+  → Primary: Discuss phase vision (how user imagines it working)
+  → Secondary: Plan directly (skip context gathering)
+- If CONTEXT.md exists:
+  → Primary: Plan the phase
+  → Option: Review roadmap
+
+**If phase ready to execute:**
+→ Primary: Execute next plan
+→ Option: Review the plan first
+</step>
+
+<step name="offer_options">
+Present contextual options based on project state:
+
+```
+What would you like to do?
+
+[Primary action based on state - e.g.:]
+1. Resume interrupted agent [if interrupted agent found]
+   OR
+1. Execute phase (/relay:execute-phase {phase})
+   OR
+1. Discuss Phase 3 context (/relay:discuss-phase 3) [if CONTEXT.md missing]
+   OR
+1. Plan Phase 3 (/relay:plan-phase 3) [if CONTEXT.md exists or discuss option declined]
+
+[Secondary options:]
+2. Review current phase status
+3. Check pending todos ([N] pending)
+4. Review brief alignment
+5. Something else
+```
+
+**Note:** When offering phase planning, check for CONTEXT.md existence first:
+
+```bash
+ls .relay/tickets/XX-name/*-CONTEXT.md 2>/dev/null
+```
+
+If missing, suggest discuss-phase before plan. If exists, offer plan directly.
+
+Wait for user selection.
+</step>
+
+<step name="route_to_workflow">
+Based on user selection, route to appropriate workflow:
+
+- **Execute plan** → Show command for user to run after clearing:
+  ```
+  ---
+
+  ## ▶ Next Up
+
+  **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
+
+  `/relay:execute-phase {phase}`
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
+  ```
+- **Plan phase** → Show command for user to run after clearing:
+  ```
+  ---
+
+  ## ▶ Next Up
+
+  **Phase [N]: [Name]** — [Goal from ROADMAP.md]
+
+  `/relay:plan-phase [phase-number]`
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
+
+  **Also available:**
+  - `/relay:discuss-phase [N]` — gather context first
+  - `/relay:research-phase [N]` — investigate unknowns
+
+  ---
+  ```
+- **Transition** → ./transition.md
+- **Check todos** → Read .relay/todos/pending/, present summary
+- **Review alignment** → Read PROJECT.md, compare to current state
+- **Something else** → Ask what they need
+</step>
+
+<step name="update_session">
+Before proceeding to routed workflow, update session continuity:
+
+Update STATE.md:
+
+```markdown
+## Session Continuity
+
+Last session: [now]
+Stopped at: Session resumed, proceeding to [action]
+Resume file: [updated if applicable]
+```
+
+This ensures if session ends unexpectedly, next resume knows the state.
+</step>
+
+</process>
+
+<reconstruction>
+If STATE.md is missing but other artifacts exist:
+
+"STATE.md missing. Reconstructing from artifacts..."
+
+1. Read PROJECT.md → Extract "What This Is" and Core Value
+2. Read ROADMAP.md → Determine phases, find current position
+3. Scan \*-SUMMARY.md files → Extract decisions, concerns
+4. Count pending todos in .relay/todos/pending/
+5. Check for .continue-here files → Session continuity
+
+Reconstruct and write STATE.md, then proceed normally.
+
+This handles cases where:
+
+- Project predates STATE.md introduction
+- File was accidentally deleted
+- Cloning repo without full .relay/ state
+  </reconstruction>
+
+<quick_resume>
+If user says "continue" or "go":
+- Load state silently
+- Determine primary action
+- Execute immediately without presenting options
+
+"Continuing from [state]... [action]"
+</quick_resume>
+
+<success_criteria>
+Resume is complete when:
+
+- [ ] STATE.md loaded (or reconstructed)
+- [ ] Incomplete work detected and flagged
+- [ ] Clear status presented to user
+- [ ] Contextual next actions offered
+- [ ] User knows exactly where project stands
+- [ ] Session continuity updated
+      </success_criteria>