How to work with Plan, Scratch, and Tasks

Plan

Plan.md is the short routing artifact for the current session. The ToInitializeSessionPlanAndScratch action creates Plan.md and Scratch.md together if missing. Plan operations let you set the routing explanation and manage task steps:

Use Plan for the immediate route, current/next concrete step, compact statuses (pending/in progress/completed/blocked), and a short note explaining why a step changed.

Scratch

Scratch.md is session-local working memory. The same ToInitializeSessionPlanAndScratch call ensures it exists alongside Plan. Use it for implementation files inspected, command output summaries, hypotheses, pivots, intermediate conclusions, blockers, and reminders for the next turn.

Do not treat Scratch as durable memory, a final deliverable, a protected secret store, or the only record of work that spans multiple days. If acceptance criteria or handoff evidence matter, promote the durable state into a task artifact.

Tasks

A durable task artifact is a root-level markdown file (task-*.md). The typed actions ToCreateAndMaintainLocalTask and ToUpdateExistingLocalTask manage these artifacts with concrete scope and acceptance criteria.

Use a task artifact for multi-turn implementation, debugging that spans turns, delegated child-session work, explicit acceptance criteria, decisions a future session may need, and validation history.

A good task artifact names the task scope, acceptance criteria, references inspected, decisions made, files changed, validation performed, blockers or open questions, and final result such as a commit hash when applicable.

How these layers relate to timeline and artifacts

When Buffaly should create or update each layer

1. At task start: initialize Plan and Scratch; create a durable task artifact if acceptance criteria or multiple turns are expected.
2. During investigation: keep Plan short; append evidence to Scratch; update the task artifact when durable state changes.
3. Before compaction or delegation: preserve scope, acceptance criteria, changed files, blockers, and next validation step in the task artifact.
4. When resuming: re-read Plan, Scratch, task artifacts, target files, and scoped git status before acting.
5. At completion: update the task artifact with final validation, changed files, commit hash, and open questions.

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.

How to verify Plan, Scratch, and Tasks

Ask Buffaly for direct evidence: "Show the current Plan summary, the latest Scratch evidence note, and the task artifact status. Include file names and last modified times if available."

• Check the session directory for Plan.md, Scratch.md, and root-level task-*.md artifacts.
• Use session artifact surfaces when available to list or read artifacts without relying only on prose summaries.
• Confirm final deliverables independently by file path, diff, command output, route render, or commit hash.

Common mistakes and how to avoid them