devlyn-cli 4.0.0 → 4.1.0

package/AGENTS.md

@@ -1,6 +1,6 @@
-# Codex Project Instructions
+# Project Instructions
 
-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.
+devlyn-cli installs planning and full-pipeline skills alongside the execution contract below. Codex, omp, Pi and Grok read this file, and so does Claude Code when the project has no CLAUDE.md. The principles are non-negotiable on every change.
 
 ## North Star
 
@@ -42,7 +42,7 @@ Conversational entry: Before loading a workflow or writing files, inspect the re
 
 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. 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, BLOCKED:repair-budget-exhausted) 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, BLOCKED:repair-budget-exhausted) 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 `references/outer-loop.md` in the installed `devlyn-resolve` skill.
 
 ## Subtractive-First Editing
 

package/CLAUDE.md

@@ -62,7 +62,7 @@ The user does not invoke skills manually; the orchestrating model does. For work
 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, BLOCKED:repair-budget-exhausted) → 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.
 
-**Intent queue (unattended drain)**: the user stacks intents in `docs/specs/queue.md` (ordered checklist; `/devlyn-queue` is the front-end — no args shows status, `add <intent>` appends, `drain` starts the serial drain). Drain strictly serially — per item: spec it, commit the scoped owner baseline, run the outer loop, mark `[x]` done or `[F]` blocked with reason, commit that terminal transition, then complete eligible delivery once. Retain PR/pending workspaces; unavailable separate safe placement stops the drain with remaining items pending. A product-blocked item otherwise never halts the queue. The queue entry is the user's go-ahead, so assume-and-log replaces the interactive checkpoint — but unattended assumptions may only take scope-narrowing, reversible, non-user-visible defaults. Material ambiguity (user-visible behavior, data/state semantics, new files/scripts/flags, implementation surface) → mark `[F] needs-review`, commit it, and move on. End the drain with a per-item product verdict, separate delivery status/URL/resume and assumptions report. The canonical commit order is `config/skills/devlyn-resolve/references/outer-loop.md`.
+**Intent queue (unattended drain)**: the user stacks intents in `docs/specs/queue.md` (ordered checklist; `/devlyn-queue` is the front-end — no args shows status, `add <intent>` appends, `drain` starts the serial drain). Drain strictly serially — per item: spec it, commit the scoped owner baseline, run the outer loop, mark `[x]` done or `[F]` blocked with reason, commit that terminal transition, then complete eligible delivery once. Retain PR/pending workspaces; unavailable separate safe placement stops the drain with remaining items pending. A product-blocked item otherwise never halts the queue. The queue entry is the user's go-ahead, so assume-and-log replaces the interactive checkpoint — but unattended assumptions may only take scope-narrowing, reversible, non-user-visible defaults. Material ambiguity (user-visible behavior, data/state semantics, new files/scripts/flags, implementation surface) → mark `[F] needs-review`, commit it, and move on. End the drain with a per-item product verdict, separate delivery status/URL/resume and assumptions report. The canonical commit order is `references/outer-loop.md` in the installed `devlyn-resolve` skill.
 
 ## Subtractive-first editing — perfection = nothing left to remove
 <!-- runtime-principles:section=subtractive-first:begin -->

package/README.md

@@ -27,7 +27,14 @@ 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 two things:
+
+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`.
+
+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. Global installs skills only: `~/.agents/skills/` (omp, Pi, Grok) and `~/.codex/skills/` (Codex), plus `~/.claude/skills/` for Claude Code. Every target gets the `devlyn-resolve`, `devlyn-ideate`, and `devlyn-design-ui` skills plus the `devlyn-engines` and `devlyn-queue` utilities. In Codex / omp / Pi, invoke them as skills (`$devlyn-resolve`, `$devlyn-ideate`, `$devlyn-design-ui`); in Claude Code and Grok they're slash commands (`/devlyn-resolve`). 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.
+
+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.
 
 ---
 
@@ -39,7 +46,7 @@ devlyn-cli supports direct execution for clear, low-risk work with decisive chec
 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.
+Non-Claude agents (Codex / omp / Pi / Grok): the AGENTS.md choice installs the workflows as their 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`
 
@@ -147,7 +154,7 @@ If an engine is absent when explicitly selected by flag, pin, or role profile, o
 ### 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 +173,18 @@ 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`.
 
+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 Check 10c skips this block -->
 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
+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
@@ -197,7 +211,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 |
 |---|---|
@@ -232,7 +246,7 @@ 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 |
 |---|---|
@@ -250,9 +264,9 @@ Selected during install. Run `npx devlyn-cli` again to add more.
 
 - **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
+- **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)
 
-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-resolve`), 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.