@miroshnik/elves 2026.1026.3 → 2026.1026.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/AGENTS.md +0 -3
  2. package/README.md +3 -7
  3. package/bin/elves.ts +128 -780
  4. package/claude/CLAUDE.md +2 -3
  5. package/dist/github/scripts/github.js +100 -181
  6. package/dist/spec/scripts/architecture.js +2 -2
  7. package/dist/spec/scripts/{harness-dgtt7kht.js → harness-nn3hnqwn.js} +14 -32
  8. package/dist/spec/scripts/{harness-xqp7tdyr.js → harness-t9bqz3st.js} +5 -22
  9. package/dist/spec/scripts/harness.js +1 -1
  10. package/docs/cloud-sessions.md +0 -3
  11. package/package.json +2 -2
  12. package/skills/est/reference.md +1 -3
  13. package/skills/est/scripts/est.ts +3 -21
  14. package/skills/github/SKILL.md +1 -1
  15. package/skills/github/locales/en.json +0 -7
  16. package/skills/github/locales/ru.json +0 -7
  17. package/skills/github/reference.md +8 -21
  18. package/skills/github/scripts/github.ts +123 -226
  19. package/skills/github/scripts/locale.ts +10 -37
  20. package/skills/slot/SKILL.md +1 -9
  21. package/skills/slot/scripts/slot.ts +8 -29
  22. package/skills/spec/SKILL.md +3 -17
  23. package/skills/spec/canon.md +3 -5
  24. package/skills/spec/checks.md +2 -8
  25. package/skills/spec/migration.md +0 -43
  26. package/skills/spec/reference.md +5 -45
  27. package/skills/spec/scripts/harness.ts +14 -34
  28. package/skills/spec/scripts/spec-claims.ts +3 -8
  29. package/skills/spec/scripts/spec-diff.ts +44 -195
  30. package/skills/spec/scripts/spec-doc.ts +21 -48
  31. package/skills/spec/scripts/speclib.ts +12 -39
  32. package/skills/task-env/SKILL.md +4 -10
  33. package/skills/task-env/reference.md +0 -26
  34. package/skills/task-env/scripts/task-env.ts +53 -67
  35. package/bin/ai-dev.ts +0 -10
  36. package/skills/spec/scripts/spec-exceptions.ts +0 -233
package/AGENTS.md CHANGED
@@ -35,9 +35,6 @@ a release is the owner's step (`elves release`), I cut one only when asked.
35
35
  loaded at the start.
36
36
  - **The project is behind** (or git ignores flow files) — `update` in the
37
37
  task's branch: the package version.
38
- - **The project keeps a copy of the flow** — the move is a task of its own,
39
- one per project (`check` prints its `github task new`): I recommend it and
40
- ask whether to queue it.
41
38
  - **`update` refused or the check unavailable** — I don't fix the clone; I
42
39
  work by the current flow and say so.
43
40
 
package/README.md CHANGED
@@ -180,7 +180,7 @@ An agent's sandbox (Claude Code's Bash) doesn't let bunx write its cache `~/.bun
180
180
 
181
181
  `install` in a project asks in the terminal whether the agent should do tasks entirely by itself — answer the task's questions by recommendation, commit, push, fix CI and merge its own PR on green checks (default — no); without a terminal — `install --auto` or `--no-auto`, without the flag the previous answer stays. `check` names the mode. With auto, `install` prints a hint for Claude Code: the app rejects a merge without human review in this mode too, and the session merges its own PR by itself only with the `Bash(gh pr merge *)` rule in `permissions.allow` of `~/.claude/settings.json` — the owner adds it, `install` doesn't change the machine's permission settings.
182
182
 
183
- `install` also asks for the **project language** the agent works in: dialog, tasks, prompts, documents; the flow itself is written in English. It is stored in `.agents/elves.json` as `language` — a BCP 47 code (`ru`, `en`, `pt-BR`), `en` by default; an install of a previous version without the field counts as `ru`. Without a terminal — `install --lang <code>`, without the flag the previous language stays; `update` keeps it, `check` and the hook name it. The manifest belongs in git: in a checkout without it the language is unknown, the `github` skill refuses to write names to GitHub, and `check` names a manifest that is missing or not committed. The flow isn't installed into an Elves clone — `install` writes only its manifest there: these two settings, `env` and `batch` carried over as in a project.
183
+ `install` also asks for the **project language** the agent works in: dialog, tasks, prompts, documents; the flow itself is written in English. It is stored in `.agents/elves.json` as `language` — a BCP 47 code (`ru`, `en`, `pt-BR`), `en` by default. Without a terminal — `install --lang <code>`, without the flag the previous language stays; `update` keeps it, `check` and the hook name it. The manifest belongs in git: in a checkout without it the language is unknown, the `github` skill refuses to write names to GitHub, and `check` names a manifest that is missing or not committed. The flow isn't installed into an Elves clone — `install` writes only its manifest there: these two settings, `env` and `batch` carried over as in a project.
184
184
 
185
185
  <details>
186
186
  <summary><b>What goes where</b></summary>
@@ -192,15 +192,13 @@ An agent's sandbox (Claude Code's Bash) doesn't let bunx write its cache `~/.bun
192
192
  - `.agents/slot.sh` — the machine queue's shim the `package.json` checks source (`slot` below).
193
193
  - A block at the top of the project's `AGENTS.md` linking to the canon on the machine, `~/.agents/elves/AGENTS.md` — for the agents that read the project's file.
194
194
  - The cloud session's `SessionStart` hook in `.claude/settings.json` (your own settings and hooks stay): in a Claude Code cloud session (`CLAUDE_CODE_REMOTE=true`) it installs a fresh Bun and the flow onto the session's machine and runs `check --hook`, outside the cloud it exits at once — no setup script in the environment is needed (`docs/cloud-sessions.md`).
195
- - Updating — `update` bumps the package version: `package.json` and the lockfile, a few lines in the branch of the current task, committed with it. A project with a copy of the flow of an earlier release moves to a thin one in a task of its own, one per project — `check` prints its `task new`, the hook names the canon loaded twice until then: `update` removes the copy, its symlinks and `.gitignore` exceptions, leads imports and CI paths into the copy to the package and lists what else names `.agents`.
195
+ - Updating — `update` bumps the package version: `package.json` and the lockfile, a few lines in the branch of the current task, committed with it.
196
196
  - The manifest, the shim, `AGENTS.md` and `.claude/settings.json`, if the project's git ignores them (`.agents/` or `.claude/` in `.gitignore`), are un-ignored by `install` and `update` with exceptions — an Elves block at the end of `.gitignore`, committed with them; what an exception can't un-ignore (a directory excluded by a personal rule), and anything ignored until `update` runs — `❌` in the output of the install and of `check`.
197
197
 
198
198
  **Onto the machine** (`-g`) — the canon, the skills and the hook: a thin project keeps no copy of the canon, its agents get it from the machine. `~/.agents/elves/` — `AGENTS.md`, `claude/CLAUDE.md`, `docs/*.md`; Claude Code — symlinks `~/.claude/rules/elves.md` and `elves-claude.md` (loaded in every project without the external-imports dialog), `~/.claude/skills` and the `SessionStart` hook in `~/.claude/settings.json`; the other agents — their global rule file linking to the canon (`~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.copilot/copilot-instructions.md`, `~/.config/opencode/AGENTS.md`, `~/.config/amp/AGENTS.md`; a file of your own stays) and `~/.agents/skills`. The `elves` command in the terminal — in `~/.local/bin`, or the first directory of `PATH` inside the home directory you can write to: with `--link` a symlink to the clone's `bin/elves.ts`, otherwise a shim to the machine's release (`bunx @miroshnik/elves@<version>`) that `update -g` rewrites; an `elves` of your own (a script, a global package) stays, and `check -g` names it, a command missing or of another release, an `elves` earlier on `PATH`, and — when `PATH` has no such directory — the command that adds `~/.local/bin`. A project that still has a copy loads the canon twice until it moves — the hook names it. Claude Code's prompt cache TTL is your choice: with `promptCacheTtl` or `subagentPromptCacheTtl` not set, `install -g`, `update -g`, `check -g` and the hook print a command that sets the hour and leaves the rest of `~/.claude/settings.json` alone — none of them edits the file (`docs/prompt-cache.md`). A Claude Code cloud session gets the same from the project's `SessionStart` hook — `npm i -g bun@latest @miroshnik/elves && elves install -g` (the image's Bun lags behind), then `check --hook`; the machine's hook isn't there (the cloud doesn't read `~/.claude/settings.json`), an environment's setup script with the same command is an optional faster start. In an Elves clone with `--link` the machine's canon is the clone; its `.claude/CLAUDE.md` keeps the root `AGENTS.md` from loading a second time.
199
199
 
200
200
  **Personal configuration** — everything that depends on specific repositories (the registry for `est`, your own model prices, notes) — lives outside the flow, in `~/.config/elves`; another directory — the `ELVES_CONFIG_DIR` variable, read by all skill scripts. `ELVES_PRIVATE=<path>` with `install -g` makes `~/.config/elves` a symlink to a private checkout; with `ELVES_CONFIG_DIR` the symlink isn't needed — the variable points at the checkout itself.
201
201
 
202
- **Before the rename to Elves** an install had the names `ai-dev`: `.agents/ai-dev.json`, `.agents/ai-dev/`, `.claude/rules/ai-dev*.md`, `~/.config/ai-dev`, variables `AI_DEV_*`. `update` and `update -g` move them to the new names with the same contents, the skills' scripts read the former ones until then, and `check` names what is left with how to move it.
203
-
204
202
  </details>
205
203
 
206
204
  <details>
@@ -209,7 +207,7 @@ An agent's sandbox (Claude Code's Bash) doesn't let bunx write its cache `~/.bun
209
207
  The machine's copy and a project's package version follow the flow **by releases** — tags `vYYYY.MM.DD` (a same-day patch is `.N`), not the head of `main`: a commit to the rules without a release doesn't make anyone "behind". The commands go through the npm package, and it is a release itself: `install` from it installs its own version without the network, `check` and `update` restart from the latest release's npm package. The fallback `bunx github:miroshnik/elves` installs the package from `main` once and then runs it from its cache, so that package is only a launcher: it finds the latest tag and restarts from it by its SHA; in a cloud session `github:` gives 403.
210
208
 
211
209
  - `check` changes nothing: it compares the machine's copy and a project's package version with the latest release (the same install as a dry run, a list of differences), a `--link` clone — with `origin/main` after `git fetch`.
212
- - `update`: the machine's copy — reinstalled from the latest release; a project — the package version raised to it, a copy of the flow moved to a thin project; a clone — `git pull --ff-only` and links to new skills (a clone not on `main` or with edits — refused with a reason). It says what changed, and the agent tells the user: the machine's copy and a project — every release after the installed one (a project — after its package version), newest first, with the list of its GitHub Release; a clone — the flow commits it pulled. A project's update is committed into the current task's branch; no task branch — the agent doesn't commit it and says so.
210
+ - `update`: the machine's copy — reinstalled from the latest release; a project — the package version raised to it; a clone — `git pull --ff-only` and links to new skills (a clone not on `main` or with edits — refused with a reason). It says what changed, and the agent tells the user: the machine's copy and a project — every release after the installed one (a project — after its package version), newest first, with the list of its GitHub Release; a clone — the flow commits it pulled. A project's update is committed into the current task's branch; no task branch — the agent doesn't commit it and says so.
213
211
  - `release` — the owner's step: a date tag (UTC) on `origin/main` and a GitHub Release listing the flow and installer changes since the previous release (the same list `update` prints); nothing to release — refused.
214
212
  - The npm package `@miroshnik/elves` — CI publishes every release tag (`.github/workflows/npm.yml`): `elves pack <tag>` sets the version (`vYYYY.MM.DD.N` → `YYYY.MMDD.N`, versions sort as tags) and builds for Node the modules a project imports, then `npm publish` by npm [trusted publishing](https://docs.npmjs.com/trusted-publishers) — OIDC, no token or secret, provenance included. The owner's step, once: a trusted publisher is set in the package settings on npmjs.com, so first a `0.0.0` stub published from the owner's machine; then the trusted publisher — GitHub Actions, `miroshnik/elves`, workflow `npm.yml` — no earlier than 2 days before the first release from CI (a new one expires without a successful publish within 2 days: delete it and create it again); after that release the stub may be `npm deprecate`d.
215
213
 
@@ -228,7 +226,6 @@ bun --no-env-file node_modules/.bin/elves spec-run …
228
226
  bun --no-env-file node_modules/.bin/elves spec-shard …
229
227
  bun --no-env-file node_modules/.bin/elves spec-claims …
230
228
  bun --no-env-file node_modules/.bin/elves spec-break …
231
- bun --no-env-file node_modules/.bin/elves spec-exceptions …
232
229
  bun --no-env-file node_modules/.bin/elves precommit
233
230
  bun --no-env-file node_modules/.bin/elves task-env up …
234
231
  bun --no-env-file node_modules/.bin/elves task-env e2e …
@@ -286,7 +283,6 @@ A browser page the script serves itself, with two tabs. Sessions (the main one)
286
283
  - `spec-shard` — a CI shard's test files by the durations of the last green run, not by the count of tests: the heavy tests of one folder don't all land in one shard.
287
284
  - `spec-claims` — every entry point (route, page, job, command) is called by a capability test — by the call log, not by coverage.
288
285
  - `spec-break` — proves that a check catches a breakage: break the code → run the test → always revert.
289
- - `spec-exceptions` — moves a project's exceptions from `exceptions.ts` into the `exceptions/` directory of the decision folder, one file per exception: parallel PRs paying down debt don't conflict.
290
286
  - `precommit` — the checks before a commit in one call: `lint`, `typecheck`, `test:spec` and `test --changed=<base>` at once, each through the machine queue; a line per check, the details of the failed ones only; a test check's result — by the runner's summary, not the exit code.
291
287
  - `harness.ts` — mechanical checks: "registry + invariant" with a violator, lint-rule examples, exceptions with a ratchet (an element with its own file — a mark in it), the C1–C3 architecture model, dead code (knip, with the config-hints reporter `knip-hints.cjs`), the environment.
292
288