flatfile-agent-workspace

A folder structure for keeping AI-assisted work organized — notes, decisions, and daily progress in plain text files, run by an AI coding agent.

Five folders, each self-documenting through an AGENTS.md file, plus paired start- and close-session runbooks (short how-to procedures) that book-end a working day. No proprietary tools, no databases, no hidden state — just plain files and git, so your work outlives whichever assistant you happen to use.

The workspace is built so a person — or an agent — can open any folder without prior context and work out how to use it from the AGENTS.md inside. It keeps AI-assisted work organized and auditable: a running daily log, a durable record of decisions and findings, and a handoff that lets the next session pick up where the last one stopped.

Two ways to use it

Just want a workspace. Download the latest release, unzip it wherever you keep your projects, and start your AI tool in the folder. The workspace's own README.md takes it from there. This is the path for most people.

Want to customize the template, or spin up workspaces repeatedly. Clone this repo and use create-workspace.py:

git clone https://github.com/melek/flatfile-agent-workspace.git
cd flatfile-agent-workspace
python3 create-workspace.py main

Requires Python 3.9+ — check with python3 --version, or get it from python.org/downloads. On Windows, use python in place of python3.

This creates ~/agent-workspaces/main/ — a fresh copy of the template, initialized as its own git repo with one initial commit. Keep one workspace for everything, or create separate ones for different experiments or parts of your life. Pass an absolute or ~/-prefixed path to put it elsewhere:

python3 create-workspace.py /tmp/test-workspace
python3 create-workspace.py ~/Code/some-project

Open the new folder with your AI tool and ask it to read AGENTS.md for an orientation.

What's in a workspace

my-workspace/
├── AGENTS.md         # base workspace context — the entry point for an agent
├── methodology.md    # the thinking behind the workspace
├── decisions.md      # append-only register of commitments
├── observations.md   # append-only register of findings worth keeping
├── daybook/          # one dated file per workday
├── projects/         # one subfolder per ongoing project
├── runbooks/         # how-to procedures (ships with start-session/ and close-session/)
├── resources/        # static reference material
└── tmp/              # gitignored scratch

Each folder carries its own AGENTS.md documenting the conventions for that folder, so an agent keeps filing and workflow discipline without re-reading the root.

Walking through the workflow

If you start your tool of choice in the folder, you can just start and it may work "ok". To get the full value of the workspace, a bit of user discipline helps:

• When you start, open the session intentionally by stating what you're hoping to work on and achieve by the end of the day. This should engage the 'start-session' runbook and create a dated log entry for the day, recording your intent.
  • If there is already a daybook entry for the day, the system should try to 'pick up' wherever you are in the day from the context on disk.
• During the session, you can prompt the LLM to freshen good working discipline (or question its methodology):
  • "Note that in today's log."
  • "Create a runbook for what we just did."
  • "Why do you keep a decision log?"
• At the end of your day, declare your intent: "Please close the session." The LLM should read the 'close-session' runbook which processes the session into log notes, decisions, and observations, it may ask some questions on how to reckon with open threads, and then commits the local repository as a checkpoint.
  • The daybook is organized by day, not by session, but the start/close day rituals are meant to work just fine across multiple daily sessions.

How the files are used

Each file has a different purpose and a preferred style for entries to support that purpose.

File	What it captures	Style
decisions.md	Binding commitments that affect future sessions	Future-binding
observations.md	Findings that would cost inference to re-derive	Descriptive
projects/<name>/AGENTS.md	Live state of project-scoped work	Forward-looking
daybook/	Today's events	Chronological

When layered with regular git commits these files become durable, interconnected records useful both for carrying context forward and for auditing the workspace.

Repo layout

If you cloned the repo rather than downloading a workspace:

• agent-workspace-template/ — the deliverable: the workspace create-workspace.py copies. Generated — don't edit it directly.
• dev/annotated-source/ — the source of truth for the template, carrying maintainer annotations that are stripped from the deliverable.
• create-workspace.py — copies the template into a new, git-initialized workspace.

Customizing the template or contributing? See dev/AGENTS.md for the editing workflow. The scripts are single-file, stdlib-only, Python 3.9+ — no install step.

Related plugins

The flat-file workspace is meant as a minimal starting point: it carries the load-bearing pieces and assumes you'll extend it as you find what works for you. I have a few Claude Code plugins I use which pair extend this template's methodology:

• For safer model responses: lcars — in-session scoring hooks and ratification-flagging. Where this template's methodology.md says "intent, not enforcement," lcars is the enforcement layer for drift: instructs the model to give ergonomic responses, mitigates rubber-stamping, and flags sycophantic or overstated claims.
• For more hands-on work assistant features: workplanner — durable task list, plan, and backlog state across sessions, with profile support for different workspaces.
• For highly structured research: stepwise — a tool for generating structured literature review in an artifact-bound, step-by-step procedure for Claude Code. This plugin serves as an example of practicing a high level of deterministic scaffolding which can be referenced when populating runbooks/ with critical workflows.

The general idea behind these is that they introduce scaffolding via hooks and scripts which force the model to follow methodology more closely. This can't guarantee great results, but mitigates common risks of LLM usage.

Evaluation

The template is benchmarked against earlier versions of itself across a fixed scenario set — a same-shape A/B that surfaces where edits change agent behavior, and where different scoring rubrics disagree about whether a change helps. Methodology and run transcripts: flatfile-agent-workspace-bench.

License

MIT — see LICENSE.