rh-cli 0.1.0__py3-none-any.whl

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.
rh/search.py ADDED
@@ -0,0 +1,123 @@
1
+ """Local search over .rh/ + SKILL.md artifacts. No indexing.
2
+
3
+ Uses rg when available (fast, gitignore-aware), falls back to a pure-Python
4
+ scan. Structures files with anchors so `rh add` grouping helps retrieval.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import re
9
+ import shutil
10
+ import subprocess
11
+ from dataclasses import dataclass, field
12
+ from pathlib import Path
13
+
14
+ from . import paths
15
+
16
+ SEARCHABLE_SUFFIXES = {".md", ".txt", ".json", ".bib", ".tex"}
17
+ SEARCHABLE_NAMES = {"ENV.md", "PROBLEM.md", "PLAN.md", "STATUS.md", "LITERATURE.md",
18
+ "OUTPUT_LAYOUT.md", "GAPS.md", "MANUSCRIPT.md", "tasks.json", "env.json"}
19
+
20
+
21
+ @dataclass
22
+ class Hit:
23
+ path: Path
24
+ line_no: int
25
+ line: str
26
+ context: list[str] = field(default_factory=list)
27
+
28
+ def render(self, root: Path, width: int = 100) -> str:
29
+ try:
30
+ rel = self.path.relative_to(root)
31
+ except ValueError:
32
+ rel = self.path
33
+ snippet = self.line.strip()
34
+ if len(snippet) > width:
35
+ snippet = snippet[: width - 1] + "…"
36
+ out = [f"{rel}:{self.line_no} {snippet}"]
37
+ for ctx in self.context:
38
+ out.append(f" {ctx.strip()[:width]}")
39
+ return "\n".join(out)
40
+
41
+
42
+ def candidate_files(root: Path) -> list[Path]:
43
+ files: list[Path] = []
44
+ rh = paths.rh_dir(root)
45
+ if rh.exists():
46
+ for p in rh.rglob("*"):
47
+ if p.is_file() and p.suffix in SEARCHABLE_SUFFIXES:
48
+ files.append(p)
49
+ for name in SEARCHABLE_NAMES - {"tasks.json", "env.json"}:
50
+ for base in (root, rh):
51
+ p = base / name
52
+ if p.exists():
53
+ files.append(p)
54
+ for sub in ("src", "results"):
55
+ d = root / sub
56
+ if d.exists():
57
+ for p in d.rglob("*"):
58
+ if p.is_file() and p.suffix in SEARCHABLE_SUFFIXES:
59
+ files.append(p)
60
+ # dedupe, stable order
61
+ seen, out = set(), []
62
+ for f in files:
63
+ key = str(f.resolve()) if f.exists() else str(f)
64
+ if key not in seen:
65
+ seen.add(key)
66
+ out.append(f)
67
+ return out
68
+
69
+
70
+ def search_rg(root: Path, query: str, *, smart_case: bool = True, max_hits: int = 50) -> list[Hit]:
71
+ files = candidate_files(root)
72
+ if not files:
73
+ return []
74
+ cmd = ["rg", "--no-heading", "--line-number", "--with-filename"]
75
+ if smart_case:
76
+ cmd.append("--smart-case")
77
+ else:
78
+ cmd.append("--ignore-case")
79
+ cmd += ["-e", query, "--", *[str(f) for f in files]]
80
+ try:
81
+ proc = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
82
+ except (subprocess.TimeoutExpired, FileNotFoundError):
83
+ return []
84
+ hits: list[Hit] = []
85
+ if proc.returncode not in (0, 1): # 1 = no matches
86
+ return []
87
+ for line in proc.stdout.splitlines()[:max_hits]:
88
+ parts = line.split(":", 2)
89
+ if len(parts) < 3:
90
+ continue
91
+ fpath, lno, text = parts
92
+ try:
93
+ hits.append(Hit(Path(fpath), int(lno), text))
94
+ except ValueError:
95
+ continue
96
+ return hits
97
+
98
+
99
+ def search_python(root: Path, query: str, *, max_hits: int = 50) -> list[Hit]:
100
+ pattern = re.compile(re.escape(query), re.IGNORECASE)
101
+ hits: list[Hit] = []
102
+ for f in candidate_files(root):
103
+ try:
104
+ lines = f.read_text(encoding="utf-8", errors="ignore").splitlines()
105
+ except OSError:
106
+ continue
107
+ heading = ""
108
+ for i, line in enumerate(lines, 1):
109
+ if line.startswith("#"):
110
+ heading = line
111
+ if pattern.search(line):
112
+ ctx = [heading] if heading and heading not in line else []
113
+ hits.append(Hit(f, i, line, ctx))
114
+ if len(hits) >= max_hits:
115
+ return hits
116
+ return hits
117
+
118
+
119
+ def search(root: Path, query: str, *, max_hits: int = 50) -> tuple[list[Hit], str]:
120
+ """Return (hits, engine). Engine is 'rg' or 'python'."""
121
+ if shutil.which("rg"):
122
+ return search_rg(root, query, max_hits=max_hits), "rg"
123
+ return search_python(root, query, max_hits=max_hits), "python"
@@ -0,0 +1,497 @@
1
+ ---
2
+ name: research-helper
3
+ description: Orchestrate a research project end to end — intake, environment setup, literature survey, dual-model planning, implementation with adversarial review, critique gate, manuscript, close — driven by an ENV.md in the project root that holds the config block (agent count, per-role models, literature tooling, approval gates) and the environment notes. Use when the user wants to scope a research question, survey literature, build and test an experiment, or write it up.
4
+ ---
5
+
6
+ # Research Helper
7
+
8
+ A research project is a pipeline of phases with hard gates. This skill defines the
9
+ phases, who owns each artifact, what must be true to leave a phase, and what the
10
+ Orchestrator must ask the user instead of deciding alone.
11
+
12
+ Nothing here is advisory. If a rule cannot be followed, stop and ask.
13
+
14
+ ---
15
+
16
+ ## 0. Non-negotiables
17
+
18
+ 1. **The current runner is always the Orchestrator.** Whoever loaded this skill is the head.
19
+ 2. **Never choose a model.** Agent count and every role's model live in the config block at
20
+ the top of `ENV.md`. To change them, the user asks the Orchestrator to edit that block.
21
+ 3. **Ask before every state-changing action.** See §6.
22
+ 4. **No empty placeholder files.** Every artifact is created when it first has content.
23
+ 5. **No silent scope change.** Anything not in an approved `PLAN.md` needs approval first.
24
+ 6. **Never substitute a reference.** Paywalled paper → ask the user for the PDF by DOI.
25
+ 7. **No result without a file.** A number that is not in `results/` with the script that
26
+ produced it does not exist and may not appear in `MANUSCRIPT.md`.
27
+ 8. **"Done" requires proof.** Tests green, plan steps checked, Critique has zero open
28
+ blocking questions. Claims without evidence are rework.
29
+ 9. **`STATUS.md` is truth.** Update it after every step and before every question to the user.
30
+ 10. **Re-read the `ENV.md` config block at the start of every phase.** Never cache it. The
31
+ environment notes below it are re-read too — a version recorded in phase 2 may have moved.
32
+ 11. **The user may waive a rule.** A waiver is not silent: name it in `STATUS.md` history with
33
+ the rule number and in the manuscript's limitations. Without one, an unmet rule stops
34
+ the phase.
35
+
36
+ ---
37
+
38
+ ## 1. Where things live
39
+
40
+ One location for all state: the **project root**, chosen by the user in phase 0. The skill
41
+ directory holds no config and no project data — this file is the whole skill.
42
+
43
+ Inside the project root:
44
+
45
+ ```
46
+ <project root>/
47
+ PROBLEM.md goal, scope, success criteria, falsifier Orchestrator phase 1
48
+ ENV.md config block (phase 0) + environment notes Orchestrator phase 0/2
49
+ PLAN.md approved step list (links ENV.md for tooling) Planners phase 4
50
+ STATUS.md current state, roster, blockers, open questions Orchestrator phase 5+
51
+ LITERATURE.md what we took from each paper, with citations Literature phase 3
52
+ OUTPUT_LAYOUT.md output skeleton the user asked for + the patterns Lit/Researcher phase 3+
53
+ comparable papers follow (sections, equations, figures, emphasis) Writer follows
54
+ GAPS.md implementation sourcing + upstream gaps Lit/Researcher phase 3+
55
+ MANUSCRIPT.md write-up Writer phase 8
56
+ papers/ downloaded PDFs, named <firstauthor><year>_<slug>.pdf
57
+ logs/ event logs, see §7
58
+ src/ implementation
59
+ results/ every produced number, table, figure + the script that made it
60
+ ```
61
+
62
+ Artifacts are created on first write, in the phase that first needs them. If a phase is
63
+ skipped with the user's agreement, its artifact simply never exists — that is allowed;
64
+ an empty file is not.
65
+
66
+ The `rh` CLI (§10) keeps a machine-readable mirror of this state under `.rh/`
67
+ (`env.json`, `tasks.json`, `logs/`, `notes/`, `workflow.mmd`) — the artifacts
68
+ above remain the truth; `.rh/` is derived display state, with the single
69
+ exception that `rh env set` writes ENV.md itself.
70
+
71
+ ---
72
+
73
+ ## 2. `ENV.md` — config block
74
+
75
+ Location: `<project root>/ENV.md`. The `jsonc` block at its top is the only config in this
76
+ system; there is no separate config file and nothing config-like lives in the skill
77
+ directory. If the block is absent or unparseable, run phase 0. Never hand-edit it silently;
78
+ propose a diff, get approval, then write. Phase 2 appends the environment notes below the block.
79
+
80
+ Ask the user each key (batch only unrelated ones). Offer only what the user actually names
81
+ or confirms — never invent model or tool names, and never infer them from what happens to be
82
+ installed on the machine. A binary on PATH does not mean this project should use it.
83
+
84
+ ```jsonc
85
+ {
86
+ "agents": {
87
+ "count": 1, // how many agents may run at once, 1..4
88
+ "backend": "tmux", // tmux | herdr | tuios | none (none = no panes, serial)
89
+ "roles": {
90
+ // provider+model per role; the Orchestrator slot must be
91
+ "orchestrator": {}, // the model actually running this session
92
+ "literature": {},
93
+ "researcher": {},
94
+ "reviewer": {},
95
+ "critique": {},
96
+ "writer": {},
97
+ },
98
+ "planners": {
99
+ // the two independent planners in phase 4
100
+ "models": [{}, {}], // must be different models
101
+ "max_rounds": 0, // 0 = cap at 3 rounds, then escalate with the split
102
+ },
103
+ },
104
+ "literature": {
105
+ "ref_manager": "zot", // user-named tool, e.g. zot | bibtex | none
106
+ "reading": "lit", // user-named reader, e.g. lit | pdftotext | images
107
+ "paywall": "ask_user", // ask_user | skip (skip = proceed without that paper)
108
+ "search": "crw", // user-named search tool; any binary or service is valid
109
+ },
110
+ "project": {
111
+ "slug": "", // short kebab-case name
112
+ "git": false, // true only if user says the project is already a repo
113
+ },
114
+ "gates": {
115
+ "user_approves_plan": true,
116
+ "critique_veto": true,
117
+ },
118
+ }
119
+ ```
120
+
121
+ Interview order (batch 2–3 unrelated keys per question; show the resulting block before
122
+ moving on): project root → slug → agent count → backend → per-role models → planner models →
123
+ search/browse tool → reference manager → reading method → paywall policy → git → confirm
124
+ gates. The root is never stored: it is the directory `ENV.md` sits in.
125
+
126
+ ---
127
+
128
+ ## 3. Phase pipeline
129
+
130
+ ```
131
+ 0 CONFIG → 1 INTAKE → 2 ENVIRONMENT → 3 LITERATURE → 4 PLAN → 5 STATE
132
+ → 6 IMPLEMENT → 7 CRITIQUE → 8 MANUSCRIPT → 9 CLOSE
133
+ ↑ │
134
+ └── replan ──┘ (verdicts go back to 3, 4 or 6)
135
+ ```
136
+
137
+ Every phase states its **exit gate**. Do not enter the next phase with an unmet gate.
138
+
139
+ ### Phase 0 — CONFIG → `ENV.md` config block
140
+
141
+ Ask for the project root, then load `<root>/ENV.md`; if absent or its config block does not
142
+ parse, interview and write the block. Print it and get a yes. Exit gate: the block parses,
143
+ the user confirmed, and the file sits in the root the user named.
144
+
145
+ ### Phase 1 — INTAKE → `PROBLEM.md`
146
+
147
+ Ask, do not assume: research question in one sentence; why it matters; what would count
148
+ as success; what would **falsify** the result; constraints (time, hardware, data licence);
149
+ explicitly out of scope. Exit gate: `PROBLEM.md` has all six sections and the user has read
150
+ it back to the Orchestrator in their own words or approved it.
151
+
152
+ ### Phase 2 — ENVIRONMENT → `ENV.md` environment notes, under the config block
153
+
154
+ Interview the user; do not probe. Ask which runtimes, packages, simulators, solvers, GPU
155
+ stack and CLI tools this project will actually use, and which versions they expect. Record
156
+ what the user names in an `## Environment` section below the config block — including tools
157
+ the CLI has never heard of. Never run `command -v` to decide the environment: a binary being
158
+ installed says nothing about whether this project should use it.
159
+
160
+ This section is the source for the manuscript's methods section — never re-type versions
161
+ later, and amend it later only with a dated note.
162
+
163
+ Exit gate: the user has named the tools and versions for every part of the phase-1 scope,
164
+ and the `## Environment` section records them. Unknown or user-named tools are valid.
165
+
166
+ ### Phase 3 — LITERATURE → `papers/`, `LITERATURE.md`, `OUTPUT_LAYOUT.md`, `GAPS.md`
167
+
168
+ Survey with the `literature.search` tool (finding, fetching) and read with
169
+ `literature.reading`. For every paper that survives reading, `LITERATURE.md` gets:
170
+ citation, DOI/URL, one-paragraph relevance, exactly what we take (method, number,
171
+ parameter), what we reject and why, and page/section anchors. Anything useful noticed
172
+ mid-read — a method, a number, a parameter, a dataset, a tool, an author to contact — gets
173
+ its own line with that paper's DOI even when the paper is rejected, because a finding
174
+ without its DOI cannot be cited later and will be lost.
175
+
176
+ `OUTPUT_LAYOUT.md` is written while reading, not afterwards. The Literature agent decides it
177
+ from what the user asked for — a manuscript, a report, a letter — and asks if the output is
178
+ unclear; never impose a paper structure the user did not want. Literature owns the file; the
179
+ Researcher appends whenever it reads a paper or source repo mid-implementation. It holds
180
+ **exactly one layout** (ours) plus the notes that justify it. For every paper that survives
181
+ reading, add one row: DOI, what to copy or avoid, the equations it uses (form and where they
182
+ appear), the figures/images it produces (what they show, axes, units), how it explains (what
183
+ is emphasised first, intuition vs derivation, how much space), and what it conspicuously
184
+ never shows (no error bars, no baseline, no uncertainty). Keep a running tally at the top —
185
+ it is the evidence for "every paper in this field does X". Never transcribe several papers'
186
+ layouts side by side; a note either changes the single layout or stays a note, and every
187
+ layout edit names the paper that drove it. The layout is the output's skeleton: one entry per
188
+ section naming its heading, topics, equations, figures/tables with axes and units, and the
189
+ source of every number. If the deliverable is not a manuscript or report, say so and this
190
+ file may not exist.
191
+
192
+ `GAPS.md` records implementation sourcing: repo or paper, licence, what we borrow, what the
193
+ source is missing, who to credit, and whether an upstream fix/PR is warranted. While
194
+ reading a source's code, anything suspicious goes to the Orchestrator or Critique, not into
195
+ the implementation.
196
+
197
+ Paywall: ask the user for the PDF by DOI. With a `ref_manager` it goes into that collection,
198
+ which is then authoritative and `papers/` holds only unmanaged PDFs; otherwise it goes into
199
+ `papers/`. If they cannot get it, continue with what exists — never swap in a different
200
+ paper, never paraphrase a paper you have not read. Absences are recorded in
201
+ `LITERATURE.md` under "not obtained".
202
+
203
+ Exit gate: the question in `PROBLEM.md` is either addressed by existing work (say so, and
204
+ stop or re-scope with the user) or has a named gap we can attack; when the output is a
205
+ manuscript or report, `OUTPUT_LAYOUT.md` has a pattern tally over every paper read and
206
+ exactly one layout.
207
+
208
+ ### Phase 4 — PLAN → `PLAN.md`
209
+
210
+ Two planners on different models plan **independently** (no shared transcript), each
211
+ writing its own candidate plan. Then they argue directly with each other: defend, concede,
212
+ or counter. Planners run one after the other, so they are exempt from the `agents.count`
213
+ concurrency budget (§5). `planners.max_rounds = 0` means three rounds; past that, record the
214
+ unresolved split in `PLAN.md` and ask the user — never keep arguing on the user's credits.
215
+ Every round is logged (§7).
216
+
217
+ The merged `PLAN.md` is ordered steps, each with: id, action, owner role, deliverable file,
218
+ **verification command or check**, dependencies on other steps, and estimated risk. Plus the
219
+ tooling table from `ENV.md` (link it, never copy it). Steps that are pure research (unknown
220
+ feasibility) are marked `spike` and carry a `timebox`.
221
+
222
+ Exit gate: both planners state agreement in `PLAN.md` ("agreed by <model> / <model> on
223
+ <date>"), and the user approves the plan (`gates.user_approves_plan`). No implementation
224
+ before that yes.
225
+
226
+ ### Phase 5 — STATE → `STATUS.md`, `logs/`
227
+
228
+ `STATUS.md` holds: current phase and step id, agent roster (role → model → backend window),
229
+ blockers, open questions aimed at the user, and a timestamped one-line change history.
230
+ Every step transition edits it. Exit gate: it accurately describes reality (re-read and
231
+ check before answering any "where are we" question).
232
+
233
+ ### Phase 6 — IMPLEMENT → `src/`, `results/`
234
+
235
+ Researcher implements step by step. Move in small steps: implement → test → record result →
236
+ tick the plan step. If `agents.count >= 2`, the tests are written by a different context
237
+ than the implementer (the second agent); otherwise the Reviewer hat writes them and the
238
+ Researcher may not edit them to pass.
239
+
240
+ Tests are the contract: a step is done when its plan verification command succeeds and its
241
+ output lands in `results/` with the generating script, the exact command, the seed and the
242
+ date. Bugs are fixed at the root cause once, not patched at call sites.
243
+
244
+ Anything not in the approved plan — new dependency, new experiment, scope drift — stops and
245
+ asks. Drastic changes never happen on the agent's own initiative.
246
+
247
+ Exit gate: all plan steps (except open `spike`s) checked, full test suite green, `results/`
248
+ reproduces from a clean run.
249
+
250
+ ### Phase 7 — CRITIQUE → verdict in `STATUS.md` + `logs/`
251
+
252
+ Critique writes numbered must-answer questions against the actual artifacts (not the plan's
253
+ intentions): why this baseline, why this parameter, does the claim follow from the data,
254
+ what breaks under load/edge cases, what was never tested, what would a hostile reviewer say.
255
+ Each question gets an answer with evidence (file path, command, number) or is closed as
256
+ `non-blocking` by the user.
257
+
258
+ Any blocking question → return to phase 6 to fix, and to phase 4 if the answer changes
259
+ scope. Then re-run Critique on the changed parts only.
260
+
261
+ Exit gate: zero open blocking questions. With `gates.critique_veto` true, Critique can
262
+ refuse this gate; its refusal names the specific questions.
263
+
264
+ ### Phase 8 — MANUSCRIPT → `MANUSCRIPT.md`
265
+
266
+ Writer drafts from artifacts only: methods cite the `ENV.md` versions, every claim traces to
267
+ a `results/` file or a `LITERATURE.md` entry, every borrowed implementation is attributed
268
+ via `GAPS.md`. Setup comes from the single layout in `OUTPUT_LAYOUT.md`: open `MANUSCRIPT.md`
269
+ with those headings in that order, carrying the listed topics, equations and figures. If the
270
+ layout is wrong, fix `OUTPUT_LAYOUT.md` first and say why. Reviewer pass checks
271
+ claim↔evidence, number↔table, and section↔layout drift; Critique signs off. Missing evidence
272
+ is a hard stop — delete the claim, never soften it.
273
+
274
+ Exit gate: every claim has an evidence line, no number↔source mismatch remains, Critique has
275
+ signed off.
276
+
277
+ ### Phase 9 — CLOSE
278
+
279
+ Finalize `STATUS.md` (all steps checked, tests green, gate closed), write one log with
280
+ lessons and dead ends, list what is reusable next time, and state what was left undone.
281
+ Ask whether to push (`project.git`) — never push unasked.
282
+
283
+ Exit gate: `STATUS.md` shows every step checked and the suite green, the close log exists,
284
+ and the push question has been answered.
285
+
286
+ ---
287
+
288
+ ## 4. Replanning
289
+
290
+ Replanning is normal, not failure. Triggers: Critique blocking questions, a `spike` that
291
+ proves infeasible, literature that invalidates an assumption, a failed reproduction, or a
292
+ user change of direction.
293
+
294
+ The Orchestrator writes the proposed diff to `PLAN.md` (added / removed / reordered steps
295
+ with the reason), gets user approval, then edits. The user is always the decider here.
296
+ Never quietly rewrite the plan to match what was already built.
297
+
298
+ ---
299
+
300
+ ## 5. Roles
301
+
302
+ | Role | Owns | May | May not |
303
+ | ------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
304
+ | **Orchestrator** (the current runner) | routing, `STATUS.md`, `PLAN.md` merges, all user questions | delegate, gate, escalate, edit artifacts | implement, fix code, approve its own plan, pick models |
305
+ | **Literature** | `papers/`, `LITERATURE.md`, `OUTPUT_LAYOUT.md`, `GAPS.md` | download open-access, read, cite, decide the layout from the user's requested output, flag code smells in sources | paraphrase unread papers, substitute references, change the plan |
306
+ | **Researcher** | `src/`, `results/` | implement, test, probe tools, append to `OUTPUT_LAYOUT.md` from papers/repos it reads, ask for guidance | change scope, delete user files, install system packages, edit tests to pass |
307
+ | **Reviewer** | review verdicts | read everything, file findings, demand evidence | fix what it finds (independence is the point) |
308
+ | **Critique** | blocking-question list, veto | question anything, block a gate, demand falsification | implement, soften its own findings |
309
+ | **Writer** | `MANUSCRIPT.md` | draft, restructure, cite from artifacts | introduce evidence not in `results/` or `LITERATURE.md` |
310
+
311
+ **Agent budget mapping.** The Orchestrator wears every hat not given its own agent:
312
+
313
+ | `agents.count` | Separate agents | Hats worn by Orchestrator |
314
+ | -------------- | ------------------------------ | -------------------------------------------------- |
315
+ | 1 | — | Literature, Researcher, Reviewer, Critique, Writer |
316
+ | 2 | Researcher | Literature, Reviewer, Critique, Writer |
317
+ | 3 | Researcher, Critique | Literature, Reviewer, Writer |
318
+ | 4 | Researcher, Critique, Reviewer | Literature, Writer |
319
+
320
+ Critique gets its own agent from count 3 up because veto power needs an independent context.
321
+ When a hat's work would be reviewed by the same context that did the work, say so in
322
+ `STATUS.md` — the user must know a review was not independent.
323
+
324
+ Spawn agents with `agents.backend` (`tmux new-window`, `herdr`, `tuios`; see those skills).
325
+ Record each spawn in `STATUS.md`. Confirm count and models with the user before spawning if
326
+ anything differs from the `ENV.md` config block.
327
+
328
+ ---
329
+
330
+ ## 6. Ask-before list
331
+
332
+ Free without asking: reading, searching, writing the skill's own artifacts, running tests,
333
+ downloading open-access papers, spawning agents up to `agents.count` with the `ENV.md` models.
334
+
335
+ Ask first, every time: installing system packages or new dependencies, deleting or
336
+ overwriting any file the skill did not create, exceeding `agents.count` or changing a model,
337
+ buying/borrowing anything behind a paywall, changing `PLAN.md` after approval, rewriting
338
+ `GAPS.md` sourcing decisions, any `git push` or history rewrite, anything irreversible or
339
+ outward-facing.
340
+
341
+ When asking: state the action, why it is needed, the blast radius, and the alternative.
342
+
343
+ ---
344
+
345
+ ## 7. Log policy
346
+
347
+ Log only when something must be remembered — a decision, a dead end, a failed run, a plan
348
+ change, a user override. Routine success is not logged; the artifacts already show it.
349
+
350
+ `logs/YYYY-MM-DD-HHMM-<role>-<slug>.md`:
351
+
352
+ ```
353
+ # <title>
354
+ - phase / step:
355
+ - what was tried:
356
+ - outcome: worked | failed | partial
357
+ - evidence: <command, file, number>
358
+ - decision taken + why:
359
+ - what a future agent must not redo:
360
+ ```
361
+
362
+ ---
363
+
364
+ ## 8. Templates
365
+
366
+ `ENV.md` — the config block from §2 on top, then the environment notes the Orchestrator
367
+ writes after asking (free-form; any tool the user names is valid):
368
+
369
+ ```
370
+ ## Environment
371
+
372
+ - meep 1.29.0 — FDTD, 2D/3D (user-confirmed)
373
+ - jax — not used; the user prefers numpy on this machine
374
+ - custom solver "foo" 2.0 — user-named, not on PATH
375
+ ```
376
+
377
+ `STATUS.md`
378
+
379
+ ```
380
+ # Status — <project slug>
381
+ phase: 6 IMPLEMENT | step: S07 | updated: <ISO timestamp>
382
+ agents: orchestrator=<model> researcher=<model> (backend: tmux window 2)
383
+ blockers: none
384
+ open questions for user: (numbered, each answerable in one line)
385
+ history:
386
+ - <ISO> S06 done, tests green (24 passed), results/S06.csv
387
+ ```
388
+
389
+ `OUTPUT_LAYOUT.md`
390
+
391
+ ```
392
+ # Output layout — <manuscript | report | ...>
393
+
394
+ Target: <what the user asked for> | Venue/audience: <if named> | Length: <target>
395
+
396
+ ## Patterns in comparable papers
397
+ | pattern | papers | count | note |
398
+ |---|---|---|---|
399
+ | setup schematic as Fig 1 | A, B, D | 3 | left-to-right, labelled a–d |
400
+ | governing equation before results | A, C | 2 | Eq. 1, in Methods |
401
+ | measured vs simulated curve | A, B, C, D | 4 | log y, dB |
402
+ | comparison table vs prior work | B, C | 2 | includes our metric |
403
+ | uncertainty stated | D | 1 | the rest omit it |
404
+ | explanation emphasis | A, B | 2 | physical intuition before math |
405
+
406
+ ## Per paper
407
+ | paper (DOI) | copy / avoid | equations (form, placement) | figures / images (what, axes, units) | explanation emphasis | never shows |
408
+ |---|---|---|---|---|---|
409
+ | 10.1234/abcd | theory before sim; clean Fig 1 | Eq. 1: <form>, in Methods | Fig 1 schematic; Fig 2 <x> vs <y> (nm, dB) | intuition first, then derivation | error bars, baseline |
410
+
411
+ ## Our layout (single, edited in place)
412
+ ### 1 <Section heading>
413
+ - purpose: <what this section must establish>
414
+ - topics: <point 1>; <point 2>; <what must be stated explicitly>
415
+ - equations: <Eq. n — form — where it comes from>
416
+ - figures/tables: Fig 1 <what> (axes/units) — data: <results/file>
417
+ - evidence: <results/S05.csv | 10.1234/abcd §3> | changed by: <paper DOI, if this was driven by one>
418
+ - status: <have data | data missing → step>
419
+ ### 2 <...>
420
+ ...
421
+ ```
422
+
423
+ Every note above is either folded into this one layout or left as a note. Two layouts in the
424
+ file is a defect.
425
+
426
+ `PLAN.md` step
427
+
428
+ ```
429
+ ### S07 — <action>
430
+ owner: researcher | deliverable: results/S07.csv
431
+ verify: `uv run pytest tests/test_s07.py`
432
+ depends on: S05 | risk: <what could invalidate it> | kind: build | spike
433
+ timebox: 90m # only for kind: spike
434
+ ```
435
+
436
+ ---
437
+
438
+ ## 9. Anti-patterns
439
+
440
+ - Planning before reading the literature, then rewriting `PLAN.md` to fit what got built.
441
+ - A plan approved by the Orchestrator alone, or by nobody.
442
+ - A rule counted as met because an agent said so, not because a command or a file shows it.
443
+
444
+ ---
445
+
446
+ ## 10. The `rh` CLI — the machine layer for this skill
447
+
448
+ `rh` (installed from the skill's sibling `cli/` package) is the machine-readable
449
+ layer for everything above. It never replaces the artifacts or decides anything:
450
+ artifacts stay the truth, `rh` displays, validates, and mirrors them. Its state
451
+ lives in `.rh/` at the project root:
452
+
453
+ ```
454
+ .rh/
455
+ env.json machine mirror of the ENV.md config block (written by rh env set)
456
+ tasks.json task board: phases + steps + subtasks, states idle|working|complete
457
+ logs/ papers/ notes/ tmp/
458
+ workflow.mmd the project workflow diagram — AUTHORED by the Orchestrator
459
+ or Researcher (see below); `rh workflow` only displays it
460
+ ```
461
+
462
+ Commands agents use per phase:
463
+
464
+ | Command | Phase | Notes |
465
+ |---|---|---|
466
+ | `rh init --slug NAME` | 0 | creates the `.rh/` layout; config is still asked per §2 |
467
+ | `rh env show` / `env list` | 0–2 | read and validate the config block + environment notes |
468
+ | `rh env set KEY=VALUE ...` | 0 | writes ENV.md's block **and** the `.rh/env.json` mirror; preserves the notes below it |
469
+ | `rh add note\|literature\|gaps\|log <h> -m "..."` | 3+ | appends under a heading, creating it if missing; literature accepts a DOI |
470
+ | `rh search <query>` | any | rg-first local search over `.rh/` + artifacts, no indexing |
471
+ | `rh add task / plan import` | 4–6 | mirrors PLAN.md steps into the board (`rh plan import`) |
472
+ | `rh task set <id> idle\|working\|complete` | 5–6 | board state; `rh tasks` / `rh status` display it |
473
+ | `rh phase <0-9>` | any | **gated**: refuses to advance past unmet exit gates; `--force` is a waiver → record it in STATUS.md (rule 11) |
474
+ | `rh resume` / `rh -r` | any | opens the agent harness as the Orchestrator with a go-forward prompt (skill loaded). If backend/agent CLI are unset it asks in the CLI. Pane/spawn bookkeeping is still the Orchestrator's job (§5) |
475
+ | `rh workflow` | 4+ | displays `.rh/workflow.mmd` as ASCII (renderer-dependent); `--tools` lists renderers; `--example` prints a starter source |
476
+
477
+ Contracts that keep the two layers consistent:
478
+
479
+ 1. **`workflow.mmd` is agent-authored.** The Orchestrator or Researcher creates
480
+ or updates it when the plan changes (the PLAN.md step DAG with dependencies
481
+ and current position), shaped for the renderers available (`rh workflow
482
+ --tools`). `rh workflow` displays it as ASCII when a local renderer is
483
+ installed and can render `--png`/`--svg` artifacts. If no renderer is
484
+ installed, the CLI lists installation options and the USER picks (nothing
485
+ is ever downloaded or installed automatically — not even via `npx`); the
486
+ agent then writes the .mmd in the syntax the chosen renderer consumes.
487
+ The file is the contract, the CLI is only the viewer. **`rh` never creates
488
+ or overwrites `<root>/.rh/workflow.mmd`** (transient render sources live in
489
+ `.rh/tmp/`); when the file is absent the CLI reports the workflow as
490
+ pending and draws nothing.
491
+ 2. **`rh phase` enforces §3's hard gates, but the artifacts it checks are the
492
+ gate.** Passing the CLI check is not an exit gate by itself; the user
493
+ confirmation, planner agreement, and critique sign-off still happen per §3.
494
+ 3. **The board mirrors the plan, not the reverse.** `rh plan import` reads
495
+ PLAN.md; replanning (§4) updates PLAN.md first, then re-imports. STATUS.md
496
+ remains the truth (rule 9) — the board is display state for `rh tasks`.
497
+ 4. **`--json` works on every command** for agent reads; never parse the pretty UI.