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/__init__.py +12 -0
- rh/add.py +105 -0
- rh/cli.py +799 -0
- rh/config.py +308 -0
- rh/paths.py +96 -0
- rh/resume.py +186 -0
- rh/search.py +123 -0
- rh/skills/research-helper/SKILL.md +497 -0
- rh/tasks.py +221 -0
- rh/ui.py +128 -0
- rh/workflow.py +268 -0
- rh_cli-0.1.0.dist-info/METADATA +217 -0
- rh_cli-0.1.0.dist-info/RECORD +17 -0
- rh_cli-0.1.0.dist-info/WHEEL +5 -0
- rh_cli-0.1.0.dist-info/entry_points.txt +2 -0
- rh_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
- rh_cli-0.1.0.dist-info/top_level.txt +1 -0
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.
|