opencastle 0.1.0

package/src/orchestrator/skills/fast-review/SKILL.md

@@ -0,0 +1,327 @@
+````skill
+---
+name: fast-review
+description: "Mandatory single-reviewer gate that runs after every agent delegation. Provides automatic retry with feedback and escalation to panel review after repeated failures. Essential for overnight/long-running autonomous sessions."
+---
+
+# Skill: Fast Review
+
+Mandatory lightweight review that runs after **every** agent delegation. Inspired by the [Steroids CLI](https://github.com/UnlikeOtherAI/steroids-cli) coder/reviewer separation pattern.
+
+## Why Fast Review Exists
+
+Panel reviews (3 reviewers, majority vote) are thorough but expensive and slow. Running them after every step is impractical. Without any review, agent output ships unchecked — risky for overnight runs where no human is watching.
+
+Fast review fills the gap: **a single reviewer sub-agent that validates every delegation output before acceptance**, with automatic retry and escalation.
+
+```
+                    ┌─────────────────────────────────┐
+                    │         Agent completes          │
+                    └────────────┬────────────────────┘
+                                 │
+                    ┌────────────▼────────────────────┐
+                    │     Fast Review (mandatory)      │
+                    │     Single reviewer sub-agent    │
+                    └────────────┬────────────────────┘
+                                 │
+                    ┌────────────▼────────────────────┐
+                    │          PASS?                   │
+                    ├── YES ──▶ Accept & continue      │
+                    ├── FAIL ──▶ Retry (up to 2x)     │
+                    └── 3x FAIL ──▶ Escalate to panel │
+                                                      │
+                    ┌─────────────────────────────────┐
+                    │   Panel Review (escalation)      │
+                    │   3 reviewers, majority vote     │
+                    ├── PASS ──▶ Accept                │
+                    ├── BLOCK ──▶ Re-delegate + retry  │
+                    └── 3x BLOCK ──▶ Dispute record   │
+                                       │
+                    ┌──────────────────▼──────────────┐
+                    │   Dispute (human decision)       │
+                    │   Both perspectives + options    │
+                    │   → Human picks resolution       │
+                    └─────────────────────────────────┘
+```
+
+## When to Use
+
+| Scenario | Use Fast Review | Use Panel Review |
+|----------|----------------|-----------------|
+| Any agent delegation output | **Always** (mandatory) | — |
+| Security changes (auth, RLS, headers) | ✅ then also → | **Always** |
+| DB migrations | ✅ then also → | **Always** |
+| Architecture decisions | ✅ then also → | **Always** |
+| Complex business logic without tests | ✅ then also → | **Recommended** |
+| Feature implementation with tests | ✅ | Only if fast review flags concerns |
+| Config changes, docs, simple fixes | ✅ | No |
+
+Fast review is **never skipped**. Panel review remains opt-in for high-stakes work, or triggers as escalation when fast review fails repeatedly.
+
+## Contract
+
+- Runs **after every delegation** — no exceptions.
+- Single reviewer sub-agent (not 3).
+- Uses Economy/Standard tier models (cost-efficient).
+- Produces PASS or FAIL with structured feedback.
+- On FAIL: automatic retry with reviewer feedback (up to 2 retries).
+- On 3rd FAIL: auto-escalates to panel review.
+- Total review time budget: ~2-5 minutes per review.
+
+## Reviewer Model Selection
+
+| Implementation Agent Tier | Reviewer Model | Rationale |
+|--------------------------|---------------|-----------|
+| Economy (GPT-5 mini) | GPT-5 mini | Peer-level review is sufficient |
+| Utility (GPT-5.3-Codex) | GPT-5 mini | One tier lower for cost savings |
+| Standard (Gemini 3.1 Pro) | GPT-5 mini | Economy is enough for structured checks |
+| Premium (Claude Opus 4.6) | Gemini 3.1 Pro | Premium work deserves Standard review |
+
+**Override:** If the task touches security, auth, or data integrity, upgrade the reviewer to Standard regardless of the implementation tier.
+
+## Procedure
+
+### Step 1: Collect Review Context
+
+Before spawning the reviewer, gather:
+
+1. **Issue** — acceptance criteria from the tracked issue
+2. **File diff** — list of changed files and their contents (or key sections)
+3. **File partition** — the agent's assigned files (to check for boundary violations)
+4. **Deterministic results** — lint, test, build output (already run as part of validation gates)
+5. **Agent's self-report** — what the agent claims to have done
+
+### Step 2: Spawn Reviewer Sub-Agent
+
+Launch a single `runSubagent` with the review prompt (see § Reviewer Prompt Template below).
+
+**Critical:** The reviewer runs in an isolated sub-agent context. It must NOT have access to the original delegation prompt — it reviews the *output*, not the *intent*. The acceptance criteria from the issue serve as the objective reference.
+
+### Step 3: Parse Verdict
+
+The reviewer must output this exact structure:
+
+```
+VERDICT: PASS | FAIL
+
+ISSUES:
+- [severity:critical|major|minor] Description of issue
+- [severity:critical|major|minor] Description of issue
+
+FEEDBACK:
+Specific, actionable feedback for the implementer if FAIL.
+
+CONFIDENCE: low | medium | high
+```
+
+**Verdict rules:**
+- **PASS** — No critical or major issues. Minor issues are noted but don't block.
+- **FAIL** — At least one critical or major issue found.
+
+**Auto-PASS conditions (skip reviewer):**
+- The delegation was pure research/exploration with no code changes
+- The delegation only modified documentation files (`.md`)
+- All deterministic gates already passed AND the change is ≤10 lines across ≤2 files
+
+### Step 4: Handle Verdict
+
+#### On PASS
+
+1. Accept the agent's output
+2. Log the review result (see § Logging)
+3. Continue orchestration
+
+#### On FAIL (attempt 1 or 2)
+
+1. Log the review result
+2. Extract the reviewer's ISSUES and FEEDBACK
+3. Re-delegate to the **same agent** with:
+   - Original task context
+   - Reviewer's feedback appended
+   - Instruction: "Address the following review feedback before resubmitting"
+   - Note: "This is retry attempt N/2 after fast review"
+4. After the agent re-submits, run fast review again (go back to Step 1)
+
+#### On FAIL (attempt 3 — escalation)
+
+1. Log the review result with `escalated: true`
+2. **Auto-escalate to panel review** — load the `panel-majority-vote` skill
+3. Include all 3 fast review reports as context for the panel
+4. The panel decides PASS/BLOCK with the standard majority vote protocol
+5. If panel PASS → accept with a note that it required escalation
+6. If panel BLOCK → follow the standard panel retry flow (max 3 panel attempts)
+7. If panel BLOCKs 3 times → create a **dispute record** in `.github/customizations/DISPUTES.md` (see **team-lead-reference** skill § Dispute Protocol)
+
+```
+Fast Review Attempt 1: FAIL → retry
+Fast Review Attempt 2: FAIL → retry
+Fast Review Attempt 3: FAIL → escalate to panel
+Panel Attempt 1: BLOCK → re-delegate with MUST-FIX
+Panel Attempt 2: BLOCK → re-delegate with MUST-FIX
+Panel Attempt 3: BLOCK → create dispute record for human resolution
+```
+
+## Reviewer Prompt Template
+
+```markdown
+You are a code reviewer. Your job is to verify that a delegated task was
+completed correctly. Be concise and specific. Focus on correctness, not style.
+
+## Task Under Review
+
+**Issue:** [ID] — [Title]
+**Acceptance Criteria:**
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+## Agent's File Partition (allowed files)
+[List of directories/files the agent was allowed to modify]
+
+## Changed Files
+[For each file: path, key sections of the diff or full new content]
+
+## Deterministic Check Results
+- Lint: [PASS/FAIL + details]
+- Tests: [PASS/FAIL + details]
+- Build: [PASS/FAIL + details]
+
+## Review Checklist
+
+Evaluate EACH item. Only flag issues you are confident about.
+
+1. **Acceptance criteria met** — Does the implementation satisfy every criterion?
+2. **File partition respected** — Were only allowed files modified?
+3. **No regressions** — Could any change break existing functionality?
+4. **Error handling** — Are errors surfaced clearly? No swallowed exceptions?
+5. **Type safety** — Proper TypeScript types? No `as any` or unsafe casts?
+6. **Security basics** — No exposed secrets, no injection vectors, no unsafe user input handling?
+7. **Edge cases** — Are obvious edge cases handled (null, empty, overflow)?
+
+## Previous Review Feedback (if retry)
+[Include prior FAIL feedback so the reviewer can verify fixes]
+
+## Output Format (MANDATORY — follow exactly)
+
+VERDICT: PASS | FAIL
+
+ISSUES:
+- [severity:critical|major|minor] Description
+
+FEEDBACK:
+Actionable feedback for the implementer.
+
+CONFIDENCE: low | medium | high
+```
+
+## Logging
+
+Append a JSON line to `customizations/logs/reviews.ndjson` after each fast review:
+
+```json
+{
+  "timestamp": "2026-02-28T14:30:00Z",
+  "linear_issue": "PRJ-42",
+  "agent": "Developer",
+  "reviewer_model": "gpt-5-mini",
+  "verdict": "pass",
+  "attempt": 1,
+  "issues_critical": 0,
+  "issues_major": 0,
+  "issues_minor": 2,
+  "confidence": "high",
+  "escalated": false,
+  "duration_sec": 45
+}
+```
+
+## Integration with Existing Workflow
+
+### Position in the Verification Loop
+
+Fast review sits between the agent's output and the Team Lead's acceptance:
+
+```
+Agent completes work
+       │
+       ▼
+Deterministic checks (lint, test, build)  ← validation-gates Gate 1
+       │
+       ▼
+Fast Review (this skill)                  ← validation-gates Gate 1.5
+       │
+       ├── PASS → Accept, move to next task
+       ├── FAIL → Retry loop (up to 2x)
+       └── 3x FAIL → Escalate to Panel (Gate 5)
+```
+
+### Relationship to on-post-delegate Hook
+
+Fast review is executed as part of the `on-post-delegate` hook in the agent-hooks skill. The hook sequence is:
+
+1. Verify output (file changes within partition)
+2. Run deterministic checks (lint, test, build)
+3. **Run fast review** ← inserted here
+4. Check acceptance criteria (reviewer does this too, as cross-check)
+5. Update issue
+
+### Skipping Panel Review
+
+When fast review passes, you can safely skip panel review for **non-high-stakes** tasks. The thresholds for mandatory panel review remain:
+
+- Security-sensitive changes
+- Database migrations
+- Architecture decisions
+- Complex business logic without test coverage
+
+These tasks get **both** fast review AND panel review.
+
+## Cost Impact
+
+Estimated cost per fast review:
+
+| Review Tier | Est. Tokens | Est. Duration |
+|-------------|-------------|---------------|
+| Economy reviewer | ~3K-8K tokens | 30-90 sec |
+| Standard reviewer | ~5K-12K tokens | 60-180 sec |
+
+For a typical 7-delegation session:
+- **Without fast review:** 0 review tokens
+- **With fast review:** ~20K-60K additional tokens (~5-15% overhead)
+- **With panel on every step:** ~150K-450K additional tokens (prohibitive)
+
+Fast review provides ~85% of the safety benefit of full panel review at ~15% of the cost.
+
+## Overnight/Long-Run Mode
+
+For autonomous overnight sessions, fast review is the primary quality gate. Additional considerations:
+
+1. **Lower PASS threshold** — In overnight mode, consider upgrading the reviewer model one tier for extra safety (no human in the loop to catch issues).
+2. **Stricter escalation** — Escalate to panel after 2 FAILs instead of 3 when running unattended.
+3. **Checkpoint on escalation** — If fast review escalates to panel during an overnight run, save a session checkpoint before proceeding. This allows human review of the escalation decision.
+4. **Aggregated review log** — At the end of an overnight session, generate a summary of all fast reviews (pass rate, common issues, escalations) as part of the session-end hook.
+
+## Anti-Patterns
+
+- **Skipping fast review** — Never. Not even for "trivial" changes. The cost is minimal, the risk of uncaught issues in overnight runs is high.
+- **Using Panel as fast review** — Panel is 3 reviewers with majority vote. Using it for every step wastes ~3x the tokens and time.
+- **Reviewer sees the delegation prompt** — The reviewer should evaluate output against acceptance criteria, not the prompt. This prevents rubber-stamping intent as completion.
+- **Ignoring minor issues** — Minor issues get a PASS verdict but should be tracked. If the same minor issue appears 3+ times across reviews, create a ticket.
+- **Manual override of FAIL** — The Team Lead should never force-accept a FAIL verdict. Either fix the issues through retry or escalate.
+- **Skipping deterministic checks** — Fast review does NOT replace lint/test/build. Those run first. The reviewer focuses on semantic correctness beyond what tools can check.
+
+## Metrics & Continuous Improvement
+
+Track these metrics from `reviews.ndjson` to optimize the review process:
+
+| Metric | Target | Action if Off-Target |
+|--------|--------|---------------------|
+| First-pass rate | > 80% | Improve delegation prompts with more specific acceptance criteria |
+| Escalation rate | < 5% | Review why agents fail 3x — prompts may be ambiguous |
+| False positive rate | < 10% | If reviewer FAILs work that's actually correct, adjust reviewer prompt |
+| Avg review duration | < 120 sec | If too slow, reduce review context or use a faster model |
+| Retry success rate | > 90% | If retries don't fix issues, the feedback isn't specific enough |
+
+Review these metrics monthly (or after every 50 reviews) and adjust the reviewer prompt template accordingly.
+
+````

package/src/orchestrator/skills/frontend-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics."
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

package/src/orchestrator/skills/jira-management/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: jira-management
+description: "Jira board conventions for tracking feature work — issue naming, labels, priorities, status workflow, and session continuity via Atlassian Rovo MCP. Use when decomposing features into tasks or resuming interrupted sessions."
+---
+
+# Task Management with Jira
+
+Conventions for tracking feature work on Jira via the Atlassian Rovo MCP server. For project-specific project keys, workflow state IDs, and board configuration, see [jira-config.md](../../customizations/project/jira-config.md).
+
+## Atlassian Rovo MCP Server
+
+The Atlassian Rovo MCP server connects to Jira (and Confluence) via `https://mcp.atlassian.com/v2/sse`. It uses OAuth authentication — users authenticate through their Atlassian account when the MCP connection is first established.
+
+**Available capabilities:**
+- Search Jira issues with JQL
+- Create and update issues
+- Read issue details, comments, and attachments
+- Search Confluence pages for context
+- Create Confluence pages
+
+**Rate limits** (per hour):
+- Free: 500 calls
+- Standard: 1,000 calls
+- Premium/Enterprise: 1,000 + 20 per user (up to 10,000)
+
+## Discovered Issues (Bug Tickets)
+
+When an agent encounters a pre-existing bug or issue unrelated to the current task, it must be tracked. Follow this flow:
+
+1. **Check** known issues docs and Jira (search for open bugs) to see if it's already tracked
+2. **If tracked** — skip it, continue with current work
+3. **If NOT tracked:**
+   - **Unfixable limitation** — add to known issues with Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
+   - **Fixable bug** — create a Jira issue:
+     - **Summary:** `[Area] Short description of the symptom`
+     - **Type:** Bug
+     - **Priority:** High if it affects users, Medium if cosmetic or non-blocking
+     - **Description:** Include symptoms, reproduction steps, affected files, and any error messages or screenshots
+     - **Status:** Backlog (unless it's blocking current work, then To Do)
+
+## Issue Naming
+
+Use `[Area] Short description` format in the Summary field:
+
+```
+[Schema] Add priceRange field to place type
+[DB] Add price_range column and migration
+[Query] Update query with priceRange filter
+[UI] Build PriceRangeFilter component
+[Page] Integrate price filter into /places
+[Test] E2E test price range filtering
+[Docs] Update data model documentation
+```
+
+**Area prefixes:** `[Schema]`, `[DB]`, `[Query]`, `[UI]`, `[Page]`, `[API]`, `[Auth]`, `[Test]`, `[Docs]`, `[Deploy]`, `[Data]`, `[Perf]`, `[Security]`
+
+## Priority
+
+| Jira Priority | Meaning | When to use |
+|---------------|---------|-------------|
+| Highest | Blocker | Blocks other tasks, critical path |
+| High | Important | Core feature work, on critical path |
+| Medium | Normal | Supporting tasks, can be parallelized |
+| Low | Nice-to-have | Docs, cleanup, polish |
+| Lowest | Backlog | Captured for future consideration |
+
+## Status Workflow
+
+```
+Backlog → To Do → In Progress → In Review → Done
+```
+
+- **Backlog** — Captured but not yet planned
+- **To Do** — Planned for current sprint/feature, ready to start
+- **In Progress** — Actively being worked on by an agent
+- **In Review** — PR opened, awaiting review/merge
+- **Done** — Completed and verified
+
+### Status Drivers
+
+Issue status is driven by **two sources** — the Team Lead agent (via MCP) and the Jira automation/GitHub integration (automatically).
+
+**Agent-driven transitions (via MCP):**
+- **To Do → In Progress** — when the agent starts working on a task
+- **In Progress → Done** — when non-PR tasks are verified (e.g., docs, config changes)
+
+**Automation-driven transitions:**
+If your Jira project has GitHub integration or automation rules configured, PR lifecycle events can auto-update issue status. Configure these in Jira under *Project settings → Automation*.
+
+**Linking issues to PRs:** Include the Jira issue key (e.g., `PROJ-123`) in the branch name or PR title. Use the branch name format: `<type>/<issue-key>-<short-description>`.
+
+## Issue Descriptions
+
+Every issue must include:
+
+```markdown
+**Objective:** One sentence describing the deliverable
+
+**Files (partition):**
+- `path/to/relevant/file.ts`
+- `path/to/another/file.ts`
+
+**Acceptance Criteria:**
+- [ ] Specific, verifiable outcome 1
+- [ ] Specific, verifiable outcome 2
+
+**Dependencies:** PROJ-XX (if any)
+```
+
+The **Files (partition)** section defines which files this agent is allowed to modify. This prevents merge conflicts when multiple agents work in parallel — no two issues in the same phase should list overlapping files.
+
+## Feature Grouping
+
+- Use a **Jira Epic** for each major feature
+- All related issues (Stories/Tasks) belong to that Epic
+- Issues track individual subtasks within the feature
+- Use components or labels for domain grouping (e.g., `frontend`, `backend`, `database`)
+
+## Session Workflow
+
+### Starting a new feature
+
+1. Search the board (JQL) to check for existing in-progress work
+2. Decompose the feature into issues following the conventions above
+3. Create all issues in Jira with correct naming, type, priority, and descriptions
+4. Link dependencies between issues using Jira issue links
+5. Begin delegation
+
+### During execution
+
+- Move issue to **In Progress** before delegating to an agent
+- Move issue to **Done** immediately after the agent completes and output is verified
+- Add comments to the issue if a task is blocked, explaining the blocker
+
+### Resuming an interrupted session
+
+1. Search issues by status (In Progress, To Do) in the project
+2. Read issue descriptions to restore context
+3. Pick up where work left off — no need to re-analyze from scratch
+
+### Completing a feature
+
+1. Verify all issues in the Epic are **Done** or closed
+2. Run final build/lint/test checks
+3. Close the Epic
+
+## JQL Quick Reference
+
+Common queries for agent workflows:
+
+```jql
+# Find in-progress work
+project = PROJ AND status = "In Progress" ORDER BY priority DESC
+
+# Find planned work
+project = PROJ AND status = "To Do" ORDER BY priority DESC
+
+# Find bugs
+project = PROJ AND type = Bug AND status != Done ORDER BY priority DESC
+
+# Find work in current sprint
+project = PROJ AND sprint in openSprints() ORDER BY priority DESC
+
+# Find blockers
+project = PROJ AND priority = Highest AND status != Done
+```
+
+Replace `PROJ` with the actual project key from [jira-config.md](../../customizations/project/jira-config.md).

package/src/orchestrator/skills/memory-merger/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: memory-merger
+description: "Protocol for graduating mature lessons from LESSONS-LEARNED.md into permanent instruction and skill files. Closes the self-improvement loop by codifying validated knowledge at the source level."
+---
+
+# Skill: Memory Merger
+
+This skill automates the final step of the self-improvement cycle: promoting validated lessons into the instruction and skill files where they have structural, permanent impact.
+
+## Why Merge?
+
+`.github/customizations/LESSONS-LEARNED.md` is a flatfile that grows over time. Lessons buried in a 400+ line file lose their impact — agents skim past them or miss relevant entries. The most valuable lessons should **graduate** into the instruction/skill files where they're encountered naturally during every task.
+
+## When to Run
+
+Invoke a memory merge when:
+
+- **LESSONS-LEARNED.md exceeds 50 entries** — periodic cleanup
+- **A lesson has been cited 3+ times** — it's clearly a recurring pattern
+- **A lesson is older than 60 days** — mature enough to be considered stable
+- **After a major feature ships** — good checkpoint to extract patterns
+- **Team Lead's discretion** — any time the lessons file feels stale
+
+## Merge Protocol
+
+### Step 1: Scan for Merge Candidates
+
+Read `.github/customizations/LESSONS-LEARNED.md` and identify lessons that meet any of these criteria:
+
+| Criterion | Signal |
+|-----------|--------|
+| **High frequency** | Cited or re-discovered 3+ times |
+| **High severity** | Marked `high` severity |
+| **Age** | Added more than 60 days ago and still relevant |
+| **Category concentration** | 5+ lessons in the same category → extract a pattern |
+| **Tool-specific** | Lesson about a specific MCP tool, NX command, or framework pattern |
+
+### Step 2: Map Lessons to Target Files
+
+Each lesson has a natural home in the instruction/skill hierarchy:
+
+| Lesson Category | Target File |
+|----------------|-------------|
+| `linear` | `.github/skills/task-management/SKILL.md` |
+| `mcp-tools` | The corresponding agent file or skill that uses the tool |
+| `nx-commands` | `.github/skills/nx-workspace/SKILL.md` |
+| `sanity` | `.github/skills/sanity-cms/SKILL.md` |
+| `supabase` | `.github/skills/supabase-database/SKILL.md` |
+| `browser-testing` | `.github/skills/browser-testing/SKILL.md` |
+| `git-workflow` | `.github/instructions/general.instructions.md` |
+| `deployment` | `.github/skills/deployment-infrastructure/SKILL.md` |
+| `delegation` | `.github/agents/team-lead.agent.md` or `.github/skills/team-lead-reference/SKILL.md` |
+| `testing` | `.github/skills/testing-workflow/SKILL.md` |
+| `react` / `nextjs` | Corresponding global skill file |
+| Cross-cutting pattern | `.github/instructions/general.instructions.md` |
+
+### Step 3: Draft the Merge
+
+For each candidate lesson, draft a concrete edit to the target file:
+
+```markdown
+**Lesson:** LES-XXX — [title]
+**Target:** [target file path]
+**Section:** [which section to add to or modify]
+**Edit:** [exact text to add or modify]
+**Rationale:** [why this belongs here rather than staying in lessons]
+```
+
+#### Merge Strategies
+
+- **Add a rule** — if the lesson reveals a new "always do X" or "never do Y", add it to the target file's rules section
+- **Add an anti-pattern** — if the lesson describes a common mistake, add it to an anti-patterns or "Common Mistakes" section
+- **Add a code example** — if the lesson includes a correct approach with a code block, add it as a documented pattern
+- **Expand existing rule** — if a rule already exists but the lesson adds nuance (edge case, exception), update the rule
+- **Add a table row** — if the target has a reference table, add the lesson as a new row
+
+### Step 4: Apply Edits
+
+1. Edit each target file with the drafted changes
+2. Add a comment or note attributing the source: `<!-- Merged from LES-XXX -->`
+3. Verify the edit reads naturally in context (not just pasted in)
+
+### Step 5: Archive the Merged Lessons
+
+Move merged lessons from the main body of `LESSONS-LEARNED.md` to an `## Archived (Merged)` section at the bottom of the file:
+
+```markdown
+## Archived (Merged)
+
+Lessons below have been merged into instruction/skill files. They are kept here for historical reference.
+
+### LES-XXX: [title] → Merged to `[target file]` on YYYY-MM-DD
+```
+
+**Do NOT delete lessons.** Archive them so they remain searchable and traceable.
+
+### Step 6: Update the Index
+
+Update the `## Index by Category` table in `LESSONS-LEARNED.md` to reflect which lessons are now archived.
+
+## Quality Gates
+
+Before finalizing a merge:
+
+- [ ] The merged content reads naturally in the target file (not copy-pasted)
+- [ ] The target file's structure and tone are preserved
+- [ ] No duplicate information created (check if a similar rule already exists)
+- [ ] The archived lesson references the target file
+- [ ] The lesson's core insight is preserved — don't lose nuance when summarizing
+
+## Anti-Patterns
+
+- **Don't merge too eagerly** — a lesson needs to prove itself (3+ citations or 60+ days) before graduating
+- **Don't copy verbatim** — lessons are written as incident reports; instruction files should read as rules/guidelines
+- **Don't merge conflicting lessons** — if two lessons contradict, resolve the conflict first
+- **Don't merge without context** — if the lesson only makes sense with the full story, either include enough context in the target file or keep it in LESSONS-LEARNED.md
+- **Don't create new files for merged content** — merge INTO existing files; only create new skills if a genuinely new domain emerges
+
+## Frequency
+
+- **Quarterly review** — schedule a full scan of LESSONS-LEARNED.md every ~3 months
+- **Post-feature review** — after major features ship, scan for relevant lessons
+- **Ad-hoc** — any time an agent notices "this lesson should be a permanent rule"