devlyn-cli 3.1.2 → 3.2.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Codex Project Instructions
 
-devlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.
+devlyn-cli installs planning and full-pipeline skills alongside the execution contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.
 
 ## North Star
 
@@ -27,22 +27,22 @@ Three discipline rules govern HOW the principles are applied:
 ## Quick Start
 
 ```text
-ideate (optional)  ->  resolve  ->  ship
+inspect intent  ->  direct work or full resolve  ->  ship
 ```
 
 - `/devlyn:ideate` (optional) — unstructured idea → `docs/specs/<id>/spec.md` + `spec.expected.json`. Modes: default Q&A, `--quick` (autonomous-pipeline-safe), `--from-spec <path>`, `--project` (multi-feature).
-- `/devlyn:resolve` — hands-free pipeline for any coding task. Free-form goal, `--spec <path>`, or `--verify-only <ref> --spec <path>`. Phases run inline: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh-subagent, findings-only).
+- `/devlyn:resolve` — full pipeline for work selected by the conversational-entry rules below. Free-form goal, `--spec <path>`, or `--verify-only <ref> --spec <path>`. Phases: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh-subagent, findings-only).
 - `/devlyn:design-ui` — required creative UI exploration surface. Spawns a 5-specialist design team (Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer) to generate N (default 5) portfolio-worthy HTML/CSS samples. The optional `/devlyn:reap` companion lives in `optional-skills/` and installs only when the user opts in.
 
 Each skill's `SKILL.md` is the source of truth for flags and workflow. Do not duplicate.
 
 Engine roles: orchestrator = whichever CLI the user opened (this contract is symmetric with CLAUDE.md. If you are Codex orchestrating `/devlyn:resolve`, the phase machinery is mandatory regardless of task size; if you will not run it, say so explicitly and stop — do not silently degrade to ad-hoc execution); legacy executor (with optional separate worker/primary/pair profiles) uses the canonical skill's orchestrator-supported default, overridable per run with `--engine <name>` or durably via machine-local `.devlyn/engines.json` `{"executor": "<name>", "pair_judge_priority": ["<name>", ...]}`; PLAN is orchestrator-fixed and never inherits `--engine` or the executor pin; pair judge = first available OTHER engine, default for VERIFY whenever available; risk probes remain conditional and --no-pair opts out. Pins fail closed (`BLOCKED:<engine>-unavailable` / `BLOCKED:invalid-engine-config`); new engines plug in by shipping `_shared/adapters/<name>.md`. `/devlyn:engines` (no args) shows the role table + detected engines; `executor <name>` / `pair <name>,...` / `clear` manage the pins. The executor pin binds the orchestrator in plain conversation too, not only inside a skill run: when you would implement directly and executor is pinned to a non-default engine, route that work through the pin — via `/devlyn:resolve` (reads it at PHASE 0) or by delegating to that engine; no pin / no file → use the canonical skill's orchestrator-supported default. The pair-judge pin stays pipeline-scoped. `/devlyn:engines role` configures explicit engine/model/effort for supported worker and judge routes; `/devlyn:resolve --role-config <path>` overrides roles for one run. Canonical skills define precedence, evidence and unsupported-route errors; absent profiles preserve existing defaults.
 
-Conversational entry: Before writes, inspect requested files and relevant callers/tests. Default to direct execution only for clear, local, reversible, low-risk work with a decisive existing or small task-specific acceptance check. Preserve requested behavior, scope, explicit constraints and the executor pin; make scoped edits, run required checks, review the final diff, and report changes with evidence. One concise route/check explanation suffices; ordinary direct work needs no spec, pipeline state, phase workers or extra approval. For direct/full/queue work, the outer owner reads `references/task-completion.md` relative to the installed `devlyn:resolve` skill's directory: prospective task-branch ownership (linked worktree optional), scoped commit acceptance, then PR/merge and recoverable owned-resource cleanup after required archive/queue commits. Local-only/no-push wins; delivery pending/failure stays separate from product verification.
+Conversational entry: Before loading a workflow or writing files, inspect the requested change and relevant callers/tests. Quoted phase names, past logs and skill-file paths are context, not an instruction to invoke that workflow; follow the current user request. Default to direct execution when inspection makes the requested behavior, affected boundaries and verification tractable in the current context, including bounded multi-file work. Preserve requested behavior, scope, explicit constraints and the executor pin; make scoped edits, run required checks, review the final diff, and report changes with evidence. One concise route/check explanation suffices; ordinary direct work needs no spec, pipeline state, phase workers or extra approval. For direct/full/queue work, the outer owner reads `references/task-completion.md` relative to the installed `devlyn:resolve` skill's directory: prospective task-branch ownership (linked worktree optional), scoped commit acceptance, then PR/merge and recoverable owned-resource cleanup after required archive/queue commits. Local-only/no-push wins; delivery pending/failure stays separate from product verification.
 
-Use full `/devlyn:resolve` for material ambiguity, subsystem/design work, security/auth/payment/persistence/concurrency/public-API-contract changes, or inconclusive inspection/checks. Counts of lines, files or words alone do not establish low risk. Explicit resolve (even small), formal spec workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If new risk appears mid-edit, preserve the delta in the full run's scope/evidence; do not hide it in a new baseline or reconfirm existing authorization.
+Use full `/devlyn:resolve` automatically only when inspection identifies interacting requirements or verification work too complex to manage reliably in the current context, such as coupled durable state, concurrent ownership and failure recovery across boundaries. Name the concrete interaction or verification gap. Domain labels (security/auth/payment/persistence/concurrency/API), file count and a spec document alone do not trigger it. Investigate or clarify missing intent/access first; a pipeline cannot supply them. Direct work still requires risk-proportionate checks and independent review for consequential changes. Explicit resolve (even small), explicit spec-mode workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If the full-route condition emerges mid-edit, carry the existing delta into its scope/evidence; do not reset the baseline or reconfirm existing authorization.
 
-Full-route handoff + loop engineering: the orchestrating model — not the user — invokes the skills. `/devlyn:queue` fronts the intent queue (`docs/specs/queue.md`): no args = status, `add <intent>`, `drain` = serial unattended drain per the contract below. Large agreed work is written to `docs/specs/<id>/spec.md` (always a spec file — the user's reviewed contract; free-form large assumes-and-logs instead of halting, zero-scope-signal goals still halt to ideate), summarized once for user review, then run hands-free via `--spec`. Outer loop per task: before the first full run, commit the scoped queue-item delta (when applicable) and linked spec bundle; findings-backed verdicts (NEEDS_WORK, verify/build-gate exhaustion) get a committed spec amendment before re-run, max 3 iterations; infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts surface immediately. Unattended queue drain (`docs/specs/queue.md`, strictly serial): assumptions may only take scope-narrowing, reversible, non-user-visible defaults — material ambiguity marks the item `[F] needs-review`; commit every terminal `[x]` / `[F]` transition before advancing. The canonical commit order is `config/skills/devlyn:resolve/references/outer-loop.md`.
+Full-route handoff + loop engineering: the orchestrating model — not the user — invokes the skills. `/devlyn:queue` fronts the intent queue (`docs/specs/queue.md`): no args = status, `add <intent>`, `drain` = serial unattended drain per the contract below. Work selected for full resolve is written to `docs/specs/<id>/spec.md` (always a spec file — the user's reviewed contract; free-form large assumes-and-logs instead of halting, zero-scope-signal goals still halt to ideate), summarized once for user review, then run hands-free via `--spec`. Outer loop per task: before the first full run, commit the scoped queue-item delta (when applicable) and linked spec bundle; findings-backed verdicts (NEEDS_WORK, verify/build-gate exhaustion) get a committed spec amendment before re-run, max 3 iterations; infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts surface immediately. Unattended queue drain (`docs/specs/queue.md`, strictly serial): assumptions may only take scope-narrowing, reversible, non-user-visible defaults — material ambiguity marks the item `[F] needs-review`; commit every terminal `[x]` / `[F]` transition before advancing. The canonical commit order is `config/skills/devlyn:resolve/references/outer-loop.md`.
 
 ## Subtractive-First Editing
 

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Project Instructions
 
-devlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. These principles are non-negotiable on every change — yours and any sub-agent's.
+devlyn-cli installs planning and full-pipeline skills alongside the execution contract below. These principles are non-negotiable on every change — yours and any sub-agent's.
 
 ## North Star
 
@@ -28,10 +28,10 @@ The runtime sub-agent contract below (Subtractive-first / Goal-locked / No-worka
 
 ## Quick Start
 
-Engine selection follows the role map below.
+Choose direct work or full resolve using the conversational-entry rules below; engine selection follows the role map.
 
 1. `/devlyn:ideate` (optional) — unstructured idea → `docs/specs/<id>/spec.md` + `spec.expected.json`. Modes: default Q&A, `--quick` (autonomous-pipeline-safe), `--from-spec <path>`, `--project`.
-2. `/devlyn:resolve` — hands-free pipeline for any coding task. Free-form goal, `--spec <path>`, or `--verify-only <diff> --spec <path>`. Phases: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh subagent, findings-only).
+2. `/devlyn:resolve` — full pipeline for work selected by the conversational-entry rules below. Free-form goal, `--spec <path>`, or `--verify-only <diff> --spec <path>`. Phases: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh subagent, findings-only).
 
 Each skill's `SKILL.md` is the source of truth for its flags and workflow — don't duplicate them here.
 
@@ -51,13 +51,13 @@ Each skill's `SKILL.md` is the source of truth for its flags and workflow — do
 
 ### Conversational entry + full-route handoff
 
-Before writes, inspect requested files and relevant callers/tests. Default to direct execution only for clear, local, reversible, low-risk work with a decisive existing or small task-specific acceptance check. Preserve requested behavior, scope, explicit constraints and the executor pin; make scoped edits, run required checks, review the final diff, and report changes with evidence. One concise route/check explanation suffices; ordinary direct work needs no spec, pipeline state, phase workers or extra approval. For direct/full/queue work, the outer owner reads `references/task-completion.md` relative to the installed `devlyn:resolve` skill's directory: prospective task-branch ownership (linked worktree optional), scoped commit acceptance, then PR/merge and recoverable owned-resource cleanup after required archive/queue commits. Local-only/no-push wins; delivery pending/failure stays separate from product verification.
+Before loading a workflow or writing files, inspect the requested change and relevant callers/tests. Quoted phase names, past logs and skill-file paths are context, not an instruction to invoke that workflow; follow the current user request. Default to direct execution when inspection makes the requested behavior, affected boundaries and verification tractable in the current context, including bounded multi-file work. Preserve requested behavior, scope, explicit constraints and the executor pin; make scoped edits, run required checks, review the final diff, and report changes with evidence. One concise route/check explanation suffices; ordinary direct work needs no spec, pipeline state, phase workers or extra approval. For direct/full/queue work, the outer owner reads `references/task-completion.md` relative to the installed `devlyn:resolve` skill's directory: prospective task-branch ownership (linked worktree optional), scoped commit acceptance, then PR/merge and recoverable owned-resource cleanup after required archive/queue commits. Local-only/no-push wins; delivery pending/failure stays separate from product verification.
 
-Use full `/devlyn:resolve` for material ambiguity, subsystem/design work, security/auth/payment/persistence/concurrency/public-API-contract changes, or inconclusive inspection/checks. Counts of lines, files or words alone do not establish low risk. Explicit resolve (even small), formal spec workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If new risk appears mid-edit, preserve the delta in the full run's scope/evidence; do not hide it in a new baseline or reconfirm existing authorization.
+Use full `/devlyn:resolve` automatically only when inspection identifies interacting requirements or verification work too complex to manage reliably in the current context, such as coupled durable state, concurrent ownership and failure recovery across boundaries. Name the concrete interaction or verification gap. Domain labels (security/auth/payment/persistence/concurrency/API), file count and a spec document alone do not trigger it. Investigate or clarify missing intent/access first; a pipeline cannot supply them. Direct work still requires risk-proportionate checks and independent review for consequential changes. Explicit resolve (even small), explicit spec-mode workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If the full-route condition emerges mid-edit, carry the existing delta into its scope/evidence; do not reset the baseline or reconfirm existing authorization.
 
-The user does not invoke skills manually; the orchestrating model does. Large tasks agreed in conversation:
+The user does not invoke skills manually; the orchestrating model does. For work selected for full resolve:
 
-1. Write the agreed contract to `docs/specs/<id>/spec.md` (+ `spec.expected.json` when mechanical verifications exist). Always a spec file for large work — a written spec is the user's reviewed contract; free-form large now assumes-and-logs instead of halting (zero-scope-signal goals still halt to ideate).
+1. Write the agreed contract to `docs/specs/<id>/spec.md` (+ `spec.expected.json` when mechanical verifications exist). Use a spec file for the selected work — a written spec is the user's reviewed contract; free-form large now assumes-and-logs instead of halting (zero-scope-signal goals still halt to ideate).
 2. Present a one-screen plan-contract summary — the user's single review checkpoint, BEFORE the pipeline starts.
 3. On go-ahead, commit the scoped queue-item delta (when applicable) and linked spec bundle, then invoke `/devlyn:resolve --spec <path>` hands-free to completion.
 4. **Per-task outer loop**: read the terminal verdict. Successful normal-run archive → outer-owner completion per the canonical task-completion reference, after any terminal queue commit. Verdicts backed by spec/verification findings (NEEDS_WORK, verify/build-gate exhaustion) → adjudicate the findings, amend the spec (recorded in the spec file; spec stays read-only inside a run), commit that scoped amendment, then re-invoke — at most 3 outer iterations, then surface with the findings trail. Infrastructure, invalid-input, engine-availability, and implement-empty BLOCKED verdicts are not spec-amendable: surface immediately. Every iteration re-enters through committed durable artifacts (spec, findings, run archive), never conversation memory.

package/README.md

@@ -27,16 +27,16 @@ If devlyn-cli saved you time, [give it a star](https://github.com/fysoul17/devly
 npx devlyn-cli
 ```
 
-That's it. The installer opens with a single **agent selector** — pick any combination of **Claude Code**, **Codex CLI**, **oh-my-pi (omp)**, **Pi**, or **Grok Build CLI**, and devlyn installs into every one you choose in a single pass. Claude Code and any agent already present on your machine are pre-checked, so the common case is just Enter. Skill-capable agents receive the `devlyn:resolve`, `devlyn:ideate`, and `devlyn:design-ui` skills — plus the `devlyn:engines` and `devlyn:queue` utilities — in the directory each one loads from: Codex → `~/.codex/skills/`, Grok → `~/.grok/skills/`, while **omp and Pi share `~/.agents/skills/`** — the cross-agent standard both read — so the bundle is written there once, not duplicated per agent. In Codex / omp / Pi, invoke them as skills (`$devlyn:resolve`, `$devlyn:ideate`, `$devlyn:design-ui`); in Claude Code and Grok Build CLI they're slash commands (`/devlyn:resolve`). Rerunning refreshes skills for selected agents, preserves existing AGENTS.md without legacy managed markers (legacy appended blocks are still cleaned up), and replaces CLAUDE.md when Claude Code is selected. Use the bundled AGENTS.md template path printed by the installer to compare and merge relevant shared runtime instructions into your preserved AGENTS.md, retaining your content and keeping engine-specific instructions distinct. (`npx devlyn-cli -y` installs the Claude core non-interactively; `npx devlyn-cli agents <cli>` adds one agent later.)
+That's it. The installer opens with a single **agent selector** — pick any combination of **Claude Code**, **Codex CLI**, **oh-my-pi (omp)**, **Pi**, or **Grok Build CLI**, and devlyn installs into every one you choose in a single pass. Claude Code and any agent already present on your machine are pre-checked, so the common case is just Enter. Skill-capable agents receive the `devlyn:resolve`, `devlyn:ideate`, and `devlyn:design-ui` skills — plus the `devlyn:engines` and `devlyn:queue` utilities — in the directory each one loads from: Codex → `~/.codex/skills/`, Grok → `~/.grok/skills/`, while **omp and Pi share `~/.agents/skills/`** — the cross-agent standard both read — so the bundle is written there once, not duplicated per agent. In Codex / omp / Pi, invoke them as skills (`$devlyn:resolve`, `$devlyn:ideate`, `$devlyn:design-ui`); in Claude Code and Grok Build CLI they're slash commands (`/devlyn:resolve`). Rerunning refreshes skills and the managed instruction block for selected agents while preserving project rules outside it. See [Migration from earlier versions](#migration-from-earlier-versions) for legacy migration and merge recovery. (`npx devlyn-cli -y` installs the Claude core non-interactively; `npx devlyn-cli agents <cli>` adds one agent later.)
 
 ---
 
-## How It Works — Two Skills, Full Cycle
+## How It Works — Direct Work or Full Pipeline
 
-devlyn-cli turns your AI coding agent into a hands-free development pipeline. The pipeline surface is two skills, with `/devlyn:design-ui` installed as the required creative UI surface:
+devlyn-cli supports direct execution for clear, low-risk work with decisive checks and a full pipeline for work that needs it. The pipeline surface is two skills, with `/devlyn:design-ui` installed as the required creative UI surface:
 
 ```
-ideate (optional)  →  resolve  →  ship
+inspect intent  →  direct work or full resolve  →  ship
 ```
 
 Non-Claude agents (Codex / omp / Pi / Grok): when one of these is selected, the workflows install as that agent's skills. In Codex / omp / Pi, use `$devlyn:ideate`, `$devlyn:resolve`, or `$devlyn:design-ui`; in Grok, use `/devlyn:ideate`, `/devlyn:resolve`, or `/devlyn:design-ui`, the same slash-command form as Claude Code.
@@ -60,9 +60,9 @@ Default mode produces a `docs/specs/<id>-<slug>/spec.md` plus `spec.expected.jso
 
 Skip ideate entirely if you have a spec or just want to describe the work — `/devlyn:resolve` accepts free-form goals too.
 
-### Step 2 — Resolve with `/devlyn:resolve`
+### Choose direct execution or `/devlyn:resolve`
 
-Before writes, inspect requested files and relevant callers/tests. Clear, local, reversible, low-risk conversational edits with a decisive acceptance check run directly, honoring scope, constraints and executor pins; finish required checks and diff review, then accept the scoped commit for owner completion below. Material ambiguity, subsystem/design work, security/auth/payment/persistence/concurrency/public-API-contract changes or no decisive check use full `/devlyn:resolve`. Explicit resolve (including small tasks), formal specs and queue drains keep the full workflow below. Pass a spec, a free-form goal, or a diff to verify.
+Inspect the requested behavior, affected callers and tests first. Default to direct work when its scope and verification are tractable, including bounded multi-file changes; honor constraints and executor pins, run risk-proportionate checks and independent review for consequential changes, then review the diff and deliver. Automatically use full `/devlyn:resolve` only for concrete interacting requirements or verification too complex to manage reliably in the current context, such as coupled durable state, concurrent ownership and failure recovery. Domain labels, file count and a spec document alone do not trigger it. Investigate or clarify missing intent/access first. Explicit resolve (including small tasks), explicit spec-mode workflows and queue drains keep the full workflow below.
 
 ```
 /devlyn:resolve "fix the login bug"                                # free-form
@@ -76,10 +76,10 @@ Internal phases run sequentially with file-based handoff via `.devlyn/pipeline.s
 PLAN  →  IMPLEMENT  →  BUILD_GATE  →  CLEANUP  →  VERIFY (fresh subagent, findings-only)
 ```
 
-- **PLAN** is the heaviest phase by design — formalizes invariants from the spec/goal and the file list to touch.
-- **BUILD_GATE** runs your project's real compilers, typecheckers, linters, and `python3 .claude/skills/_shared/spec-verify-check.py` (verification commands literal-match). Auto-detects Next.js, Rust, Go, Solidity, Expo, Swift, and Dockerfiles. Browser flows route through Chrome MCP → Playwright → curl tier.
+- **PLAN** runs in the owner context and freezes requirements, verification and the authorized file surface before implementation.
+- **BUILD_GATE** runs commands in the owner context without another model invocation, using your project's real compilers, typecheckers, linters, and `python3 .claude/skills/_shared/spec-verify-check.py` (verification commands literal-match). Auto-detects Next.js, Rust, Go, Solidity, Expo, Swift, and Dockerfiles. Browser flows route through Chrome MCP → Playwright → curl tier.
 - **VERIFY** runs in a fresh subagent context with no code-mutation tools — findings only, structurally independent.
-- Git checkpoints at every phase for safe rollback. Fix-loop budget shared across BUILD_GATE and VERIFY (`--max-rounds N`, default 4).
+- Git checkpoints at every phase for safe rollback. Fix-loop budget shared across BUILD_GATE, CLEANUP and VERIFY (`--max-rounds N`, default 4).
 
 Common flags: `--engine claude|codex|omp` (default: the orchestrator-supported default), `--role-config <path>` (one-run worker/judge profiles, see below), `--bypass build-gate,cleanup`, `--pair-verify` (force pair-mode JUDGE in VERIFY), `--no-pair` (intentional solo VERIFY), `--risk-probes` / `--no-risk-probes`, `--perf` (per-phase timing).
 `--pair-verify` and `--no-pair` are mutually exclusive; using both stops with `BLOCKED:invalid-flags`.
@@ -118,10 +118,10 @@ Stack tasks to run back-to-back without supervision. `/devlyn:queue add "<intent
 devlyn separates three engine roles:
 
 - **Orchestrator** — the CLI you opened (Claude Code, Codex, or omp) that drives the conversation and loop. The contract is symmetric (`CLAUDE.md` ↔ `AGENTS.md`), so the same phase-gated pipeline runs whichever you launch; the file artifacts (spec, queue, state) carry over if you switch.
-- **Executor** (legacy) — the worker for IMPLEMENT / CLEANUP and their repair rounds, and the primary VERIFY judge, unless either is separately profiled (below). Defaults to the orchestrator-supported default. PLAN is orchestrator-fixed and never inherits `--engine` or an executor pin. An absent primary profile follows the legacy executor, not an opt-in worker profile.
+- **Executor** (legacy) — the worker for IMPLEMENT, its included code/doc cleanup, and their repair rounds, and the primary VERIFY judge, unless either is separately profiled (below). Defaults to the orchestrator-supported default. PLAN is orchestrator-fixed and never inherits `--engine` or an executor pin. An absent primary profile follows the legacy executor, not an opt-in worker profile.
 - **Pair judge** — the first available *other* engine, default for VERIFY and conditional for risk probes.
 
-`--engine <name>` sets the legacy executor for one run as an engine-only entry (it clears any lower-precedence profile's model/effort). BUILD_GATE and risk-probe derivation keep their existing routes; PLAN always runs on the orchestrator's native worker. VERIFY/JUDGE runs pair mode by default when the OTHER engine is available.
+`--engine <name>` sets the legacy executor for one run as an engine-only entry (it clears any lower-precedence profile's model/effort). PLAN stays in the owner context; BUILD_GATE/CLEANUP run owner commands; risk-probe derivation keeps its existing route. VERIFY/JUDGE runs pair mode by default when the OTHER engine is available.
 
 Pin roles durably with `/devlyn:engines` (no args shows the role table + detected engines; `executor <name>` / `pair <name>,...` / `role <worker|primary_judge|pair_judge> <JSON object>` / `role <name> clear` manage the pins, stored machine-local in `.devlyn/engines.json`; `clear` removes all legacy and role pins, preserves unrelated keys, and deletes an empty file). Pins fail closed: an unavailable pinned engine stops with `BLOCKED:<engine>-unavailable`, and a name with no `_shared/adapters/<name>.md` adapter stops with `BLOCKED:invalid-engine-config`. New engines plug in by shipping an adapter file — no skill changes.
 
@@ -144,12 +144,12 @@ Pin roles durably with `/devlyn:engines` (no args shows the role table + detecte
 `--role-config <path>` supplies the same `{"roles": {...}}` object for one run only, with no other top-level keys; the flag may appear once.
 
 - **Precedence** — an entry replaces the lower one as a whole; model/effort never merge across engines. Worker and primary judge: run `--role-config` entry > `--engine` (engine-only) > project role entry > legacy executor/default. Pair judge: run entry > project entry > `pair_judge_priority` / the OTHER-engine complement. A missing `model`/`effort` keeps that route's current default and is shown as inherited/unresolved.
-- **Boundaries** — `worker` covers IMPLEMENT / CLEANUP and their repair rounds; `primary_judge` and `pair_judge` cover VERIFY only. PLAN stays orchestrator-fixed, BUILD_GATE keeps its existing route, and risk-probe derivation stays outside these controls. OTHER must differ from the primary by engine: an explicit same-engine pair is `BLOCKED:invalid-engine-config`. `--no-pair` is unchanged — explicit solo VERIFY; an unused pair entry is neither dispatched nor availability-checked.
+- **Boundaries** — `worker` covers IMPLEMENT, its included code/doc cleanup, and their repair rounds; `primary_judge` and `pair_judge` cover VERIFY only. PLAN stays orchestrator-fixed, BUILD_GATE/CLEANUP run owner commands, and risk-probe derivation stays outside these controls. OTHER must differ from the primary by engine: an explicit same-engine pair is `BLOCKED:invalid-engine-config`. `--no-pair` is unchanged — explicit solo VERIFY; an unused pair entry is neither dispatched nor availability-checked.
 - **Initial explicit routes** — Codex worker/primary/pair accept exact `model` + `effort` (dispatched as `-m` / `-c model_reasoning_effort=`, validated against the installed Codex CLI's native model metadata for its version). Claude primary/pair judges pass an exact `model` as `--model` and validate native result identity; model-only selection needs no source update for a new ID. Explicit `effort` separately requires the adapter's version/model support declaration. The Claude worker stays the native `Agent` route and is engine-only: explicit `model`/`effort` on a Claude worker is `BLOCKED:unsupported-role-option` — a supported-route boundary, not a claim that Claude cannot implement. Other adapters (omp, grok) are engine-only for their eligible roles.
 - **Errors** — `BLOCKED:unsupported-role-option` names the role, engine and field with guidance; there is no clamp, fallback, substituted model, or weaker retry. An explicitly selected engine (flag, pin, or profile) that is unavailable stops with `BLOCKED:<engine>-unavailable`. A native warning that a requested option was ignored is a failed promise even at exit 0.
 - **Requested vs observed** — `/devlyn:engines` status prints each role's requested engine/model/effort, source and dispatch channel before dispatch; it describes a request and does not prove a native invocation happened. Effective model is reported only with native evidence; a Codex worker receipt binds requested dispatch and leaves effective model unknown. A reported worker model reroute blocks completion even at exit 0. SURFACE_CLOSE inherits native Claude model settings and records the model from its required JSON result. Effective effort stays unknown unless native evidence establishes it — invocation arguments prove dispatch, not provider-internal reasoning.
 
-`--engine codex` routes IMPLEMENT / CLEANUP to Codex as a supported engine-only route (exact model/effort via the profiles above). Historical record: iter-0020 closed Codex BUILD/IMPLEMENT below the quality floor on the 9-fixture suite (L2 vs L1 = −3.6, 3/8 gated fixtures cleared the +5 margin floor — release-readiness FAIL). Separately, PLAN-pair remains research-only: iter-0033g + iter-0034 closed it with explicit unblock conditions (container/sandbox infra OR production telemetry capturing positive evidence of subagent introspection). Install the Codex CLI (https://platform.openai.com/docs/codex) and pass the flag explicitly to opt in:
+`--engine codex` routes IMPLEMENT and its included code/doc cleanup to Codex as a supported engine-only route (exact model/effort via the profiles above). Historical record: iter-0020 closed Codex BUILD/IMPLEMENT below the quality floor on the 9-fixture suite (L2 vs L1 = −3.6, 3/8 gated fixtures cleared the +5 margin floor — release-readiness FAIL). Separately, PLAN-pair remains research-only: iter-0033g + iter-0034 closed it with explicit unblock conditions (container/sandbox infra OR production telemetry capturing positive evidence of subagent introspection). Install the Codex CLI (https://platform.openai.com/docs/codex) and pass the flag explicitly to opt in:
 
 ```
 /devlyn:resolve "fix the auth bug" --engine codex
@@ -227,6 +227,27 @@ ids.
 
 ### Migration from earlier versions
 
+Reinstall with the new version to refresh instructions and skills for the selected
+CLIs. Claude uses `CLAUDE.md`; Codex, Grok, omp and Pi share `AGENTS.md`.
+Devlyn updates its checksum-marked instruction block and preserves project-specific
+rules outside it. Keep custom rules outside the block; they take precedence over
+its defaults. Exact pre-update backups are saved in `.devlyn/instructions/`.
+When recovery is needed, pre-existing symlinks or non-directory entries at `.devlyn/` or
+`.devlyn/instructions/` stop installation without replacing the instruction file.
+
+Templates from versions 3.0.0–3.1.2 migrate automatically, including custom
+text before or after the template. Replaced or extended introductions under the
+original project heading also migrate when the entire body from `## North Star`
+onward matches a known template hash. Replacement project rules are preserved
+outside the managed block; only an exact original introduction is removed.
+Recognizable leftover Devlyn text, changed bodies and ambiguous templates stop
+with a concise recovery message and leave the original unchanged. The message
+links an exact `.backup`, new defaults in `.incoming`, and a `.merge.md` guide.
+Compare the two files, preserve all project rules outside one new managed block,
+and rerun the same install command. Earlier selected agents may already be updated.
+Plain custom instruction files retain their contents and gain a managed block.
+Use 3.1.3 or newer consistently: older installers still overwrite `CLAUDE.md`.
+
 <!-- legacy-surface-map:begin — retired command names below are documented as OLD, not current; lint Check 10c skips this block -->
 Earlier versions of devlyn-cli shipped 16+ slash commands. The iter-0034 Phase 4 cutover (2026-05-04) and the 2026-05-14 follow-up consolidated them down to the three current commands. Upgrades automatically purge the legacy skill directories from `~/.claude/skills/`.
 

package/bin/devlyn.js

@@ -9,6 +9,7 @@ const { execSync } = require('child_process');
 const CONFIG_SOURCE = path.join(__dirname, '..', 'config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
 const PKG = require('../package.json');
+const { updateInstructions, InstructionError } = require('./instructions');
 
 // The devlyn skill bundle installed into every skill-capable agent's loader
 // directory. Single source of truth so codex/omp/pi stay in lockstep — adding a
@@ -700,20 +701,6 @@ function installSkillsForCLI(cliKey) {
   return copied;
 }
 
-// Strip the legacy "# Devlyn Agent Instructions" block (the retired evaluator
-// agent) that earlier installs appended to instruction files, so upgrades scrub
-// it instead of carrying it forever. Anchors on the LAST marker so user content
-// above a stray copy of the block is preserved.
-const DEVLYN_AGENTS_MARKER = '# Devlyn Agent Instructions';
-function stripManagedBlock(content) {
-  const markerIdx = content.lastIndexOf(DEVLYN_AGENTS_MARKER);
-  if (markerIdx > 0) {
-    const sepIdx = content.lastIndexOf('\n---', markerIdx);
-    return content.slice(0, sepIdx > 0 ? sepIdx : markerIdx).trimEnd();
-  }
-  return content.trimEnd();
-}
-
 // One-line description of exactly what selecting a CLI target installs, so the
 // unified selector stays honest.
 function targetDesc(cli) {
@@ -723,35 +710,10 @@ function targetDesc(cli) {
   return `${cli.instructionsFile} instructions only`;
 }
 
-// Install the packaged base instruction file for a CLI (project AGENTS.md for
-// codex/omp/pi). Creates it from the packaged base when missing; on existing
-// files, scrubs the legacy appended block and otherwise leaves user content
-// untouched. Returns true when the destination was written.
+// Shared instruction ownership and preservation rules apply to every CLI.
 function installInstructionsForCLI(cliKey) {
   const cli = CLI_TARGETS[cliKey];
-  if (!cli || !cli.baseInstructionsFile) return false;
-
-  const destFile = path.join(process.cwd(), cli.instructionsFile);
-  const baseInstructionsSrc = path.join(__dirname, '..', cli.baseInstructionsFile);
-  let content = null;
-  if (fs.existsSync(destFile)) {
-    const current = fs.readFileSync(destFile, 'utf8');
-    if (current.includes(DEVLYN_AGENTS_MARKER)) {
-      content = stripManagedBlock(current) + '\n';
-    } else {
-      log(`  → Preserved existing ${cli.instructionsFile}. Compare with the bundled template at ${baseInstructionsSrc} and merge relevant instructions.`, 'dim');
-    }
-  } else {
-    if (fs.existsSync(baseInstructionsSrc)) {
-      content = fs.readFileSync(baseInstructionsSrc, 'utf8');
-    }
-  }
-  if (content === null) return false;
-
-  log(`\n🤖 Installing instructions for ${cli.name}...`, 'cyan');
-  fs.writeFileSync(destFile, content);
-  log(`  → ${cli.instructionsFile}`, 'dim');
-  return true;
+  return cli?.baseInstructionsFile ? updateInstructions(cli.baseInstructionsFile) : false;
 }
 
 // Install both instructions and skills for a single CLI. Used by the
@@ -803,8 +765,31 @@ function installAgentsForAllDetected() {
 // Install the Claude Code core config: project .claude/ (skills, templates,
 // settings, CLAUDE.md, .gitignore) plus global ~/.claude/settings.json tweaks.
 // Extracted so the unified target selector installs it only when "Claude Code"
-// is chosen. Behavior is unchanged from the previous unconditional core install.
+// is chosen. Check global settings and instruction conflicts before writes.
 function installClaudeCore() {
+  const globalClaudeDir = path.join(os.homedir(), '.claude');
+  const globalSettingsPath = path.join(globalClaudeDir, 'settings.json');
+  function readGlobalSettings() {
+    let settings = {};
+    try {
+      if (fs.lstatSync(globalSettingsPath, { throwIfNoEntry: false })) {
+        settings = JSON.parse(fs.readFileSync(globalSettingsPath, 'utf8'));
+      }
+    } catch (error) {
+      const reason = error instanceof SyntaxError ? 'invalid JSON' : error.message;
+      throw new Error(`Cannot merge ${globalSettingsPath}: ${reason}. Original preserved; correct the file or its access and rerun installation.`);
+    }
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+      throw new Error(`Cannot merge ${globalSettingsPath}: root must be a JSON object. Original preserved; correct it and rerun installation.`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(settings, 'env')) settings.env = {};
+    if (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env)) {
+      throw new Error(`Cannot merge ${globalSettingsPath}: env must be a JSON object. Original preserved; correct it and rerun installation.`);
+    }
+    return settings;
+  }
+  readGlobalSettings();
+  updateInstructions('CLAUDE.md');
   const targetDir = getTargetDir();
   const skillsDir = path.join(targetDir, 'skills');
   log('\n📁 Installing Claude Code config to .claude/', 'green');
@@ -831,15 +816,6 @@ function installClaudeCore() {
     log(`\n🧹 Cleaned up ${removed} deprecated file${removed > 1 ? 's' : ''}`, 'yellow');
   }
 
-  // Copy Claude project instructions to project root. Other CLI instruction
-  // files are installed only when explicitly selected below or via `agents`.
-  const claudeMdSrc = path.join(__dirname, '..', 'CLAUDE.md');
-  const claudeMdDest = path.join(process.cwd(), 'CLAUDE.md');
-  if (fs.existsSync(claudeMdSrc)) {
-    fs.copyFileSync(claudeMdSrc, claudeMdDest);
-    log('  → CLAUDE.md', 'dim');
-  }
-
   // Keep installer-managed pipeline state and install metadata out of git.
   const gitignorePath = path.join(process.cwd(), '.gitignore');
   const gitignoreEntries = ['.devlyn/', '.claude/skills/.devlyn-install.json'];
@@ -950,17 +926,8 @@ function installClaudeCore() {
   }
 
   // Configure global Claude Code settings (~/.claude/settings.json)
-  const globalClaudeDir = path.join(os.homedir(), '.claude');
-  const globalSettingsPath = path.join(globalClaudeDir, 'settings.json');
-  let globalSettings = {};
-  if (fs.existsSync(globalSettingsPath)) {
-    try {
-      globalSettings = JSON.parse(fs.readFileSync(globalSettingsPath, 'utf8'));
-    } catch {
-      globalSettings = {};
-    }
-  }
-  if (!globalSettings.env) globalSettings.env = {};
+  // Project settings may refer to this same file; merge the latest bytes.
+  const globalSettings = readGlobalSettings();
   let globalSettingsChanged = false;
   if (!globalSettings.env.CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING) {
     globalSettings.env.CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING = '1';
@@ -1250,6 +1217,8 @@ function showBenchmarkModeHelp(mode) {
 
 // Main
 const args = process.argv.slice(2);
+
+async function main() {
 const command = args[0];
 
 switch (command) {
@@ -1259,7 +1228,7 @@ switch (command) {
     break;
   case '-y':
   case '--yes':
-    init(true);
+    await init(true);
     break;
   case 'list':
   case 'ls':
@@ -1314,10 +1283,14 @@ switch (command) {
       log('\n🤖 Installing agents for all supported CLIs...', 'blue');
       const count = installSelectedCLITargets(Object.keys(CLI_TARGETS));
       log(`\n✅ Agents installed for ${count} CLI${count !== 1 ? 's' : ''}`, 'green');
-    } else if (subArg && CLI_TARGETS[subArg]) {
+    } else if (Object.keys(CLI_TARGETS).includes(subArg)) {
       // Install for a specific CLI
       installAgentsForCLI(subArg);
       log('\n✅ Done!', 'green');
+    } else if (subArg !== undefined) {
+      log(`Unknown CLI target: ${JSON.stringify(subArg)}`, 'yellow');
+      log(`Supported: ${Object.keys(CLI_TARGETS).join(', ')}, all`, 'dim');
+      process.exit(1);
     } else {
       // Auto-detect and install
       const detected = detectOtherCLIs();
@@ -1336,10 +1309,16 @@ switch (command) {
   }
   case 'init':
   case undefined:
-    init(false);
+    await init(false);
     break;
   default:
     log(`Unknown command: ${command}`, 'yellow');
     showHelp();
     process.exit(1);
 }
+}
+
+main().catch((error) => {
+  console.error(error instanceof InstructionError ? `\n${error.message}` : error);
+  process.exitCode = 1;
+});

package/bin/instruction-templates.json

@@ -0,0 +1,82 @@
+{
+  "AGENTS.md": [
+    {
+      "versions": [
+        "3.0.0"
+      ],
+      "length": 11091,
+      "sha256": "099e68f3e203fa735bb1ebcd780a0e18bde462ea7de5f74fb3d17cee5e64b63a",
+      "preamble": "# Codex Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.\n\n",
+      "body": {
+        "length": 10816,
+        "sha256": "8b972c2c379e5ff8411bf1214f926a3b9904bdf857ac6b30a8c79ce0e32182e3"
+      }
+    },
+    {
+      "versions": [
+        "3.0.1"
+      ],
+      "length": 12166,
+      "sha256": "33fbd5b01c8e65f4c663f95423a45b16dcf5bb28f1fd0c6791079abd20c267ae",
+      "preamble": "# Codex Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.\n\n",
+      "body": {
+        "length": 11891,
+        "sha256": "52326a832df6d5ab13bddca5a1a01ad338a3db71d172c70d3eaed806668db4d8"
+      }
+    },
+    {
+      "versions": [
+        "3.1.0",
+        "3.1.1",
+        "3.1.2"
+      ],
+      "length": 12581,
+      "sha256": "acd3672efaa33e75455f8530a7425e950c01c822c6f5d85d7dbc9d7ff1958028",
+      "preamble": "# Codex Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.\n\n",
+      "body": {
+        "length": 12306,
+        "sha256": "0de6061f9dff8e88964e542bb8a5e113996e480bef597774fb15eaa766472129"
+      }
+    }
+  ],
+  "CLAUDE.md": [
+    {
+      "versions": [
+        "3.0.0"
+      ],
+      "length": 24434,
+      "sha256": "29ddcc5ef4d5b44b2ba6aae22bd3c0c033ceaa47b240bd647aaefbe00f2a6e4e",
+      "preamble": "# Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. These principles are non-negotiable on every change \u2014 yours and any sub-agent's.\n\n",
+      "body": {
+        "length": 24204,
+        "sha256": "555d8b9a4c154ec5225105919836a4d9831c76c1b1c7ee4c19fecac8fbd1c948"
+      }
+    },
+    {
+      "versions": [
+        "3.0.1"
+      ],
+      "length": 25417,
+      "sha256": "50301bf98507c83da1576be7f443885236e7d421ff2e40fd077ed9652ea3a2e0",
+      "preamble": "# Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. These principles are non-negotiable on every change \u2014 yours and any sub-agent's.\n\n",
+      "body": {
+        "length": 25187,
+        "sha256": "53a933e22369438a5d9dd7aa5f778909aeba5a38d5e2e68b8a36dab5c874d84d"
+      }
+    },
+    {
+      "versions": [
+        "3.1.0",
+        "3.1.1",
+        "3.1.2"
+      ],
+      "length": 26152,
+      "sha256": "d11a863907dabdf827063df7133a8a46a14e018f608884f08c601bf36e0f3f0c",
+      "preamble": "# Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. These principles are non-negotiable on every change \u2014 yours and any sub-agent's.\n\n",
+      "body": {
+        "length": 25922,
+        "sha256": "dd9f0f63f559a3b9a6e2bbf102045b01f6b73bce684dd27124ee6d6af3641b91"
+      }
+    }
+  ]
+}