opencastle 0.1.0

package/src/orchestrator/prompts/bug-fix.prompt.md

@@ -0,0 +1,141 @@
+---
+description: 'Investigate and fix a reported bug with proper triage, root cause analysis, Linear tracking, and verification.'
+agent: Team Lead
+---
+
+# Fix Bug
+
+You are the Team Lead. Investigate and fix the bug described below. Bugs are real defects that affect users — treat them seriously with proper triage, tracking, and verification.
+
+## Bug Report
+
+{{bugDescription}}
+
+---
+
+> **Canonical workflow:** `.github/agent-workflows/bug-fix.md` defines the phase structure. This prompt expands each phase with delegation-specific detail. If the two diverge, update the workflow first (SSOT) then sync the prompt.
+
+## How Bug Fixes Differ from Other Workflows
+
+| Aspect | Roadmap Task | Follow-Up | Bug Fix |
+|--------|-------------|-----------|---------|
+| Linear tracking | Required | Not required | **Required** |
+| Urgency | Planned | Low | Can be critical |
+| Root cause analysis | Feature design | Not needed | **Required** |
+| Reproduction steps | N/A | N/A | **Required** |
+| Panel review | High-stakes only | Rarely | If security-related |
+| Documentation | Roadmap + ADRs | Minimal | Known issues if needed |
+| Scope | Multi-step feature | Focused tweak | Focused fix |
+
+## Workflow
+
+### 1. Triage & Reproduce
+
+Before fixing anything, understand the bug:
+
+1. **Check known issues** — Search `docs/KNOWN-ISSUES.md` for an existing entry. If found, note workarounds and decide if a fix is now feasible
+2. **Check Linear** — Search for existing bug tickets. If one exists, take it over instead of creating a duplicate
+3. **Read lessons learned** — Check `.github/customizations/LESSONS-LEARNED.md` for related pitfalls
+4. **Reproduce the bug** — Start the dev server and confirm you can trigger the issue:
+   - `yarn nx run <app>:serve`
+   - Navigate to the affected page in Chrome
+   - Follow the reproduction steps from the bug report
+   - Take a screenshot of the broken state as evidence
+5. **Determine scope** — Which apps are affected? (see `project.instructions.md` for the app inventory)
+6. **Assess severity**:
+   - **Critical** — App crashes, data loss, auth bypass, page won't load
+   - **High** — Feature broken but workaround exists, significant UI breakage
+   - **Medium** — Minor functional issue, cosmetic but noticeable
+   - **Low** — Edge case, minor visual glitch
+
+### 2. Create Linear Issue
+
+Every bug gets tracked. Create a Linear issue with:
+
+- **Title**: `[Bug] Short description of the symptom`
+- **Label**: `bug`
+- **Priority**: Based on severity assessment above
+- **Description**:
+  - **Symptom**: What the user sees
+  - **Reproduction steps**: Exact steps to trigger
+  - **Expected behavior**: What should happen
+  - **Actual behavior**: What happens instead
+  - **Affected apps**: which apps from the project inventory
+  - **Affected files** (once identified): File paths for the partition
+  - **Screenshot**: Link or description of the broken state
+
+### 3. Root Cause Analysis
+
+Find WHY the bug happens, not just WHERE:
+
+1. **Search the codebase** — Find the components, queries, styles, and logic involved
+2. **Trace the data flow** — Follow the data from source (CMS/database) → query → component → render
+3. **Check recent changes** — Use `git log` on suspected files to see if a recent commit introduced the issue
+4. **Identify the root cause** — Distinguish between:
+   - **Code bug** — Logic error, wrong condition, missing null check
+   - **Data issue** — Unexpected data shape, missing field, bad reference
+   - **Race condition** — Timing issue, hydration mismatch, async ordering
+   - **CSS/Layout** — Specificity conflict, missing responsive rule, overflow
+   - **Integration** — API contract mismatch, schema drift, stale cache
+5. **Update the Linear issue** — Add root cause findings and affected file paths
+
+### 4. Implement the Fix
+
+Delegate to the appropriate specialist agent via **sub-agent** (inline). For bugs that are clearly isolated and well-understood, a single delegation is usually sufficient.
+
+#### Delegation Prompt Must Include
+
+- **Linear issue ID and title** — e.g., `TAS-XX — [Bug] Description`
+- **Root cause** — What's wrong and why
+- **Fix approach** — How to fix it (be specific)
+- **File paths** — Exact files to read and modify
+- **Reproduction steps** — So the agent can verify the fix
+- **Boundaries** — "Only modify files listed above. Fix the bug, do not refactor surrounding code."
+- **Self-improvement reminder** — include per `general.instructions.md` § Self-Improvement Protocol
+
+#### Implementation Rules
+
+- **Minimal change** — Fix the bug with the smallest correct change. Resist the urge to refactor
+- **Fix the cause, not the symptom** — A CSS `!important` or silent `catch {}` is not a fix
+- **DRY** — If the fix involves logic that exists elsewhere, reuse it
+- **Add a test** — If no test covers this scenario, add one. Bugs that aren't tested come back
+- **Cross-app awareness** — If the fix is in shared code (`libs/`), verify it works for both apps
+
+### 5. Validate
+
+> Load the **validation-gates** skill for detailed steps on each gate.
+
+Every bug fix must pass ALL of these checks:
+
+1. **Deterministic Checks** — `yarn nx run <project>:lint --fix`, `:test`, `:build` — all zero errors
+2. **Bug-Specific Verification** (mandatory) — start dev server, reproduce original bug (should be gone), verify correct behavior, test edge cases, screenshot before/after, check both apps if shared code
+3. **Regression Check** — run tests for all projects consuming modified files, browser-test adjacent functionality
+4. **Panel Review** (only if needed) — use **panel-majority-vote** skill if fix touches auth/authorization, RLS, security headers/CSP, or sensitive data
+
+### 6. Delivery
+
+Follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to Linear.
+
+### 7. Wrap Up
+
+1. **Move Linear issue to Done** — Only after all validation passes
+2. **Update Known Issues** — If this was a documented known issue, remove or update the entry in `docs/KNOWN-ISSUES.md`
+3. **Capture lessons** — If the root cause reveals a pattern that other agents should know about, add it to `.github/customizations/LESSONS-LEARNED.md`
+4. **Note prevention** — If this class of bug could be caught earlier (by a lint rule, test, or type check), note that in the Linear issue as a follow-up suggestion
+
+### 8. Completion Criteria
+
+The bug fix is complete when:
+
+- [ ] Bug is reproduced and root cause identified
+- [ ] Linear issue created with full details
+- [ ] Fix implemented with minimal change
+- [ ] Test added covering the bug scenario
+- [ ] Lint, test, and build pass for all affected projects
+- [ ] Bug verified fixed in the browser
+- [ ] No regressions in adjacent functionality
+- [ ] Both apps checked if shared code was modified
+- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+- [ ] Linear issue moved to Done
+- [ ] Known issues updated if applicable
+- [ ] Lessons learned captured if any retries occurred

package/src/orchestrator/prompts/create-skill.prompt.md

@@ -0,0 +1,103 @@
+---
+description: 'Scaffold a new skill directory with proper frontmatter, structure, and content sections. Use when adding a new domain skill to the AI configuration.'
+agent: Team Lead
+---
+
+# Create Skill
+
+Scaffold a new skill for the AI agent configuration. Skills encode domain-specific knowledge that agents load on demand.
+
+## Skill Request
+
+{{skillDescription}}
+
+---
+
+## Workflow
+
+### Step 1: Determine Scope
+
+Classify the skill:
+
+| Scope | Prefix | When to Use |
+|-------|--------|-------------|
+| **Global** | `global-` | Domain knowledge applicable to any project (React, testing, security) |
+| **Local** | `local-` | Project-specific conventions (Linear config, Sanity schema patterns, this project's API structure) |
+
+### Step 2: Name the Skill
+
+- Format: `<scope>-<domain>` (e.g., `global-react-development`, `local-sanity-cms`)
+- Use kebab-case
+- Be specific enough to distinguish from other skills, broad enough to be reusable
+- Check existing skills in `.github/skills/` to avoid overlap
+
+### Step 3: Create the Skill File
+
+Create `.github/skills/<skill-name>/SKILL.md` with this structure:
+
+```markdown
+````skill
+---
+name: <skill-name>
+description: "<One-line description of what the skill covers. Include key topics and when to use it.>"
+---
+
+# Skill: <Display Name>
+
+<1-2 sentence overview of the skill's purpose and scope.>
+
+## When to Use
+
+- <Trigger condition 1>
+- <Trigger condition 2>
+- <Trigger condition 3>
+
+## Core Principles
+
+1. **<Principle>** — <Explanation>
+2. **<Principle>** — <Explanation>
+3. **<Principle>** — <Explanation>
+
+## <Domain Section 1>
+
+<Content organized by topic. Use tables, code blocks, and checklists.>
+
+## <Domain Section 2>
+
+<More domain content.>
+
+## Checklist
+
+- [ ] <Verification item 1>
+- [ ] <Verification item 2>
+
+## Anti-Patterns
+
+- **<Bad pattern>** — <Why it's bad and what to do instead>
+- **<Bad pattern>** — <Why it's bad and what to do instead>
+````
+```
+
+### Step 4: Register the Skill
+
+1. **Add to the skill matrix** — Update `.github/customizations/agents/skill-matrix.md` with the new skill mapping
+2. **Add to relevant agents** — Update the `skills` section in each agent that should use this skill
+3. **Reference in instructions** — If the skill is loaded by default, add it to the appropriate `.github/instructions/` file
+
+### Step 5: Validate
+
+- [ ] File created at `.github/skills/<name>/SKILL.md`
+- [ ] Frontmatter has `name` and `description` fields
+- [ ] Description is a single line (no line breaks)
+- [ ] Content follows the template structure
+- [ ] No overlap with existing skills
+- [ ] Skill matrix updated
+- [ ] At least one agent references the skill
+
+## Quality Guidelines
+
+- **Be prescriptive** — Skills should give clear instructions, not vague advice. "Use `fetchPlaces()` from `libs/queries`" beats "use the query library"
+- **Include examples** — Code snippets, file path examples, and table references from the actual codebase
+- **Keep it scannable** — Use headings, tables, bullets, and code blocks. Agents need to find information fast
+- **Avoid duplication** — If a rule already exists in `.github/instructions/`, reference it instead of repeating it
+- **Size target** — 100-300 lines. Under 100 is probably too thin; over 300 should be split into multiple skills

package/src/orchestrator/prompts/generate-task-spec.prompt.md

@@ -0,0 +1,154 @@
+---
+description: 'Generate a valid opencastle.tasks.yml spec file for autonomous overnight runs based on a high-level description of what needs to be done.'
+agent: Team Lead
+---
+
+# Generate Task Spec for Autonomous Run
+
+You are the Team Lead. The user wants to run `opencastle run` to execute a batch of tasks autonomously (e.g., overnight). Your job is to produce a valid `opencastle.tasks.yml` file they can feed to the CLI.
+
+## User Goal
+
+{{goal}}
+
+## Additional Context
+
+{{context}}
+
+---
+
+## YAML Spec Schema Reference
+
+The output file must conform to the following schema. Fields marked **(required)** cause validation errors if missing.
+
+### Top-Level Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | **yes** | — | Human-readable name for the run |
+| `concurrency` | integer ≥ 1 | no | `1` | Max tasks executing in parallel |
+| `on_failure` | `continue` \| `stop` | no | `continue` | Behaviour when a task fails |
+| `adapter` | string | no | `claude-code` | Default CLI adapter (`claude-code`, `copilot`, `cursor`) |
+| `tasks` | list | **yes** | — | Non-empty list of task objects |
+
+### Task Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `id` | string | **yes** | — | Unique identifier (lowercase, kebab-case recommended) |
+| `prompt` | string | **yes** | — | The instruction sent to the AI agent |
+| `agent` | string | no | `developer` | Agent role hint (see Agent Roster below) |
+| `description` | string | no | same as `id` | Short human label shown in progress output |
+| `depends_on` | list of ids | no | `[]` | Task ids that must finish before this one starts |
+| `files` | list of globs | no | `[]` | File scope the agent is allowed to modify |
+| `timeout` | duration | no | `30m` | Max wall time (`<number><s|m|h>`, e.g. `10m`, `1h`) |
+
+### Agent Roster
+
+Available values for the `agent` field:
+
+`api-designer` · `architect` · `content-engineer` · `copywriter` · `data-expert` · `database-engineer` · `developer` · `devops-expert` · `documentation-writer` · `performance-expert` · `release-manager` · `researcher` · `security-expert` · `seo-specialist` · `team-lead` · `testing-expert` · `ui-ux-expert`
+
+### Adapter Options
+
+| Adapter | CLI binary | Notes |
+|---------|-----------|-------|
+| `claude-code` | `claude` | Default. JSON output, max-turns flag. |
+| `copilot` | `copilot` | Uses `--autopilot --allow-all-tools`. |
+| `cursor` | `agent` | Uses `--force` for unattended file writes. |
+
+---
+
+## Workflow
+
+### 1. Analyse the Goal
+
+- Read the user's goal carefully. Identify the **deliverables** — what must exist or change after the run completes.
+- If context references a codebase, search it to understand current state, file layout, and conventions.
+- List the high-level workstreams (e.g., "database changes", "UI components", "tests", "docs").
+
+### 2. Decompose into Tasks
+
+For each workstream, break it down into the smallest meaningful unit of work that can be expressed as a single AI prompt. Follow these rules:
+
+1. **Single responsibility** — each task does exactly one thing.
+2. **Self-contained prompt** — the `prompt` field must contain everything the agent needs: objective, file paths, constraints, acceptance criteria. The agent has no other context.
+3. **Explicit file scopes** — list every directory or file the task may touch in `files`. This prevents conflicts between parallel tasks.
+4. **Appropriate agent** — pick the agent whose speciality matches the task (e.g., `testing-expert` for tests, `database-engineer` for migrations).
+5. **Realistic timeouts** — default 30 m is fine for most tasks; use `1h` for large refactors or test suites; use `10m` for small docs or config changes.
+
+### 3. Define the Dependency Graph (DAG)
+
+- Tasks with no dependencies go first (they run in parallel up to `concurrency`).
+- Tasks that consume output of earlier tasks declare `depends_on` with the prerequisite ids.
+- **Never create cycles** — if A depends on B, B must not depend on A (directly or transitively).
+- Draw the implicit phase structure:
+  ```
+  Phase 1: [independent tasks]
+  Phase 2: [tasks depending only on Phase 1]
+  Phase 3: [tasks depending on Phase 2]
+  ...
+  ```
+
+### 4. Set Global Options
+
+- `concurrency` — set to 2–3 for overnight runs; keep at 1 if tasks share files or the machine is constrained.
+- `on_failure` — use `continue` (default) when tasks are independent so one failure doesn't waste the whole run. Use `stop` when every subsequent task depends on success.
+- `adapter` — pick based on which CLI the user has installed.
+
+### 5. Write the Prompts
+
+Each task `prompt` must be a **complete, standalone instruction**. Include:
+
+- **What** to build / change / fix.
+- **Where** — exact file paths or directories.
+- **Why** — business context so the agent can make good decisions.
+- **Constraints** — coding standards, conventions, do-not-touch files.
+- **Acceptance criteria** — bullet list of pass conditions.
+- **Verification command** — e.g., `Run: yarn nx run project:test` so the agent self-checks.
+
+> **Weak prompt:** "Add tests for the auth module."
+>
+> **Strong prompt:** "Write unit tests for `libs/auth/src/server.ts` covering token refresh, expiry edge cases, and invalid signatures. Place tests in `libs/auth/src/__tests__/server.test.ts`. Follow the existing Jest conventions (see `jest.preset.js`). Achieve ≥ 95 % coverage for `server.ts`. Run: `yarn nx run auth:test --coverage` and fix any failures."
+
+### 6. Validate Before Outputting
+
+Before presenting the YAML, mentally verify:
+- [ ] Every task has a unique `id`
+- [ ] Every `depends_on` reference points to a valid `id` defined earlier in the list
+- [ ] No dependency cycles exist
+- [ ] No two parallel tasks share the same `files` entries (partition check)
+- [ ] Prompts are self-contained — an agent with zero context can execute them
+- [ ] Timeouts are reasonable for the scope of each task
+
+### 7. Output
+
+Return the final YAML inside a fenced code block with a filename annotation:
+
+````yaml
+# opencastle.tasks.yml
+name: <run name>
+concurrency: <n>
+on_failure: <continue|stop>
+adapter: <adapter>
+
+tasks:
+  - id: <task-id>
+    agent: <agent>
+    description: <short label>
+    timeout: <duration>
+    files:
+      - <glob>
+    prompt: |
+      <full self-contained instruction>
+
+  - id: <next-task-id>
+    depends_on:
+      - <task-id>
+    ...
+````
+
+Also provide:
+1. A **DAG summary** showing the phase structure so the user can verify execution order.
+2. An **estimated total duration** (sum of timeouts on the critical path).
+3. A `--dry-run` command they can use to validate: `opencastle run --file opencastle.tasks.yml --dry-run`

package/src/orchestrator/prompts/implement-feature.prompt.md

@@ -0,0 +1,124 @@
+---
+description: 'Instruct the Team Lead to implement a specific task from the post-MVP roadmap with full orchestration, validation, and traceability.'
+agent: Team Lead
+---
+
+# Implement Roadmap Task
+
+You are the Team Lead. Implement the roadmap task described below following this strict workflow. The task comes from `docs/ROADMAP-POST-MVP.md`.
+
+## Task
+
+{{roadmapTask}}
+
+---
+
+> **Canonical workflow:** `.github/agent-workflows/feature-implementation.md` defines the phase structure. This prompt adds Linear traceability, validation gate references, and completion criteria.
+
+## Workflow
+
+> **HARD GATE:** Steps 1→2 are **blocking prerequisites**. Do NOT write, edit, or delegate any code until Linear issues exist for every subtask. If you catch yourself writing code before issues are created, STOP immediately, create the issues, then resume.
+
+### 1. Research & Context Gathering
+
+Before writing any code, gather all relevant context:
+
+1. **Read the roadmap** — Open `docs/ROADMAP-POST-MVP.md` and find the full scope, status, and acceptance criteria for this task
+2. **Read known issues** — Check `docs/KNOWN-ISSUES.md` for blockers or workarounds that affect this task
+3. **Read architecture docs** — Check `docs/PROJECT.md` and `docs/DECISIONS.md` for constraints and prior decisions
+4. **Read lessons learned** — Check `.github/customizations/LESSONS-LEARNED.md` for pitfalls relevant to this feature area
+5. **Search existing code** — Find all files, components, queries, and tests related to this feature area
+6. **Identify reusable code** — Before creating anything new, check if similar logic, components, or utilities already exist in the codebase that can be reused or extended
+
+### 2. Linear Board Setup (BLOCKING — must complete before Step 3)
+
+Every subtask must be tracked on Linear. **No issue = no implementation.** This step produces the issues that gate all downstream work.
+
+1. **Check existing issues** — Search the board for any in-progress or completed work related to this task
+2. **Decompose into issues** — Create one Linear issue per subtask using `[Area] Short description` naming
+3. **Set metadata** — Assign labels (agent name), priority, dependencies, and file partitions
+4. **Write descriptions** — Each issue must include:
+   - **Objective:** One sentence
+   - **Files (partition):** Exact paths this agent may modify
+   - **Acceptance criteria:** Verifiable checklist
+   - **Dependencies:** Links to prerequisite issues
+5. **Link to roadmap** — Reference the roadmap section in the issue description so context is never lost
+6. **Verify issues exist** — List all created issue IDs. If count is 0, do NOT proceed to Step 3
+
+### 3. Implementation Rules
+
+#### Linear Issue Traceability
+
+- **Pass issue ID to every agent** — When delegating a subtask (sub-agent or background), include the Linear issue ID and title in the prompt so the agent knows which tracked task it is completing
+- **Reference in commits** — Include the issue ID (e.g., `TAS-42`) in commit messages when possible
+- **Update issue status** — Move issues to In Progress before starting, Done after verification passes
+
+#### DRY Code
+
+- **Search before creating** — Before writing any new component, hook, utility, query, or type, search the codebase for existing implementations
+- **Extract shared logic** — If two agents need similar functionality, extract it to a shared library (`libs/`) first
+- **No copy-paste across apps** — Shared code belongs in shared libraries, not duplicated between apps
+- **Refactor on discovery** — If you find duplicated code during implementation, create a subtask to consolidate it
+
+#### Self-Improvement
+
+Include the self-improvement reminder in every delegation prompt (see `general.instructions.md` § Self-Improvement Protocol).
+
+#### Visual Consistency
+
+- **Reuse existing components** — Use the shared component library; never re-implement a component that already exists
+- **Follow the design system** — Match spacing, typography, colors, and interaction patterns from existing pages
+- **Cross-app consistency** — Changes must look correct in all apps that share the codebase
+- **Browser verification required** — Every UI change must be visually confirmed in Chrome (see Testing below)
+
+### 4. Validation & Testing
+
+> Load the **validation-gates** skill for detailed steps on each gate.
+
+Every subtask must pass ALL gates before being marked Done:
+
+1. **Gate 1: Deterministic Checks** — `yarn nx run <project>:lint --fix`, `:test`, `:build` — all zero errors
+2. **Gate 2: Browser Testing** (MANDATORY for UI changes) — clear cache, start server, verify features + responsive + screenshots
+3. **Gate 3: Regression Testing** — full test suite for affected projects, browser-test adjacent pages if shared components changed
+4. **Gate 4: Panel Review** (for high-stakes changes) — use **panel-majority-vote** skill for security, DB migrations, architecture
+
+### 5. Delivery
+
+Follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to Linear.
+
+### 6. Documentation & Traceability
+
+Keep documentation current so future sessions have full context:
+
+1. **Update roadmap** — Mark completed items in `docs/ROADMAP-POST-MVP.md` with ✅ and the completion date. **Include Linear issue IDs and links** next to each scope item so progress is traceable across sessions. Format:
+   ```
+   **Linear Issues:**
+   - [PREFIX-6](https://linear.app/<workspace>/issue/PREFIX-6) — [Search] Description ✅ Done
+   - [PREFIX-7](https://linear.app/<workspace>/issue/PREFIX-7) — [UI] Description 📋 Todo
+   ```
+   > Replace `PREFIX` and `<workspace>` with the project's Linear prefix and workspace slug (see `linear-config.md`).
+2. **Update known issues** — If new limitations are discovered, add them to `docs/KNOWN-ISSUES.md`
+3. **Update architecture docs** — If architectural decisions were made, add an ADR to `docs/DECISIONS.md`
+4. **Link Linear issues** — Every issue description should reference:
+   - Related roadmap section
+   - Files modified (the partition)
+   - Related issues (dependencies and follow-ups)
+5. **Close issues properly** — Move to Done only after independent verification passes all gates
+
+### 7. Completion Criteria
+
+The roadmap task is complete when:
+
+- [ ] All Linear subtask issues are Done
+- [ ] All deterministic checks pass (lint, test, build) for affected projects
+- [ ] **Dev server started with CLEAN cache** (`rm -rf .next && yarn nx reset` before serving)
+- [ ] **All UI changes verified in Chrome browser via MCP with screenshots taken as proof**
+- [ ] **Every feature in the acceptance criteria visually confirmed** — not just "page loads"
+- [ ] Regression tests confirm no existing functionality is broken
+- [ ] No duplicated code — shared logic extracted to libraries
+- [ ] Visual consistency maintained across all affected pages and apps
+- [ ] Documentation updated (roadmap, known issues, decisions)
+- [ ] Panel review passed for any high-stakes changes
+- [ ] Roadmap item marked complete in `docs/ROADMAP-POST-MVP.md`
+- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+- [ ] Lessons learned captured if any retries occurred

package/src/orchestrator/prompts/metrics-report.prompt.md

@@ -0,0 +1,142 @@
+---
+description: 'Collect and report metrics from agent logs, GitHub PRs, Linear issues, and Vercel deployments'
+agent: Researcher
+---
+
+# Metrics Report
+
+Generate a comprehensive metrics dashboard from all project data sources.
+
+## Data Sources
+
+Collect data from ALL of these sources. Run collections in parallel where possible.
+
+### 1. Agent Session Logs (local)
+
+Read `.github/customizations/logs/sessions.ndjson` and `.github/customizations/logs/delegations.ndjson`.
+
+Compute:
+- **Total sessions** and **sessions per agent**
+- **Success rate** — `outcome` field breakdown (success / partial / failed)
+- **Retries per session** — average and total
+- **Lessons added** — count and which agents contribute most
+- **Delegation stats** — mechanism (sub-agent vs background), tier distribution, success rate per agent
+- **Model usage** — which models used how often
+- **Activity timeline** — sessions per day/week
+
+### 2. GitHub PRs and Commits
+
+Use `gh` CLI commands (always prefix with `GH_PAGER=cat`):
+
+```bash
+# All PRs (open + closed + merged)
+GH_PAGER=cat gh pr list --state all --limit 100 --json number,title,state,createdAt,mergedAt,closedAt,author,additions,deletions,changedFiles,labels,headRefName
+
+# Recent commits on main
+GH_PAGER=cat gh api repos/{owner}/{repo}/commits --paginate -q '.[0:50] | .[] | {sha: .sha[0:7], date: .commit.author.date, message: .commit.message}' 2>/dev/null || git --no-pager log main --oneline -50
+```
+
+Compute:
+- **PR count** — total, open, merged, closed-without-merge 
+- **Merge rate** — merged / (merged + closed-without-merge)
+- **Time to merge** — median and average (createdAt → mergedAt)
+- **PR size** — average additions, deletions, changedFiles
+- **Commit frequency** — commits per day/week on main
+- **Bogus/closed PRs** — PRs closed without merge (potential failed agent work)
+
+### 3. Linear Issues
+
+Use Linear MCP tools (`list_issues`, `search_issues`):
+
+```
+list_issues with status filter for each state: Backlog, Todo, In Progress, Done, Cancelled
+```
+
+Compute:
+- **Issue count by status** — Backlog, Todo, In Progress, Done, Cancelled
+- **Completion rate** — Done / (Done + Cancelled + In Progress + Todo)
+- **Issues by label** — which areas have the most work
+- **Issues by priority** — distribution across Urgent/High/Medium/Low
+- **Cycle time** — average time from In Progress → Done (if dates available)
+- **Stale issues** — In Progress for >7 days without updates
+
+### 4. Vercel Deployments
+
+Use Vercel MCP tools (`list_deployments`, `get_deployment`):
+
+Query deployments for all configured apps (see `project.instructions.md` for the app inventory).
+
+Compute:
+- **Total deployments** — count over last 30 days
+- **Deployment success rate** — ready / (ready + error + cancelled)
+- **Failure rate** — error / total
+- **Build times** — average, median, p95
+- **Deployments per day** — activity timeline
+- **Failed deployment details** — which commits/branches failed and why (use `get_deployment_build_logs` for recent failures)
+
+### 5. Panel Reviews (local)
+
+Read `.github/customizations/logs/panels.ndjson`.
+
+Compute:
+- **Total reviews** — count of panel runs
+- **Pass rate** — pass / total
+- **Must-fix vs should-fix** — average counts per review
+- **Retry rate** — reviews with attempt > 1
+- **Model usage** — which reviewer models used
+- **Reviews by panel key** — what gets reviewed most
+
+### 6. Agent Failures (DLQ)
+
+Read `.github/customizations/AGENT-FAILURES.md`.
+
+Compute:
+- **Total failures** — count of DLQ entries
+- **Failures by agent** — which agents fail most
+- **Failure status** — pending vs resolved
+- **Common root causes** — categorize failure reasons
+
+## Report Format
+
+Present the report as a structured markdown summary with these sections:
+
+```markdown
+# Project Metrics Dashboard
+> Generated: {date}  |  Period: Last 30 days
+
+## Executive Summary
+- X agent sessions, Y% success rate
+- Z PRs merged, W% merge rate  
+- N deployments, M% success rate
+- P Linear issues completed
+
+## Agent Activity
+{sessions table, success rates, model usage}
+
+## Delegation Performance  
+{per-agent delegation stats, tier distribution}
+
+## GitHub
+{PR stats, merge rates, commit frequency}
+
+## Linear Board
+{issue distribution, completion rate, stale issues}
+
+## Vercel Deployments
+{success rate, failure rate, build times}
+
+## Panel Reviews
+{pass rate, retry rate, must-fix/should-fix stats}
+
+## Agent Failures (DLQ)
+{failure count, pending items}
+
+## Trends & Recommendations
+{observations, areas for improvement}
+```
+
+## Usage
+
+Run this prompt periodically (weekly recommended) to track project health. Compare with previous reports to identify trends.
+
+If session logs are empty (no data yet), still collect GitHub/Linear/Vercel data and note that agent logging has just been enabled.