cairn-ai 0.2.9 → 0.4.0

package/skills/cairn-plan/SKILL.md

@@ -5,200 +5,59 @@ description: Use before non-trivial implementation, refactoring, migrations, deb
 
 # Cairn Plan
 
-Use this before non-trivial implementation, refactoring, migrations, debugging, or repository automation. Also use it when the user asks for planning, design, "설계부터", "신중하게", "꼼꼼히", complexity triage, or coordinated agent work.
-
-## Purpose
-
-Plans must reduce execution tokens. Do not leave long plans only in chat. Store the topic in `PLAN.md` and details in `docs/plan/<topic>.md`.
-
-When project-root `MEMORY.md` exists, read it as the repository policy and domain-knowledge index before exploring or delegating work. If it is absent, continue without repository memory; never invoke another memory service or block solely because the file is missing. Delegated agents follow the same rule.
-
-Do not treat planning as optional for implementation work that is more than a narrow single-file fix. Produce or update a plan when the request changes behavior, architecture, data, or multiple files, or when an external operation requires code edits, conflict resolution, destructive recovery, release/deploy, or design. External-state mutation alone is not a planning trigger: routine known-target Git/GitHub operations such as status, fetch, checkout, branch, merge, push, and PR management stay plan/goal-free.
-
-Plan from the whole work down. First understand the full requested outcome and affected surfaces, then classify the work into small executable tasks. If one task is still too broad to verify cleanly, split that task into sub-tasks.
+Use before non-trivial implementation, refactoring, migrations, debugging, or repository automation, or when the user asks for planning, design, "설계부터", "신중하게", "꼼꼼히", or coordinated agents. Plans reduce execution tokens: store the topic in `PLAN.md` and details in `docs/plan/<topic>.md`, never only in chat.
 
 ## Re-entry and Required References
 
-At the start and after compaction, restart, or handoff, restore context in this order: optional root `MEMORY.md` → `cairn-plan` → the active plan → current-task references → model guidance recorded by the plan. A new implementation request with no persisted goal may create its initial plan through the procedure below. Missing `MEMORY.md` is not an inconsistency. If persisted state names a plan or task and that required reference is missing, unreadable, or inconsistent, do not explore, edit, delegate, or complete work; report or record a blocker first. Do not add a read-receipt field that claims the model read a file: filesystem/state consistency and bound tool evidence remain the fail-closed authority.
+At the start and after compaction, restart, or handoff, restore context in this order: optional root `MEMORY.md` → `cairn-plan` → the active plan → current-task references → model guidance recorded by the plan. Missing `MEMORY.md` is not an inconsistency: continue without repository memory and never invoke another memory service. If persisted state names a plan or task and that required reference is missing, unreadable, or inconsistent, do not explore, edit, delegate, or complete work; report or record a blocker first. No read-receipt fields: state consistency and bound tool evidence are the authority.
 
 ## Runtime Location
 
-Resolve Cairn's read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md`. Its `pluginRoot` contains Cairn's `scripts/`, `templates/`, commands, agents, and model guidance. In a source checkout where the locator does not exist, resolve the plugin root from this `SKILL.md` location (`../..`). Never search the target repository for Cairn scripts, templates, or model guidance, and never derive the plugin root from the current working directory. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover from the published/global package with `cairn doctor` followed by `cairn upgrade`; do not use another mirror as a repair source.
+Resolve the read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md` (its `pluginRoot`; in a source checkout without it, this file's `../..`). Never search the target repository for Cairn files or derive `pluginRoot` from the cwd. If the runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover with published/global `cairn doctor` followed by `cairn upgrade`; never repair from another mirror.
 
-Use logical resource IDs such as `cairn://templates/work-plan.md` and `cairn://docs/model-guidance/codex.md` in repository plans. Resolve those IDs through `pluginRoot` only while executing. Keep `repoRoot` separate and pass it explicitly as `--root <repoRoot>`.
+Plans use logical IDs such as `cairn://templates/work-plan.md`, resolved through `pluginRoot`. The session-start hook prints a ready prefix `Cairn CLI: node "<abs>/scripts/cairn.mjs" goal <command>`: copy it literally into every command and never store it in a shell variable (shell variables do not persist between tool calls). `--root` may be omitted when the cwd is inside the repository (it resolves via `HARNESS_REPO_ROOT`, else the nearest `.git` ancestor).
 
-For a non-trivial implementation request or continuation of already planned work, treat the request itself as authorization to create or restore a two-phase plan and activate its roadmap, even when the user does not mention a goal. Do not create a plan or goal for a routine known-target Git/GitHub operation unless it crosses one of the escalation boundaries above. The initial plan is decision-complete for the `triage-plan` task but is not implementation-ready. After writing it and its `PLAN.md` index entry, synchronize the same ordered steps to Codex UI tools when available (`update_plan` first, then `create_goal`) and start the repository goal before exploration, toolcheck, complexity triage, or a non-blocking user question:
+## Reference Files
 
-```sh
-node "<pluginRoot>/scripts/cairn.mjs" goal start --root "<repoRoot>" --goal "<objective>" --plan "docs/plan/<topic>.md" --tasks '[{"id":"triage-plan","title":"Run planned triage and finalize the plan","requiredEvidence":["planArtifact","triageDecision"]},{"id":"implement","title":"Implement the finalized plan"},{"id":"verify","title":"Verify and review the result"}]' --criteria "<completion criterion>" --session "<current session_id>"
-```
-
-Pass `--session` only with a session ID the surface actually exposes to the model; never guess or invent one, because a mismatched owner makes every later hook treat the goal as foreign. If no stable session ID is exposed, omit `--session` and record that the goal is repository-scoped.
+Read a reference only when the selected path or situation requires it (Quick and Light Path never need `heavy-path.md`):
 
-If an unfinished repository goal already exists when a new implementation request, steer, or drift arrives, do not cancel it to start another. Fold the new work into it with `goal replan` (completed tasks and their evidence are preserved; resume a paused or blocked goal first), synchronize the plan artifact and native UI roadmap, and keep advancing until goal final review. Start a separate goal only when the user explicitly switches work. When a hook reports that another session owns the goal and this session continues that same work, take ownership with `goal claim --session <id>` using the ID shown by the hook.
- If Codex UI plan/goal tools are unavailable, record that limitation and continue with the repository plan and goal; never claim UI synchronization that did not occur.
+- `cairn://skills/cairn-plan/planning-rules.md`: plan rules, route record, tool readiness, dry-run policy; read when finalizing a plan.
+- `cairn://skills/cairn-plan/delegation.md`: subagent lifecycle, prompt format, reasoning-effort routing; read before dispatching.
+- `cairn://skills/cairn-plan/heavy-path.md`: Heavy Path flow, route changes, review gates; read only on a Heavy signal or route change.
 
-## Procedure
+## Path Selection
 
-1. Run `node "<pluginRoot>/scripts/cairn.mjs" init --root "<repoRoot>"` through the resolved runtime. If the runtime is unavailable, ensure `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` directly and report that `cairn doctor` or `cairn upgrade` is required.
-2. Read project-root `MEMORY.md` when present; otherwise continue without repository memory.
-3. Classify the request as non-trivial implementation/planned-work continuation, routine known-target Git/GitHub operation, or consultation/explanation/plan-only. For a routine operation, execute without creating a plan or goal unless it requires code edits, conflict resolution, destructive recovery, release/deploy, or design. For non-trivial implementation/planned-work continuation, immediately create an initial `docs/plan/<topic>.md` from `cairn://templates/work-plan.md` and add its `PLAN.md` index entry. Based only on the request and `MEMORY.md`, describe the observable outcome, anticipated affected surfaces, and stable top-level roadmap. Make `triage-plan` the first active task and specify its memory inputs, investigation scope, toolcheck, Heavy Path criteria, and exact condition for updating the plan. Mark the plan `initial: decision-complete for triage; not implementation-ready`.
-4. Before reading detailed memory, toolcheck, repository exploration, complexity triage, delegation, or any non-blocking user question, synchronize the initial roadmap:
-   - Call Codex `update_plan` first when available so the UI displays the ordered tasks with `triage-plan` in progress.
-   - Call Codex `create_goal` next when available so the UI displays the active objective. The non-trivial implementation request plus this developer-level skill instruction is authorization; do not use it for routine known-target Git/GitHub operations, consultation, explanation, or plan-only requests.
-   - Start or attach the repository Cairn goal with the same objective, plan ID, stable task IDs, and current session ID.
-   - If a UI tool is unavailable, record the limitation in the plan and continue with repository state.
-5. Execute the planned `triage-plan` task: read only the relevant `docs/memory/*.md`, read applicable installed model guidance, run toolcheck, and explore the repository with focused search and LSP/symbol tools.
-6. Treat tool installation as a separate external-state change. Do not install during planning without explicit user approval. After approval, use `toolcheck --install --yes --root "<repoRoot>"` only for pinned/supported installers, or the approved repository-native command. Otherwise record the missing tool and proposed command as a blocker.
-7. Summarize the whole work and affected surfaces, classify it into small executable tasks/sub-tasks, identify dry-run/check modes, and run complexity triage before applying workflow guidance from agents, plugins, or delegated roles.
-8. Update the same repository plan with the selected route, all checked Heavy Path signals, concrete file scope, tool readiness, delegation, verification commands, and fail-closed evidence. Mark it `decision-complete for implementation`, then call Codex `update_plan` again so the UI matches the finalized roadmap.
-   - Spend planning tokens on executable test design: requirements, invariants, boundaries, failure modes, expected initial failure, and authoritative tool result.
-   - Give implementation a bounded test contract and exact file scope; require the minimum passing change rather than renewed broad discovery.
-   - Plan focused tests first, one final full check, and a package dry-run when no change occurred after the full check. Require lifecycle inspection, normal script execution for content-producing or unknown scripts, and `--ignore-scripts` only for absent or proven content-neutral scripts. Mark evidence stale after relevant mutation.
-9. Only after step 8, record bound `planArtifact` and `triageDecision` evidence records, complete the `triage-plan` task, and advance to implementation.
-10. Delegate according to the selected path and model guidance instead of asking the user.
-   - Use `explorer` for independent read-only codebase discovery, impact analysis, pattern searches, and read-only verification that can run in parallel when the current tool list supports it.
-   - Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, and records evidence.
-   - Use `worker` for actual implementation edits with clear file ownership whenever subagent tools are available, on both Light Path and Heavy Path.
-   - When the subagent tool provides a progress-reporting channel, require subagents to report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; the orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion.
-   - Require delegated subagents to provide a final report before leaving; after capturing the final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete.
-   - When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents, subject to the current surface's depth and concurrency limits.
-   - If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence; do not stop before local implementation solely because subagent tools are unavailable.
-   - Keep urgent non-implementation blocking work local when the next step depends immediately on the result.
-   - Tell every delegated agent and child subagent to read project-root `MEMORY.md` when present and continue when absent, keep scope, and tell workers they are not alone in the codebase and must not revert others' edits.
-11. Give every plan and ordered task step a stable ID and declare task-level and goal-level required evidence. The task order must be sufficient for both Codex UI and hook context to show the roadmap and restore the current task after side questions.
-12. Advance a Codex UI step only after the matching repository Cairn task transition succeeds with all required bound evidence records. The repository state is the fail-closed transition authority; UI state is its synchronized projection.
-13. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
-
-## Reasoning Effort Routing
-
-- Models always inherit the host/user default; never configure or override them.
-- Light Path planning, implementation, and verification request `medium`.
-- Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
-- Every module task records `Requested reasoning effort` and `Effective reasoning effort` in `docs/plan/<topic>.md`. Requested is Cairn's desired profile; Effective is what the dispatch result confirms.
-- Pass requested effort only when dispatching a new task/worker and the host exposes a reasoning-effort option or host-native equivalent. Omit model overrides. Effective `inherited` means no task-level override was confirmed, not proof of missing host capability. Describe capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and leave model/global config unchanged.
-- On every route change, synchronize the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before mutation. Completed task profiles are preserved as audit history; incomplete task profiles are recalculated for the new path.
-
-## Complexity Triage
-
-Decide triage from repository evidence without asking the user.
-
-Use three mandatory checkpoints and record each result, evidence, newly discovered Heavy Path signals, and current route in the plan artifact:
-
-1. **Request checkpoint:** before exploration, make a provisional classification from the request and `MEMORY.md`; uncertainty stays explicit and this result is not implementation authority.
-2. **Planning checkpoint:** after repository exploration, affected-surface analysis, and test design, re-evaluate the provisional route and finalize the implementation plan.
-3. **Code checkpoint:** during `cairn-work`, inspect the exact files, callers, and tests, then record one final re-evaluation immediately before the first edit. A pending or missing code checkpoint blocks mutation.
-
-Before the first edit, the planning or code checkpoint may change Light Path to Heavy Path or Heavy Path to Light Path when the evidence supports it. Every route change must rebuild and synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including assignments, reviews, and required evidence; do not mutate until all three agree. After editing starts, only promote Light Path to Heavy Path: stop further edits, mark affected evidence stale, revise and synchronize all three roadmaps, run newly required Heavy Path review, and repeat the code checkpoint before resuming.
-
-This decision takes priority over plugin, agent, or delegated workflow guidance unless higher-priority system or developer instructions say otherwise. The default is Light Path; use Heavy Path only when a Heavy Path condition clearly applies.
-
-### Light Path
-
-Use Light Path for narrow changes inside existing architecture layers. Skip planning/review agents when appropriate, but actual implementation edits still go to `worker` whenever subagent tools are available. Keep the verification gate.
-
-Light Path conditions:
-
-- The change stays inside existing architecture layers.
-- No new domain model, service class, or abstraction is introduced.
-- No security, authentication, authorization, session, external API, message queue, payment, DB schema, migration, concurrency, transaction-boundary, or cache-invalidation change is involved.
-
-Light Path examples:
-
-- One new API endpoint within existing layers.
-- Add or modify a controller or service method.
-- Strengthen validation rules.
-- Adjust query logic.
-- Change copy text or constants.
-- Fix one clearly scoped bug.
-
-Light Path flow: main-agent orchestration -> bounded `worker` implementation when subagent tools are available -> main-agent takeover when subagent tools are unavailable -> focused verification by the main agent or a scoped verification `worker` -> report. If there is no plan artifact, use the original user request and the diff as the verification baseline.
-
-### Heavy Path
-
-Use Heavy Path when the request clearly needs the full planning and review pipeline.
-
-Heavy Path conditions:
-
-- Creating a new directory, module, or architecture layer.
-- Introducing a new domain model, service class, or abstraction.
-- Changing security, authentication, authorization, or sessions.
-- Integrating an external API, message queue, or payment flow.
-- Changing DB schema or migrations.
-- Changing concurrency, transaction boundaries, or cache invalidation.
-- Refactoring across multiple domains.
-- The user signals extra care, such as "신중하게", "검토 받고", "설계부터", or "꼼꼼히".
-
-Heavy Path flow: plan -> pre-implementation review -> bounded `worker` implementation -> verification worker or read-only review.
-
-### Route Record
-
-`docs/plan/<topic>.md` must record:
-
-- Selected path.
-- Selection rationale.
-- Heavy Path conditions found, if any.
-- Heavy Path conditions checked and not found.
-- Roles or delegation omitted in Light Path and why.
-- Any unavailable subagent tool main-agent takeover and its evidence record.
-- Pre-implementation decisions that review must resolve in Heavy Path.
-- Request checkpoint, planning checkpoint, and code checkpoint status, evidence, newly found signals, and route.
-- Every route change and the synchronized plan artifact, repository goal task roadmap, native UI plan, assignments, reviews, required evidence, and stale evidence invalidation.
-
-## Planning Rules
-
-- Every initial plan must be decision-complete for its triage task and explicitly not implementation-ready; the post-triage revision must be decision-complete for implementation.
-- Every non-trivial implementation or planned-work continuation plan must be shown through Codex `update_plan` and `create_goal` before triage when those tools are available, then synchronized again after triage. Routine known-target Git/GitHub operations do not create a plan or goal. Repository plan/goal persistence remains required for work that crosses the planning boundary.
-- Every plan must describe the whole work first, then classify it into executable tasks and any needed sub-tasks.
-- Every plan must treat the user-called/main agent as the orchestrator and assign actual implementation edits to `worker` whenever subagent tools are available, regardless of Light Path or Heavy Path.
-- Every plan must require subagents to report status when the subagent tool provides a progress-reporting channel. If no mid-run reporting channel exists, the orchestrator must relay observable events such as assignment, waiting, and final completion.
-- Every plan must require delegated subagents to provide a final report before leaving, require the orchestrator to close or release completed subagents after capturing final report and evidence, and require the orchestrator to review the final report and evidence before marking work complete.
-- Every plan must allow recursive subagent delegation for bounded sub-tasks when the current agent surface supports it.
-- Every plan must include complexity triage and the selected path.
-- Every plan must explicitly list Heavy Path signals checked, even when Light Path is selected.
-- Every plan must include applied model guidance and rationale.
-- Every plan must include tool readiness results: detected stack, required LSP/check tools, installed tools, and blockers.
-- Every executable plan must include a stable goal ID, stable task IDs, explicit terminal states, and fail-closed required evidence. A missing evidence section never means success.
-- Every implementation task must be small enough to verify with two checks.
-- Heavy Path tasks must include an explicit automated test command and a `Tests:` evidence line; Heavy Path completion cannot rely on generic verification wording without test evidence.
-- The default checks are module acceptance verification and surface integration verification.
-- Every risky or external-state-changing task must include the closest available dry-run or check command before the write/apply command.
-- Verification can expand for risk, but the reason must be recorded.
-- The default loop budget is two verification passes per task. If a gate fails, diagnose once, shrink the task or split it into sub-tasks, and rerun both gates. After two failed passes, record the blocker in `docs/plan/<topic>.md` instead of continuing an open-ended loop.
-- Ask the user only when agents, repository evidence, or local verification cannot answer the decision.
-- User-visible responses and generated or updated documentation, plans, and memory artifacts must follow the OS locale unless the user asks for another language.
+Decide from repository evidence without asking; this outranks plugin or agent workflow guidance.
 
-## Tool Readiness Policy
+- **Routine known-target Git/GitHub operation** (status, fetch, checkout, branch, merge, push, PR management): plan/goal-free unless it requires code edits, conflict resolution, destructive recovery, release/deploy, or design.
+- **Consultation, explanation, or plan-only**: no goal.
+- **Quick Path**: all must hold: requirements are unambiguous; the expected change touches about 3 files or fewer inside existing layers; no Heavy Path signal; no external-state mutation; verification is one or two commands. No `docs/plan` artifact and no repository goal: implement, run one focused check plus the project's normal check, and report. If any criterion fails during work, escalate to Light Path (create plan + goal) before further edits.
+- **Light Path** (default): stays inside existing layers, adds no domain model, service class, or abstraction, and has no Heavy signal.
+- **Heavy Path**: any clear signal: new directory, module, or architecture layer; new domain model, service class, or abstraction; security, authentication, authorization, or sessions; external API, message queue, or payment; DB schema or migration; concurrency, transaction boundaries, or cache invalidation; multi-domain refactor; the user asks for extra care ("신중하게", "검토 받고", "설계부터", "꼼꼼히").
 
-Do not silently skip LSP, typecheck, lint, dry-run, or verification because the tool is missing. Tool installation still requires explicit user approval.
+Record three triage checkpoints: request (provisional), planning (after exploration), and code (in `cairn-work`, just before the first edit; pending blocks mutation). Before the first edit the route may change either way; after editing starts, only Light → Heavy promotion is allowed. Every route change synchronizes the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before mutation.
 
-- Detect the codebase stack from repository files before choosing tools.
-- Prefer repository-local installation through the existing package manager and lockfile.
-- Use ephemeral tool runners only when project-local installation is not appropriate.
-- Run the tool after installation and record the command result.
-- If installation was not approved or is impossible, record the proposed or attempted command, failure output summary when applicable, and blocker in `docs/plan/<topic>.md`.
-- Treat "LSP server not installed" as an unresolved blocker until installation or an equivalent symbol-aware fallback has been attempted.
+## Procedure (Light and Heavy Path)
 
-## Dry-Run Policy
+1. Run `node "<pluginRoot>/scripts/cairn.mjs" init --root "<repoRoot>"`. If unavailable, create `MEMORY.md`, `PLAN.md`, `docs/memory`, `docs/plan` and report that `cairn doctor`/`cairn upgrade` is needed.
+2. Read `MEMORY.md` when present. A non-trivial implementation request authorizes the plan and goal even if the user never says "goal".
+3. Write the initial plan `docs/plan/<topic>.md` from `cairn://templates/work-plan.md` plus its `PLAN.md` entry from the request and `MEMORY.md`: outcome, anticipated surfaces, stable roadmap, and `triage-plan` as first active task (investigation scope, toolcheck, Heavy criteria, update condition); mark it `initial: decision-complete for triage; not implementation-ready`.
+4. Before exploration, toolcheck, delegation, or a non-blocking question, call Codex `update_plan` first and then `create_goal` when available (record unavailability; never claim sync that did not occur), then start the repository goal:
 
-Prefer repository-native dry-run and check modes before mutating external state.
+```sh
+node "<pluginRoot>/scripts/cairn.mjs" goal start --root "<repoRoot>" --goal "<objective>" --plan "docs/plan/<topic>.md" --tasks '[{"id":"triage-plan","title":"Run planned triage and finalize the plan","requiredEvidence":["planArtifact","triageDecision"]},{"id":"implement","title":"Implement the finalized plan"},{"id":"verify","title":"Verify and review the result"}]' --criteria "<completion criterion>" --session "<current session_id>"
+```
 
-- Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
-- Package and release work: inspect lifecycle scripts first, then use normal `npm pack --dry-run`, publish dry-run, build check, or equivalent. Never skip content-producing or unknown lifecycle scripts with `--ignore-scripts`; it is allowed only for absent or proven content-neutral scripts while prior full-check evidence remains fresh.
-- Infrastructure and deployment: plan, diff, validate, check, or equivalent.
-- Code generation and formatting: check mode before write mode when available.
-- If no dry-run mode exists, record that fact and select the smallest reversible command or test artifact available.
+   Pass `--session` only with an ID the surface exposes; never invent one. Fold new work into an unfinished goal with `goal replan` (resume a paused or blocked goal first), never cancel it; start a separate goal only when the user explicitly switches work. When a hook reports another session owns the goal you continue, run `goal claim --session <id>` with the ID shown.
+5. Run `triage-plan`: read only relevant `docs/memory/*.md` and installed model guidance, run `toolcheck --root "<repoRoot>"`, and explore with focused search and LSP/symbol tools. Install tools only with explicit user approval.
+6. Split the whole work into tasks each verifiable with two checks, each with `dependsOn` and `writeScope` in the `--tasks` JSON and named handoff files for cross-task data (`delegation.md`); design the test contract (requirements, invariants, boundaries, failure modes, expected failure) and dry-run/check modes.
+7. Update the plan with route, checked Heavy signals, tool readiness, delegation, verification commands, stable IDs, and fail-closed required evidence (`planning-rules.md`). Mark it `decision-complete for implementation` and call `update_plan` again.
+8. Only then record bound `planArtifact` and `triageDecision` evidence, complete `triage-plan`, and continue with `cairn-work`.
+9. Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, and records evidence. Implementation edits go to `worker` whenever subagent tools are available, on Light and Heavy Path; `explorer` does read-only discovery; without subagent tools the main agent takes over and records it.
+10. Advance a UI step only after the matching repository task transition succeeds.
+11. Ask the user only when evidence and local checks cannot decide. Use the OS locale for user-visible output and artifacts unless asked otherwise.
 
-## Delegation Prompt Format
-
-```text
-TASK: Produce <role> input needed for the <topic> plan.
-EXPECTED OUTCOME: Return concrete decisions, file paths, dependencies, risks, and evidence requirements.
-REQUIRED TOOLS: Read-only repository exploration, tool readiness checks, LSP/symbol tools, local command checks.
-MUST DO: Read the project-root `MEMORY.md` before doing assigned work. Preserve proper nouns exactly. Prefer repository evidence. Report missing tools and obtain explicit user approval before any installation. Identify assumptions. Treat the user-called/main agent as the orchestrator. Use `explorer` for read-only discovery and `worker` for actual implementation edits or verification when subagent tools are available, regardless of Light Path or Heavy Path. When the subagent tool provides a progress-reporting channel, require subagents to report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; the orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion. Require delegated subagents to provide a final report before leaving; after capturing the final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence. When subagent tools are available, allow recursive delegation of bounded sub-tasks. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work. Tell workers they are not alone in the codebase and must not revert others' edits. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts.
-MUST NOT DO: Edit production code. Ask the user. Expand scope. Delegate vague or unbounded work.
-CONTEXT: User request, MEMORY.md, relevant docs/memory notes, applied model guidance, repository root.
-```
+Model and reasoning effort: This skill explicitly instructs the effort level for delegated work. Pick each task's model tier (fast `haiku`, balanced `sonnet`, stronger `opus`, strongest `fable`) and request Light `medium`, Heavy `high`, final verification/review `xhigh`. Every new task/worker dispatch MUST pass the task's model and effort via the host option (Claude Code: Agent `model`/`effort`; never `fork`). Recording without passing is a defect. Record Requested/Effective model and effort per task; mark Heavy tasks `route: "heavy"` (details: `delegation.md`).
 
 ## Completion Criteria
 

package/skills/cairn-plan/delegation.md

@@ -0,0 +1,62 @@
+# Cairn Plan: Delegation and Reasoning Effort
+
+Reference for `cairn-plan`. Read before dispatching `explorer` or `worker` agents or recording reasoning effort. Quick Path work done directly by the main agent does not need this file.
+
+## Subagent Lifecycle
+
+- Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, and records evidence.
+- Use `explorer` for independent read-only codebase discovery, impact analysis, pattern searches, and read-only verification that can run in parallel when the current tool list supports it.
+- Use `worker` for actual implementation edits with clear file ownership whenever subagent tools are available, on both Light Path and Heavy Path.
+- When the subagent tool provides a progress-reporting channel, require subagents to report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; the orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion.
+- Require delegated subagents to provide a final report before leaving; after capturing the final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete.
+- When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents, subject to the current surface's depth and concurrency limits.
+- If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence; do not stop solely because subagent tools are unavailable.
+- Keep urgent non-implementation blocking work local when the next step depends immediately on the result.
+- Tell every delegated agent and child subagent to read project-root `MEMORY.md` when present and continue when absent, keep scope, and tell workers they are not alone in the codebase and must not revert others' edits.
+- Every plan must require these status, final-report, close-and-review, and recursive-delegation rules.
+
+## Task Graph
+
+- Every task in `goal start --tasks` / `goal replan --tasks` JSON declares `dependsOn` (task ids) and `writeScope` (literal repo-relative paths; no globs, `..`, or absolute paths). Example: `{"id":"api","title":"API","dependsOn":["triage-plan"],"writeScope":["src/api"]}`.
+- Omitted `dependsOn` means the previous task in list order (first task: none); explicit `[]` means no dependency, so sequential plans keep working. In `goal replan` the default chains across completed and new tasks, and `dependsOn` may reference completed tasks. Duplicate ids, unknown ids, self references, and cycles are rejected.
+- Omitted `writeScope` is null: that task can only be active alone. Give independent tasks disjoint scopes so they can run in parallel; scope is declarative, not filesystem-enforced.
+- Cairn has no messaging channel: name the handoff files that carry data between tasks in the plan (`Handoff files:`) and include them in the producer's `writeScope`.
+
+## Delegation Prompt Format
+
+```text
+TASK: Produce <role> input needed for the <topic> plan.
+EXPECTED OUTCOME: Return concrete decisions, file paths, dependencies, risks, and evidence requirements.
+REQUIRED TOOLS: Read-only repository exploration, tool readiness checks, LSP/symbol tools, local command checks.
+MODEL: <tier/value> (passed via host option)
+REASONING EFFORT: <value> (passed via host option)
+MUST DO: Read the project-root `MEMORY.md` before doing assigned work. Preserve proper nouns exactly. Prefer repository evidence. Report missing tools and obtain explicit user approval before any installation. Identify assumptions. Follow the subagent lifecycle rules (status reporting when a channel exists, final report before leaving, recursive delegation only for bounded sub-tasks, passing each child's reasoning effort through the host option). Tell workers they are not alone in the codebase and must not revert others' edits. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts.
+MUST NOT DO: Edit production code. Ask the user. Expand scope. Delegate vague or unbounded work.
+CONTEXT: User request, MEMORY.md, relevant docs/memory notes, applied model guidance, repository root, Cairn CLI prefix line from the session-start hook.
+```
+
+## Model and Reasoning Effort Routing
+
+This skill explicitly instructs the effort level for delegated work. It also instructs each task's model.
+
+- The plan decides each task's model from its nature and records `Requested model` and `Effective model`; models are not always inherited. Tiers: fast = read-only exploration, search, inventory, summarization (Claude Code `haiku`); balanced = Light Path implementation and routine verification (`sonnet`); stronger = planning, complexity triage, Heavy Path implementation, review, and final verification/review (`opus`); strongest = Heavy Path design only (`fable`).
+- Model Effective: passed and not rejected is that value; not passed is `not-applied: <reason>`; `inherited` only when the host has no model option. Codex passes the tier's slug (table below) through the host-native model option, else `inherited`.
+- If a lower-tier worker fails a gate, re-dispatch that task one tier up (fast, balanced, stronger, strongest) before recording a blocker.
+- Routing is per dispatch only; never change model or global/user config files. `Model routing: inherited` in `MEMORY.md` or the plan disables per-task selection.
+- Light Path planning, implementation, and verification request `medium`.
+- Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
+- Every new task/worker dispatch MUST pass the task's requested effort through the host option. Recording without passing is a defect. Pass the chosen model the same way (Claude Code: Agent `model`). Child (recursive) dispatches follow the same rule.
+- Every module task records `Requested reasoning effort` and `Effective reasoning effort` in `docs/plan/<topic>.md`. Requested is Cairn's desired profile; Effective is decided by the dispatch call:
+  - Effort passed and not rejected: Effective is the requested value.
+  - Effort not passed: `not-applied: <reason>`; the reason is required.
+  - `inherited` only when the host exposes no effort option. Describe host capability only from the exposed interface or dispatch response, and distinguish Cairn non-integration from host non-support.
+
+| Host | Model / effort option | Effective |
+| --- | --- | --- |
+| Claude Code | Agent tool `model` parameter (`haiku\|sonnet\|opus\|fable`). `effort` parameter (`low\|medium\|high\|xhigh\|max`), matching Cairn values one to one. `subagent_type: "fork"` ignores `model` and `effort`, so never dispatch routed work as a fork. | requested value |
+| Codex | Host-native model option (fast `gpt-6-luna`, balanced `gpt-6.1-terra`, stronger `gpt-6-sol`, strongest `gpt-6-astra`) and task/subagent reasoning-effort option or equivalent. | requested value |
+| Antigravity | `invoke_subagent` `Model` takes only a tier enum: fast `flash_lite`, balanced `flash`, stronger `pro`, strongest `pro` (no tier above `pro`); `inherit` is not used for routed work. No effort option. | model: passed value; effort: `inherited` |
+| Host without an option | None. | `inherited` |
+
+- After each dispatch, record state with `goal assign --task <id> --agent <id> --effort <value> --effort-source <host-option|inherited|not-applied>`. Mark Heavy tasks with `route: "heavy"` (tasks JSON field or `goal assign --route heavy`). A Heavy task with no effort, `not-applied`, or `inherited` fails `goal task --status completed` unless `--allow-inherited-effort <reason>` records why.
+- On every route change, synchronize the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before mutation. Completed task profiles are preserved as audit history; incomplete task profiles are recalculated for the new path.

package/skills/cairn-plan/heavy-path.md

@@ -0,0 +1,26 @@
+# Cairn Plan: Heavy Path and Route Changes
+
+Reference for `cairn-plan`. Read only when a Heavy Path signal is present or a route change is being considered. Quick Path and Light Path never need this file.
+
+## Heavy Path Flow
+
+Heavy Path flow: plan -> pre-implementation review -> bounded `worker` implementation -> verification worker or read-only review.
+
+- Record the pre-implementation decisions that review must resolve before any mutation.
+- Every Heavy Path task includes an explicit automated test command and a `Tests:` evidence line; completion cannot rely on generic verification wording without test evidence.
+- Planning, review, and implementation request `high` reasoning effort; final verification and review request `xhigh` (see `cairn://skills/cairn-plan/delegation.md`).
+
+## Complexity Checkpoints
+
+Use three mandatory checkpoints and record each result, evidence, newly discovered Heavy Path signals, and current route in the plan artifact:
+
+1. **Request checkpoint:** before exploration, make a provisional classification from the request and `MEMORY.md`; uncertainty stays explicit and this result is not implementation authority.
+2. **Planning checkpoint:** after repository exploration, affected-surface analysis, and test design, re-evaluate the provisional route and finalize the implementation plan.
+3. **Code checkpoint:** during `cairn-work`, inspect the exact files, callers, and tests, then record one final re-evaluation immediately before the first edit. A pending or missing code checkpoint blocks mutation.
+
+## Route Changes
+
+- Before the first edit, the planning or code checkpoint may change Light Path to Heavy Path or Heavy Path to Light Path when the evidence supports it.
+- Every route change rebuilds and synchronizes the plan artifact, the repository goal task roadmap through `goal replan`, and the native UI plan, including assignments, reviews, required evidence, and the reasoning effort profile. Do not mutate until all agree.
+- After editing starts, only promote Light Path to Heavy Path: stop further edits, mark affected evidence stale, revise and synchronize all roadmaps, run newly required Heavy Path review, and repeat the code checkpoint before resuming.
+- A Quick Path change that meets any failed Quick Path criterion escalates to Light Path first (plan + goal) before further edits; a Heavy signal then follows this file.

package/skills/cairn-plan/planning-rules.md

@@ -0,0 +1,68 @@
+# Cairn Plan: Planning Rules
+
+Reference for `cairn-plan`. Read when writing or finalizing a Light or Heavy Path plan. Quick Path work has no plan and never needs this file.
+
+## When Planning Is Required
+
+Do not treat planning as optional for implementation that is more than a Quick Path change. Produce or update a plan when the request changes behavior, architecture, data, or multiple files, or when an external operation requires code edits, conflict resolution, destructive recovery, release/deploy, or design. External-state mutation alone is not a planning trigger: routine known-target Git/GitHub operations such as status, fetch, checkout, branch, merge, push, and PR management stay plan/goal-free.
+
+Plan from the whole work down. First understand the full requested outcome and affected surfaces, then classify the work into small executable tasks. If one task is still too broad to verify cleanly, split it into sub-tasks.
+
+## Planning Rules
+
+- Every initial plan must be decision-complete for its triage task and explicitly not implementation-ready; the post-triage revision must be decision-complete for implementation.
+- Every non-trivial implementation or planned-work continuation plan must be shown through Codex `update_plan` and `create_goal` before triage when those tools are available, then synchronized again after triage. Routine known-target Git/GitHub operations and Quick Path work do not create a plan or goal.
+- Every plan must describe the whole work first, then classify it into executable tasks and any needed sub-tasks.
+- Every plan must treat the user-called/main agent as the orchestrator and assign implementation edits to `worker` whenever subagent tools are available, regardless of Light Path or Heavy Path (see `cairn://skills/cairn-plan/delegation.md`).
+- Every plan must include complexity triage, the selected path, and the Heavy Path signals checked, even when Light Path is selected.
+- Every plan must include applied model guidance and rationale.
+- Every plan must include tool readiness results: detected stack, required LSP/check tools, installed tools, and blockers.
+- Every executable plan must include a stable goal ID, stable task IDs, explicit terminal states, and fail-closed required evidence. A missing evidence section never means success.
+- Every implementation task must be small enough to verify with two checks: module acceptance verification and surface integration verification. Plan one goal-level final check (`finalReview`) run once through `goal finish` instead of rerunning earlier task checks after later edits.
+- Spend planning tokens on executable test design: requirements, invariants, boundaries, failure modes, expected initial failure, and authoritative tool result. Give implementation a bounded test contract and exact file scope; require the minimum passing change rather than renewed broad discovery.
+- Plan focused tests first, one final full check, and a package dry-run when no change occurred after the full check. Require lifecycle inspection, normal script execution for content-producing or unknown scripts, and `--ignore-scripts` only for absent or proven content-neutral scripts.
+- Heavy Path tasks must include an explicit automated test command and a `Tests:` evidence line.
+- Every risky or external-state-changing task must include the closest available dry-run or check command before the write/apply command.
+- Verification can expand for risk, but the reason must be recorded.
+- The default loop budget is two verification passes per task. If a gate fails, diagnose once, shrink or split the task, and rerun both gates. After two failed passes, record the blocker in `docs/plan/<topic>.md`.
+- Give every plan and ordered task a stable ID and declare task-level and goal-level required evidence, so Codex UI and hook context can show the roadmap and restore the current task after side questions.
+- Ask the user only when agents, repository evidence, or local verification cannot answer the decision.
+- User-visible responses and generated or updated documentation, plans, and memory artifacts follow the OS locale unless the user asks for another language.
+
+## Light Path Detail
+
+Light Path examples: one new API endpoint within existing layers; add or modify a controller or service method; strengthen validation rules; adjust query logic; change copy text or constants; fix one clearly scoped bug that exceeds Quick Path limits.
+
+Light Path flow: main-agent orchestration -> bounded `worker` implementation when subagent tools are available -> main-agent takeover when they are unavailable -> focused verification by the main agent or a scoped verification `worker` -> report. Planning/review agents may be skipped; the verification gate stays.
+
+## Route Record
+
+`docs/plan/<topic>.md` must record:
+
+- Selected path and selection rationale.
+- Heavy Path conditions found, if any, and conditions checked and not found.
+- Roles or delegation omitted in Light Path and why.
+- Any main-agent takeover because subagent tools were unavailable, and its evidence record.
+- Pre-implementation decisions that review must resolve in Heavy Path.
+- Request checkpoint, planning checkpoint, and code checkpoint status, evidence, newly found signals, and route.
+- Every route change and the synchronized plan artifact, repository goal task roadmap, native UI plan, assignments, reviews, required evidence, and stale evidence invalidation.
+
+## Tool Readiness Policy
+
+Do not silently skip LSP, typecheck, lint, dry-run, or verification because the tool is missing. Tool installation is a separate external-state change and requires explicit user approval.
+
+- Detect the codebase stack from repository files before choosing tools.
+- Prefer repository-local installation through the existing package manager and lockfile; use ephemeral runners only when project-local installation is not appropriate.
+- After approval, use the runtime's `toolcheck --install --yes --root "<repoRoot>"` only for pinned/supported installers, or the approved repository-native command. Run the tool after installation and record the result.
+- If installation was not approved or is impossible, record the proposed or attempted command, failure summary, and blocker in `docs/plan/<topic>.md`.
+- Treat "LSP server not installed" as an unresolved blocker until installation or an equivalent symbol-aware fallback has been attempted.
+
+## Dry-Run Policy
+
+Prefer repository-native dry-run and check modes before mutating external state.
+
+- Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
+- Package and release work: inspect lifecycle scripts first, then use normal `npm pack --dry-run`, publish dry-run, build check, or equivalent. Never skip content-producing or unknown lifecycle scripts with `--ignore-scripts`; it is allowed only for absent or proven content-neutral scripts while prior full-check evidence remains fresh.
+- Infrastructure and deployment: plan, diff, validate, check, or equivalent.
+- Code generation and formatting: check mode before write mode when available.
+- If no dry-run mode exists, record that fact and select the smallest reversible command or test artifact available.