From 78ef086c7ef5993b63cd1bceaa94c6563d27ed21 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Fri, 1 May 2026 12:02:45 +0200 Subject: [PATCH] Move IDEAS.md to doc/ directory --- IDEAS.md | 6 --- doc/IDEAS.md | 102 +++------------------------------------------------ 2 files changed, 5 insertions(+), 103 deletions(-) delete mode 100644 IDEAS.md diff --git a/IDEAS.md b/IDEAS.md deleted file mode 100644 index 140b15f..0000000 --- a/IDEAS.md +++ /dev/null @@ -1,6 +0,0 @@ -# Ideas and Potential Improvements - -- **Status Polling Mechanism**: Implement a mandatory `status` file for all agents that the orchestrator can poll. This would prevent having to tail `chat` files to estimate if an agent is stuck or done (see [TRIAL_1.md](experiments/TRIAL_1.md)). -- **Verification of Premises**: Require agents to perform an "Environment Check" before acting on prompts to prevent fulfillment of hallucinated requirements (e.g., CMake in a Makefile-only project). -- **Administrative Handshake**: Force a "Sync" step at the end of every subagent task where they must receive an ACK from the parent before idling, reducing the "Done State Trap." -- **Purity Reviewers**: Introduce specialized reviewer scripts that look for "extraness" (extra files, unrelated changes, or phantom technical debt) rather than just functional correctness. \ No newline at end of file diff --git a/doc/IDEAS.md b/doc/IDEAS.md index bb60339..140b15f 100644 --- a/doc/IDEAS.md +++ b/doc/IDEAS.md @@ -1,98 +1,6 @@ -## Ideas - -### Network & Remote Access - -**Store federation** — because `FlatDirStore` and other stores operate purely on filesystem paths, pointing a store at a 9pfuse-mounted remote directory is indistinguishable from pointing it at a local one. Federation requires no new implementation — just env vars: - -- `OLLIE_TOOLS_PATH=~/mnt/remotehostA/t`: centralized tool distribution; one host is authoritative -- `OLLIE_TRANSCRIPTS_PATH=~/mnt/remotehostA/tr`: centralized transcript archive across all hosts - -The OS handles the proxying transparently via FUSE. Configuration is the only moving part. - -### Multi-Agent Workflows - -Two distinct patterns apply depending on whether work is delegated to ephemeral agents or distributed across persistent concurrent sessions. - -#### Subagent delegation - -For one-off focused tasks, use `subagent_spawn`. The parent spawns one or more sessions under `s/`, each running independently. Subagents signal completion by writing results to the parent's `prompt` file. The parent may kill subagent sessions when done, or leave them running for further interaction. - -See `prompts/tools-subagent.md` and `skills/session-management/SKILL.md` for usage. - -#### Concurrent sessions - -For workflows where multiple long-lived agents work in parallel and need to coordinate, the mechanism is direct prompt passing. Each agent is told its own session ID and its peers' IDs at startup. When an agent finishes a step and wants to hand off, it writes the result to another session's `prompt` — a plain file write from within `execute_code`. Writing to `prompt` queues by default, so a busy agent will not drop a message. - -When a peer needs to read back the response it triggered, it waits for `state` to return to idle, then reads `offset` and extracts the new output: `tail -c +$((offset+1)) s/$peer/chat`. The server sets `offset` to the byte position immediately after the user prompt is appended, so everything from that position to EOF is exactly the model response for that turn. - -No external coordinator is needed after the initial kickoff. The agents themselves route work based on context in their prompts. A human can intervene at any time by writing to any session's `prompt`. - -Each agent can use a different backend, model, or tool configuration. The boundary between fully automated and human-in-the-loop is just whether any agent's instructions include a step that asks before proceeding. - -#### Predefined workflows - -When the coordination logic is known in advance, a shell script can drive the entire workflow externally. Named sessions make routing unambiguous; `statewait` eliminates polling races on submit. - -```sh -#!/bin/sh -cwd=${1:?usage: $0 } -cd ~/mnt/ollie - -echo "name=developer agent=developer cwd=$cwd" > s/new -echo "name=reviewer agent=reviewer cwd=$cwd" > s/new -echo "name=tester agent=tester cwd=$cwd" > s/new - -# Send a prompt and return the model response. -# Opens statewait before writing prompt so the "idle" baseline is snapshotted -# before the agent has a chance to start processing. The server sets offset to -# the byte position immediately after the user prompt is appended to chat; -# everything from that position to EOF is the model response for that turn. -send() { - sid=$1; shift - exec 3< s/$sid/statewait - printf '%s' "$*" > s/$sid/prompt - while true; do - read -r _ <&3 && { exec 3<&- 2>/dev/null; break; } - exec 3<&- - [ "$(cat s/$sid/state)" != "idle" ] && break - exec 3< s/$sid/statewait - done - until [ "$(cat s/$sid/state)" = "idle" ]; do sleep 0.5; done - tail -c +$(($(cat s/$sid/offset) + 1)) s/$sid/chat -} - -reply=$(send developer "Implement a function that parses a JSON config file.") - -while true; do - review=$(send reviewer "Review the following code. Reply LGTM if ready, or PTAL with feedback. - -$reply") - - if ! printf '%s' "$review" | grep -qi "LGTM"; then - reply=$(send developer "Revise based on this feedback: - -$review") - continue - fi - - result=$(send tester "Test the following code. Reply Approved if all tests pass, or Rejected with details. - -$reply") - - if printf '%s' "$result" | grep -qi "Approved"; then - printf '%s\n' "$reply" - break - fi - - reply=$(send developer "Fix the following test failures: - -$result") -done -``` - -The script is the coordinator; agents have no knowledge of each other. Information flow is fully explicit. A human can intervene by writing directly to any session's `prompt`. - -### Self-Generating Workflows - -Since agents have access to `execute_code`, a session can write and execute a workflow script without any human involvement. Given a task and knowledge of the filesystem layout, an agent can decompose the work, spawn sessions, write the coordination script, and run it — all in a single turn. The README you are reading is essentially its system prompt. Conductor functionality, for free. +# Ideas and Potential Improvements +- **Status Polling Mechanism**: Implement a mandatory `status` file for all agents that the orchestrator can poll. This would prevent having to tail `chat` files to estimate if an agent is stuck or done (see [TRIAL_1.md](experiments/TRIAL_1.md)). +- **Verification of Premises**: Require agents to perform an "Environment Check" before acting on prompts to prevent fulfillment of hallucinated requirements (e.g., CMake in a Makefile-only project). +- **Administrative Handshake**: Force a "Sync" step at the end of every subagent task where they must receive an ACK from the parent before idling, reducing the "Done State Trap." +- **Purity Reviewers**: Introduce specialized reviewer scripts that look for "extraness" (extra files, unrelated changes, or phantom technical debt) rather than just functional correctness. \ No newline at end of file