opencastle 0.1.0

package/src/orchestrator/skills/react-development/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: react-development
+description: "React development standards for functional components, hooks, TypeScript integration, state management, styling with CSS Modules/Sass, and testing patterns. Use when creating or modifying React components, custom hooks, or component tests."
+---
+
+# React Development Standards
+
+Modern React patterns following the official React documentation at https://react.dev.
+
+## Architecture
+
+- Functional components with hooks as primary pattern.
+- Component composition over inheritance.
+- Organize by feature/domain, not by type.
+- Separate presentational and container components.
+- Custom hooks for reusable stateful logic.
+
+## TypeScript Integration
+
+- Interfaces for props, state, and component definitions.
+- Proper types for API responses, event handlers, and refs.
+- Generic components where appropriate.
+- Strict mode in `tsconfig.json`.
+- Leverage built-in types (`React.FC`, `React.ComponentProps`, etc.).
+- Union types for component variants and states.
+- Shared types in `interfaces/` folder of appropriate project.
+
+## Component Design
+
+- Single responsibility principle.
+- Descriptive, consistent PascalCase naming.
+- Props validation via TypeScript.
+- Small, focused, testable, reusable.
+- Use `<>...</>` or `React.Fragment` to avoid extra DOM nodes.
+- Never mutate props or state directly.
+- Destructure props in function signature.
+
+## State Management
+
+- `useState` for local state.
+- `useReducer` for complex state logic.
+- `useContext` for cross-tree state sharing.
+- React Query for server state.
+
+## Hooks and Effects
+
+- `useEffect` with proper dependency arrays.
+- Cleanup functions in effects to prevent memory leaks.
+- `useMemo`/`useCallback` for performance optimization when needed.
+- Custom hooks for reusable logic.
+- Rules of hooks: only call at top level.
+- `useRef` for DOM access and mutable values.
+
+## Styling
+
+- **CSS Modules** with `.module.scss` files.
+- **Sass** for advanced features.
+- Scoped styles to avoid global conflicts.
+- Responsive design with mobile-first approach.
+- CSS custom properties for theming.
+- Consistent spacing, typography, color systems.
+- Sass variables and mixins from shared libraries.
+- Co-locate styles with components.
+
+## Performance
+
+- Stable `key` props in lists.
+- `React.memo` when appropriate.
+- Code splitting with `React.lazy` and `Suspense`.
+- Tree shaking and dynamic imports.
+- Virtual scrolling for large lists.
+- Profile with React DevTools.
+- Avoid anonymous functions in render.
+- `ErrorBoundary` for graceful error handling.
+
+## Data Fetching
+
+- Libraries: React Query, SWR, Apollo Client.
+- Loading, error, and success states.
+- Handle race conditions and request cancellation.
+- Optimistic updates.
+- Caching strategies.
+- Offline/network error handling.
+
+## Error Handling
+
+- Error Boundaries for component-level errors.
+- Proper error states in data fetching.
+- Fallback UI for error scenarios.
+- Meaningful error messages to users.
+
+## Forms
+
+- Controlled components.
+- React Hook Form + Zod for validation.
+- Form submission and error states.
+- Accessibility: labels, ARIA attributes.
+- Debounced validation.
+
+## Testing
+
+- React Testing Library: test behavior, not implementation.
+- Jest as test runner.
+- Mock external dependencies and API calls.
+- Test accessibility and keyboard navigation.
+- Co-locate tests in `__tests__` subdirectory.
+- **CRITICAL**: Never mix static imports and `require()` for lazy-loaded libraries in tests.
+- Use `jest.requireMock()` instead of `require()` in test functions.
+- Use `jest.requireActual()` in mock setup.
+
+## Security
+
+- Sanitize user inputs (XSS prevention).
+- Validate/escape data before rendering.
+- HTTPS for external APIs.
+- Avoid storing sensitive data in localStorage/sessionStorage.
+- CSP headers.

package/src/orchestrator/skills/sanity-cms/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: sanity-cms
+description: "Sanity CMS development rules, GROQ query patterns, and content management best practices. Use when working with Sanity schemas, writing GROQ queries, modifying content models, or managing CMS configuration."
+---
+
+# Sanity CMS
+
+Generic Sanity CMS development methodology. For project-specific configuration, schemas, plugins, document types, and GROQ examples, see [sanity-config.md](../../customizations/stack/sanity-config.md).
+
+## Critical Development Rules
+
+1. **Always check the schema before querying** — use `get_schema` to understand document types and field structures before writing GROQ queries
+2. **Array vs single reference** — always verify whether a field is an array of references or a single reference; using the wrong query operator causes silent failures
+3. **Local schema files are source of truth** — the Studio schema directory takes precedence over deployed schemas; deploying schemas from a local Studio context creates drift
+4. **Follow `defineType` and `defineField` patterns** — always use Sanity helpers for type safety and consistency
+5. **Test GROQ queries in Vision** — validate queries against real data in the Vision plugin before deploying
+6. **Handle draft/publish workflow** — remember drafts have `drafts.` prefix; mutations create drafts, not published documents
+7. **Keep queries in the shared library** — queries belong in a shared queries library, never inline in components

package/src/orchestrator/skills/security-hardening/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: security-hardening
+description: "Security architecture including authentication, authorization, RLS policies, security headers, CSP, input validation, API security, and OAuth patterns. Use when implementing auth flows, writing RLS policies, configuring security headers, validating inputs, or auditing security."
+---
+
+# Security Hardening
+
+## Security Architecture
+
+```
+Vercel Edge Network (WAF, DDoS)
+  → Security Headers (next.config.js: HSTS, CSP, X-Frame-Options)
+    → Middleware (proxy.ts: session refresh)
+      → Server Actions (Supabase Auth: CSRF protection)
+        → RLS Policies (row-level authorization)
+```
+
+| Layer | Technology | Protection |
+|-------|-----------|------------|
+| Edge | Vercel WAF | DDoS, bot detection |
+| Headers | Next.js config | HSTS, CSP, XSS protection |
+| Middleware | proxy.ts | Session management |
+| Server Actions | Supabase Auth | Authentication, CSRF |
+| Database | RLS Policies | Row-level authorization |
+| API Routes | CRON_SECRET | Cron job authorization |
+| Input | Zod | Schema validation |
+| Rate Limiting | Proxy layer | IP-based throttling |
+
+## Authentication
+
+**Platform:** Supabase Auth with Server Actions pattern.
+
+- **Server Actions** for sign in/up/out, session management.
+- **Middleware** for session refresh, protected routes.
+- **RLS Policies** in Postgres.
+- **OAuth providers:** Google, Facebook (configured in Supabase dashboard)
+- **User roles:** `user`, `moderator`, `admin` (stored in `profiles.roles TEXT[]`)
+- **Key auth files:** `libs/supabase-auth/src/actions/auth.ts`, `apps/*/proxy.ts`
+- **Cron authorization:** `CRON_SECRET` env var, `Bearer` token in `authorization` header
+
+### Server Actions Pattern Benefits
+
+- Automatic CSRF protection (Next.js POST-only Server Actions).
+- No exposed API endpoints for auth.
+- Server-side session management.
+
+### Session Management
+
+- HTTP-only cookies (Supabase client managed).
+- Automatic refresh via middleware (`updateSession()`).
+- Sign out clears cookie and invalidates session.
+
+## Content Security Policy
+
+### Allowed External Domains (`next.config.js`)
+
+| Purpose | Domains |
+|---------|--------|
+| Scripts | `challenges.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.sanity.io`, `maps.googleapis.com` |
+| Styles | `cdn.jsdelivr.net`, `fonts.googleapis.com` |
+| Fonts | `fonts.gstatic.com` |
+| Frames | `challenges.cloudflare.com` |
+
+### Directives
+
+General CSP directives follow the principle of least privilege:
+- `default-src 'self'` — deny by default.
+- Whitelist only required external domains per directive.
+- `object-src 'none'` — block plugins.
+- `frame-ancestors 'self'` — prevent clickjacking.
+- `upgrade-insecure-requests` — enforce HTTPS.
+
+**Known weaknesses:** `'unsafe-inline'` and `'unsafe-eval'` in script-src (required for Next.js dev mode). Consider nonces/hashes for production inline scripts.
+
+## RLS Policy Patterns
+
+> **Detailed RLS patterns and SQL examples:** See the **supabase-database** skill, which is the authoritative source for RLS policies, role systems, and migration rules.
+
+### Best Practices
+
+- Enable RLS on all tables: `ALTER TABLE x ENABLE ROW LEVEL SECURITY;`
+- Test policies with different user roles.
+- Use `auth.uid()` for authentication checks.
+- EXISTS subqueries for role checks.
+- Never rely solely on client-side authorization.
+- Never disable RLS in production.
+
+## API Security
+
+### Cron Job Authorization
+
+```typescript
+export async function GET(request: NextRequest) {
+  const authHeader = request.headers.get('authorization');
+  if (!authHeader || authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+}
+```
+
+- Strong random CRON_SECRET: `openssl rand -hex 32`
+- Rotate quarterly.
+
+### Input Validation
+
+- Zod schemas for all request validation.
+- React Hook Form for client-side validation.
+- Server-side validation in all Server Actions and route handlers.
+
+## Critical Rules
+
+1. Never commit secrets — use Vercel environment variables.
+2. Always use Server Actions for auth operations.
+3. Enable RLS on all tables — default-deny, explicit-allow.
+4. Validate all inputs with Zod before database operations.
+5. Sanitize user content — escape HTML in reviews/descriptions.
+6. Parameterized queries (Supabase client handles automatically).
+7. Rotate secrets regularly (quarterly).

package/src/orchestrator/skills/self-improvement/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: self-improvement
+description: "Protocol for reading and updating the lessons-learned knowledge base. MUST be followed by ALL agents — read lessons before work, write lessons after retries. This makes the agent team self-improving across sessions."
+---
+
+# Self-Improvement Protocol
+
+This skill defines how agents learn from mistakes and share knowledge so the same pitfalls are never repeated.
+
+## Core Principle
+
+**If you retry something with a different approach and it works, document the lesson immediately.** The cost of writing a lesson (2 minutes) is always less than the cost of someone else hitting the same pitfall (5-30 minutes).
+
+## The Lessons File
+
+Location: `.github/customizations/LESSONS-LEARNED.md`
+
+This is the team's collective memory — a structured log of tool/command pitfalls, workarounds, and correct approaches discovered through execution.
+
+## Protocol for All Agents
+
+### BEFORE Starting Work (Mandatory)
+
+1. **Read `.github/customizations/LESSONS-LEARNED.md`** — scan the full file or at minimum the categories relevant to your task
+2. **Apply relevant lessons proactively** — don't wait to hit the same wall; use the documented correct approach from the start
+3. **Check the Index by Category table** at the bottom of the file to quickly find relevant sections
+
+### DURING Execution (Trigger-Based)
+
+A lesson MUST be written when **any** of these triggers occur:
+
+| Trigger | Example |
+|---------|---------|
+| **Retry with different approach** | Command fails, you try a different flag/syntax and it works |
+| **Tool call fails unexpectedly** | MCP tool returns error, you discover the correct parameter format |
+| **Workaround needed** | Platform limitation requires non-obvious solution |
+| **Docs are misleading** | Official docs say X but reality is Y |
+| **Configuration surprise** | Default behavior differs from expectation |
+| **Error message is unhelpful** | Error says "failed" but the real cause was something else |
+
+### AFTER Completing Work
+
+1. If you wrote any new lessons during execution, **update the Index by Category table** at the bottom of `.github/customizations/LESSONS-LEARNED.md` to include the new lesson IDs.
+
+2. **Log the session** — append one JSON line to `.github/customizations/logs/sessions.ndjson` with: `timestamp`, `agent`, `model`, `task`, `linear_issue`, `outcome` (success/partial/failed), `files_changed`, `retries`, `lessons_added`, `discoveries`. See `.github/customizations/logs/README.md` for the full schema.
+
+   ```bash
+   echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","agent":"Agent Name","model":"model-id","task":"Short description","outcome":"success","files_changed":N,"retries":0}' >> .github/customizations/logs/sessions.ndjson
+   ```
+
+   This is **mandatory** — session logging fuels the metrics dashboard (`metrics-report` prompt).
+
+## How to Write a Lesson
+
+### Step 1: Determine the next lesson ID
+
+Look at the last `LES-XXX` entry in `.github/customizations/LESSONS-LEARNED.md` and increment by 1.
+
+### Step 2: Write the entry
+
+Add it **before** the `## Index by Category` section, following this template:
+
+```markdown
+### LES-XXX: Short descriptive title
+
+| Field | Value |
+|-------|-------|
+| **Category** | `category-name` |
+| **Added** | YYYY-MM-DD |
+| **Severity** | `high` / `medium` / `low` |
+
+**Problem:** What went wrong and what error/behavior was observed.
+
+**Wrong approach:** The obvious/intuitive approach that fails (with code block).
+
+**Correct approach:** The working solution (with code block).
+
+**Why:** Root cause explanation (if known).
+```
+
+### Step 3: Update the index
+
+Add the lesson ID to the appropriate category row in the `## Index by Category` table.
+
+### Step 4: Update related instruction files (if applicable)
+
+If the lesson reveals a gap in existing instruction/skill files, **also update those files** to include the correct approach. This prevents the pitfall at the source level, not just as a retroactive note.
+
+Examples:
+- Lesson about Linear tool → update `task-management/SKILL.md`
+- Lesson about NX commands → update `nx-workspace/SKILL.md`
+- Lesson about Sanity queries → update `sanity-cms/SKILL.md`
+- Lesson about browser testing → update `browser-testing/SKILL.md`
+
+## Categories
+
+| Category | Covers |
+|----------|--------|
+| `linear` | Linear MCP tools, issue management, workflow states |
+| `mcp-tools` | Any MCP server tool quirks (deferred loading, parameters) |
+| `nx-commands` | NX CLI commands, task runner, caching |
+| `terminal` | Shell commands, port management, process management |
+| `next-js` | Next.js App Router, build, dev server, SSR |
+| `sanity` | Sanity CMS, GROQ queries, schema deployment |
+| `supabase` | Supabase auth, migrations, RLS, SQL |
+| `git` | Git operations, branching, merge conflicts |
+| `vercel` | Deployment, environment variables, edge config |
+| `browser-testing` | E2E testing, screenshots, browser automation |
+| `general` | Anything that doesn't fit above |
+
+## Severity Guide
+
+| Level | Meaning | Impact |
+|-------|---------|--------|
+| `high` | Blocks work entirely | Agent cannot proceed without the workaround |
+| `medium` | Wastes 5+ minutes | Agent will eventually figure it out but wastes time |
+| `low` | Minor friction | Slight annoyance, easy to work around |
+
+## Quality Standards
+
+- **Be specific** — include exact error messages, exact commands, exact tool parameters
+- **Show both wrong and right** — the contrast is what makes lessons actionable
+- **Explain why** — root cause helps agents reason about similar situations
+- **Keep it concise** — one lesson per entry, no essays
+- **Code blocks are mandatory** — for commands, tool calls, and configurations
+
+## Anti-Patterns
+
+- **Never skip reading lessons** before starting work — this is the #1 cause of repeated mistakes
+- **Never "fix it and move on"** without documenting — your fix dies with your session
+- **Never write vague lessons** like "Linear is tricky" — be specific about what fails and what works
+- **Never duplicate existing lessons** — check the index first
+- **Never wait until the end of a session** to write lessons — write them immediately when the retry succeeds
+
+## Agent Memory Protocol
+
+For agent expertise tracking and cross-session knowledge graphs, load the **agent-memory** skill. It covers memory templates, update triggers, retrieval protocols, and the knowledge graph format.

package/src/orchestrator/skills/seo-patterns/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: seo-patterns
+description: "Technical SEO patterns for meta tags, structured data, sitemaps, URL strategy, and rendering. Use when optimizing pages for search engines or implementing SEO features."
+---
+
+# SEO Patterns
+
+## Meta Tags & Open Graph
+- `<title>`, `<meta name="description">` for every page template
+- Open Graph tags (`og:title`, `og:description`, `og:image`, `og:type`)
+- Twitter Card tags (`twitter:card`, `twitter:title`, `twitter:image`)
+- Canonical URLs (`<link rel="canonical">`)
+- Robots directives (`noindex`, `nofollow` where appropriate)
+
+## Structured Data (JSON-LD)
+- **LocalBusiness** / **Restaurant** / **CafeOrCoffeeShop** for venue pages
+- **BreadcrumbList** for navigation hierarchy
+- **WebSite** with **SearchAction** for sitelinks search box
+- **ItemList** for venue listing pages
+- **Organization** for the site entity
+- Validate against schema.org and Google's requirements
+
+## Sitemap & Crawlability
+- Dynamic XML sitemap generation for all venue pages
+- Sitemap index for large venue counts (705+ and growing)
+- `robots.txt` configuration
+- Internal linking structure
+- Page speed impact on crawl budget
+
+## URL Strategy
+- Clean, keyword-relevant slugs for venue pages
+- Consistent URL patterns across venue categories
+- Redirect handling for renamed/moved venues (301 redirects)
+- Trailing slash consistency
+
+## Rendering & Indexability
+- Ensure critical content is server-rendered (not client-only)
+- Verify pages are indexable with `fetch as Googlebot`
+- Check hydration doesn't break structured data
+- Image optimization for search (alt text, file names, lazy loading below fold)

package/src/orchestrator/skills/session-checkpoints/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: session-checkpoints
+description: "Protocol for saving and restoring session state across agent sessions. Enables replay, fork, and resume of interrupted work — inspired by Sandcastle Run Time Machine."
+---
+
+# Skill: Session Checkpoints
+
+Use this skill when working on multi-session features or when a session may be interrupted. Checkpoints allow any future session to resume work without re-analyzing the entire codebase.
+
+## When to Checkpoint
+
+Create a checkpoint:
+
+- **Before delegation** — After decomposition but before first agent delegation
+- **After each phase** — When a group of parallel tasks completes
+- **Before risky work** — Before DB migrations, large refactors, or security changes
+- **On session end** — Always checkpoint before ending a session with incomplete work
+- **On interruption** — If context is running low, checkpoint immediately
+
+## Checkpoint Format
+
+Create or update the file `docs/SESSION-CHECKPOINT.md` with this structure:
+
+```markdown
+# Session Checkpoint
+
+**Last Updated:** YYYY-MM-DD HH:MM
+**Feature:** Short feature name
+**Branch:** git branch name
+**Linear Issues:** TAS-XX, TAS-YY, TAS-ZZ
+
+## Current Phase
+
+Phase N of M — Brief description of what this phase does
+
+## Completed Work
+
+| Task | Linear | Agent | Status | Files |
+|------|--------|-------|--------|-------|
+| Description | TAS-XX | Agent Name | ✅ Done | file1.ts, file2.ts |
+| Description | TAS-YY | Agent Name | ✅ Done | file3.ts |
+
+## In Progress
+
+| Task | Linear | Agent | Status | Notes |
+|------|--------|-------|--------|-------|
+| Description | TAS-ZZ | Agent Name | 🔄 In Progress | What's been done so far |
+
+## Remaining Work
+
+| Task | Linear | Agent | Dependencies | Files |
+|------|--------|-------|-------------|-------|
+| Description | TAS-AA | Agent Name | TAS-ZZ | file4.ts, file5.ts |
+
+## Key Decisions Made
+
+- Decision 1: Why this approach was chosen
+- Decision 2: Why alternative X was rejected
+
+## Blockers & Issues
+
+- Blocker 1: Description and what's needed to unblock
+- Issue found: DLQ-XXX reference if logged
+
+## Delegation Cost Log
+
+Track each delegation to monitor budget and optimize future model assignments:
+
+| # | Agent | Linear | Model Tier | Est. Tokens | Duration | Status |
+|---|-------|--------|------------|-------------|----------|--------|
+| 1 | Content Engineer | TAS-XX | Standard | ~20K | 8 min | ✅ Done |
+| 2 | DB Engineer | TAS-YY | Standard | ~25K | 12 min | ✅ Done |
+| 3 | UI Expert | TAS-ZZ | Standard | ~30K | ❌ Failed → retry |
+
+**Running totals:** 3 delegations / ~75K tokens / 0 panel reviews
+
+## File Partitions
+
+```
+Agent A: dir1/, dir2/
+Agent B: dir3/, dir4/
+Agent C: docs/
+```
+
+## Resume Instructions
+
+Step-by-step instructions for a new session to pick up where this one left off:
+
+1. Check out branch `feat/xxx`
+2. Read Linear issues TAS-XX, TAS-YY for context
+3. Start Phase N+1: [specific instructions]
+```
+
+## Resuming from a Checkpoint
+
+When starting a new session:
+
+1. **Check for checkpoint** — Read `docs/SESSION-CHECKPOINT.md` if it exists
+2. **Verify state** — Run `git status`, check branch, verify files match checkpoint
+3. **Check Linear** — List in-progress and todo issues for current feature
+4. **Follow resume instructions** — Execute the specific steps listed in the checkpoint
+5. **Update checkpoint** — After resuming, update the checkpoint with current progress
+
+## Fork Points
+
+When a checkpoint reveals multiple possible paths forward, document them as fork points:
+
+```markdown
+## Fork Point: Feature X Implementation
+
+### Option A: Server-side approach
+- Pros: Better SEO, simpler client code
+- Cons: More server load, slower interactions
+- Files: api/route.ts, lib/server-utils/
+
+### Option B: Client-side approach
+- Pros: Faster interactions, less server load
+- Cons: No SEO, complex client state
+- Files: components/Feature.tsx, hooks/useFeature.ts
+
+**Decision needed from:** User or Architect agent
+```
+
+## Cleanup
+
+After a feature is fully complete (all Linear issues Done):
+
+1. Archive the checkpoint content to the relevant Linear issue comments
+2. Delete `docs/SESSION-CHECKPOINT.md` to keep the workspace clean
+3. The next feature starts with a fresh checkpoint
+
+## Integration with Team Lead
+
+The Team Lead should:
+
+- Create a checkpoint after Step 2 (Decompose & Partition) of the Decomposition Flow
+- Update the checkpoint after each verification pass
+- Include checkpoint reading in session resume workflow
+- Reference the checkpoint file in delegation prompts for context
+
+## Step Output Log (Time-Travel Replay)
+
+Record the output of each completed delegation step. When a later step fails, replay from the failure point using cached outputs instead of re-running everything.
+
+### Why This Matters
+
+A multi-phase feature might complete phases 1-3 successfully before phase 4 fails. Without step logs, retrying requires re-running all 4 phases. With logs, the retry starts at phase 4 with cached context from phases 1-3.
+
+### Step Log Format
+
+Add a `## Step Output Log` section to the checkpoint file:
+
+```markdown
+## Step Output Log
+
+### Step 1: [Short description]
+- **Agent:** [Agent Name]
+- **Linear:** TAS-XX
+- **Status:** ✅ Completed
+- **Duration:** ~X minutes
+- **Key Outputs:**
+  - Created `path/to/file.ts` — [description]
+  - Modified `path/to/other.ts` — [what changed]
+- **Verification:** Lint ✅ | Tests ✅ | Build ✅
+- **Cached Context:** [1-3 sentence summary of what this step produced that downstream steps depend on]
+
+### Step 2: [Short description]
+- **Agent:** [Agent Name]
+- **Linear:** TAS-YY
+- **Status:** ❌ Failed (attempt 1)
+- **Error:** [Specific error message or failure reason]
+- **Cached Context from Step 1:** [Reference what Step 1 produced]
+```
+
+### Replay Protocol
+
+When retrying a failed step:
+
+1. **Read the step log** — identify the last successful step and its cached context
+2. **Build replay context** — concatenate cached context from all completed steps into the retry prompt
+3. **Scope the retry** — only re-delegate the failed step, not earlier completed steps
+4. **Include the error** — add the specific failure reason to the retry prompt so the agent knows what went wrong
+5. **Update the log** — record the retry attempt with attempt number
+
+### Replay Prompt Template
+
+```
+**Retry: TAS-XX (attempt N)**
+
+Previous steps completed successfully. Here is the cached context:
+- Step 1 produced: [cached context from log]
+- Step 2 produced: [cached context from log]
+
+Step 3 failed with: [error from log]
+
+Your task: [re-state the failed step's objective with additional guidance based on the error]
+
+[Include the original delegation spec/prompt with corrections]
+```
+
+### When NOT to Replay
+
+- If the failure invalidates earlier steps (e.g., Step 1's output is wrong), re-run from Step 1
+- If 3+ steps need replay, consider checkpointing and starting a fresh session instead
+- If the codebase changed significantly since the cached steps ran (e.g., another PR merged)