Plan, Scratch, and Tasks
To keep long-running work reviewable and prevent context bloat, Buffaly isolates state into three distinct layers. Understanding how the agent uses these layers is critical for managing complex operations.
The LLM Drift Problem
Standard agents keep their "plan" in the chat window. The moment they get distracted by a sub-task or encounter an error, they overwrite their own instructions, lose the context of the overarching goal, and abandon the task. Buffaly prevents this by strictly separating the immediate routing (Plan), the agent's internal thoughts (Scratch), and the overarching deliverable (Tasks).
Plan
The immediate queue of next steps. It tracks what the agent is doing right now.
Scratch
An ephemeral whiteboard for the agent to think and hypothesize. Not meant for human consumption.
Task Artifacts
Durable markdown files defining explicit acceptance criteria. The anchor that survives compaction.
1. Plan (The Immediate Route)
Plan.md is the short routing artifact for the current session. Use Plan for the immediate route, the current concrete step, and compact statuses (pending / in progress / completed / blocked). It is not for long-term requirements.
| Action | Purpose |
|---|---|
ToSetSessionPlanExplanation | Set the short routing summary |
ToAddSessionPlanTask | Add a pending plan step |
ToStartSessionPlanTask | Mark a step in progress |
ToCompleteSessionPlanTask | Mark a step complete |
ToBlockSessionPlanTask | Mark a step blocked |
2. Scratch (The Ephemeral Whiteboard)
Scratch.md is session-local working memory. It is the agent's internal whiteboard. The agent uses it to summarize command outputs, draft hypotheses, log intermediate conclusions, and set reminders for its next turn.
Important rule regarding Scratch:
Do not treat Scratch as durable memory, a final deliverable, or a protected secret store. It is meant to be messy and temporary. If acceptance criteria or handoff evidence matter, promote the state into a Task Artifact.
3. Tasks (The Durable Anchor)
A durable task artifact is a root-level markdown file (e.g., task-01.md) stored in the session's Files Drawer. This is the core innovation for long-running work.
Because it lives outside the immediate conversational "Plan," the agent can drift into 10 nested sub-tasks or get compacted, and the overarching Task remains safe, explicitly defining what success looks like when it eventually returns.
- Explicit acceptance criteria.
- Decisions a future session may need.
- Target files to change and validation history.
- Blockers, open questions, and the final commit hash.
When Buffaly creates or updates each layer
- 1.At task start: Initialize Plan and Scratch. Create a durable task artifact if multiple turns or strict acceptance criteria are expected.
- 2.During investigation: Keep Plan short. Append raw evidence to Scratch.
- 3.Before compaction or delegation: Preserve scope, changed files, and the next validation step in the durable task artifact so it survives the context wipe.
- 4.When resuming: Re-read Plan, Scratch, and task artifacts before acting.
- 5.At completion: Update the task artifact with final validation and the commit hash.
Practical Prompt Examples
"This is a multi-step documentation task. Initialize Plan and Scratch. Create a durable task artifact with acceptance criteria and implementation files to inspect."
"Continue the current task. Re-read Plan, Scratch, the durable task artifact, and the target article. Report the last completed step and next safe step before editing."
"Inspect session artifacts for Plan.md, Scratch.md, task-*.md, compaction files, and the last timeline result. Tell me whether the task is ready to continue, blocked, or already complete."
Common mistakes
| Mistake | The Fix (What to prompt) |
|---|---|
| Putting all evidence in Plan | "Keep Plan short and put your raw evidence in Scratch." |
| Treating Scratch as durable memory | "Create a durable task artifact for these decisions so we don't lose them." |
| Waiting until the end to create a task file | "Create the task artifact before investigation begins to establish acceptance criteria." |
| Storing secrets in task files | "Store credentials using the secret mechanism; refer to them by key only. Do not write them to disk." |