@miroshnik/elves 2026.1112.1 → 2026.1117.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.
Files changed (56) hide show
  1. package/.claude-plugin/plugin.json +8 -0
  2. package/AGENTS.md +134 -289
  3. package/README.md +68 -245
  4. package/agents/executor.md +22 -0
  5. package/bin/elves.ts +507 -285
  6. package/claude/CLAUDE.md +40 -68
  7. package/dist/github/scripts/github.js +1420 -634
  8. package/dist/spec/scripts/architecture.js +2 -2
  9. package/dist/spec/scripts/{harness-yh1g3dhm.js → harness-7780cv0k.js} +1 -1
  10. package/dist/spec/scripts/{harness-1rfkbdbn.js → harness-efesfpam.js} +9 -131
  11. package/dist/spec/scripts/harness.js +1 -1
  12. package/docs/ci-concurrency.md +8 -3
  13. package/docs/installation.md +85 -0
  14. package/docs/other-agents.md +19 -0
  15. package/docs/parallel-checkouts.md +24 -16
  16. package/docs/prompt-cache.md +1 -1
  17. package/docs/testing.md +22 -10
  18. package/hooks/hooks.json +47 -0
  19. package/package.json +8 -6
  20. package/skills/ci-wait/SKILL.md +8 -9
  21. package/{docs/pr-checks.md → skills/ci-wait/reference.md} +29 -34
  22. package/skills/ci-wait/scripts/wait-ci.sh +13 -1
  23. package/skills/est/SKILL.md +56 -107
  24. package/skills/est/reference.md +68 -153
  25. package/skills/est/scripts/est.ts +710 -1421
  26. package/skills/github/SKILL.md +60 -69
  27. package/skills/github/locales/en.json +4 -65
  28. package/skills/github/locales/ru.json +4 -65
  29. package/skills/github/reference.md +551 -459
  30. package/skills/github/scripts/bypasses.ts +47 -0
  31. package/skills/github/scripts/command.ts +40 -0
  32. package/skills/github/scripts/github.ts +1632 -789
  33. package/skills/github/scripts/locale.ts +12 -54
  34. package/skills/github/scripts/queue.ts +338 -0
  35. package/skills/slot/SKILL.md +1 -1
  36. package/skills/spec/SKILL.md +19 -15
  37. package/skills/spec/canon.md +16 -7
  38. package/skills/spec/checks.md +2 -2
  39. package/skills/spec/ci.md +74 -47
  40. package/skills/spec/migration.md +2 -1
  41. package/skills/spec/reference.md +67 -15
  42. package/skills/spec/scripts/harness.ts +1 -1
  43. package/skills/spec/scripts/spec-diff.ts +17 -3
  44. package/skills/spec/scripts/spec-red.ts +337 -0
  45. package/skills/spec/scripts/spec-run.ts +10 -2
  46. package/skills/spec/scripts/speclib.ts +66 -16
  47. package/skills/task-env/SKILL.md +2 -8
  48. package/skills/task-env/proxy/compose.yaml +0 -11
  49. package/skills/task-env/reference.md +5 -20
  50. package/skills/task-env/scripts/task-env.ts +1 -83
  51. package/docs/cloud-sessions.md +0 -205
  52. package/docs/judgment.md +0 -104
  53. package/docs/production.md +0 -15
  54. package/skills/dashboard/SKILL.md +0 -214
  55. package/skills/dashboard/scripts/dashboard.ts +0 -912
  56. package/skills/dashboard/scripts/sessions.ts +0 -772
@@ -0,0 +1,8 @@
1
+ {
2
+ "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
3
+ "name": "elves",
4
+ "version": "2026.1117.0",
5
+ "description": "Elves — the development flow for Claude Code: the skills elves:<name>, the SessionStart hook (the flow check and the agent's Bash environment), the PreToolUse guard of the flow's commands and the dispatcher's executor agent elves:executor. Installed by bunx @miroshnik/elves install -g as ~/.claude/skills/elves.",
6
+ "homepage": "https://github.com/miroshnik/elves",
7
+ "repository": "https://github.com/miroshnik/elves"
8
+ }
package/AGENTS.md CHANGED
@@ -1,313 +1,158 @@
1
1
  # Shared rules for all projects
2
2
 
3
- ## This file and skills
4
-
5
- The Elves canon for any agent. It lives in **miroshnik/elves** with the
6
- skills (`skills/*`) and references (`docs/`, next to this file), installed
7
- onto the machine — README, "Installation". A rule or skill change from
8
- another project's session is a task in Elves (project #6) without that
9
- project's names, for a separate session; I don't edit an Elves clone from
10
- someone else's session. A Claude Code **cloud session** sees only the
11
- repository and its project hook's flow — `docs/cloud-sessions.md`.
3
+ The Elves canon: each rule names the mechanism that holds it or stands in
4
+ "Judgment".
12
5
 
13
- **The repository is public:** no names, owners, paths or numbers of other
14
- repositories, no colleagues or clients — in files, git history or issues;
15
- examples are made up. **A skill is `SKILL.md` + `scripts/`** in TypeScript
16
- under Bun (Agent Skills; README, "Repository layout"); repository specifics
17
- — local configuration. **Budgets** (standard `documents#canon-size`): this file ≤
18
- 3,000 words, `SKILL.md` ≤ 2,500, a description ≤ 1,024 characters.
19
- Here — what always applies and where to go; reference — a skill's
20
- `reference.md` or `--help`, `docs/`. **A file at its budget** — a detail
21
- moves whole, by its topic, into that topic's md (an existing one, else
22
- `docs/<topic>.md`), here — a link to it; a fact is never deleted for the
23
- budget.
6
+ ## This file and skills
24
7
 
25
- ## First step of a session — an up-to-date flow
8
+ - **The canon lives in Elves.** The rules, skills and references come from
9
+ miroshnik/elves by `elves install -g`; a change to them from another
10
+ project's session is a task in Elves without that project's names, not an
11
+ edit of an Elves clone.
12
+ - **References load by themselves.** `elves install -g` links every
13
+ reference with `paths:` into `~/.claude/rules`, and Claude Code loads it
14
+ when I work with matching files: tests, workflows, compose files.
26
15
 
27
- Rules load at the session start, so before the task: `bunx
28
- @miroshnik/elves check -g` (machine) and `check` (project, with its mode
29
- and language). The machine's copy and a project's package version
30
- follow Elves releases (tags `vYYYY.MM.DD`), a `--link` clone — `origin/main`;
31
- a release is the owner's step (`elves release`), I cut one only when asked.
16
+ ## First step of a session
32
17
 
33
- - **The machine is behind** — `update -g`. After an `update` I tell the user
34
- briefly what changed and re-read what was updated: it applies, not what
35
- loaded at the start.
36
- - **The project is behind** (or git ignores flow files) — `update` in the
37
- task's branch: the package version.
38
- - **`update` refused or the check unavailable** — I don't fix the clone; I
39
- work by the current flow and say so.
18
+ - **The SessionStart hook checks the flow.** Its `elves check --hook` lines
19
+ say whether the machine or the project is behind and name the project's
20
+ mode and language; I do what they say, tell the user what an update
21
+ changed and re-read the updated files.
40
22
 
41
23
  ## Language
42
24
 
43
- The flow is written in English; the agent works in the **project language**
44
- (`language` in `.agents/elves.json`, printed by `check`; none — `github` won't
45
- write): talking with the user, issues, prompts to subagents, documents, commit
46
- and PR descriptions, `describe`/`it` names, decision docs — briefly. Always English:
47
- code, identifiers, terms, conventional-commit type and scope. Names that
48
- scripts write to GitHub and parse back are exact — `locales/<language>.json`
49
- of the `github` skill; in `en`: sections `## Questions`, `## Scenarios`;
50
- `Status` `Backlog` → `In progress` → `Done`; the comment `State`; `Task #N`,
51
- `epic #M` in a subagent's prompt; the last line `All
52
- done. The session can be closed.` · `All done, but there are questions: …` ·
53
- `Remaining: …`.
25
+ - **The project language.** I talk to the user and write issues, subagent
26
+ prompts, documents, commit and PR descriptions and test names in the
27
+ language the SessionStart hook names; code, identifiers and terms stay in
28
+ English, and the names scripts parse back come exactly from the locales of
29
+ the `elves:github` skill.
54
30
 
55
31
  ## What I do without asking and what needs a yes
56
32
 
57
- - **Without asking:** reading and search, tests, lint, typecheck, build, local
58
- edits in my checkout, local infrastructure (Docker, dev database), logs and
59
- read-only requests to external systems; task tracking; re-running my own CI
60
- run, closing my own duplicate PR, deleting my own merged branch; updating
61
- the flow and committing it.
62
- - **Only on an explicit "yes"** — anything irreversible or external: `git
63
- commit`, `git push`, merge, deploy, tag, migrations and writes to live
64
- databases, external service settings, deleting others' or unmerged remote
65
- branches and data, outgoing messages (auto mode — below).
66
- - **Permission is for this action, this time:** "commit" ≠ "and push", "fix
67
- whatever is needed" ≠ a merge, a past "yes" doesn't carry over; one
68
- "commit" covers all current work in logical steps. A repository may set
69
- another mode in its `AGENTS.md`. "Do it all yourself" lifts intermediate
70
- confirmations for the named task, except on a discrepancy that changes
71
- scope or approach. An autonomous routine does exactly what
72
- its assignment names; merge, deploy, external settings — only if named.
73
- - **`"auto": true` in `.agents/elves.json` — the whole task without asking**:
74
- commit, push, fixing CI, merging my own PR on green checks; work outside the
75
- task — a Backlog task and the question «queue it?». The task's open
76
- questions — I answer by a recommendation with ✅ auto (`task answer
77
- --auto`); my own question goes into the questions section the same way,
78
- before code, not into chat. I ask only
79
- without a clear recommendation, when the decision is critical or a human's,
80
- or on a discrepancy that changes scope or approach — not when the answer
81
- would be "yes" or "as you recommend". Anything else irreversible or
82
- external still needs a "yes".
83
- - **Secrets and bypassing protections — only with permission** (tokens, keys,
84
- bypass secrets, disabling checks at the host, CI or cloud): first — what
85
- will appear and where; a secret from chat — never stored (memory, files,
86
- commits, issues, logs), rotation reminded.
33
+ - **Commit, push and merge ask in a project without auto.** `elves install`
34
+ puts them into `permissions.ask` of the project's `.claude/settings.json`,
35
+ so Claude Code asks the owner itself. With `"auto": true` in
36
+ `.agents/elves.json` the whole task goes without asking, and I answer its
37
+ questions by the recommendation with `github task answer --auto`, asking
38
+ only without a clear recommendation, on a critical or a human's decision,
39
+ or on a discrepancy that changes the scope.
87
40
 
88
41
  ## Task tracking
89
42
 
90
- - Tasks live in the repository's **GitHub Issues**, not in local lists, TODO
91
- files or the agent's task list; no repository — ask where. The `github`
92
- skill runs them, not `gh issue view`/`edit` (descriptions — `task
93
- edit`); how tasks, the project and
94
- milestones are organized — its `reference.md`.
95
- - **Types:** Task (one PR), Bug, Epic (a personal account — the `epic`
96
- label). **Decision labels** — the topic's name, kind by color: a task
97
- carries those of the topics it introduces or changes, an epic — their
98
- union.
99
- - **A big task is an epic** (prefix `<Prefix> · …`) **+ subtasks**
100
- (sub-issues); **dependencies only as GitHub links** (sub-issue, blocked
101
- by — on another repository's issue too; a blocker that isn't an issue — the
102
- `external blocker` label, the reason in a comment): a task with an open
103
- *blocked by* or that label isn't taken. Before creating — check it doesn't
104
- exist (`gh issue list --search`).
105
- - **What GitHub keeps natively isn't repeated in an issue's text** —
106
- sub-issues, blocked by, `Status`, milestone, labels, fields, the PR: a copy
107
- goes stale; an epic's description has no list of subtasks or stages.
108
- - **One GitHub Project per repository**, named after it, with all tasks;
109
- `project check` once per session, ❌ — `project fix`. `Status` I set
110
- **myself, immediately**: `task status`, `task close`, `task drop` (won't
111
- do, duplicate). An organization's open task requires `Priority`
112
- (`Urgent` → `Low`, `Medium` by default). A milestone (an epic stage, a
113
- release) I close with its last task.
114
-
115
- ### Session and branch — one task
116
-
117
- - **Session = task:** `task start` won't take a second one. Another task —
118
- Backlog and the question «queue #263?», "yes" — its executor at once;
119
- "do it here" — a one-sentence refusal and the question again. My own
120
- regression and a fix for a green PR are the same task. A new epic — the
121
- question «run the dispatcher on epic #M?», without In progress.
122
- - **A dispatcher** — "do all tasks of epic #M", "fix all High bugs", a "yes"
123
- (scope, not merges outside auto) — any session, its task stays; one started
124
- for it — in the project folder, not a worktree: executors start from `main`.
125
- `github task queue` prints executors' prompts; an executor — a background
126
- subagent (own worktree) or a cloud session: at most the machine's executors
127
- in subagents and 5 cloud sessions at once, the owner's number replaces
128
- either (`task queue` names the executors, `slot`'s `machine.json` sets them); failed — a task
129
- comment, no restart; an executor session whose task closed — the dispatcher
130
- archives it in an auto project, not one still working in the background or
131
- awaiting the owner's answer; outside auto the owner closes it. A batch
132
- project — `github batch release`.
133
- - **The session is named `#<number> <task title>`** (without a task — by
134
- meaning, no number) as soon as the task is clear (no tool — ask the user):
135
- `est` links the session to the task by it.
136
- - **Branch = `<type>/<issue>-<slug>`** (`feat/42-invoice-export`): `type` —
137
- conventional-commit types (`feat fix docs refactor perf test chore ci
138
- build`) plus `research` (a spike without code); slug — Latin kebab-case,
139
- 2–5 words; a repository's area prefix goes first (`backend/fix/263-…`). A
140
- branch named by a worktree tool is renamed before the first push by `github
141
- task start <N> --branch <type>/<N>-<slug>`.
142
- - **PR:** the title is a conventional commit, the body has `Closes #263`.
143
- **Merge — rebase only** (`gh pr merge <N> --rebase`): commits land in
144
- `main`, each a conventional commit with `Refs #263` (`Closes` would close
145
- the task). Without PRs — `Closes #N` in the last commit.
146
-
147
- ### Open questions — at the start of work
148
-
149
- A task's questions are a numbered list in its description's questions
150
- section. Taking a task, **first of all** — before the plan, code and
151
- subagents — I read the questions of the task and its epic (`github task start
152
- <N>` prints them) and **ask the user all open ones (without ✅)** in one message, each
153
- with options and a recommendation. What already has an answer (comments,
154
- code) gets ✅; my own questions join the message and the section. While
155
- waiting I do what doesn't depend on the answer — what does, I neither start
156
- nor replace with an assumption. The answer goes straight into the issue:
157
- `github task answer <N> <k> "<answer>"`. An autonomous routine doesn't take a
158
- task with open questions.
159
-
160
- ### Estimate and actual — the `est` skill
161
-
162
- The unit is the agent's hours on the task except waits for the user's input;
163
- CI and check waits count, split out.
164
- The estimate is set by `github task new`, the actual by `github task close`;
165
- neither is written by hand, the estimate isn't rewritten after
166
- work starts, no actual — "actual unavailable", not a number by eye. Work is
167
- linked to the task by the pinned session, the session name, the branch,
168
- `Closes #N` and the task number in every subagent's assignment ("Subagents
169
- and worktrees") — otherwise there is no actual.
170
-
171
- ### Epic refresh on task close
172
-
173
- Once a task is merged, **a subagent with a fresh context** brings the open
174
- tasks of its epic in line with what shipped: `github task finish <N>` waits
175
- for the deploy, does the mechanics, prints its prompt and, after its report,
176
- closes the task. The last line of the answer ("Language"): merged,
177
- deployed, branch removed, epic refreshed, no questions — "all done, can be
178
- closed"; the owner has something to decide — "all done, but there are
179
- questions" with them; otherwise — "remaining" with what the session waits for
180
- and from whom. In auto mode after "can be closed" the session archives itself
181
- where the agent has the tool; information without a decision doesn't prevent
182
- it.
43
+ - **Tasks live in GitHub Issues.** Not in local lists, TODO files or the
44
+ agent's task list: the `elves:github` skill creates and edits them, and the
45
+ PreToolUse hook denies `gh issue view` and `gh issue edit --body` with the
46
+ command to run instead. Without a repository I ask where tasks go.
47
+ - **`github task next` is the entry.** It prints the task's state and the
48
+ one next step as a ready command, and every task command ends with the
49
+ same `Next:` line; I run what it prints.
50
+ - **One session, one task.** `github task start` pins the task to the
51
+ session and refuses another one with the question «queue #N?»: "yes" gives
52
+ that task its own executor, "do it here" gets a one-sentence refusal and
53
+ the question again. My own regression and a fix for a green PR are the
54
+ same task.
55
+ - **Open questions first.** `github task start` stops on open questions of
56
+ the task or its epic: I ask the user all of them in one message, each with
57
+ options and a recommendation, and meanwhile do only what doesn't depend on
58
+ them.
59
+ - **A big task is an epic with subtasks.** `github task new --epic` makes a
60
+ subtask and `--blocked-by` a dependency — dependencies are GitHub links
61
+ only, a blocker that isn't an issue is the `external blocker` label — and
62
+ `github task queue` hands out no blocked task, `github task start` doesn't
63
+ take one.
64
+ - **The dispatcher runs the queue.** "Do all tasks of epic #M" or "fix all
65
+ High bugs" makes any session a dispatcher: `github task queue` prints each
66
+ executor's prompt and, after each answer, the next step.
67
+ - **The actual comes from transcripts.** `github task close` writes it; the
68
+ work is linked to the task by the session name, the branch, `Closes #N`
69
+ and «Task #N», in the project language, at the start of every subagent's
70
+ prompt.
183
71
 
184
72
  ## Git, PRs and merging
185
73
 
186
- - **Taking a task** — check it isn't going in a parallel session (an open PR,
187
- a branch `*/<N>-*` — `task start` checks): continue that work or wait
188
- for the merge; two PRs for one thing — close the second.
189
- - **Branch only from a fresh `origin/main`** (`git fetch origin && git switch
190
- -c feat/263-slug origin/main --no-track`). Into `main` only via a PR; a
191
- direct push and `gh pr merge --admin` — only on the owner's direct
192
- instruction. **Before a push** — is it my branch.
193
- - **Commits in logical steps**, tests in the same commit as the code.
194
- **Before a commit — one `elves precommit`** (`lint`, `typecheck`,
195
- `test:spec`, the affected tests; the full run — CI, `docs/testing.md`);
196
- before merging — a full build; `set -o pipefail` in
197
- `script | tail`.
198
- - **I merge as soon as all checks are green** (the preview deploy too; an
199
- empty list is "not registered yet") and GitHub merges without a conflict;
200
- rebase and `--force-with-lease` — only on a textual conflict or my own
201
- changes. **Before merging — `github pr premerge`:** `main` moved after the
202
- PR's CI — fast checks on the merge with it; red — I fix the root cause;
203
- `main` red by itself (code 3) — no merge and no fix in the PR: one bug
204
- for it, I wait for it to close.
205
- - **The tail — `github task finish <N>`**, resumable: push, PR, labels, CI,
206
- `premerge`, the merge command, the deploy on the merge SHA, refresh, close;
207
- a batch's — its release's.
208
- Others' branches, stacks and unmerged work I don't touch.
209
- - Mechanics — the `github` skill, "Git, PRs and merging — mechanics";
210
- waiting for checks and deploys — `docs/pr-checks.md`.
74
+ - **A branch from a fresh base.** The task branch `<type>/<N>-<slug>` starts
75
+ from a fresh `origin/main`, and `github task start --branch` renames a
76
+ branch a worktree tool named; into `main` only through a PR, on which
77
+ `github project fix` sets the `elves` ruleset with required checks and
78
+ the rebase-only merge.
79
+ - **Before a commit — `elves precommit`.** One call runs `lint`,
80
+ `typecheck`, `test:spec` and the affected tests through the machine queue;
81
+ the full run is CI's.
82
+ - **The tail — `github task finish <N>`.** It pushes, opens the PR with
83
+ `Closes #N` and the body from `spec-diff`, waits for CI, runs `github pr
84
+ premerge` and prints the merge command; after the merge it waits for the
85
+ deploy, prints the epic refresh prompt, closes the task and names the
86
+ session's last line. I call it again while its `Next:` says so.
211
87
 
212
88
  ## Specification — decisions
213
89
 
214
- A project's spec is **decisions with a mechanical check**, functional and
215
- non-functional (a test, a lint rule, an architecture check).
216
- **No check — no decision; no decision — no code:** behavior without a check
217
- may change without agreement; code no decision claims is dead. A check is
218
- written before the code, red first (acceptance), then holds the decision
219
- (regression); a decision changes through its check: the check first, red,
220
- then the code. Three `tests/` roots by the reader's question:
221
- `capabilities` (what the system does), `architecture` (what it's made of),
222
- `standards` (code rules, qualities); a decision is a topic with sections
223
- (`<topic>.md` — the subject, `<section>.md` — why, `<section>.test.ts` —
224
- statements), a new rule — a section of the topic covering it.
225
- Exceptions — a mark in the element's file or an `exceptions/` file, with an
226
- `#issue`, a reason, a ratchet. Test names are statements in the project
227
- language; a code task gets the scenarios section (future `it` names) before
228
- code. The PR body is `spec-diff` output; docs — generated (`spec-doc`),
229
- published by CI to the `spec` branch. A recurring decision — a "Standard · …"
230
- issue, a rule in `tests/standards/`; repeats in a PR's files — fixed in it.
231
- The full canon and wiring — the `spec` skill (`canon.md`, `checks.md`).
232
-
233
- ## Tests and code
234
-
235
- - **A test failed — I fix the root cause** (the test or the logic), even if
236
- unrelated to my changes or a rerun is green — no "pre-existing flake",
237
- timeouts or retries; a race goes by its cause (the real event, not a
238
- pause). A flake suspicion — the same run on the base branch: red there too
239
- — I compare the delta; a timeout — first `slot`'s overload line, it's there
240
- — a rerun on an idle machine (`docs/testing.md`).
241
- - **A run's result — by the runner's summary**, not the wrapper's exit code.
242
- Project checks go through the machine queue (the `slot` skill), a full run
243
- — in the background; e2e and UI in a browser — `docs/testing.md`.
244
- - **A regression test and a "no defect" guard must be able to fail**: I
245
- revert the fix, see red, restore it; it didn't fail — it guards against
246
- overcorrection (named so) or is deleted.
247
- - **An external API contract — by its schema or docs**, not intuition; on a
248
- mismatch I fix the test, not the code.
249
- - **Intentionally different behavior in two places** — mirrored comments
250
- with the reason.
251
- - **I check what reached the human** (the delivered email, the page at the
252
- recipient), not my output; a component on several surfaces — in each.
253
- - **Judgment:** before a run — which of our mistakes would give the same
254
- outcome; labels — after checking what the numbers mean; I edit exactly
255
- what was named; "doesn't reproduce" — with what I measured.
256
- `docs/judgment.md`.
257
-
258
- ## Production and debugging
259
-
260
- - **The production database is read-only.** Data and schema change via a
261
- migration in a PR; DDL on production — only on
262
- the owner's direct instruction, as a migration file; the environment
263
- refuses — I explain, no workaround. Data the application manages (roles,
264
- permissions, audited settings) never changes by direct DML: the audit is
265
- lost, guards bypassed; what the UI lacks is a code change.
266
- - **Production numbers — first, is it the right database:** the first query
267
- checks it against the repository; no match — stop (`docs/production.md`).
268
- - **"Didn't help" → production facts, not a third reproduction:** the logs
269
- of the real request and production data (the row, `updated_at`, audit),
270
- then a new hypothesis.
90
+ - **Decisions with a deterministic check.** A project's spec is decisions
91
+ held by checks — tests, lint rules, architecture checks — under
92
+ `tests/capabilities`, `tests/architecture` and `tests/standards`: behavior
93
+ without a check may change without agreement, code no decision claims is
94
+ dead. The full canon is the `elves:spec` skill.
95
+ - **The check comes first, red.** A code task gets its scenarios, the future
96
+ test names, before code, and `github pr premerge` runs the tests a PR adds
97
+ on the base code (`spec-red`): one that passes there checks nothing.
271
98
 
272
99
  ## Subagents and worktrees
273
100
 
274
- - **Subagents don't share a dirty worktree.** An agent that may install
275
- packages or touch files "to try" gets an isolated worktree or "read-only
276
- plus a temp folder" without `git checkout/restore/stash/clean`: its cleanup
277
- reverts everything uncommitted, others' work too. Several agents in one
278
- worktree, temp files shared with subagents — `docs/parallel-checkouts.md`.
279
- After a fan-out — `git status` and `git diff --stat`.
280
- - **A fresh worktree lacks untracked files** (dependencies, `.env*.local`) —
281
- I install and copy them. Paths in commands and assignments lead into the
282
- worktree (a path "from memory" edits `main`); `git -C <worktree> status`
283
- before and after an edit.
284
- - **Parallel checkouts share ports, databases and `.git/config`:** the task's
285
- apps, databases and e2e run in its own Compose stack (the `task-env`
286
- skill), not on a host port; others'
287
- stacks and busy ports I don't touch — `docs/parallel-checkouts.md`.
288
- - **A subagent gets a unit of ~50 turns** (one decision's folder, one file,
289
- one spec), not a 200-turn zone: its price is quadratic in turns. The
290
- assignment has the task
291
- number after the word for "task" or at the start, the epic after the word
292
- for "epic" ("Language") — so `est` links its work. **Fewer turns:** a file
293
- in one full read, independent tool calls in one turn.
294
-
295
- ## Project knowledge and handoff
296
-
297
- - **Shared — in Elves, project-specific — in the project's spec**
298
- ("Specification — decisions"), the reason in the section's `<section>.md`;
299
- neither shared nor checkable (operations, product documents) — the
300
- project's `docs/`. The project's `AGENTS.md` — the install block and how
301
- its mode differs. An agreement from chat goes there too, not into the
302
- agent's memory: memory is a cache, not a source.
303
- - **I don't revisit the stack** or drag in dependencies; something in the way
304
- — a question to the user, not a silent replacement. Versions — latest
305
- stable; a tool question — its official documentation first.
306
- - **Before a pause or an agent change — a State comment in the issue:** done,
307
- the branch, next, blockers.
308
-
309
- ## CI: parallel tasks
310
-
311
- Branches and PRs in parallel, `main`, tags and manual runs never cancelled,
312
- deploy — a queue per environment; others' runs I don't cancel or re-run —
313
- `docs/ci-concurrency.md`.
101
+ - **Heavy runs wait in the machine queue.** `elves install` wraps the
102
+ project's `lint`, `typecheck`, `test` and `test:*` in `slot`; I run checks
103
+ by those scripts, a full run in the background.
104
+ - **A task's services run in its own stack.** Apps, databases and e2e run in
105
+ the task's Compose stack by `task-env up` and `task-env e2e`, not on a host
106
+ port; `elves check` holds the compose file to the isolation rules, `github
107
+ task close` takes the stack down.
108
+ - **A fresh worktree gets its files.** Claude Code copies `.env*.local` by
109
+ the `.worktreeinclude` of `elves install`; dependencies I install.
110
+
111
+ ## Judgment
112
+
113
+ - **Irreversible and external actions need a yes.** A deploy, a tag or a
114
+ release, migrations and writes to live databases, external service
115
+ settings, deleting others' data or unmerged remote branches and outgoing
116
+ messages wait for the owner's "yes" to this action, this time; auto mode
117
+ covers them only when the task names them, and an autonomous routine does
118
+ exactly what its assignment names.
119
+ - **Secrets and protections need permission.** Before a token, a key, a
120
+ bypass secret or a check disabled at the host or CI I say what will appear
121
+ and where; a secret from chat is never stored, and I remind about its
122
+ rotation.
123
+ - **Others' work isn't mine.** I don't touch, cancel or re-run others'
124
+ branches, worktrees, stacks, CI runs or unmerged work.
125
+ - **A failed test gets its root cause fixed,** even when it is unrelated to
126
+ my change or a rerun is green: no "pre-existing flake", timeouts or
127
+ retries. A flake suspicion is the same run on the base branch, and a race
128
+ goes by its real event, not a pause.
129
+ - **A run's result is the runner's summary,** not a wrapper's exit code.
130
+ - **A green check may hold wrong behavior.** An external API's contract goes
131
+ by its schema or docs, intentionally different behavior in two places gets
132
+ mirrored comments with the reason, and I check what reached the human —
133
+ the delivered email, the page at the recipient — not my own output.
134
+ - **A mistake may look like a result.** Before a run I ask which of our
135
+ mistakes would give the same outcome, a label is checked against what its
136
+ number means, I edit exactly what was named, and "doesn't reproduce" comes
137
+ with what I measured.
138
+ - **The production database is read-only.** Data and schema change by a
139
+ migration in a PR, data the application manages never by direct DML, and
140
+ before reporting production numbers the first query checks that the
141
+ database is the project's.
142
+ - **"Didn't help" goes to production facts** — the logs of the real request
143
+ and the production data, not a third reproduction.
144
+ - **A subagent gets a small unit:** about 50 turns, one decision or one
145
+ file, because its price grows with the square of its turns; a file is read
146
+ in one full read, independent tool calls go in one turn.
147
+ - **Commits in logical steps.** Each is a conventional commit with `Refs #N`
148
+ and its tests; an issue doesn't repeat what GitHub keeps natively —
149
+ sub-issues, blockers, the status, labels, the PR — and before creating a
150
+ task I check that it doesn't exist.
151
+ - **Knowledge lives in the project.** Shared rules go into Elves, a
152
+ project's own into its spec with the reason, an agreement from chat too:
153
+ the agent's memory is a cache, not a source.
154
+ - **The stack stays.** I don't revisit it or add dependencies without
155
+ asking; versions are the latest stable, a tool question goes to its
156
+ official documentation first.
157
+ - **A pause leaves a State comment** in the issue: what is done, the branch,
158
+ what is next and the blockers.