skynet/best-practices
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: scratchpad/ cross-node artifact channel, never merged into main

Browse Source 
Documents the pattern shipped in agent-runtime-framework's agent-repo/v1
init.sh + agent-runtimes' no-scratchpad-in-main CI gate: manifest nodes
share no filesystem, only the git branch, so scratchpad/ is where a
node hands data to a downstream node in the same manifest — and it
must never be cherry-picked or copied into a target repo's main branch.
This commit is contained in:
Paul O'Reilly
2026-09-06 23:45:21 +12:00
parent a69d0da22c
commit 43c20a0da5
1 changed files with 6 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
agent-repos.md
View File

@@ -462,6 +462,12 @@ Phase 5 is the one most teams skip and the one that prevents the largest class o
**Alternative:** Require agents to commit before exit (finalize phase auto-commits everything under `/workspace/working/`), which unlocks git-branch artifact passing. The finalize-phase auto-commit described above is the canonical implementation — enforce it for any agent whose output other tasks depend on. **Alternative:** Require agents to commit before exit (finalize phase auto-commits everything under `/workspace/working/`), which unlocks git-branch artifact passing. The finalize-phase auto-commit described above is the canonical implementation — enforce it for any agent whose output other tasks depend on.
## `scratchpad/` — the Cross-Node Artifact Channel, Never Merged
**Context:** manifest nodes (agent or `kind: script`) each run in their own ephemeral container/pod with no shared filesystem — a `verdict-tx` script node reading `/workspace/verdict` after an earlier `agent` node wrote it there fails every time, because that `/workspace` belonged to a container that's already gone. The git branch the task is working on is the only thing every node in the same manifest actually shares.
**Convention:** every agent-repo task branch gets a `scratchpad/` directory at the repo's top level (auto-created by `agent-repo/v1`'s `init.sh`, committed via the existing finalize-phase `git add -A`). A node that needs to hand data to a downstream node in the same manifest writes it under `scratchpad/` and commits — the downstream node clones the same branch and reads it back. This is scratch, not deliverable content: never review it, never treat it as part of the diff that matters, and — the part that's easy to get wrong during integration — **never copy or cherry-pick `scratchpad/` content into the target repo's main branch.** A CI gate (`no-scratchpad-in-main` in the target repo's build workflow) rejects any commit to `main` that still contains a `scratchpad/` directory, as the hard backstop behind this convention — but don't rely on the gate alone; a human or ralph doing a surgical cherry-pick should exclude `scratchpad/` by habit, the same way `results/` (AR-15) and secrets patterns (AR-32) are already excluded by convention from what actually ships.
## Include Exact Dataclass/Context Schemas in Template-Writing Agent Prompts ## Include Exact Dataclass/Context Schemas in Template-Writing Agent Prompts
**Symptom:** Agents writing templates invent their own mock context objects (e.g., dict-style `model["fields"]`) while real code provides a different shape (e.g., dataclass `model.fields`). Templates render against the mocks but produce attribute errors against real objects during integration. **Symptom:** Agents writing templates invent their own mock context objects (e.g., dict-style `model["fields"]`) while real code provides a different shape (e.g., dataclass `model.fields`). Templates render against the mocks but produce attribute errors against real objects during integration.