diff --git a/.claude/commands/loop.md b/.claude/commands/loop.md index 56f0ffe..4bbc4f0 100644 --- a/.claude/commands/loop.md +++ b/.claude/commands/loop.md @@ -2,14 +2,25 @@ description: Take ownership of the engineering objective and drive the next consequential action --- -Read PROJECT.md, AGENTS.md, STATE.md, and relevant project resources. Take -ownership of the engineering objective. Identify and execute the most -consequential useful next action; implement, test, diagnose, refine, and update -durable state and evidence. Use specialists/subagents for bounded tasks when -useful. Continue autonomously until validation is complete, an explicit review -gate is reached, or no useful independent work remains because of a genuine -human decision or external dependency. For hardware: complete hardware-free -development and validation → prepare a hardware-ready candidate → save -AWAITING_HUMAN_REVIEW and stop for explicit candidate approval → perform -authorized physical integration and validation. On resume, honor the gate and -retain recorded candidate approval within its scope. +Take ownership of the engineering objective in this repository and drive it to a +validated result. + +Read AGENTS.md first and follow it. It defines the workflow, the evidence and +record conventions, your authority limits, and the review gates. Let it route +your other reading; PROJECT.md holds the intent and STATE.md the current +checkpoint. Reconcile that checkpoint against the actual artifacts before you +act on it. + +Work in many actions, not one: pick the most consequential useful gap, close it, +record the evidence, then pick the next. Decide routine reversible things +yourself instead of asking permission for work you are already authorized to do. +Do not interact with physical hardware before the explicit approval AGENTS.md +requires. + +Stop only when the requirements are validated, a review gate in AGENTS.md is +reached, or every remaining useful action depends on a human decision or an +external dependency. Checkpoint STATE.md before stopping and record exactly what +you need and what happens next. + +The repository is the source of truth, not this conversation. Leave nothing a +successor would need only in chat. diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ac7178..1608916 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,27 @@ All notable changes to this template are documented here. The format is based on ### Changed +- Fixed the README diagram connection lines in GitHub dark mode. The diagrams + set `theme: 'base'`, whose default `lineColor` is `#333333` — that reads at + 12.63:1 on the light canvas but only 1.50:1 on dark `#0d1117` and 1.19:1 on + dark-dimmed `#22272e`, so the edges were effectively invisible to dark-mode + readers. Set an explicit `lineColor` of `#768390`, chosen by computing WCAG + relative-luminance contrast rather than by eye: 3.87:1 on light, 4.88:1 on + dark, 3.88:1 on dark-dimmed, and 3.32:1 against the base theme's own node fill + where an edge crosses a node. All clear the 3:1 threshold for non-text + graphical elements. Only the line colour changes: the theme, the node fills, + and `fontSize` are all untouched. +- Rewrote the persistent engineering loop prompt. It no longer restates the + hardware phase chain, stopping conditions, or file list that `AGENTS.md` owns — + that duplication was a second source of truth and had already gone stale + (it omitted `records/HUMAN_INPUTS.md` and the Loop continuity reconciliation). + The prompt now points at `AGENTS.md` and spends its words on what a file cannot + carry: ownership, working through many actions rather than stopping to report + after one, deciding routine reversible things without asking, and checkpointing + before stopping. The one deliberate redundancy is safety-relevant — an explicit + line not to touch hardware before approval. Dropped the subagent instruction, + which is the harness's decision and is covered by `AGENTS.md`. + `.claude/commands/loop.md` is kept byte-identical to the README prompt. - `ARCHITECTURE.md`: the engineering loop diagram now shows resume reconciliation, reading the ruled-out list before choosing an action, recording intent before irreversible actions, clearing the in-flight entry on state update, and the diff --git a/README.md b/README.md index 889ece7..2f2f0a0 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ schedule work, or grant device access. A single capable agent is sufficient. prompt. The agent chooses the implementation and maintains progress in files. ```mermaid -%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '18px'}}}%% +%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '18px', 'lineColor': '#768390'}}}%% flowchart TD D[Discuss the objective] --> S[Setup prompt:
capture intent] S --> L[Loop prompt:
autonomous engineering] @@ -60,17 +60,28 @@ next useful action, leaving the repository ready for autonomous engineering. ### PERSISTENT ENGINEERING LOOP PROMPT ```text -Read PROJECT.md, AGENTS.md, STATE.md, and relevant project resources. Take -ownership of the engineering objective. Identify and execute the most -consequential useful next action; implement, test, diagnose, refine, and update -durable state and evidence. Use specialists/subagents for bounded tasks when -useful. Continue autonomously until validation is complete, an explicit review -gate is reached, or no useful independent work remains because of a genuine -human decision or external dependency. For hardware: complete hardware-free -development and validation → prepare a hardware-ready candidate → save -AWAITING_HUMAN_REVIEW and stop for explicit candidate approval → perform -authorized physical integration and validation. On resume, honor the gate and -retain recorded candidate approval within its scope. +Take ownership of the engineering objective in this repository and drive it to a +validated result. + +Read AGENTS.md first and follow it. It defines the workflow, the evidence and +record conventions, your authority limits, and the review gates. Let it route +your other reading; PROJECT.md holds the intent and STATE.md the current +checkpoint. Reconcile that checkpoint against the actual artifacts before you +act on it. + +Work in many actions, not one: pick the most consequential useful gap, close it, +record the evidence, then pick the next. Decide routine reversible things +yourself instead of asking permission for work you are already authorized to do. +Do not interact with physical hardware before the explicit approval AGENTS.md +requires. + +Stop only when the requirements are validated, a review gate in AGENTS.md is +reached, or every remaining useful action depends on a human decision or an +external dependency. Checkpoint STATE.md before stopping and record exactly what +you need and what happens next. + +The repository is the source of truth, not this conversation. Leave nothing a +successor would need only in chat. ``` Reuse the loop prompt after interruptions, context loss, or agent replacement. @@ -150,7 +161,7 @@ dead end is not retried. See the [persistent loop robustness rules](AGENTS.md#persistent-loop-robustness). ```mermaid -%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '18px'}}}%% +%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '18px', 'lineColor': '#768390'}}}%% flowchart TD R[Session starts or resumes] --> RC[Reconcile Loop continuity] RC --> IF{In-flight action?}