devlyn-cli 4.0.1 → 4.2.0

package/README.md

@@ -8,7 +8,7 @@
 
 ### Context, Harness & Loop Engineering Toolkit for AI Coding Agents
 
-**Structured prompts, agent orchestration, and automated pipelines — debugging, code review, UI design, product specs, and more.**
+**Engineering principles for every coding agent, and a loop designer that turns one intent into tasks agents drain without you.**
 
 [![npm version](https://img.shields.io/npm/v/devlyn-cli.svg)](https://www.npmjs.com/package/devlyn-cli)
 [![npm downloads](https://img.shields.io/npm/dw/devlyn-cli.svg)](https://www.npmjs.com/package/devlyn-cli)
@@ -27,127 +27,67 @@ 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 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.)
+That's it. The installer asks:
 
----
-
-## How It Works — Direct Work or Full Pipeline
+1. **What** — `AGENTS.md — Codex · omp · Pi · Grok` (checked) and `CLAUDE.md — Claude Code` (checked when this project already has a devlyn Claude install). Space toggles, Enter confirms.
+2. **Where** — `This project` (default) or `Global — every project on this machine`.
+3. **Optional skills & packs** — none checked; see [Optional Add-ons](#optional-add-ons) below. MCP servers are offered only with CLAUDE.md.
 
-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:
+In a project, AGENTS.md readers load the skills from `.agents/skills/`; Claude Code loads only `.claude/skills/` and reads AGENTS.md when the project has no CLAUDE.md; a CLAUDE.md the installer creates imports an existing AGENTS.md (`@AGENTS.md`). Global installs skills only: `~/.agents/skills/` (omp, Pi, Grok) and `~/.codex/skills/` (Codex), plus `~/.claude/skills/` for Claude Code. Every target gets the `devlyn-ideate` skill and the `devlyn-engines` utility. In Codex / omp / Pi, invoke them as skills (`$devlyn-ideate`); in Claude Code and Grok they're slash commands (`/devlyn-ideate`). Rerunning refreshes skills and the managed instruction block while preserving project rules outside it. See [Migration from earlier versions](#migration-from-earlier-versions) for legacy migration and merge recovery.
 
-```
-inspect intent  →  direct work or full resolve  →  ship
-```
+Without prompts, `npx devlyn-cli -y` installs AGENTS.md + `.agents/skills/` plus every target this project already has; add `--claude` for Claude Code. With `--global` it installs for every project on this machine, plus `~/.claude/skills/` with `--claude` or when it already has a devlyn install.
 
-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.
+---
 
-### Step 1 (optional) — Plan with `/devlyn-ideate`
+## How It Works — Principles and Loops
 
-Turn a raw idea into a verifiable spec — single-feature, multi-feature, or "normalize this external doc".
+The managed `CLAUDE.md` / `AGENTS.md` block carries the North Star, seven principles (no workaround, no overengineering, no guesswork, worldclass, best practice, optimized, production ready) and three discipline rules, plus short pointers to the skills. Agents do the work directly under it; for work that splits into tasks, ideate designs a loop and drains it:
 
 ```
-/devlyn-ideate "I want to build a habit tracking app with AI nudges"
+intent  →  direct work under the installed principles, or an ideate loop  →  ship
 ```
 
-Default mode produces a `docs/specs/<id>-<slug>/spec.md` plus `spec.expected.json` (mechanical verification block) that `/devlyn-resolve --spec` consumes directly. Modes:
-
-| Mode | When to use |
-|---|---|
-| `default` | One feature, AI drives focused Q&A |
-| `--quick` | One-line goal → assume-and-confirm spec, single-turn (autonomous-pipeline-safe) |
-| `--from-spec <path>` | You already wrote a spec; ideate normalizes + lints it |
-| `--project` | Multi-feature project: emits `plan.md` index + N child specs |
-
-Skip ideate entirely if you have a spec or just want to describe the work — `/devlyn-resolve` accepts free-form goals too.
+Non-Claude agents (Codex / omp / Pi / Grok): the AGENTS.md choice installs the skills for them. In Codex / omp / Pi, use `$devlyn-ideate`; in Grok, use `/devlyn-ideate`, the same slash-command form as Claude Code. A drain from Pi or Grok needs [a pinned executor](#executor--devlyn-engines).
 
-### Choose direct execution or `/devlyn-resolve`
+### Plan and drain loops — `/devlyn-ideate`
 
-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.
+Give ideate an intent or a document. It writes a loop package — a meta-prompt plus self-contained task contracts with mechanical acceptance — and agents drain the tasks one by one without you.
 
-```
-/devlyn-resolve "fix the login bug"                                # free-form
-/devlyn-resolve --spec docs/specs/2026-05-04-auth/spec.md          # spec mode
-/devlyn-resolve --verify-only <diff-or-PR-ref> --spec <path>       # verify-only
-```
-
-Internal phases run sequentially with file-based handoff via `.devlyn/pipeline.state.json`:
-
-```
-PLAN  →  IMPLEMENT  →  BUILD_GATE  →  CLEANUP  →  VERIFY (fresh subagent, findings-only)
-```
+| Command | What it does |
+|---|---|
+| `/devlyn-ideate plan <intent or document>` | Inspects the project, asks only what it must, and writes a validated package to `docs/specs/<loop-id>/`. Nothing is queued or run. |
+| `/devlyn-ideate add <intent or package>` | Plans when needed, then queues the package's tasks in dependency order. It makes no commit on your branch: the package and its rows in `docs/specs/<loop-id>/queue.md` are held at `refs/devlyn/captures/<loop-id>` and your copies are removed. The first task's commit brings them into history, and the drain report's `Bring into` command brings the result into your branch. |
+| `/devlyn-ideate status` | Pending, active, accepted and failed counts; the next runnable task; delivery and recovery blockers. |
+| `/devlyn-ideate drain` | Runs the queue serially and hands-free. |
 
-- **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, CLEANUP and VERIFY (`--max-rounds N`, default 4).
+A bare intent is planned and, when your request authorizes the work, added and drained without another confirmation; no arguments shows status. Questions come only when the answer changes behavior, scope, data semantics, acceptance or delivery, each with a recommended answer; `--autonomous` plans without questions, recording ordinary low-consequence, reversible defaults within the request, including user-visible details; material ambiguity in intended outcomes, persistent data or state semantics, or public surface beyond the request stops planning with a concrete question. Each task runs in its own worktree with the executor pinned by `/devlyn-engines` (default: the CLI you opened; Pi and Grok need a pin) under your installed CLAUDE.md/AGENTS.md instructions. Tasks start from committed state, the branch you added the loop on or the remote base for `auto`/`pr`, so commit the installer's changes and whatever a plan depends on before adding a loop, and push them for `auto`/`pr`. It is marked `[x]` only when its declared checks pass on its committed source and its required reviews cover it: the checks run through the drain's runner (a wholly clean run the executor lists for that source is reused; the drain runs any other check itself), and review coverage is attested by records the executor submits; a failed task becomes `[F]` with its reason and blocks only its dependents. An interrupted drain resumes without repeating accepted work. `--local-only` (or `--no-push`) keeps delivery local: each accepted task stays on its `devlyn/<loop-id>/<task-id>` branch in a retained worktree, nothing is merged or pushed, and the drain report's `Bring into` command is `git merge --ff <latest accepted task branch>`.
 
-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`.
+### Delivery
 
-Each task gets its own linked worktree; accepted tasks default to scoped commit → push → PR
-→ merge when the repository allows it (otherwise the PR waits for a person). After the
+Direct work edits your current checkout; run parallel sessions in separate worktrees (for example `claude -w`). Completed, verified direct requests with changes, and
+every drained task, are delivered by project policy from their own linked worktrees. A commit request stays local and a PR request stops at the PR; otherwise accepted tasks default to
+scoped commit → push → PR → merge when the repository allows it (otherwise the PR waits for a person). After the
 PR merges, the worktree and branch its session released are cleaned; anything in use is
 kept. Set `git config --local devlyn.completionMode pr` to stop at the PR; `task-complete.py complete --mode auto|pr`
-overrides one task. Local-only/no-push instructions take precedence; existing
-branches cannot be adopted. Full runs require successful archive before delivery;
-direct tasks use their actual checks and root acceptance. Verify-only never
-publishes. Pending checks or unsupported merge policy retain resources and
+overrides one task. Local-only/no-push instructions take precedence: nothing is pushed or merged;
+a direct task's commit is fast-forwarded into your branch when that is safe, and a drained task
+stays on its task branch in its retained worktree. Existing
+branches cannot be adopted. Direct tasks use their actual checks and root
+acceptance. Pending checks or unsupported merge policy retain resources and
 report a receipt-based resume command separately from product verification.
-See [task completion](config/skills/devlyn-resolve/references/task-completion.md)
+See [task completion](config/skills/_shared/task-completion.md)
 for allocation, acceptance, writer cessation and recovery.
 
-### Queue multiple intents for unattended drain — `/devlyn-queue`
-
-Stack tasks to run back-to-back without supervision. `/devlyn-queue add "<intent>"` appends to `docs/specs/queue.md` (an ordered checklist); `/devlyn-queue drain` runs each item serially — spec it, run the resolve outer loop, commit `[x]` done or `[F]` blocked with a reason, then complete eligible delivery once. Product verdict and delivery status are separate. A blocked product otherwise never halts the queue; pending delivery retains its branch, and the next item requires separate safe placement. Unattended runs only take scope-narrowing, reversible defaults — anything user-visible or ambiguous is marked `[F] needs-review` for you to adjudicate afterward. `/devlyn-queue` with no args shows status.
+### Executor — `/devlyn-engines`
 
-### Engine roles — auto-detected, pinnable with `/devlyn-engines`
+The orchestrator is the CLI you opened (Claude Code, Codex, omp, Pi or Grok); the contract is symmetric (`CLAUDE.md` ↔ `AGENTS.md`), so the loop's file artifacts carry over if you switch. The executor does the implementation work, direct or drained: the engine pinned in machine-local `.devlyn/engines.json`, else the CLI you opened. Pi and Grok have no executor adapter, so a drain from them needs `devlyn-engines executor <claude|codex|omp>`.
 
-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, 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). 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.
-
-#### Explicit worker and judge profiles
-
-`.devlyn/engines.json` may add a `roles` object with `worker`, `primary_judge`, and `pair_judge` entries. Each entry requires `engine` and accepts an optional exact `model` ID and `effort`; unknown fields, aliases (`default`, `auto`, `opus`, `sonnet`, `fable`, `codex` as a model), null/empty values, and duplicate keys stop with `BLOCKED:invalid-engine-config`. Only the project's own `.devlyn/engines.json` is read — no parent or global lookup. Example (an example, not a default or ranking):
-
-```json
-{
-  "executor": "codex",
-  "pair_judge_priority": ["claude"],
-  "roles": {
-    "worker": {"engine": "codex", "model": "gpt-6-astra", "effort": "xhigh"},
-    "primary_judge": {"engine": "codex", "model": "gpt-6-astra", "effort": "high"},
-    "pair_judge": {"engine": "claude", "model": "claude-fable-5-1", "effort": "medium"}
-  }
-}
-```
-
-`--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, 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 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
-```
-
-If an engine is absent when explicitly selected by flag, pin, or role profile, or OTHER engine is absent under `--pair-verify`, the harness stops with `BLOCKED:<engine>-unavailable` and prints setup guidance. Automatic VERIFY absence is a reported solo route. Use `--no-pair` only when intentionally accepting solo VERIFY; use `--no-risk-probes` only when intentionally disabling automatic high-risk probes.
+`/devlyn-engines` with no arguments shows the executor and the engines detected on this machine; `executor <name>` pins one and `clear` removes the pin. A pin is a promise: an unavailable pinned engine stops dispatch with `BLOCKED:<engine>-unavailable`, and a name with no executor-eligible `_shared/adapters/<name>.md` stops with `BLOCKED:invalid-engine-config`. Adapters ship with devlyn-cli releases; a reinstall replaces `_shared`.
 
 ### 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`.
+targets. 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/`.
@@ -166,11 +106,36 @@ Release packaging refreshes the offline fingerprints from Git history using
 `node scripts/update-instruction-templates.js`; installation needs no Git or network.
 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 -->
+Upgrading to 4.1.0: `npx devlyn-cli -y` in a 4.x project keeps its Claude Code install
+current and adds `AGENTS.md` + `.agents/skills/`. Earlier releases put the Codex, omp, Pi
+and Grok skills in `~/.codex/skills`, `~/.agents/skills` and `~/.grok/skills`; a project
+install no longer refreshes them and names each one it finds. Refresh them with `--global`
+or delete them; delete `~/.grok/skills`, since Grok now reads `~/.agents/skills`.
+`npx devlyn-cli agents` was removed.
+
+<!-- legacy-surface-map:begin — retired command names below are documented as OLD, not current; lint Checks 5e and 10c skip this block -->
+Upgrading to 4.2.0: `/devlyn-resolve` and the pipeline helpers only it used are retired;
+no measured replacement ships in their place. Run the installer again where devlyn is
+installed. It removes the `devlyn-resolve` folders (and pre-4.0.0 `devlyn:resolve` ones)
+where it installs, removes the Stop hook it added to `.claude/settings.json` while keeping
+your own hooks, and names the other settings it once added for the pipeline
+(`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` and its `.devlyn` and git permissions) without
+deleting them. `/devlyn-engines` keeps only the executor pin: `pair_judge_priority` and
+`roles` in `.devlyn/engines.json` stay as written, select nothing, and `clear` removes them.
+`task-complete.py` refuses acceptance that points at an archived resolve run
+(`kind: pipeline`) before changing anything, and prints the command that finishes the run
+with the release that produced it: `npm pack devlyn-cli@4.1.0`, extract the tarball, and run
+`python3 package/config/skills/_shared/task-complete.py complete --receipt <receipt>
+--acceptance <acceptance>` with your delivery flags. A PR/merge completion there binds the
+acceptance before publishing, and a receipt it binds resumes delivery with the current
+helper; with `--local-only` it ends as LOCAL_ONLY without binding, as 4.1.0 always did. To
+keep using resolve itself, stay on `devlyn-cli@4.1.0`. The Claude target no longer installs
+`.claude/templates`; a copy an earlier release installed stays yours.
+
 Upgrading to 4.0.0: every devlyn skill is renamed to the Agent Skills standard
-(`/devlyn:resolve` → `/devlyn-resolve`; the full list is in the table below). Run the
-installer for each agent you use, in each project that has devlyn (`npx devlyn-cli` and
-select them, or `-y` plus `npx devlyn-cli agents <cli>`): each run removes the old folders
+(`/devlyn:ideate` → `/devlyn-ideate`; the full list is in the table below). Run the
+installer in each project that has devlyn (`npx devlyn-cli`, or `-y` with `--claude` and
+`--global` as needed): each run removes the old folders
 where it installs and keeps an optional skill you had under its new name. A 3.x installer run
 afterwards brings the old `devlyn:*` folders back beside some new ones and drops opted-in
 pencil skills; run the 4.x installer again to repair it, and re-add those pencil skills from
@@ -179,15 +144,18 @@ devlyn skill by its old name or path (for example Codex `[[skills.config]]` or o
 `disabledExtensions`) needs the new name. A project that committed the old `devlyn:*`
 folders checks out on Windows once that re-sync is committed.
 
-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, and 4.0.0 renamed every devlyn skill to the Agent Skills naming standard (`devlyn-<name>`: lowercase, digits and hyphens, the same as its folder). Upgrades automatically purge the legacy skill directories.
+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, 4.0.0 renamed every devlyn skill to the Agent Skills naming standard (`devlyn-<name>`: lowercase, digits and hyphens, the same as its folder), and after 4.1.0 resolve and design-ui were retired and the queue moved into ideate. Upgrades automatically purge the legacy skill directories.
 
 | Old command | Now use |
 |---|---|
-| `/devlyn:auto-resolve`, `/devlyn:preflight`, `/devlyn:evaluate`, `/devlyn:review`, `/devlyn:team-resolve`, `/devlyn:team-review`, `/devlyn:clean`, `/devlyn:update-docs`, `/devlyn:browser-validate`, `/devlyn:implement-ui` | `/devlyn-resolve` (folds them into PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY) |
+| `/devlyn:auto-resolve`, `/devlyn:preflight`, `/devlyn:evaluate`, `/devlyn:review`, `/devlyn:team-resolve`, `/devlyn:team-review`, `/devlyn:clean`, `/devlyn:update-docs`, `/devlyn:browser-validate`, `/devlyn:implement-ui` | Folded into resolve, now retired — work directly under the installed principles |
 | `/devlyn:product-spec`, `/devlyn:feature-spec`, `/devlyn:recommend-features`, `/devlyn:discover-product` | `/devlyn-ideate` |
-| `/devlyn:team-design-ui` | `/devlyn-design-ui` (now always spawns the 5-specialist team — Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer) |
 | `/devlyn:design-system` | Removed 2026-05-14 — no replacement |
-| `/devlyn:resolve`, `/devlyn:ideate`, `/devlyn:design-ui`, `/devlyn:engines`, `/devlyn:queue`, `devlyn:pencil-pull`, `devlyn:pencil-push`, `devlyn:reap` (3.x and earlier) | `/devlyn-resolve`, `/devlyn-ideate`, `/devlyn-design-ui`, `/devlyn-engines`, `/devlyn-queue`, `devlyn-pencil-pull`, `devlyn-pencil-push`, `devlyn-reap` (4.0.0) |
+| `/devlyn:ideate`, `/devlyn:engines`, `devlyn:pencil-pull`, `devlyn:pencil-push`, `devlyn:reap` (3.x and earlier) | `/devlyn-ideate`, `/devlyn-engines`, `devlyn-pencil-pull`, `devlyn-pencil-push`, `devlyn-reap` (4.0.0) |
+| `/devlyn:resolve` (3.x and earlier), `/devlyn-resolve` (4.0.0–4.1.0) | Retired — work directly under the installed principles; `/devlyn-ideate` plans and drains multi-task work |
+| `/devlyn:queue` (3.x and earlier), `/devlyn-queue` (4.0.0–4.1.0) | `/devlyn-ideate add`, `status` and `drain` |
+| `/devlyn-ideate --quick`, `--from-spec`, `--project` (4.1.0 and earlier) | `/devlyn-ideate plan`; `--autonomous` replaces `--quick` |
+| `/devlyn:team-design-ui`, `/devlyn:design-ui` (3.x and earlier), `/devlyn-design-ui` (4.0.0–4.1.0) | Retired — no replacement |
 <!-- legacy-surface-map:end -->
 
 ---
@@ -197,7 +165,7 @@ Earlier versions of devlyn-cli shipped 16+ slash commands. The iter-0034 Phase 4
 Selected during install. Run `npx devlyn-cli` again to add more.
 
 <details>
-<summary><strong>Skills</strong> — copied to <code>.claude/skills/</code></summary>
+<summary><strong>Skills</strong> — copied into every skill root the install writes</summary>
 
 | Skill | Description |
 |---|---|
@@ -206,6 +174,7 @@ Selected during install. Run `npx devlyn-cli` again to add more.
 | `generate-skill` | Create Claude Code skills following Anthropic best practices |
 | `prompt-engineering` | Claude prompt optimization |
 | `better-auth-setup` | Better Auth + Hono + Drizzle + PostgreSQL |
+| `polar-billing-setup` | Polar usage-based / metered billing — setup and silent $0-billing diagnosis |
 | `pyx-scan` | Check if an AI agent skill is safe before installing |
 | `dokkit` | Document template filling for DOCX/HWPX |
 | `devlyn-pencil-pull` | Pull Pencil designs into code |
@@ -232,13 +201,13 @@ Selected during install. Run `npx devlyn-cli` again to add more.
 </details>
 
 <details>
-<summary><strong>MCP Servers</strong> — installed via <code>claude mcp add</code></summary>
+<summary><strong>MCP Servers</strong> — installed via <code>claude mcp add</code>, offered with the CLAUDE.md choice</summary>
 
 | Server | Description |
 |---|---|
-| `playwright` | Playwright MCP — powers `/devlyn-resolve` BUILD_GATE browser tier (Chrome MCP → Playwright → curl fallback) |
+| `playwright` | Playwright MCP for browser testing |
 
-> `--engine codex` and default-when-available VERIFY pair mode use the local `codex` CLI binary, not MCP. Install from https://platform.openai.com/docs/codex, run the current Codex auth/login flow, verify `codex --version`, then rerun.
+> A Codex executor uses the local `codex` CLI binary, not MCP. Install it from https://platform.openai.com/docs/codex, run the current Codex auth/login flow and verify `codex --version`.
 
 </details>
 
@@ -249,22 +218,22 @@ Selected during install. Run `npx devlyn-cli` again to add more.
 ## Requirements
 
 - **Node.js 18+** and npm
-- **Python 3.11+** available as `python3`, and Git for the resolve harness
-- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** installed and configured
+- **Python 3.11+** available as `python3`, and Git for the harness
+- **An agent CLI** installed and configured: Codex, omp, Pi or Grok (AGENTS.md), or [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLAUDE.md)
+- **For `auto`/`pr` delivery**, an `origin` remote naming one GitHub repository and an authenticated [`gh`](https://cli.github.com/)
 
-On native Windows, use native Node/npm and Python plus Git for Windows Bash for the shipped shell wrapper. Run `npx devlyn-cli -y` in the project; add Codex with `npx devlyn-cli agents codex`. Skill folders follow the Agent Skills naming standard (for example `devlyn-resolve`), so a project that commits them checks out on Windows. Harness text is UTF-8 without requiring `PYTHONUTF8`.
+On native Windows, use native Node/npm and Python plus Git for Windows Bash for the shipped shell wrapper. Run `npx devlyn-cli -y` in the project (add `--claude` for Claude Code). Skill folders follow the Agent Skills naming standard (for example `devlyn-ideate`), so a project that commits them checks out on Windows. Harness text is UTF-8 without requiring `PYTHONUTF8`.
 
 Windows completion preserves the workspace, owned refs and recovery receipt when writer cessation cannot be proved, even after merge; resume guidance and delivery status remain separate from product verification. The portability workflow checks out the repository on native Windows and tests the POSIX-packed npm artifact there. A POSIX pass alone does not establish Windows support: acceptance requires the passing Windows job for the exact source SHA/artifact hashes.
 
 ## Contributing
 
-- **Add a skill** — directory in `config/skills/` with `SKILL.md`
-- **Add optional skill** — add to `optional-skills/` and `OPTIONAL_ADDONS` in [`bin/devlyn.js`](bin/devlyn.js)
+- **Add a skill** — add it to `optional-skills/` and `OPTIONAL_ADDONS` in [`bin/devlyn.js`](bin/devlyn.js); the core skills are fixed by `DEVLYN_CORE_SKILLS` (lint Checks 5a and 6)
 - **Suggest a pack** — PR to the pack list
 
 ## Supercharge it — pair devlyn with persistent agent memory
 
-devlyn-cli gives your agent a world-class **harness**. Give it a world-class **memory** and the loop compounds — decisions, corrections, and hard-won context survive across sessions instead of resetting every conversation.
+devlyn-cli gives your agent a **harness**. Give it a world-class **memory** and the loop compounds — decisions, corrections, and hard-won context survive across sessions instead of resetting every conversation.
 
 > [!TIP]
 > ### 🧠 [pyx-memory](https://memory.pyxmate.com) — world-class agentic memory (hybrid RAG) for coding agents
@@ -274,7 +243,7 @@ devlyn-cli gives your agent a world-class **harness**. Give it a world-class **m
 - **Hybrid retrieval** — semantic *and* graph recall: find by meaning *and* by relationship
 - **Learns the loop** — reinforces what works, records corrections when it doesn't
 
-**Harness (devlyn) + Memory (pyx-memory) = agents that don't just execute — they improve.** Wire up **pyx-memory** as an MCP server and `/devlyn-resolve` recalls prior decisions before it plans and stores what it learns after it ships.
+**Harness (devlyn) + Memory (pyx-memory) = agents that don't just execute — they improve.** Wire up **pyx-memory** as an MCP server so your agent recalls prior decisions before it plans and stores what it learns after it ships.
 
 ## Support & Attribution