canary-lab

Use when creating or extending a Canary Lab feature by hand — "create a feature for X", "add test cases to <feature>", "capture the env files", "switch the feature's branch" — through the author MCP tools (create_feature, capture_feature_env_files, write_envset, start/update/apply_external_draft, get_feature_repo_status, checkout_feature_repo_branch). For docs/PRD/coverage use canary-lab-coverage; for full onboarding of a bare repo use canary-lab (flight).

Use when working the Canary Lab semantic coverage ledger — "what's actually tested?", "map coverage for <feature>", "refresh the PRD summary", "close the coverage gaps", "add this plan/spec to the feature docs" — through the coverage MCP tools (write/list/delete_feature_doc, start/submit_external_summary, start/submit_external_coverage, get_feature_coverage, clear_prd_summary). For writing new tests use canary-lab-author.

Use when exporting a Canary Lab run as an evaluation — "export the evaluation", "produce the report for run 7cvh", "give me the evaluation archive", "review what the run proved" — through the export MCP tools (start/submit_external_evaluation_export, get/list/download_evaluation_export). The run must be terminal (passed, failed, or aborted).

Use when making a Canary Lab feature concurrency-ready — "portify <feature>", "make the ports injectable", "why can't these run concurrently", "undo the portification" — through the portify MCP tools (start/submit_external_portify, get_portify, save_portify, cancel_portify, remove_portification, list_portify_status).

Use when running or healing an EXISTING Canary Lab feature locally — "run <feature>", "fix the failing run", "rerun 7cvh", "drive the heal loop" — through the repair MCP tools (start_run, wait_for_heal_task, signal_run, get_heal_context, pause_run, cancel_heal, abort_run). Fix failing runs by editing app/service code, not tests. For end-to-end onboarding of a new repo use canary-lab (flight); for deployed-environment checks use canary-lab-verify.

Use when the user wants Canary Lab to take a product repo end to end — "test this app", "onboard this repo", "run a flight", "evaluate what I just built" — through the flight pipeline (start_flight / get_flight / respond_flight_checkpoint over MCP). One conducted background pipeline goes from bare repo(s) to a green, covered, healed run ending in an evaluation export. For a single capability use the focused skills instead — canary-lab-run (run + heal), canary-lab-verify (deployed-env verification), canary-lab-author (create feature + specs), canary-lab-coverage (PRD summary + coverage ledger), canary-lab-portify (concurrency-readiness), canary-lab-export (evaluation export).

Use when verifying a Canary Lab feature against a DEPLOYED environment (staging/production URL) — "verify checkout on staging", "run the saved verify config", "check the deployed app" — through the verify MCP tools (list/get/create/update_verification_config, execute_verification, get_verification_result). No local boot, no heal loop. For local run + heal use canary-lab-run; for end-to-end onboarding use canary-lab (flight).

Use when creating or extending a Canary Lab feature by hand — "create a feature for X", "add test cases to <feature>", "capture the env files", "switch the feature's branch" — through the author MCP tools (create_feature, capture_feature_env_files, write_envset, start/update/apply_external_draft, get_feature_repo_status, checkout_feature_repo_branch). For docs/PRD/coverage use canary-lab-coverage; for full onboarding of a bare repo use canary-lab (flight).

Use when working the Canary Lab semantic coverage ledger — "what's actually tested?", "map coverage for <feature>", "refresh the PRD summary", "close the coverage gaps", "add this plan/spec to the feature docs" — through the coverage MCP tools (write/list/delete_feature_doc, start/submit_external_summary, start/submit_external_coverage, get_feature_coverage, clear_prd_summary). For writing new tests use canary-lab-author.

Use when exporting a Canary Lab run as an evaluation — "export the evaluation", "produce the report for run 7cvh", "give me the evaluation archive", "review what the run proved" — through the export MCP tools (start/submit_external_evaluation_export, get/list/download_evaluation_export). The run must be terminal (passed, failed, or aborted).

Use when making a Canary Lab feature concurrency-ready — "portify <feature>", "make the ports injectable", "why can't these run concurrently", "undo the portification" — through the portify MCP tools (start/submit_external_portify, get_portify, save_portify, cancel_portify, remove_portification, list_portify_status).

Use when running or healing an EXISTING Canary Lab feature locally — "run <feature>", "fix the failing run", "rerun 7cvh", "drive the heal loop" — through the repair MCP tools (start_run, wait_for_heal_task, signal_run, get_heal_context, pause_run, cancel_heal, abort_run). Fix failing runs by editing app/service code, not tests. For end-to-end onboarding of a new repo use canary-lab (flight); for deployed-environment checks use canary-lab-verify.

Use when the user wants Canary Lab to take a product repo end to end — "test this app", "onboard this repo", "run a flight", "evaluate what I just built" — through the flight pipeline (start_flight / get_flight / respond_flight_checkpoint over MCP). One conducted background pipeline goes from bare repo(s) to a green, covered, healed run ending in an evaluation export. For a single capability use the focused skills instead — canary-lab-run (run + heal), canary-lab-verify (deployed-env verification), canary-lab-author (create feature + specs), canary-lab-coverage (PRD summary + coverage ledger), canary-lab-portify (concurrency-readiness), canary-lab-export (evaluation export).

Use when verifying a Canary Lab feature against a DEPLOYED environment (staging/production URL) — "verify checkout on staging", "run the saved verify config", "check the deployed app" — through the verify MCP tools (list/get/create/update_verification_config, execute_verification, get_verification_result). No local boot, no heal loop. For local run + heal use canary-lab-run; for end-to-end onboarding use canary-lab (flight).

Use when adding, removing, renaming, or moving an MCP tool between profiles in apps/web-server/mcp/tools.ts, or when the MCP smoke test fails with a tool-count or unknown-tool mismatch. Not for sizing/reshaping a tool's RESULT payload (→ cl_mcp-output-design) or for run-loop semantic changes like collision/queue/heal-claim rules (→ cl_sync-agent-surfaces).

Use when adding a long-running background task to Canary Lab (anything that shouldn't block a REST request or the UI) — coverage generation, port-ification, spec/eval generation.

Use when asked to critique, review, or give design feedback on any Canary Lab web UI — a screenshot, a live screen, a Figma link, or a component ("review this design", "design feedback", "what do you think of this panel/dialog/pill"), so shared primitives and intentional choices aren't flagged as defects.

Use whenever you touch how Canary finds, reads, or builds a path to a claude/codex CLI session log (the JSONL transcript that feeds AgentSessionView), or when a user reports an agent view is "blank", "stuck", "shows nothing", or "only works on my machine". Covers where each CLI stores its logs, the env-aware config-dir resolvers (CLAUDE_CONFIG_DIR / CODEX_HOME), the one-home rule for path-building, and the boot-time shell hydration that keeps PTY + headless + read-side in agreement. Consult before recomputing any `~/.claude/projects/...` or `~/.codex/sessions/...` path by hand. NOT for designing what an agent viewer shows (that's cl_surfacing-agent-work), and note MCP external runs have no session log at all — a "blank" ExternalXXXPanel is not a path bug.

Use when adding or reshaping what any Canary Lab MCP tool returns into the agent's context — sizing an inline payload, choosing between inline content and a file path. Project-specific learned corrections, not general MCP guidance.

Use the moment you're about to add code or UI that resembles something already in the repo — a second agent spawn, a second pill/card/dialog, a second background store, a second stream parser, a second timeout. Before writing a near-copy, find the existing one and either reuse it or extend it into a shared helper/component/primitive. Captures Canary Lab's "related logic has one home" rule and the primitives that already exist. Skip when the code is genuinely one-of-a-kind or the resemblance is superficial (same shape, different concern); for styling questions use cl_ui-design-philosophy and for background-task lifecycle use cl_async-task-ux.

Use whenever you add a new page/view OR a dialog/modal to the web UI (apps/web) — a new full-screen view, a new dialog rendered from App.tsx, a wizard, a config/settings panel, anything a user opens. Also use when a user says "I want to link to X", "refresh loses my place", "make this bookmarkable", or "this dialog doesn't survive reload". The rule: every page and every cold-load-coherent dialog gets a URL param so it is deep-linkable, refresh-survivable, and revisitable. New surface with no route → it vanishes on refresh, always.

Use when building or restyling any Canary Lab web UI (apps/web) — a new panel, dialog, pill, card, or full-screen view. Captures the design language so new surfaces feel native instead of bolted on: reuse the token system, the established layout precedents, and the meaning-carries-the-style rule. No new component library. For critique-only requests ("review this design", "design feedback") use cl_design-feedback instead; terminal/CLI output styling is out of scope.

Use whenever you add or modify a server-side mutation (new route, background job completion, MCP tool write) that changes something visible in the UI — feature list, badges, coverage icons, run states, anything. Also use when a user says "I had to refresh to see X" or "the badge didn't update until I reloaded". The rule: every mutation that affects UI state must emit a WorkspaceEvent so the client updates live. No broadcast event → stale UI, always. If the server already emits the event and only the client fails to react to it, use cl_live-state-sync instead.

Use when creating or editing a sample feature under templates/project/features/ — feature.config.cjs, envsets, e2e specs — or when a template change doesn't show up in a scaffolded workspace (for general pre-claim verification checks use cl_verify-changes).

Use when adding, editing, or moving an LLM prompt an agent spawn sends (heal, wizard, portify, coverage/PRD, flights) — every prompt is a template file under apps/web-server/prompts/, never an inline string in a .ts file. NOT for MCP initialize instructions (REPAIR_INSTRUCTIONS etc. in apps/web-server/mcp/server.ts) or tool description fields in apps/web-server/mcp/tools.ts — those belong to cl_sync-agent-surfaces / cl_add-mcp-tool.

Use when publishing a new canary-lab version to npm — changelog, version bump, smoke test, publish, tag.

Use when building or changing any UI/feature that shows an agent's progress, output, or "what it's doing" (live or historical), when choosing how to stream agent output, or when a user says an agent view "looks stuck" / "I can't see the output". Prevents designing an agent viewer before knowing what the agent actually produces — and promising a rich timeline an agent can't deliver. Skip if the view is blank/stuck because the session-log path or resolution is wrong (CLAUDE_CONFIG_DIR/CODEX_HOME, missing JSONL) → cl_locate-agent-session-logs; this skill is for designing what the viewer shows and how output streams. Skip for non-agent UI styling → cl_ui-design-philosophy, and for generic "only updates after refresh" staleness → cl_live-state-sync.

Use after changing run-loop semantics — collision/queue choices, boot sessions, heal claims, signal/rerun rules, pass-count rules — or when auditing whether MCP instructions (INSTRUCTIONS_BY_PROFILE in apps/web-server/mcp/server.ts), tool-result shapes (apps/web-server/mcp/tools.ts), and the shipped agent-integrations/*/skills/canary-lab/SKILL.md files still agree. Skip for pure tool add/remove/rename/profile-move work with no semantic change → cl_add-mcp-tool.

Use the moment you're about to act on a claim about the code you didn't confirm yourself — a plan/spec/"follow-up" item, a "known gap", a bug report ("doesn't update live", "only works after refresh", "isn't wired", "X is missing"), or a "these N are identical, migrate them the same way" assumption. Any "fix X" where you haven't watched X actually fail right now.

Use when a UI must react in real time to a backend state change — a status flip, a panel swap, a list update, anything driven by a workspace/broadcast event — or when a user reports that something "only updates after I refresh", "doesn't update live", "the toggle/swap didn't happen until reload", or a live view feels stale. Also use when choosing how the client learns about a server-side change (broadcast push vs task-scoped stream vs refetch). Prevents gating a correctness-critical UI transition on a single best-effort push that can silently fail to deliver.

Use when adding, removing, renaming, or moving an MCP tool between profiles in apps/web-server/mcp/tools.ts, or when the MCP smoke test fails with a tool-count or unknown-tool mismatch.

Use when adding a long-running background task to Canary Lab (anything that shouldn't block a REST request or the UI) — coverage generation, port-ification, spec/eval generation. Defines the non-blocking · persistent · recoverable · re-openable · single-flight contract and the file-backed store pattern to copy.

Use whenever you add or modify a server-side mutation (new route, background job completion, MCP tool write) that changes something visible in the UI — feature list, badges, coverage icons, run states, anything. Also use when a user says "I had to refresh to see X" or "the badge didn't update until I reloaded". The rule: every mutation that affects UI state must emit a WorkspaceEvent so the client updates live. No broadcast event → stale UI, always.

Use before claiming any canary-lab change works, when deciding which checks a change needs, or when tests/coverage behave strangely (coverage .tmp ENOENT, template edits not showing up, UI server running stale code).

Use the moment a request is vague or open-ended — "improve the cleanup UI", "make this better", "clean this up", "let's polish X", "can we redo Y" — where the WHAT is named but the specific change is not. Stops the reflex to fire an AskUserQuestion menu guessing the goal; instead look at the target first, then ask one open question or wait for the user to point at the real thing. Applies to any Canary Lab work (UI, run loop, MCP, docs), not just UI.

Use when asked to critique, review, or give design feedback on any Canary Lab web UI — a screenshot, a live screen, a Figma link, or a component ("review this design", "design feedback", "what do you think of this panel/dialog/pill"). Grounds every finding in the component source + the design tokens BEFORE you voice it, so you don't flag a shared system primitive, an already-compliant value, or an intentional choice as a defect.

Use when a UI must react in real time to a backend state change — a status flip, a panel swap, a list update, anything driven by a workspace/broadcast event — or when a user reports that something "only updates after I refresh", "doesn't update live", "the toggle/swap didn't happen until reload", or a live view feels stale. Also use when choosing how the client learns about a server-side change (broadcast push vs task-scoped stream vs refetch). Prevents gating a correctness-critical UI transition on a single best-effort push that can silently fail to deliver.

Use when publishing a new canary-lab version to npm — changelog, version bump, smoke test, publish, tag.

Use when building or changing any UI/feature that shows an agent's progress, output, or "what it's doing" (live or historical), when choosing how to stream agent output, or when a user says an agent view "looks stuck" / "I can't see the output". Prevents designing an agent viewer before knowing what the agent actually produces — and promising a rich timeline an agent can't deliver.

Use after changing run-loop semantics — collision/queue choices, boot sessions, heal claims, signal/rerun rules, pass-count rules — or when auditing whether MCP instructions, tool results, and the shipped SKILL.md files still agree.