"the next agent was not in the room, sir"
You and today's agent have talked for an hour. The ten-line plan looks obvious because the missing context is still warm in both heads. Tomorrow's agent gets only the file.
James makes sure the file is enough.
He enters cold, works only from the project-owned evidence you declare, and finds the places where the current conversation never made it onto the page. He tidies what the evidence safely supports and returns missing decisions to the human. He will not widen the scope, invent an answer, or feature-creep the document just to earn a prettier score. James straightens the handoff; he does not remodel the product.
Install with the Skills CLI:
npx skills add AndreRatzenberger/jamesThe CLI detects supported agents and asks where to install the skill. Add -g
for a user-level installation. While this repository is private, GitHub access
to it is required.
James writes its recipe and raw review chain under ~/.james/ and may apply up
to three safe edit passes to the target document. It is not report-only unless
the user narrows the request to review-only.
James this plan before we hand it to the implementation agent.
Run $james on docs/architecture.md. It may use only that file.
Run $james on docs/post-release.md. Allowed context is docs/release-v1.md and
git history of docs/post-release.md before 2026-07-01.
Hosts that support implicit skill routing may activate James after an agent
materially writes or edits a planning artifact. Explicit $james invocation is
the portable path. James does not write the initial document.
Can a future agent understand and act on this document using only the allowed project-owned scope?
That constraint catches problems ordinary prose review misses:
- “as discussed” references with no local source
- terms that appear before definition
- acceptance criteria that are only vibes
- private paths and personal shorthand
- undeclared external dependencies
- missing authority, inputs, outputs, or success criteria
- plans that silently assume the author will remain available
James does not widen the scope to make a document pass. Missing context is the finding.
Both are useful. They are not doing the same job.
| Generic document reviewer | James | |
|---|---|---|
| Main question | How could this document be clearer, stronger, or more complete? | Can a future agent act using only the declared evidence? |
| Available context | Often free to use chat, memory, adjacent files, or outside research | Strictly limited to the project-owned scope you declare |
| Helpful additions | May suggest adjacent improvements, solutions, or new features | Never invents decisions or feature-creeps to make the review pass |
| Missing information | May resolve gaps from broader context | Keeps the gap visible and escalates it to the human |
| Output | Usually a report or edited draft | A persisted review chain plus bounded fix-and-review passes |
| Finish line | The document is improved | Explicit Passed: yes or a persisted escalation for the human |
A generic reviewer may propose a better house. James makes sure the next agent can enter this one, find the keys, and continue the work—without quietly adding a conservatory.
James does not leave behind “reviewed it, looks good.” He leaves a chain that shows what the reviewer knew, what failed, what changed, and why the final pass deserves belief.
| Artifact | What It Means |
|---|---|
recipe.md |
The evidence boundary: target, intent, allowed context, reviewer mode, and next review number. It is process memory, never secret product context. |
reviews/NNN-*.md |
Each raw cold review, preserved before any edit. Older reviews are never overwritten. |
fixes-NNN.md |
The exact attempted fixes between reviews, including which changes were safe clarifications and which required author authority. |
chain.md |
The ledger: score, explicit pass state, reviewer mode, and next action for every review. |
| Final report | The terminal state: final score, pass/fail, passes used, changes made, and unresolved human gates. |
The score is only diagnostic. 9/10 plus Passed: no is still a failure. The
receipts make that rule visible instead of letting a flattering number end the
review early.
The example starts from a cute idea: celebrate a finished task with a tiny
eight-second animal parade. The initial plan looked detailed. James still found
enough hidden implementation context to fail it at 5/10.
5/10, no → hashing, Unicode, timing, storage, tooling, and visual authority
8/10, no → clear-history race, base path, network boundary, visual oracle
9/10, no → static content root and fake "automated" appearance checks
10/10, yes → a future agent can finally act from the file alone
No new feature entered the plan during review. James clarified contracts, separated machine checks from human taste, and stopped only on explicit pass.
| Example Artifact | Read It For |
|---|---|
| Original request | The deliberately small creative brief. |
| Initial plan | What looked complete while the authoring context was still warm. |
| Final plan | The restartable artifact after three bounded edit passes. |
| Recipe | The exact file-only scope and reviewer contract. |
| Review chain | The persisted 5 → 8 → 9 → 10 progression and next actions. |
| Raw reviews: 1, 2, 3, 4 | Every issue exactly as the isolated reviewer returned it, including the terminal pass. |
| Fix attempts: 1, 2, 3 | Each bounded edit packet between reviews; no fourth edit pass exists. |
| Final report | Why the loop stopped and which future human release gate remains explicit. |
Machine-local paths and reviewer handles are sanitized in the checked-in example. The causal chain is intact; machine identity is not part of the proof.
declare scope
↓
cold review
↓
persist raw findings
↓
fix only evidence-safe issues
↓
re-review against the same boundary
↓
pass or escalate human decisions
The loop allows at most three edit passes after the initial review. Only an
explicit Passed: yes ends in a pass; the numeric score is diagnostic and never
overrides Passed: no. James does not invent product decisions to chase a
score.
Operational state stays outside the reviewed repository:
~/.james/<repo-slug>/<target-slug>/
recipe.md
chain.md
reviews/
001-initial.md
002-after-fixes.md
The recipe remembers process and scope. It is never allowed to smuggle missing product facts into the evidence boundary. Older reviews are append-only by workflow contract; James does not provide cryptographic tamper protection.
The recipe stores the project and target paths, declared scope, reviewer mode,
and possibly a reviewer handle; raw reviews may quote sensitive document text.
James does not automatically expire this state. Local files are plaintext and
inherit the operating system account and umask. Review them before sharing and
remove the matching ~/.james/<repo-slug>/<target-slug>/ tree when its
retention period ends. The host may send the target, allowed context, and saved
reviews to one or more model reviewer contexts; provider handling and retention
are governed by the host, not James. For example, docs/launch-plan.md in
acme-app uses ~/.james/acme-app/docs--launch-plan/.
repo-slug starts from the project-root basename. If an existing recipe under
that slug names a different normalized project root, James appends a short
root hash before writing so same-named repositories cannot share a chain. Root
canonicalization resolves symlinks and dot segments, uses an absolute path with
/ separators, and lowercases only a Windows drive letter. The SHA-256 suffix
starts at eight lowercase hex characters, extends four at a time on another
ownership collision, and fails closed if the full digest is occupied.
James adapts to the host without blurring the guarantee:
| Host capability | Behavior |
|---|---|
| Resumable isolated reviewer | Resume James and reset admissible evidence every call |
| Fresh isolated reviewer only | Rehydrate from the saved review chain |
| No isolated reviewer | Run a disclosed degraded local pass |
Only the first two provide an independent-review boundary.
James selects the strongest mode the host exposes: resumable reviewer first, fresh isolated reviewer second, and local review only as a disclosed fallback. “Independent” means the reviewing context did not author the document; it does not mean the stored files are cryptographically attested.
The standalone package is tested through clean-context review-loop scenarios, separate time, sunk-cost, and authority pressure runs, single-use held-outs, and routing checks against adjacent skills.
The curated record is in evidence/james-record.md,
with curated scenarios and routing summaries in
evidence/eval-fixtures.md. Raw outputs remain
local, so the checked-in evidence is a curated run record rather than a signed
transcript. The published run used two independent proxy judges because the
target host exposed no callable real dispatcher.
The reported counts are curator-attested summaries, not independently reproducible benchmark results. The fixtures disclose the scenarios, checks, and routing expectations; raw run outputs stay local.
- Not a code reviewer.
- Not an article editor or voice polisher.
- Not a general research summarizer.
- Not permission to invent missing business decisions.
- Not independent when the host cannot provide isolated context.
James protects the handoff, not the author's ego.
skills/james/ installable Agent Skill
example/ sanitized worked review chain
evidence/ curated graduation record
docs/assets/ repository artwork
MIT © 2026 Andre Ratzenberger