catalyst

Migrate a single-harness repo to the dual-harness layout so both Claude Code and Codex load the same instructions and skills — AGENTS.md as the portable canonical doc, a thin CLAUDE.md `@AGENTS.md` bridge, and a `.agents/skills` dir with a `.claude/skills` symlink onto it. Use when asked to migrate to dual-harness, make this repo work in both Claude and Codex, or for agent metadata cleanup.

Diagnose and fix Catalyst setup issues. Validates tools, database, config, OTel, direnv, and thoughts. Automatically fixes what it can — creates directories, initializes the database, sets WAL mode, runs migrations. Use for new installs, upgrades, or when something isn't working.

Fast browser automation CLI for AI agents. **ALWAYS use instead of Playwright MCP tools** for web testing, screenshots, form filling, and UI verification. Use when user says "open in browser", "check the site", "take a screenshot", "fill the form", "test the UI", or any browser interaction. Also use as a fallback when a task requires visual browser interaction that CLIs and APIs cannot handle (e.g., OAuth flows, complex dashboards, visual verification).

Goal-driven senior-engineer pipeline-unstick sweep (CTL-1176 rung 3). Given the stuck/failed/needs-human set (or ONE ticket handed by the recovery router), its GOAL is to get the pipeline MOVING again — not to fix one ticket's review findings (that is phase-remediate). It runs AFTER the eyes (diagnostician evidence) and the hands (deterministic unstuck-sweep seams) have already tried, and it CONSUMES their output from a recovery-pass.json brief rather than re-diagnosing or redoing their narrow work. It acts like a senior engineer with full tool access — it resolves merge conflicts, rebases, force-pushes, merges green PRs, and re-dispatches stalled phases AUTONOMOUSLY — and escalates to the operator ONLY for a genuine value judgment / something that degrades other functionality / a real cost-benefit trade-off / a serious architecture change / an ADR conflict. On escalation it AUTHORS the operator inbox row + the push notification (executive-voiced). Dispatched as a `claude --bg` job by phase-agent-dispatch via

Systematically pull, categorize, and address all PR review comments — code change requests, questions, and suggestions. This skill fetches comments via gh api, groups them by file, implements fixes, handles disagreements diplomatically, and pushes a single commit. You should not try to handle PR review feedback manually — this skill ensures nothing gets missed. **ALWAYS consult this skill when** the user says 'address comments', 'fix review feedback', 'handle PR comments', 'respond to reviewers', 'address review', 'review feedback', or mentions that a PR has unresolved comments or review threads. Also used by /oneshot Phase 5 to process reviewer feedback before merging.

Reference template every phase-agent skill copies (CTL-448). The leading underscore on the directory name prevents the skill loader from picking this up — it is NOT a runnable skill, only a structural template the nine real phase agents (phase-triage, phase-research, phase-plan, phase-implement, phase-verify, phase-review, phase-pr, phase-monitor-merge, phase-monitor-deploy) clone and specialize. The real phase skills MUST set `user-invocable: true` so `phase-agent-dispatch`'s `claude --bg "/catalyst-dev:phase-X ..."` slash command resolves (CTL-490).

Phase agent that triages a Linear ticket — expands acronyms, classifies (feature/bug/docs/refactor/chore), identifies genuine blockers (a semantic second-pass over the backlog — NOT a prose scrape; CTL-838), estimates scope, writes triage.json, and posts a triage analysis comment to Linear. Triage completion is signaled by that comment plus the local triage.json — there is no `triaged` label. Emits phase.triage.complete.<TICKET> on success and phase.triage.failed.<TICKET> on error. Dispatched by the phase-agent orchestrator (CTL-452) via slash command — `user-invocable: true` so the dispatcher's `claude --bg "/catalyst-dev:phase-triage ..."` resolves.

Shape every ticket around a scannable use-case before it's filed. **ALWAYS use when** the user says 'file a ticket', 'create a ticket', 'file tickets for', 'open an issue', 'add a ticket', 'log a bug', or whenever drafting, titling, or rewriting a ticket. Turns vague, implementation-first tickets into an outcome title (`<actor> should <outcome> so that <benefit>`) plus tiered Gherkin (Given/When/Then) acceptance criteria — even for backend bugs and chores.

Manage Linear tickets with workflow automation. **ALWAYS use when** the user says 'create a ticket', 'update the ticket', 'move ticket to', 'search Linear', or wants to create tickets from thoughts documents, update ticket status, or manage the Linear workflow. Uses Linearis CLI.

Linear access rule + Linearis CLI reference. READS → query the local replica by direct SQL (`~/catalyst/catalyst-replica.db`); WRITES and list/search → the `linearis` CLI. Use when working with Linear tickets, cycles, projects, milestones, or when the user mentions ticket IDs like TEAM-123, ENG-456, PROJ-789.

Phase agent for the research step of the 9-phase orchestrator pipeline (CTL-450). Wraps /catalyst-dev:research-codebase and produces thoughts/shared/research/<date>-<ticket>.md, then emits phase.research.complete.<ticket>. Reads triage.json from the worker dir as its prior-phase artifact. Spawned via plugins/dev/scripts/phase-agent-dispatch, which invokes it via slash command — hence `user-invocable: true`.

Coordinate multiple tickets in parallel across worktrees with wave-based execution, worker dispatch, and adversarial verification

Phase agent for the 10th/terminal step of the pipeline (CTL-703). Performs all terminal wrap-up after monitor-deploy — verifies the PR merged, posts a final Linear comment with per-phase timings, transitions Linear to Done (the sole Done writer now), archives the worker dir to ~/catalyst/archives/<TICKET>/, removes the local worktree + branch, then emits phase.teardown.complete.<TICKET>. Reads phase-monitor-deploy.json as its prior-phase artifact. Dispatched via phase-agent-dispatch as a slash command — user-invocable: true.

Phase agent that watches the post-merge deployment for a ticket. Reads the merge SHA from phase-monitor-merge.json (the signal file phase-monitor-merge writes after `gh pr merge` confirms via REST), subscribes via `catalyst-events wait-for` to deploy events on that SHA, then delegates a live verification check to the /canary skill (gstack). Emits phase.monitor-deploy.complete.<TICKET> on canary success, phase.monitor-deploy.failed.<TICKET> on deploy or canary failure, and phase.monitor-deploy.skipped.<TICKET> when no deploy event arrives before the timeout. Dispatched by the phase-agent orchestrator (CTL-452) via slash command — `user-invocable: true` so the dispatcher's `claude --bg "/catalyst-dev:phase-monitor-deploy ..."` resolves.

Closing ritual for the AI-native estimation feedback loop. **ALWAYS use when** a ticket's PR has just merged (runs automatically per ticket: merge-pr step 12b / phase-monitor-merge, CTL-189/CTL-831), or when the user says 'compound-estimate', 'close the estimation loop', 'record actuals', 'compound-log', or wants to log post-merge actuals for a shipped Linear ticket. Writes a structured entry (linear.key, pr_number, merged_at, estimate_at_start, estimate_actual, cost_usd, wall_time_hours, what_worked, what_surprised_me) to `thoughts/shared/retros/estimate/YYYY-WW-compound-log.md` — one file per ISO week, appends.

Generate or update PR description with incremental changes. **ALWAYS use when** the user says 'describe the PR', 'update PR description', 'generate PR description', or after pushing new commits to an existing PR. Supports incremental updates that preserve manual edits.

Generate a daily briefing markdown at thoughts/briefings/YYYY-MM-DD.md with six sections — Review yesterday, Surface decisions, Plan today, Suggest orchestrator runs, Friction since last briefing, and Learnings since last briefing — synthesized from Linear, GitHub, Granola, Google Drive, Google Calendar, and the compound-engineering stores (thoughts/shared/friction, thoughts/shared/learnings, thoughts/shared/compound/pending) in parallel. Then fans the briefing out to four destinations (Slack DM, Slack channel, Notion page, Loom script file). User-invoked from `/catalyst-dev:morning-briefing` for ad-hoc runs. The CMA Routine wraps the same skill on a weekday-morning schedule (Phase 5 of the parent plan).

Compound-engineering capture + curation for a finished ticket — the engineering feedback loop. Harvests the Friction sections that phase agents left in their artifacts plus the git diff, writes a structured entry to the shared learnings store (thoughts/shared/learnings/), prunes/amends stale notes there autonomously, captures new domain vocabulary to thoughts/shared/CONCEPTS.md, and PROPOSES (for human approval) any ADR change. Non-blocking — runs after a ticket ships or fails, never on the critical path. Use when the user says "compound this ticket", "capture learnings", "what did we learn", or run as /catalyst-dev:ticket-compound <TICKET> [mode:headless].

Reference for the canonical event-driven wait pattern in Catalyst skills. Use when a skill needs to block on a state change (PR merged, CI completed, push to branch, ticket transitioned) WITHOUT polling. Pairs the `catalyst-events` CLI with the Claude Code `Monitor` tool and `wait-for` for short-lived workers.

Protocol reference for the Catalyst event broker daemon. Covers agent identity (agent.checkin/ checkout), auto-correlation of ticket↔PR interests, ticket_lifecycle deterministic routing for Linear events, and the existing pr_lifecycle + Groq prose routing paths. Use when an agent needs to wait for events related to its own ticket/PR, watch another ticket's lifecycle, or register any semantic interest in the event stream.

Create detailed implementation plans through an interactive process. **ALWAYS use when** the user says 'plan this', 'create a plan', 'let's plan the implementation', 'design the approach', or wants a structured TDD implementation plan before writing code. Works best after /research-codebase.

Phase agent for the plan step of the 9-phase orchestrator pipeline (CTL-450). Wraps /catalyst-dev:create-plan and produces thoughts/shared/plans/<date>-<ticket>.md, then emits phase.plan.complete.<ticket>. Reads the prior research document from thoughts/shared/research/ as its prior-phase artifact. Spawned via plugins/dev/scripts/phase-agent-dispatch, which invokes it via slash command — hence `user-invocable: true`.

Conduct comprehensive codebase research using parallel sub-agents. **ALWAYS use when** the user asks to 'research', 'investigate', 'explore the codebase', 'how does X work', 'find out about', or needs deep analysis of how existing code is structured. Produces a research document in thoughts/shared/research/ with file:line references.

Validate and fix frontmatter consistency across all workflows

Implement approved technical plans from thoughts/shared/plans/. **ALWAYS use when** the user says 'implement the plan', 'start implementing', 'build from the plan', or wants to execute a previously created implementation plan using TDD (Red-Green-Refactor). Supports team mode for parallel implementation.

End-to-end autonomous workflow — research, plan, implement, validate, ship, and merge in one command. **ALWAYS use when** the user says 'oneshot', 'do everything end to end', 'full workflow', or wants to go from ticket/idea to merged PR autonomously. All phases run sequentially in the current session, using agent teams for parallelism when needed.

Research and catalog workflows from external Claude Code repositories

Import and adapt a workflow from external repositories

Observability / sensing-substrate cookbook for the recovery-pass delegate (and humans). Copy-paste-runnable LogQL + PromQL against the live OTel stack (Loki/Prometheus/Grafana) to see what the control loop is doing, detect silent freezes, read wedge signals, and turn each into an unstick action + a finding. **ALWAYS consult this skill when** the recovery-pass delegate (or a human) needs to query daemon logs/metrics, suspects the fleet is wedged or silently frozen, wants to count/see a wedge signal, detect a silent daemon (no logs in N minutes), or read cost/token/host-pressure metrics. Use when the user says "is the fleet stuck", "why isn't anything dispatching", "check the daemon logs", "query Loki", "query Prometheus", "is the monitor alive", or "what is the control loop doing".

Phase-agent that fixes a failing verify verdict so the pipeline self-heals instead of stalling to needs-human (CTL-653). Reads `${ORCH_DIR}/workers/<ticket>/verify.json`, fixes the `findings[]` (every severity:"high" plus the regression_risk drivers) directly via Edit/Write, commits the remediation, and emits `phase.remediate.complete.<ticket>`. The scheduler's router then re-dispatches `verify` to re-check (the verify⇄remediate cycle, cap 3). Dispatched as a `claude --bg` job by `phase-agent-dispatch`, which invokes it via slash command — hence `user-invocable: true`.

Phase-agent wrapper that opens the pull request after implementation completes (CTL-449 Initiative 1 Phase 3). Delegates to `/catalyst-dev:create-pr` (which already auto-runs `describe-pr` and transitions Linear to `inReview`), then writes the PR number + URL into the phase signal file so the downstream `phase-monitor-merge` agent can read it without re-querying GitHub. Dispatched as a `claude --bg` job by `phase-agent-dispatch`, which invokes it via slash command — hence `user-invocable: true`.

Phase-agent wrapper that drives TDD implementation from an approved plan (CTL-449 Initiative 1 Phase 3). Reads `thoughts/shared/plans/*-<ticket>.md`, delegates the red→green→refactor cycle to `/catalyst-dev:implement-plan`, commits each plan phase as it lands, and transitions the Linear ticket to `inProgress`. Dispatched as a `claude --bg` job by `phase-agent-dispatch`, which invokes it via slash command — hence `user-invocable: true`.

Phase-agent that watches the open PR through to merge (CTL-449 Initiative 1 Phase 3). Lifts the active listen loop from the legacy `oneshot` Phase 5 body: event-driven wait on `catalyst-events wait-for`, inline resolution of CI fix-ups, bot review threads, and BEHIND rebases, then `gh pr merge --squash --delete-branch` when the PR reaches CLEAN. Linear Done transition and worktree teardown are owned by phase-teardown (CTL-703). Dispatched as a `claude --bg` job by `phase-agent-dispatch`, which invokes it via slash command — hence `user-invocable: true`.

Phase agent for the review step of the 9-phase orchestrator pipeline (CTL-450). Wraps the /review skill (gstack) — explicitly skips /ultrareview per user decision. Reads verify.json from the prior phase, runs /review against the diff, writes ${ORCH_DIR}/workers/<TICKET>/review.json, and creates a remediation commit for any HIGH-severity finding that has a deterministic fix. Emits phase.review.complete.<ticket>. Spawned via phase-agent-dispatch via slash command — hence `user-invocable: true`.

Phase agent for the verify step of the 9-phase orchestrator pipeline (CTL-450). NEW skill — has no canonical wrapper. Runs read-only adversarial verification against the implement-phase diff: tsc, tests, lint, security scan, reward-hacking scan, code review, test coverage, silent-failure hunt. Writes ${ORCH_DIR}/workers/<TICKET>/verify.json then emits phase.verify.complete.<ticket>. Reads phase-implement.json as its prior-phase artifact. NEVER writes application code — only test files allowed. Spawned via phase-agent-dispatch via slash command — hence `user-invocable: true`.

Create pull request with automatic Linear integration. **ALWAYS use when** the user says 'create a PR', 'open a pull request', 'ship this', 'ready for review', or wants to push changes and create a GitHub PR. Handles commit, rebase, push, PR creation, description generation, and Linear ticket update.

Create tickets via Linear MCP or generate formatted ticket text

Safely merge PR with verification and Linear integration. **ALWAYS use when** the user says 'merge the PR', 'merge this', 'ship it', or wants to merge an approved pull request. Runs tests, checks CI, verifies approvals, squash merges, cleans up branches, and moves Linear ticket to Done.

Cross-ticket retrospective VIEW (CTL-789 Loop C / CTL-814). **ALWAYS use when** a ticket's PR has just merged (the workflow's compound closing step — runs automatically per ticket, CTL-831), or when the user says 'ticket retro', 'run a retro', 'retrospective', 'what did we learn lately', or 'how are the estimates calibrating'. Synthesizes everything the compound loops captured since the last retro — friction logs, learnings, compound-log calibration, catalyst.db / merged-PR actuals — into thoughts/shared/retros/ticket/<date>.md with a persisted watch-items block, and surfaces top patterns in the morning briefing's Plan today.

Interactive walk-through of today's morning briefing. Loads the briefing markdown at