@miroshnik/elves 2026.1113.0 → 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.
- package/.claude-plugin/plugin.json +8 -0
- package/AGENTS.md +134 -289
- package/README.md +36 -71
- package/agents/executor.md +22 -0
- package/bin/elves.ts +506 -284
- package/claude/CLAUDE.md +40 -68
- package/dist/github/scripts/github.js +1365 -618
- package/dist/spec/scripts/architecture.js +2 -2
- package/dist/spec/scripts/{harness-yh1g3dhm.js → harness-7780cv0k.js} +1 -1
- package/dist/spec/scripts/{harness-1rfkbdbn.js → harness-efesfpam.js} +9 -131
- package/dist/spec/scripts/harness.js +1 -1
- package/docs/ci-concurrency.md +8 -3
- package/docs/installation.md +14 -12
- package/docs/other-agents.md +19 -0
- package/docs/parallel-checkouts.md +24 -16
- package/docs/prompt-cache.md +1 -1
- package/docs/testing.md +22 -10
- package/hooks/hooks.json +47 -0
- package/package.json +8 -6
- package/skills/ci-wait/SKILL.md +8 -9
- package/{docs/pr-checks.md → skills/ci-wait/reference.md} +29 -34
- package/skills/ci-wait/scripts/wait-ci.sh +13 -1
- package/skills/est/SKILL.md +56 -107
- package/skills/est/reference.md +60 -151
- package/skills/est/scripts/est.ts +686 -1409
- package/skills/github/SKILL.md +60 -69
- package/skills/github/locales/en.json +4 -65
- package/skills/github/locales/ru.json +4 -65
- package/skills/github/reference.md +542 -465
- package/skills/github/scripts/bypasses.ts +47 -0
- package/skills/github/scripts/command.ts +40 -0
- package/skills/github/scripts/github.ts +1559 -780
- package/skills/github/scripts/locale.ts +12 -54
- package/skills/github/scripts/queue.ts +338 -0
- package/skills/slot/SKILL.md +1 -1
- package/skills/spec/SKILL.md +17 -13
- package/skills/spec/canon.md +14 -5
- package/skills/spec/ci.md +74 -47
- package/skills/spec/migration.md +2 -1
- package/skills/spec/reference.md +66 -14
- package/skills/spec/scripts/spec-diff.ts +17 -3
- package/skills/spec/scripts/spec-red.ts +337 -0
- package/skills/spec/scripts/spec-run.ts +10 -2
- package/skills/spec/scripts/speclib.ts +66 -16
- package/skills/task-env/SKILL.md +2 -8
- package/skills/task-env/proxy/compose.yaml +0 -11
- package/skills/task-env/reference.md +5 -20
- package/skills/task-env/scripts/task-env.ts +1 -83
- package/docs/cloud-sessions.md +0 -206
- package/docs/judgment.md +0 -104
- package/docs/production.md +0 -15
- package/skills/dashboard/SKILL.md +0 -214
- package/skills/dashboard/scripts/dashboard.ts +0 -912
- 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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
and
|
|
47
|
-
|
|
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
|
-
- **
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
the
|
|
62
|
-
|
|
63
|
-
|
|
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
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
`
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
-
- **
|
|
187
|
-
a
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
`
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
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
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
may change without agreement
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
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
|
-
- **
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
- **
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
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.
|