Scaffolding

Scaffolding is the shared project infrastructure that Bonsai generates inside the station directory. It gives agents a common source of truth for project status, plans, decisions, and reports — so they can coordinate without you repeating context.

What Gets Generated

During bonsai init, you choose which scaffolding modules to include. Here’s the full structure:

• Directorystation/

  • INDEX.md — project snapshot (required)
  • DirectoryPlaybook/ — operational playbook (required)

    • Status.md — live task tracker
    • Roadmap.md — long-term milestones
    • Backlog.md — ideas, bugs, debt
    • DirectoryPlans/

      • DirectoryActive/ — numbered implementation plans

        • …
    • DirectoryStandards/

      • SecurityStandards.md — security rules
  • DirectoryLogs/ — activity logs (required)

    • FieldNotes.md — your notes to agents
    • KeyDecisionLog.md — architectural decisions
    • RoutineLog.md — routine execution history
  • DirectoryReports/ — completion reports (optional)

    • report-template.md — report format
    • DirectoryPending/ — unreviewed reports

      • …

The Four Modules

Scaffolding is organized into four modules. Three are required; one is optional.

INDEX

Required. Project snapshot — what the project is, who the agents are, and where everything lives. Every agent reads this at session start.

Playbook

Required. Operational playbook — status tracking, roadmap, backlog, implementation plans, and security standards. The heart of project coordination.

Logs

Required. Activity logs — your field notes to agents, settled architectural decisions, and routine execution history.

Reports

Optional. Completion reports — template and staging area for structured agent work summaries. Code agents write reports here after finishing plans.

What Each Piece Does

INDEX.md

The project snapshot. Contains a high-level overview of the project — tech stack, current phase, agent registry, and a document map linking to everything else.

Every agent reads INDEX.md at session start via the session-context sensor. It’s the entry point for understanding “what is this project?”

Playbook

The operational core. Five files that keep the project organized:

File	Purpose	Who uses it
Status.md	Live task tracker — in progress, pending, done	All agents check before starting work
Roadmap.md	Long-term milestones and phases	Context for where tasks fit in the big picture
Backlog.md	Ideas, bugs, tech debt, feature requests	Agents add items here instead of fixing things out of scope
Plans/Active/	Numbered implementation plans	Tech Lead writes them; code agents execute them
Standards/SecurityStandards.md	Hard security rules across all agents	Referenced by the security protocol

Tip

Plans are the primary coordination mechanism. The Tech Lead writes a numbered plan (e.g., 01-user-auth.md), then dispatches it to a code agent. The plan is the contract — both agents reference the same document.

Logs

The project’s memory across sessions:

File	Purpose	Who writes it
FieldNotes.md	Your notes to the agents — changes made outside sessions, new requirements, context the agent wouldn’t otherwise have	You (the human)
KeyDecisionLog.md	Settled architectural decisions — checked before proposing alternatives, prevents re-litigating resolved discussions	The Tech Lead
RoutineLog.md	Routine execution history — when each routine ran and what it found	The Tech Lead (after running routines)

Note

FieldNotes.md is your most direct communication channel. Agents read it every session start. If you make changes outside a session (manual code edits, dependency updates, infrastructure changes), note them here so the agent has context.

Reports

The optional module. When code agents finish executing a plan, they write a structured completion report to Reports/Pending/. The Tech Lead reviews these during code review workflows.

If you skip the Reports module during setup, the reporting workflow and subagent-stop-review sensor still function — the report submission steps simply become no-ops.

Required vs. Optional

Module	Required	Why
INDEX	Yes	Every agent needs to know what the project is
Playbook	Yes	Status tracking, plans, and standards are core to coordination
Logs	Yes	Session context, decisions, and field notes are essential bridges between sessions
Reports	No	Useful for multi-agent setups with formal review, but not essential for solo workflows

Caution

Required scaffolding cannot be unchecked during bonsai init. It’s required because the session-start protocol, session-context sensor, and multiple workflows depend on these files existing.

How Scaffolding Connects to Routines

Several routines exist specifically to maintain scaffolding health:

Routine	Scaffolding it maintains	What it does
status-hygiene	Playbook/Status.md	Archives old Done items, validates Pending items
backlog-hygiene	Playbook/Backlog.md	Flags stale items, escalates P0s, cross-references with Status and Roadmap
roadmap-accuracy	Playbook/Roadmap.md	Ensures roadmap reflects what’s actually built and planned
doc-freshness-check	All docs	Detects documentation that has drifted from recent code changes

This is why scaffolding and routines work as a system — the scaffolding provides the shared documents, and the routines keep them accurate.

Scaffolding Is Write-Once

Unlike abilities (which can be re-rendered with bonsai update), scaffolding files are write-once. If a scaffolding file already exists when you re-run generation, Bonsai skips it — your content is never overwritten.

This means you can freely edit Status.md, add items to Backlog.md, and customize the Roadmap without worrying about Bonsai clobbering your changes.