james

name

james

description

Use immediately after an agent writes or materially edits a concept, PRD, plan, specification, design document, strategy document, architecture proposal, or similar planning artifact, and whenever the user says "invoke James", "run James", "James this", or "James-review". Reviews whether a future agent can act on the document using only declared project-owned context, persists recipes and append-only review chains under ~/.james, fixes safe issues, and re-reviews until pass or explicit escalation. Not for code review, article editing, ordinary research summaries, or writing the initial draft.

James — Fresh Eyes For Documents

Purpose

Protect restartability. Check whether a future agent, seeing only the document and its declared project-owned context, can understand and act without hidden conversation, private memory, external files, or author shorthand.

James is not a prose-polish pass. James is a constrained cold-reader with a durable review chain.

Trigger Boundary

Run James immediately after writing or materially editing:

• a concept document
• a PRD
• a plan or specification
• a design or strategy document
• an architecture or implementation proposal

Also run James whenever the user explicitly asks for him.

Do not use James for code review, article voice editing, ordinary research summaries, or the first drafting pass. Write the document first.

Declare The Scope Envelope

State the allowed context before review.

1. Project-owned only. Use files inside the current project root. Refuse web search, global memory, cross-project knowledge, chat history, and files outside the project.
2. Standalone documents default narrow. Review the target document alone, plus its path and project name. Add same-project context only when the document declares the dependency or the user names it.
3. Chronological documents may use older project context. Post-release notes, retrospectives, migrations, and follow-ups may use older files from the same project. Prefer git history for age; otherwise state the filesystem timestamp fallback.
4. Narrower wins. Obey any narrower user-provided boundary.
5. Missing context is a finding. Do not broaden the envelope to rescue an unclear document.

If multiple plausible target documents exist, ask which one to review.

Runtime State

Store James-owned state outside the reviewed project by default:

~/.james/<repo-slug>/<target-slug>/
  recipe.md
  chain.md
  reviews/
    001-initial.md
    002-after-fixes.md

• Canonicalize the project root by making it absolute, resolving symlinks plus . and .., rendering separators as /, removing a trailing separator except for a filesystem root, and lowercasing only a Windows drive letter. Derive repo-slug from its basename and record the canonical root in recipe.md. Before writing, read any occupied recipe. Reuse it only when the stored root matches. Otherwise append the first eight lowercase hex characters of SHA-256 over the UTF-8 canonical-root string, extending the same prefix four characters at a time through all 64 characters when an occupied candidate belongs to another or unknown root. A mismatch at the full digest is an error; never merge review chains.
• Derive target-slug from the target's relative path by replacing path separators with -- and dropping a common text extension.
• When two targets normalize to the same slug, apply the same 8-character then 4-character-extension rule to SHA-256 over the UTF-8 target-relative path and fail closed at a full-digest collision.
• Use a different output root only when the user explicitly provides one.
• Never place James operational logs in project documentation by implication.

Recipe And Review Chain

Create recipe.md before the first review and load it before later reviews. Treat it as process memory, never as product evidence. Record:

• project root
• target document
• document intent
• exact allowed context
• James output root
• reviewer identity or session handle when available
• next review number
• changes to target, scope, or reviewer mode

Save every raw review as a new file under reviews/. Update chain.md with review number, file, score, pass/fail, fixes, reviewer mode, and next action. Never overwrite an older review. This is an append-only workflow contract, not cryptographic immutability.

Reviewer Capability Ladder

Use the strongest available mode and record it:

1. Resumable isolated reviewer — preferred. Resume the same reviewer for re-review, but reset the admissible evidence on every call.
2. Fresh isolated reviewer only — send the current document, scope, previous saved review, and attempted fixes to a new reviewer. Record that continuity was rehydrated rather than resumed.
3. No isolated reviewer — perform a degraded local James pass and disclose that the independent-review guarantee is unavailable.

Never use remembered document facts as evidence unless they appear in the current allowed scope.

Review Loop

1. Load or create the recipe. Determine the output root and next review number.
2. Select the reviewer mode. Resume, rehydrate, or explicitly degrade.
3. Reset the evidence boundary. Send the target, allowed scope, and the template in references/review-prompt.md every time. For review two and later, also send the previous saved review and attempted-fix summary.
4. Require the James format. The review must include:
   • Score: X/10
   • Passed: yes/no
   • for re-review, Fixed since previous review:
   • a numbered issue list
   • whether each issue is fixable now or needs the human
5. Persist before editing or escalating. Save the raw review, then update chain.md before any target edit or terminal human escalation.
6. Fix only what is safe. Add definitions, replace private shorthand, remove local absolute paths, declare dependencies, add examples, and make acceptance checks observable. Do not invent users, pricing, policy, commitments, product decisions, or factual claims.
7. Re-review. Use the same reviewer when resumable; otherwise rehydrate a fresh reviewer from the saved chain.
8. Stop only on pass or escalation. A pass requires explicit Passed: yes. The numeric score is diagnostic and never overrides Passed: no. A missing Passed field is a malformed review, not an implicit score-based pass. Before reporting either terminal state, verify that the current raw review and its chain.md entry have already been persisted.
9. Cap the loop. Allow at most three edit passes after the initial review. If the third re-review still does not pass, stop instead of chasing a score.
10. Escalate human questions. Persist the failing review first, then surface decisions that cannot be safely derived from project-owned evidence.

Review Lens

Especially catch:

• private names, absolute local paths, and personal shorthand
• “as discussed,” “the usual flow,” and similar hidden-context residue
• terms used before definition
• vibe-based acceptance criteria
• dependencies outside the allowed scope
• missing authority, input/output shape, target user, or success criteria
• plans that require the author to remain present to explain them

Do not demand a large document. A short artifact can pass when its scope is explicit and a future agent can act from the allowed evidence.

Final Report

Report briefly:

• target document
• James output root
• reviewer mode
• final score and pass state
• number of review passes
• changes made
• unresolved human questions

The document and append-only review chain carry the detail.