relay-cc 2.0.0

package/relay/references/continuation-format.md

@@ -0,0 +1,249 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/relay:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/relay:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/relay:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/relay:plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/relay:discuss-phase 2` — gather context first
+- `/relay:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/relay:plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/relay:discuss-phase 3` — gather context first
+- `/relay:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/relay:plan-phase 3`
+
+**To discuss context first:** `/relay:discuss-phase 3`
+
+**To research unknowns:** `/relay:research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/relay:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/relay:execute-phase 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/relay:plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/relay:plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/relay/references/git-integration.md

@@ -0,0 +1,209 @@
+<overview>
+Git integration for Relay framework.
+</overview>
+
+<core_principle>
+
+**Commit outcomes, not process.**
+
+The git log should read like a changelog of what shipped, not a diary of planning activity.
+</core_principle>
+
+<commit_points>
+
+| Event                   | Commit? | Why                                              |
+| ----------------------- | ------- | ------------------------------------------------ |
+| ANALYSIS.md created     | NO      | Intermediate - analysis of ticket                |
+| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
+| **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
+| **Ticket completed**    | YES     | Metadata commit (SUMMARY + STATE)               |
+| Handoff created         | YES     | WIP state preserved                              |
+
+</commit_points>
+
+<git_check>
+
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+If NO_GIT: Run `git init` silently.
+</git_check>
+
+<branching>
+
+## Ticket Branches
+
+When branching is enabled, each ticket gets its own branch:
+
+```bash
+# Branch template from config.git.ticket_branch_template
+# Default: "{ticket_id}/{slug}"
+# Example: PROJ-123/add-user-validation
+
+SLUG=$(echo "${TITLE}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
+BRANCH="${TICKET_ID}/${SLUG}"
+git checkout -b "${BRANCH}"
+```
+
+</branching>
+
+<commit_formats>
+
+<format name="task-completion">
+## Task Completion (During Plan Execution)
+
+Each task gets its own commit immediately after completion. Include ticket ID in commit message.
+
+```
+{type}({ticket_id}): {task-name}
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+```
+
+**Commit types:**
+- `feat` - New feature/functionality
+- `fix` - Bug fix
+- `test` - Test-only (TDD RED phase)
+- `refactor` - Code cleanup (TDD REFACTOR phase)
+- `perf` - Performance improvement
+- `chore` - Dependencies, config, tooling
+
+**Examples:**
+
+```bash
+# Standard task
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(PROJ-123): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+"
+
+# Bug fix task
+git add src/utils/validation.ts
+git commit -m "fix(BUG-456): prevent null pointer in email validation
+
+- Added null check before regex match
+- Returns early with error for empty input
+"
+```
+
+</format>
+
+<format name="ticket-completion">
+## Ticket Completion (After All Tasks Done)
+
+After all tasks committed, one final metadata commit captures ticket completion.
+
+```
+docs({ticket_id}): complete {ticket-title}
+
+Tasks completed: [N]/[N]
+- [Task 1 name]
+- [Task 2 name]
+- [Task 3 name]
+
+SUMMARY: .relay/tickets/{TICKET_ID}/SUMMARY.md
+```
+
+What to commit:
+
+```bash
+git add .relay/tickets/{TICKET_ID}/PLAN.md
+git add .relay/tickets/{TICKET_ID}/SUMMARY.md
+git add .relay/tickets/{TICKET_ID}/VERIFICATION.md
+git add .relay/STATE.md
+git commit
+```
+
+**Note:** Code files NOT included - already committed per-task.
+
+</format>
+
+<format name="handoff">
+## Handoff (WIP)
+
+```
+wip({ticket_id}): paused at task [X]/[Y]
+
+Current: [task name]
+[If blocked:] Blocked: [reason]
+```
+
+What to commit:
+
+```bash
+git add .relay/
+git commit
+```
+
+</format>
+</commit_formats>
+
+<example_log>
+
+```
+# Ticket PROJ-125 - Checkout Flow
+1a2b3c docs(PROJ-125): complete checkout flow
+4d5e6f feat(PROJ-125): add webhook signature verification
+7g8h9i feat(PROJ-125): implement payment session creation
+0j1k2l feat(PROJ-125): create checkout page component
+
+# Ticket PROJ-124 - Product Catalog
+3m4n5o docs(PROJ-124): complete product catalog
+6p7q8r feat(PROJ-124): add pagination controls
+9s0t1u feat(PROJ-124): implement search and filters
+
+# Ticket BUG-200 - Login Validation
+5y6z7a fix(BUG-200): prevent crash on empty email input
+```
+
+Each ticket produces 2-5 commits (tasks + metadata). Clear, granular, bisectable.
+
+</example_log>
+
+<anti_patterns>
+
+**Still don't commit (intermediate artifacts):**
+- ANALYSIS.md creation (intermediate)
+- PLAN.md creation (commit with ticket completion)
+- Minor planning tweaks
+
+**Do commit (outcomes):**
+- Each task completion (feat/fix/test/refactor)
+- Ticket completion metadata (docs)
+- Handoff state (wip)
+
+**Key principle:** Commit working code and shipped outcomes, not planning process.
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## Why Per-Task Commits?
+
+**Context engineering for AI:**
+- Git history becomes primary context source for future Claude sessions
+- `git log --grep="{ticket_id}"` shows all work for a ticket
+- `git diff <hash>^..<hash>` shows exact changes per task
+- Less reliance on parsing SUMMARY.md = more context for actual work
+
+**Failure recovery:**
+- Task 1 committed, Task 2 failed
+- Claude in next session: sees task 1 complete, can retry task 2
+- Can `git reset --hard` to last successful task
+
+**Debugging:**
+- `git bisect` finds exact failing task
+- `git blame` traces line to specific task context
+- Each commit is independently revertable
+
+**Observability:**
+- Ticket ID in every commit links back to external system
+- Atomic commits are git best practice
+
+</commit_strategy_rationale>

package/relay/references/model-profiles.md

@@ -0,0 +1,57 @@
+# Model Profiles
+
+Model profiles control which Claude model each Relay agent uses. This allows balancing quality vs token spend.
+
+## Profile Definitions
+
+| Agent | `quality` | `balanced` | `budget` |
+|-------|-----------|------------|----------|
+| relay-planner | opus | opus | sonnet |
+| relay-ticket-researcher | opus | sonnet | haiku |
+| relay-executor | opus | sonnet | sonnet |
+| relay-debugger | opus | sonnet | sonnet |
+| relay-codebase-mapper | sonnet | haiku | haiku |
+| relay-verifier | sonnet | sonnet | haiku |
+| relay-plan-checker | sonnet | sonnet | haiku |
+| relay-estimator | opus | sonnet | sonnet |
+| relay-reviewer | opus | sonnet | sonnet |
+
+## Profile Philosophy
+
+**quality** - Maximum reasoning power
+- Opus for all decision-making agents
+- Sonnet for read-only verification
+- Use when: quota available, critical architecture work
+
+**balanced** (default) - Smart allocation
+- Opus only for planning (where architecture decisions happen)
+- Sonnet for execution and research (follows explicit instructions)
+- Sonnet for verification (needs reasoning, not just pattern matching)
+- Use when: normal development, good balance of quality and cost
+
+**budget** - Minimal Opus usage
+- Sonnet for anything that writes code
+- Haiku for research and verification
+- Use when: conserving quota, high-volume work, less critical tasks
+
+## Resolution Logic
+
+Orchestrators resolve model before spawning:
+
+```
+1. Read .relay/config.json
+2. Get model_profile (default: "balanced")
+3. Look up agent in table above
+4. Pass model parameter to Task call
+```
+
+## Switching Profiles
+
+Runtime: `/relay:set-profile <profile>`
+
+Per-project default: Set in `.relay/config.json`:
+```json
+{
+  "model_profile": "balanced"
+}
+```

package/relay/references/planning-config.md

@@ -0,0 +1,189 @@
+<planning_config>
+
+Configuration options for `.relay/` directory behavior.
+
+<config_schema>
+```json
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "branching_strategy": "none",
+  "phase_branch_template": "relay/phase-{phase}-{slug}",
+  "milestone_branch_template": "relay/{milestone}-{slug}"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `commit_docs` | `true` | Whether to commit planning artifacts to git |
+| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
+| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `git.phase_branch_template` | `"relay/phase-{phase}-{slug}"` | Branch template for phase strategy |
+| `git.milestone_branch_template` | `"relay/{milestone}-{slug}"` | Branch template for milestone strategy |
+</config_schema>
+
+<commit_docs_behavior>
+
+**When `commit_docs: true` (default):**
+- Planning files committed normally
+- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
+- Full history of planning decisions preserved
+
+**When `commit_docs: false`:**
+- Skip all `git add`/`git commit` for `.relay/` files
+- User must add `.relay/` to `.gitignore`
+- Useful for: OSS contributions, client projects, keeping planning private
+
+**Checking the config:**
+
+```bash
+# Check config.json first
+COMMIT_DOCS=$(cat .relay/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+
+# Auto-detect gitignored (overrides config)
+git check-ignore -q .relay 2>/dev/null && COMMIT_DOCS=false
+```
+
+**Auto-detection:** If `.relay/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.relay/` in `.gitignore`.
+
+**Conditional git operations:**
+
+```bash
+if [ "$COMMIT_DOCS" = "true" ]; then
+  git add .relay/STATE.md
+  git commit -m "docs: update state"
+fi
+```
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**When `search_gitignored: false` (default):**
+- Standard rg behavior (respects .gitignore)
+- Direct path searches work: `rg "pattern" .relay/` finds files
+- Broad searches skip gitignored: `rg "pattern"` skips `.relay/`
+
+**When `search_gitignored: true`:**
+- Add `--no-ignore` to broad rg searches that should include `.relay/`
+- Only needed when searching entire repo and expecting `.relay/` matches
+
+**Note:** Most Relay operations use direct file reads or explicit paths, which work regardless of gitignore status.
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+To use uncommitted mode:
+
+1. **Set config:**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **Add to .gitignore:**
+   ```
+   .relay/
+   ```
+
+3. **Existing tracked files:** If `.relay/` was previously tracked:
+   ```bash
+   git rm -r --cached .relay/
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**Branching Strategies:**
+
+| Strategy | When branch created | Branch scope | Merge point |
+|----------|---------------------|--------------|-------------|
+| `none` | Never | N/A | N/A |
+| `phase` | At `execute-phase` start | Single phase | User merges after phase |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+
+**When `git.branching_strategy: "none"` (default):**
+- All work commits to current branch
+- Standard Relay behavior
+
+**When `git.branching_strategy: "phase"`:**
+- `execute-phase` creates/switches to a branch before execution
+- Branch name from `phase_branch_template` (e.g., `relay/phase-03-authentication`)
+- All plan commits go to that branch
+- User merges branches manually after phase completion
+- `complete-milestone` offers to merge all phase branches
+
+**When `git.branching_strategy: "milestone"`:**
+- First `execute-phase` of milestone creates the milestone branch
+- Branch name from `milestone_branch_template` (e.g., `relay/v1.0-mvp`)
+- All phases in milestone commit to same branch
+- `complete-milestone` offers to merge milestone branch to main
+
+**Template variables:**
+
+| Variable | Available in | Description |
+|----------|--------------|-------------|
+| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
+| `{slug}` | Both | Lowercase, hyphenated name |
+| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
+
+**Checking the config:**
+
+```bash
+# Get branching strategy (default: none)
+BRANCHING_STRATEGY=$(cat .relay/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "none")
+
+# Get phase branch template
+PHASE_BRANCH_TEMPLATE=$(cat .relay/config.json 2>/dev/null | grep -o '"phase_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "relay/phase-{phase}-{slug}")
+
+# Get milestone branch template
+MILESTONE_BRANCH_TEMPLATE=$(cat .relay/config.json 2>/dev/null | grep -o '"milestone_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "relay/{milestone}-{slug}")
+```
+
+**Branch creation:**
+
+```bash
+# For phase strategy
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# For milestone strategy
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**Merge options at complete-milestone:**
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
+| Merge with history | `git merge --no-ff` | Preserves all individual commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling later |
+
+Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+
+**Use cases:**
+
+| Strategy | Best for |
+|----------|----------|
+| `none` | Solo development, simple projects |
+| `phase` | Code review per phase, granular rollback, team collaboration |
+| `milestone` | Release branches, staging environments, PR per version |
+
+</branching_strategy_behavior>
+
+</planning_config>