@miroshnik/elves 2026.1112.1 → 2026.1113.0
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.
- package/AGENTS.md +1 -1
- package/README.md +53 -195
- package/bin/elves.ts +1 -1
- package/dist/github/scripts/github.js +62 -23
- package/docs/cloud-sessions.md +3 -2
- package/docs/installation.md +83 -0
- package/package.json +2 -2
- package/skills/est/reference.md +8 -2
- package/skills/est/scripts/est.ts +26 -14
- package/skills/github/reference.md +18 -3
- package/skills/github/scripts/github.ts +86 -22
- package/skills/spec/SKILL.md +3 -3
- package/skills/spec/canon.md +2 -2
- package/skills/spec/checks.md +2 -2
- package/skills/spec/reference.md +1 -1
- package/skills/spec/scripts/harness.ts +1 -1
package/AGENTS.md
CHANGED
|
@@ -211,7 +211,7 @@ it.
|
|
|
211
211
|
|
|
212
212
|
## Specification — decisions
|
|
213
213
|
|
|
214
|
-
A project's spec is **decisions with a
|
|
214
|
+
A project's spec is **decisions with a deterministic check**, functional and
|
|
215
215
|
non-functional (a test, a lint rule, an architecture check).
|
|
216
216
|
**No check — no decision; no decision — no code:** behavior without a check
|
|
217
217
|
may change without agreement; code no decision claims is dead. A check is
|
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
*Elves at work*
|
|
6
6
|
|
|
7
|
-
**A development flow
|
|
7
|
+
**A development flow for AI agents: deterministic checks instead of prose specs.**
|
|
8
8
|
|
|
9
9
|
Claude Code · Codex · Gemini CLI · Cursor · Copilot · OpenCode · Amp
|
|
10
10
|
|
|
@@ -13,7 +13,7 @@ Claude Code · Codex · Gemini CLI · Cursor · Copilot · OpenCode · Amp
|
|
|
13
13
|
[](https://agentskills.io)
|
|
14
14
|
[](https://github.com/miroshnik/elves/tree/spec)
|
|
15
15
|
|
|
16
|
-
[The idea](#the-idea) · [Why](#why) · [
|
|
16
|
+
[The idea](#the-idea) · [Why](#why) · [Elves and OpenSpec](#elves-and-openspec) · [Installation](#installation) · [Skills](#skills) · [Layout](#repository-layout)
|
|
17
17
|
|
|
18
18
|
</div>
|
|
19
19
|
|
|
@@ -54,66 +54,39 @@ flowchart LR
|
|
|
54
54
|
|
|
55
55
|
Developing any software is making decisions, of two kinds:
|
|
56
56
|
|
|
57
|
-
- **functional** — what the system does: what it stores and for how long (an order — for good, a cart — for the session), what it shows and to whom
|
|
58
|
-
- **non-functional** — what it's made of and which rules it obeys: data in Postgres,
|
|
57
|
+
- **functional** — what the system does: what it stores and for how long (an order — for good, a cart — for the session), what it shows and to whom;
|
|
58
|
+
- **non-functional** — what it's made of and which rules it obeys: data in Postgres, every input form has a reset button, search answers in under 300 ms.
|
|
59
59
|
|
|
60
|
-
Every decision has a **
|
|
60
|
+
Every decision has a **deterministic check** — run by the machine, not judged by a person or an agent — that the decision holds. A decision without a check is a wish: nothing tells when the code stops following it, and a prose spec is a list of such wishes. So the code answers what the system does and how it is built now, and the checks — what it should do and how it should be built: they are its specification.
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
A check is written before the code and fails — the decision isn't implemented yet: that's its acceptance test. The code makes it pass, and from then on the check holds the decision against every later change: that's its regression test. A decision changes the same way — its check first, red on the current code, then the code follows it to green. A check that can't fail holds nothing: a regression test is proven by reverting the fix and seeing red.
|
|
63
63
|
|
|
64
|
-
|
|
|
65
|
-
|
|
66
|
-
|
|
|
67
|
-
|
|
|
64
|
+
| Decision | Kind | Check | Lives in |
|
|
65
|
+
|---|---|---|---|
|
|
66
|
+
| An order survives a restart | functional | an integration test | `tests/capabilities/orders/persistence` |
|
|
67
|
+
| Search answers in under 300 ms | non-functional, a quality of one capability | a load test with the budget | `tests/capabilities/search/latency` |
|
|
68
|
+
| Every input form has a reset button | non-functional, a standard | "registry + invariant": a test per form from the code | `tests/standards/forms/reset-button` |
|
|
69
|
+
| Data is stored in Postgres | non-functional, architecture | the model: a module importing another driver — red | `tests/architecture/model.ts` |
|
|
68
70
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
Any decision can be changed — through its check: the check changes first and goes red on the current code, then the code follows it to green. The spec leads, the code follows: a code change that breaks a decision turns its check red.
|
|
72
|
-
|
|
73
|
-
| Decision | Kind | Check | Lives in | Label |
|
|
74
|
-
|---|---|---|---|---|
|
|
75
|
-
| An order survives a restart, a cart lives for the session | functional | an integration test | `tests/capabilities/orders/persistence` | 🟩 |
|
|
76
|
-
| The manager sees overdue invoices first | functional | an e2e test | `tests/capabilities/invoices/overdue-first` | 🟩 |
|
|
77
|
-
| Search answers in under 300 ms at 100 requests per second | non-functional, a quality of one capability | a load test with the budget | `tests/capabilities/search/latency` | 🟩 |
|
|
78
|
-
| Every input form has a reset button | non-functional, a standard | "registry + invariant": every form from the code, a test per form | `tests/standards/forms/reset-button` | 🟦 |
|
|
79
|
-
| Code is TypeScript | non-functional, a standard | "registry + invariant": every source file is `.ts` | `tests/standards/source-files/typescript` | 🟦 |
|
|
80
|
-
| Data is stored in Postgres | non-functional, architecture | the model: the `db` container and its `pg` client; a module importing another driver — red | `tests/architecture/model.ts` | 🟧 |
|
|
81
|
-
|
|
82
|
-
A decision is a **topic with sections**: the topic is the subject (`orders`, `forms`) — a product area as the user names it, or the kind of element a rule applies to; a section is one statement about it (`reset-button`), with its reason in `<section>.md` and its checks in `<section>.test.ts`. A new rule goes in as a section of the topic whose subject covers it, not as a new folder.
|
|
83
|
-
|
|
84
|
-
**Decision labels** on GitHub tasks name the topic — a section has none — and show its kind by color: 🟩 green — a capability, functional; 🟦 blue — a standard and 🟧 orange — architecture, both non-functional. The color follows where the decision lives, so the budget of one capability, kept next to its behavior, is green; `github project check` holds the colors. How each check is wired — the [`spec`](skills/spec/SKILL.md) skill.
|
|
71
|
+
A decision is a **topic with sections**: the topic is the subject (`orders`, `forms`) — a product area as the user names it, or the kind of element a rule applies to; a section is one statement about it (`reset-button`), with its reason in `<section>.md` and its checks in `<section>.test.ts`. A new rule goes in as a section of the topic whose subject covers it, not as a new folder. Decision labels on GitHub tasks name the topic and show its kind by color — 🟩 a capability, 🟦 a standard, 🟧 architecture; how each check is wired — the [`spec`](skills/spec/SKILL.md) skill.
|
|
85
72
|
|
|
86
73
|
## Why
|
|
87
74
|
|
|
88
|
-
An agent writes code fast
|
|
89
|
-
|
|
90
|
-
| Without the flow | With Elves |
|
|
91
|
-
|---|---|
|
|
92
|
-
| Knowledge lives in the chat and in the agent's memory — the next session, another agent or account starts from scratch | Everything decided is in the issue and the repository; before a pause — a State comment, and any agent can continue |
|
|
93
|
-
| Specs and rules-as-text go stale silently — you see it only once a bug has happened | Every decision — functional and non-functional — is held by a check; a change without one turns CI red |
|
|
94
|
-
| Estimates are guesses — they can't be checked or learned from | An estimate comes from analogs with a measured actual; the actual comes from the agent's transcripts |
|
|
95
|
-
| Every project has its own process; one project's lesson doesn't reach another | One canon for all projects and agents; an improvement reaches everyone with a release |
|
|
96
|
-
| The agent commits, pushes and merges on its own — or asks about everything every time | Reversible — on its own, irreversible — on an explicit "yes" to a specific action |
|
|
97
|
-
|
|
98
|
-
## Principles
|
|
75
|
+
An agent writes code fast; everything around the code is what becomes slow and expensive. Each row is a section of the canon, [`AGENTS.md`](AGENTS.md).
|
|
99
76
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
8. **A script instead of memory.** Everything deterministic is in the skills' scripts (TypeScript under Bun, no dependencies): the agent decides, the script does — the same way in every project. → [This file and skills](AGENTS.md#this-file-and-skills)
|
|
110
|
-
9. **Irreversible — on an explicit "yes".** Reading, tests, local edits and task tracking — without asking; commit, push, merge, deploy and writes to live databases — with permission for that action and for this time. A project can let the agent run a task entirely by itself — up to merging its own PR on green checks — with the `auto` setting at install; the same install sets the project language the agent talks and writes in. → [What I do without asking and what needs a yes](AGENTS.md#what-i-do-without-asking-and-what-needs-a-yes)
|
|
111
|
-
10. **Into `main` — each green on its own.** Merge as soon as the PR's own checks are green, without a queue or an up-to-date-branch requirement; before merging, if `main` moved after the PR's CI — fast checks on the merge with a fresh `main`; after a deploy — waiting for its statuses; a test failed — the root cause is fixed, not a retry added. → [Git, PRs and merging](AGENTS.md#git-prs-and-merging)
|
|
112
|
-
11. **One canon, versions by releases.** A project pins the package version, not a copy of the flow, and updates by release — a few lines in the current task; a session starts by checking whether the flow is behind. → [First step of a session](AGENTS.md#first-step-of-a-session--an-up-to-date-flow)
|
|
77
|
+
| Without the flow | With Elves | Canon |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| Knowledge lives in the chat and the agent's memory; the next session starts from scratch | Agreed — in the issue: the goal, `## Questions` with answers, `## Scenarios` — future test names; every fact has one home; before a pause — a State comment | [Task tracking](AGENTS.md#task-tracking) · [Project knowledge and handoff](AGENTS.md#project-knowledge-and-handoff) |
|
|
80
|
+
| Rules-as-text go stale silently; a green test may catch nothing | Every decision is held by a deterministic check; a test failed — its root cause is fixed, not a retry added | [Specification — decisions](AGENTS.md#specification--decisions) · [Tests and code](AGENTS.md#tests-and-code) |
|
|
81
|
+
| Work isn't linked to a task | Session = task = branch = PR (`#42 …`, `feat/42-slug`, `Closes #42`); a second task — to Backlog and, on a "yes", to a background executor | [Session and branch](AGENTS.md#session-and-branch--one-task) |
|
|
82
|
+
| Estimates are guesses | From analogs with a measured actual: active hours, tokens and $ from the agent's transcripts | [Estimate and actual](AGENTS.md#estimate-and-actual--the-est-skill) |
|
|
83
|
+
| The agent merges on its own — or asks about everything | Reversible — on its own, irreversible — on an explicit "yes"; `auto` runs a task by itself, up to merging its own PR on green checks | [What I do without asking](AGENTS.md#what-i-do-without-asking-and-what-needs-a-yes) |
|
|
84
|
+
| PRs wait in a merge queue | Each PR merges on its own green checks; `main` moved after its CI — fast checks on the merge first; after a deploy — its statuses | [Git, PRs and merging](AGENTS.md#git-prs-and-merging) |
|
|
85
|
+
| Each project has its own process, and the agent improvises its routine | One canon for all projects and agents, a script for everything deterministic; a project pins the version, a session first checks the flow is up to date | [This file and skills](AGENTS.md#this-file-and-skills) · [First step of a session](AGENTS.md#first-step-of-a-session--an-up-to-date-flow) |
|
|
113
86
|
|
|
114
87
|
## Elves and OpenSpec
|
|
115
88
|
|
|
116
|
-
[OpenSpec](https://github.com/Fission-AI/OpenSpec) is a popular spec-driven framework: requirements in Markdown (`SHALL`, `WHEN` / `THEN` scenarios), every change is a folder in `openspec/changes/` with `proposal.md`, `tasks.md`, `design.md` and spec deltas
|
|
89
|
+
[OpenSpec](https://github.com/Fission-AI/OpenSpec) is a popular spec-driven framework: requirements in Markdown (`SHALL`, `WHEN` / `THEN` scenarios), every change is a folder in `openspec/changes/` with `proposal.md`, `tasks.md`, `design.md` and spec deltas merged into `openspec/specs/` after rollout. Elves used to run on top of OpenSpec; now it replaces it entirely.
|
|
117
90
|
|
|
118
91
|
| | OpenSpec | Elves |
|
|
119
92
|
|---|---|---|
|
|
@@ -121,186 +94,70 @@ The full canon is [`AGENTS.md`](AGENTS.md); here is what it stands on.
|
|
|
121
94
|
| **What keeps the spec true** | the agent's discipline; `validate` checks structure, not truth | CI: behavior changed without a test — red |
|
|
122
95
|
| **Agreement before code** | `proposal.md`, `tasks.md` | the issue: `## Questions` and `## Scenarios` — future test names |
|
|
123
96
|
| **A change in the PR** | ADDED / MODIFIED / REMOVED deltas — separate files written by the agent | `spec-diff` from git: added, changed and removed requirements |
|
|
124
|
-
| **
|
|
125
|
-
| **Architecture and "why"** | `design.md` in the change archive | a C1–C3 model with checks; the reason — in `<section>.md` next to the check |
|
|
126
|
-
| **Qualities** (performance, security, accessibility) | a prose requirement, like behavior | cross-cutting — a "registry + invariant" standard (audit on every mutation, axe on every page); one capability's budget — in its tests |
|
|
127
|
-
| **Documentation** | the specs themselves — read them whole | generated from test names into the `spec` branch |
|
|
128
|
-
| **Uncheckable (look, copy)** | a prose requirement | not called spec — acceptance in the issue; where the look is a decision, it's a screenshot test |
|
|
129
|
-
| **Tasks, estimates, CI, merge** | out of scope | the canon and skills: GitHub Projects, `est`, `ci-wait` |
|
|
130
|
-
|
|
131
|
-
### What a live project showed
|
|
132
|
-
|
|
133
|
-
A product project on OpenSpec: 68 specs, ≈1000 requirements and ≈4000 scenarios — 3 MB of Markdown, plus the change archive.
|
|
134
|
-
|
|
135
|
-
**Audit before the switch**
|
|
136
|
-
|
|
137
|
-
- **Specs go stale silently.** Of 11 requirements checked, 6 were stale; three direct contradictions between specs; 23 of 68 specs have "TBD" as their purpose; 14 of 347 file paths lead nowhere. `openspec validate --strict` is green all the while — it checks structure, not truth. The cause is one: a fact is written in several specs, and a change edits its own.
|
|
138
|
-
- **The spec and the tests are two independent records of the same behavior.** Of 40 random spec scenarios, 5 were found among test names.
|
|
139
|
-
- **Standards are held by code, not by text.** Those built into code are followed (an audit record in 64 of 65 mutations), those written in prose aren't: 26 forbidden constructs, 6 of them added after the rule.
|
|
140
|
-
- **Specs are expensive to read.** One spec is 463 KB, over 100k tokens, and to "check against the spec" the agent reads it whole. The archive of 237 changes is 10.9 MB, 19–29% of it makes it into the live specs; `proposal.md` and `tasks.md` repeat the issue. In a measured task ≈26% of what the agent read was OpenSpec artifacts.
|
|
97
|
+
| **Documentation** | the specs themselves — read them whole | generated from test names into the `spec` branch after merge, not into `main` |
|
|
141
98
|
|
|
142
|
-
**
|
|
143
|
-
|
|
144
|
-
- Only 585 requirements (56%) had a test, 255 had one partially, 149 had none at all.
|
|
145
|
-
- ≈950 requirements became tests; ≈102 were removed with a reason (look, copy, one-off migrations, infrastructure outside the repository); ≈105 were rewritten from the code — the spec had fallen behind an intentional decision.
|
|
146
|
-
- Check by breaking — over 3.6k targeted code breakages — found at least 165 tests that counted as coverage but didn't catch the breakage.
|
|
147
|
-
- Along the way, 70 bugs (2 Urgent, 6 High) and 58 standard candidates were found.
|
|
148
|
-
|
|
149
|
-
How to migrate — the reference [`skills/spec/migration.md`](skills/spec/migration.md): an outcome for every requirement, check by breaking, removal categories, "the spec fell behind the code".
|
|
150
|
-
|
|
151
|
-
No exaggeration: the spec format isn't the main token cost; what costs more is how many subagents are launched and what they are told to read. Task hours and cost before and after are to be compared by `est` actuals, once a sample accumulates.
|
|
99
|
+
**What a live project showed.** A product project on OpenSpec — 68 specs, ≈1000 requirements, 3 MB of Markdown — with `openspec validate --strict` green: 6 of 11 requirements checked were stale, and in a measured task ≈26% of what the agent read was OpenSpec artifacts. Its 1052 requirements moved into tests in 13 PRs: only 56% had a test; check by breaking found at least 165 tests that counted as coverage but didn't catch the breakage, and 70 bugs turned up along the way. How to migrate — [`skills/spec/migration.md`](skills/spec/migration.md). The spec format isn't the main token cost, though: subagents and what they are told to read cost more.
|
|
152
100
|
|
|
153
101
|
**When OpenSpec fits better:** you need a requirements document for people outside the code; the project has no tests and won't have them; you need a "proposal before code" gate as a separate artifact. Elves moves this gate into the issue — scenarios are visible before code — but not into a file.
|
|
154
102
|
|
|
155
103
|
## Installation
|
|
156
104
|
|
|
157
|
-
You need `git` and [Bun](https://bun.sh) ≥ 1.2
|
|
158
|
-
|
|
159
|
-
```bash
|
|
160
|
-
# onto the machine — the canon, skills and the hook for every agent it has, and the elves command on PATH; or a global package:
|
|
161
|
-
# bun add -g @miroshnik/elves && elves install -g
|
|
162
|
-
bunx @miroshnik/elves install -g
|
|
163
|
-
|
|
164
|
-
# into a project — from the root of a git repository; the package version, the manifest, the shim and the AGENTS.md block are committed with the project
|
|
165
|
-
bunx @miroshnik/elves install
|
|
166
|
-
|
|
167
|
-
# the fallback — straight from GitHub, any command: bunx github:miroshnik/elves <command>
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
Keeping the flow up to date:
|
|
171
|
-
|
|
172
|
-
```bash
|
|
173
|
-
bunx @miroshnik/elves check -g # 0 — up to date, 1 — behind (in a project also: git ignores flow files, the compose file breaks task isolation, standards or architecture without a test:spec script), 2 — can't check; changes nothing
|
|
174
|
-
bunx @miroshnik/elves update -g # bring it to the latest release
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
Without `-g` — the same for the project. Claude Code checks the machine and the project by itself: `install -g` sets up the `SessionStart` hook, and the `check` output lands at the start of every session; a session resumed after the app restarted also gets the wait of its task to restart — background waits die with the app's process. The same hook sets up the agent's Bash: in zsh a glob without matches and `====` go to the command as is, as in bash, and `timeout` works on macOS without coreutils (`bin/shims`); `check -g` run from the agent's Bash names it if the session didn't get that. With Docker on the machine `check -g` also names the `task-env` proxy of task addresses — running or not, with the command to start it; it doesn't change the exit code.
|
|
178
|
-
|
|
179
|
-
An agent's sandbox (Claude Code's Bash) doesn't let bunx write its cache `~/.bun/install/cache` — prefix the command with `BUN_INSTALL_CACHE_DIR="$TMPDIR/bun"` — nor the install write `.claude/skills`: then run the command in your own terminal — the refusal names it, and a repeat run finishes a cut-off install.
|
|
180
|
-
|
|
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
|
-
|
|
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
|
-
|
|
185
|
-
<details>
|
|
186
|
-
<summary><b>What goes where</b></summary>
|
|
187
|
-
|
|
188
|
-
**Into a project** — thin: no copy of the flow, its agents get the canon and the skills from the machine. Committed with the project:
|
|
189
|
-
|
|
190
|
-
- `@miroshnik/elves` in `devDependencies` of `package.json` — the exact version of the release, the project's package manager updates its lockfile: the harness and the skills' scripts at the project's version for its tests and CI, colleagues and the cloud session ("The package in a project" below); a project without `package.json` has nothing to pin.
|
|
191
|
-
- `.agents/elves.json` — `auto` — whether the agent runs a task entirely by itself, without a "yes" for commit, push and merge, `language` — the project language, `env` — the task stack settings of `task-env`, and `batch` — whether a dispatcher merges its tasks into a batch branch instead of `main` (`github task queue`).
|
|
192
|
-
- `.agents/slot.sh` — the machine queue's shim the `package.json` checks source (`slot` below).
|
|
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
|
-
- 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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
202
|
-
</details>
|
|
203
|
-
|
|
204
|
-
<details>
|
|
205
|
-
<summary><b>Releases and the up-to-date check</b></summary>
|
|
206
|
-
|
|
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.
|
|
208
|
-
|
|
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`.
|
|
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.
|
|
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.
|
|
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.
|
|
213
|
-
|
|
214
|
-
</details>
|
|
215
|
-
|
|
216
|
-
<details>
|
|
217
|
-
<summary><b>The package in a project — the harness and the scripts at the project's version</b></summary>
|
|
218
|
-
|
|
219
|
-
With `@miroshnik/elves` in a project's `devDependencies`, `bun install` brings the flow at the project's version — for CI, colleagues and a cloud session too (npm works there, `github:` gives 403). Tests import `@miroshnik/elves/spec/harness`, `@miroshnik/elves/spec/architecture`, `@miroshnik/elves/spec/eslint-config` and `@miroshnik/elves/github`: Bun and the type checker take the TypeScript source, any runner on Node (Jest, Playwright, `node:test`, the project's `eslint.config.js`) — the build; the knip reporter `@miroshnik/elves/spec/knip-hints` is CommonJS as is, its `file` — the path for `knip --reporter`. The skills' scripts run from `node_modules/.bin` with the same arguments as the scripts themselves, under `bun --no-env-file` — in `package.json` and CI alike: `bun` reads the TypeScript bin `elves` itself, past its shebang, and without the flag it would get the project's env files (`.env.local` with production keys) and pass their keys on to `gh`, `git` and the checked command. On Yarn 2+ — `bunx @miroshnik/elves@"$(jq -r '.devDependencies["@miroshnik/elves"]' package.json)" <script>`, the form `install` writes there: Yarn 2+ runs a `.ts` bin by Node with any `nodeLinker`, and PnP has no `node_modules`.
|
|
105
|
+
You need `git` and [Bun](https://bun.sh) ≥ 1.2; the `github`, `est` and `dashboard` skills also need [`gh`](https://cli.github.com) with the `project` scope, `task-env` — Docker with Compose.
|
|
220
106
|
|
|
221
107
|
```bash
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
bun --no-env-file node_modules/.bin/elves spec-shard …
|
|
227
|
-
bun --no-env-file node_modules/.bin/elves spec-claims …
|
|
228
|
-
bun --no-env-file node_modules/.bin/elves spec-break …
|
|
229
|
-
bun --no-env-file node_modules/.bin/elves precommit
|
|
230
|
-
bun --no-env-file node_modules/.bin/elves task-env up …
|
|
231
|
-
bun --no-env-file node_modules/.bin/elves task-env e2e …
|
|
232
|
-
bun --no-env-file node_modules/.bin/elves task-env down …
|
|
233
|
-
bun --no-env-file node_modules/.bin/elves task-env prune
|
|
234
|
-
bun --no-env-file node_modules/.bin/elves task-env check …
|
|
235
|
-
bun --no-env-file node_modules/.bin/elves task-env proxy up
|
|
236
|
-
bun --no-env-file node_modules/.bin/elves task-env proxy down
|
|
237
|
-
bun --no-env-file node_modules/.bin/elves task-env proxy status
|
|
108
|
+
bunx @miroshnik/elves install -g # onto the machine: the canon, the skills and the hook for every agent it has
|
|
109
|
+
bunx @miroshnik/elves install # into a project, from its git root: the package version and the manifest, committed with it
|
|
110
|
+
bunx @miroshnik/elves check -g # is the flow behind the latest release: 0 — no, 1 — yes, 2 — can't check; changes nothing
|
|
111
|
+
bunx @miroshnik/elves update -g # bring it to the latest release
|
|
238
112
|
```
|
|
239
113
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
</details>
|
|
114
|
+
Without `-g` — the same for the project. `install` in a project asks whether the agent runs a task entirely by itself, up to merging its own PR on green checks (`auto`, no by default), and which language it works in; in Claude Code the `SessionStart` hook puts the `check` output at the start of every session. The flow follows releases — date tags that `elves release` cuts as the owner's step and CI publishes to npm with `elves pack <tag>`. In a project the skills' scripts run at its package version, as `bun --no-env-file node_modules/.bin/elves <script>`: `elves spec-doc`, `elves spec-diff`, `elves spec-publish`, `elves spec-run`, `elves spec-shard`, `elves spec-claims`, `elves spec-break`, `elves precommit`, `elves slot`, `elves task-env up`, `elves task-env e2e`, `elves task-env down`, `elves task-env prune`, `elves task-env check`, `elves task-env proxy up`, `elves task-env proxy down`, `elves task-env proxy status`.
|
|
243
115
|
|
|
244
|
-
|
|
245
|
-
<summary><b>Working on the flow itself — from a clone</b></summary>
|
|
246
|
-
|
|
247
|
-
```bash
|
|
248
|
-
git clone https://github.com/miroshnik/elves && cd elves
|
|
249
|
-
bun bin/elves.ts install -g --link # symlinks to the clone instead of copies: edits show up immediately
|
|
250
|
-
bun bin/elves.ts release --dry-run # what goes into the release; without --dry-run — cut it
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
</details>
|
|
116
|
+
What goes where, the agent's sandbox, the mode and the language, releases, the package in a project and working from a clone — [`docs/installation.md`](docs/installation.md).
|
|
254
117
|
|
|
255
118
|
## Skills
|
|
256
119
|
|
|
257
|
-
|
|
120
|
+
Installed onto the machine with the flow; the agent picks a skill up by itself from its `SKILL.md`, which has the details.
|
|
258
121
|
|
|
259
122
|
### [`github`](skills/github/SKILL.md) — project and tasks by the canon
|
|
260
123
|
|
|
261
|
-
|
|
124
|
+
The GitHub project and tasks, a command per step: a task with its fields and estimate, its questions and answers, its tail from branch to close — PR, CI, merge, deploy, epic refresh — and a dispatcher's queue of background executors.
|
|
262
125
|
|
|
263
126
|
`github project check` · `github project fix` · `github task new | show | answer | edit | start | status | drop | actualize | close | finish | resume | queue` · `github batch release` · `github pr labels | premerge`
|
|
264
127
|
|
|
265
128
|
### [`est`](skills/est/SKILL.md) — estimates from actuals
|
|
266
129
|
|
|
267
|
-
An estimate from analogs with a measured actual, set by `github task new` itself
|
|
130
|
+
An estimate from analogs with a measured actual, set by `github task new` itself; the actual — active hours, tokens and the API equivalent in $ from Claude Code, Codex and cloud session transcripts.
|
|
268
131
|
|
|
269
132
|
`est estimate` · `est fact` · `est history` · `est backtest` · `est period` · `est cloud-import`
|
|
270
133
|
|
|
271
134
|
### [`dashboard`](skills/dashboard/SKILL.md) — sessions at work, estimate, actual and cost
|
|
272
135
|
|
|
273
|
-
A browser page
|
|
136
|
+
A browser page: sessions at work and what each waits for — CI, merge, deploy, a human's answer — with the owner's open questions; estimate against actual, tokens and cost by task close date.
|
|
274
137
|
|
|
275
138
|
`dashboard [--repo o/r | --all-repos] [--since 90d]`
|
|
276
139
|
|
|
277
140
|
### [`spec`](skills/spec/SKILL.md) — specification from tests
|
|
278
141
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
- `spec-publish`
|
|
282
|
-
- `spec-run` — for publishing on PR merge, finds a green run that checked exactly the merge commit's tree; there is none (a PR that fell behind was merged) — publishing is skipped, the `spec` branch isn't rolled back.
|
|
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.
|
|
284
|
-
- `spec-claims` — every entry point (route, page, job, command) is called by a capability test — by the call log, not by coverage.
|
|
285
|
-
- `spec-break` — proves that a check catches a breakage: break the code → run the test → always revert.
|
|
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.
|
|
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.
|
|
142
|
+
The spec from tests: documentation from runner reports into the `spec` branch, the PR's requirement diff, CI shards, entry points called by tests, check by breaking, the checks before a commit and the harness of deterministic checks.
|
|
143
|
+
|
|
144
|
+
`spec-doc` · `spec-diff` · `spec-publish` · `spec-run` · `spec-shard` · `spec-claims` · `spec-break` · `precommit` · `harness.ts`
|
|
288
145
|
|
|
289
146
|
### [`ci-wait`](skills/ci-wait/SKILL.md) — wait for checks, don't guess
|
|
290
147
|
|
|
291
|
-
Waits for all checks of a PR or a commit
|
|
148
|
+
Waits for all checks of a PR or a commit — CI, deploy, an external check — with progress and PASS / FAIL / TIMEOUT / ERROR outcomes instead of `gh pr checks --watch` and `sleep` in a loop.
|
|
292
149
|
|
|
293
150
|
`wait-ci pr | status | merged | issue`
|
|
294
151
|
|
|
295
152
|
### [`slot`](skills/slot/SKILL.md) — the machine's heavy runs in a queue
|
|
296
153
|
|
|
297
|
-
Project checks
|
|
154
|
+
Project checks and task stacks wait in the machine queue: as many runs at a time as the machine has slots, the rest in arrival order; the runner takes its workers from `ELVES_SLOT_CPUS`.
|
|
298
155
|
|
|
299
156
|
`slot '<command>' [args…]` · in `package.json`: `. .agents/slot.sh && <command>`
|
|
300
157
|
|
|
301
158
|
### [`task-env`](skills/task-env/SKILL.md) — a task's environment: its Compose stack and addresses `*.localhost`
|
|
302
159
|
|
|
303
|
-
A task's
|
|
160
|
+
A task's own Docker Compose stack `<project>-<N>` with addresses `http://<service>.<N>.<project>.localhost` through one Traefik proxy per machine — no host ports, separate cookies, parallel sessions don't touch each other; `check` holds the compose file to the isolation rules.
|
|
304
161
|
|
|
305
162
|
`task-env up | e2e | down | prune` · `task-env proxy up | down | status` · `task-env check [<dir>]`
|
|
306
163
|
|
|
@@ -308,14 +165,15 @@ A task's stack is the Docker Compose project `<project>-<N>`: parallel sessions
|
|
|
308
165
|
|
|
309
166
|
Mechanics the canon refers to; the agent reads them as needed.
|
|
310
167
|
|
|
311
|
-
- [`docs/
|
|
312
|
-
- [`docs/
|
|
313
|
-
- [`docs/
|
|
314
|
-
- [`docs/
|
|
315
|
-
- [`docs/
|
|
316
|
-
- [`docs/
|
|
317
|
-
- [`docs/
|
|
318
|
-
- [`docs/
|
|
168
|
+
- [`docs/installation.md`](docs/installation.md) — what goes into a project and onto the machine, the session hook and the sandbox, the mode and the language, releases, the package in a project, working from a clone.
|
|
169
|
+
- [`docs/pr-checks.md`](docs/pr-checks.md) — waiting for PR, commit and deploy checks; the app's Auto-fix is off: a conflict is a rebase.
|
|
170
|
+
- [`docs/ci-concurrency.md`](docs/ci-concurrency.md) — CI for parallel tasks: parallel branches, a non-cancellable `main`, a deploy queue.
|
|
171
|
+
- [`docs/testing.md`](docs/testing.md) — what runs before a commit and what in CI, a run's result by the runner's summary, e2e without flakes, UI state by the DOM.
|
|
172
|
+
- [`docs/judgment.md`](docs/judgment.md) — judgment and edits: a mistake disguised as an outcome, a label is a claim, editing exactly what was named.
|
|
173
|
+
- [`docs/production.md`](docs/production.md) — production: migrations, the right database, "didn't help" goes to production facts.
|
|
174
|
+
- [`docs/parallel-checkouts.md`](docs/parallel-checkouts.md) — parallel worktrees: shared files, ports, databases and `.git/config`.
|
|
175
|
+
- [`docs/cloud-sessions.md`](docs/cloud-sessions.md) — the Claude Code cloud session: what it can't access, its brief, closing a task from there.
|
|
176
|
+
- [`docs/prompt-cache.md`](docs/prompt-cache.md) — Claude Code's prompt cache TTL: 5 minutes or the hour, and when the hour pays off.
|
|
319
177
|
|
|
320
178
|
## Repository layout
|
|
321
179
|
|
|
@@ -329,7 +187,7 @@ bin/elves.ts the installer — TypeScript under Bun too: bunx runs it from
|
|
|
329
187
|
bin/shims/ commands the SessionStart hook adds to the end of the agent's Bash PATH: timeout
|
|
330
188
|
```
|
|
331
189
|
|
|
332
|
-
**A skill = a prompt + scripts** following the open [Agent Skills](https://agentskills.io) standard: a `<name>/` folder with `SKILL.md`
|
|
190
|
+
**A skill = a prompt + scripts** following the open [Agent Skills](https://agentskills.io) standard: a `<name>/` folder with `SKILL.md` — when and what to call — and `scripts/` for the deterministic part, TypeScript under Bun (`bun script.ts`: no build, no dependencies, imports with `.ts`); reference material — `reference.md` and the scripts' `--help`. Third-party code a script can't do without goes into `scripts/vendor/` as a file with its license, not as a dependency. Everything that depends on specific repositories goes into local configuration, not into the skill.
|
|
333
191
|
|
|
334
192
|
Elves lives by its own flow: the spec — [`tests/`](tests), its documentation — in the [`spec` branch](https://github.com/miroshnik/elves/tree/spec), tasks — in [Issues](https://github.com/miroshnik/elves/issues) and the [elves project](https://github.com/users/miroshnik/projects/6).
|
|
335
193
|
|
package/bin/elves.ts
CHANGED
|
@@ -247,7 +247,7 @@ Examples:
|
|
|
247
247
|
|
|
248
248
|
From an Elves clone: a vYYYY.MM.DD tag on origin/main and a GitHub Release listing the flow changes since the previous
|
|
249
249
|
release; --dry-run — only show them. CI publishes the tag to npm (.github/workflows/npm.yml, pack --help) by trusted
|
|
250
|
-
publishing, without a token; the owner's step once —
|
|
250
|
+
publishing, without a token; the owner's step once — docs/installation.md, "Releases and the up-to-date check".
|
|
251
251
|
|
|
252
252
|
Examples:
|
|
253
253
|
elves release --dry-run`,
|