The documented base I give every agent session, and how to set it up in your own project.
Last updated: 15 October 2026. Working with AI agents keeps changing, so this describes how I work at the time of writing.
The base I give every project comes from a templates/ folder in my repo: a set of blank documents. The setup skill copies the contents of the folder into the project root and fills them in with me before the first session. They are an entry point for the agent (AGENTS.md), seven documents in context/ that describe the project, a Makefile with a single check command, and a private local-docs/ folder. Nothing in them runs. They're the written context an agent reads at the start of every session, whether the project is new or already running. The folder and the skills that fill it in are in my paula-tools-marketplace repo, and this article explains how to use them and why I work this way.
An agent can only work from what it knows, and a blank prompt tells it almost nothing. What it knows also has to fit in its context, the space it has for everything it reads during a session. The templates manage that too. The entry point tells the agent which documents to read, each document stays short, and detail sits in linked documents that the agent opens only when a task needs them, so it reads what it needs and nothing more. I'm still learning what works here. This setup is based on what I've read about how agents use context and on trying different approaches: starting from blank prompts, keeping a single AGENTS.md file and using BMAD, and I kept running into tool bloat. I've written up what I've found about context so far in Smart Zone, Dumb Zone: How I Keep Context Small When Coding with AI.
I used to start with a blank prompt. I was slow to get going, and I used a different skill for each step: one to write the spec, another to write tickets, and so on. Every project began by rebuilding the same context. The templates put all of it in one place, which gives any agent a good base and keeps my workflow smooth when work passes from one session to the next.
Set it up with one skill
A project needs its structure written down before the agent starts building, and one skill does that for me. Install the project-foundation plugin once:
/plugin marketplace add paufar/paula-tools-marketplace
/plugin install project-foundation@paula-tools
Then open Claude Code in the project, new or existing, and run:
/project-foundation:init-project
The skill copies the contents of the repo's templates/ folder into the project and adds local-docs/ to .gitignore. It then fills the files in by asking me about each section, one question at a time, starting with context/PROJECT.md. It also fills in AGENTS.md and then does three more things, each for a reason:
- It replaces the
make checkstub in theMakefile. The agent runsmake checkat the start and end of every session to confirm the project is consistent. The stub fails on purpose, so a session can't pass on a check that tests nothing. The skill swaps it for the project's own lint, type-check, test and build commands, somake checkmeans something from the first session. - It writes the build plan and the first spec in
context/specs/. The workflow rules tell the agent to build against specs and not to invent behaviour. That only works if the plan and the first spec exist before the first line of code. - It checks that no placeholder is left. The templates are full of
[bracketed]text, and an agent could read it as real instructions. A section I skip keeps its placeholder, but it's logged in Open Questions inPROGRESS.md, so nothing is left unfilled without my knowing.
For an existing project, it first reads every markdown file already there. It shows me anything useful, labelled with the file it came from, and I choose whether to use, edit or replace it. Once the content is absorbed, the old files are deleted only after I confirm. Files meant for other readers, such as the README, the LICENSE and the CHANGELOG, are kept.
If a run is interrupted, a project-initialization.md tracker stays in the project root. /project-foundation:init-project resume picks up where it stopped.
One file is private. local-docs/goal.md holds anything I want to get out of the project for myself, such as learning a new concept or trying out a new tool. It is gitignored, and only the parts I clear reach a committed file.
The agent reads the same documents every session
The agent should start from written context, not from guesses. CLAUDE.md points to AGENTS.md, which is the entry point every agent reads first. From there it finds the documents in context/: PROJECT.md, ARCHITECTURE.md, UI-CONTEXT.md, CODING-STANDARDS.md, AI-WORKFLOW-RULES.md, PROGRESS.md and DECISIONS.md.
Those documents decide what happens when something is unclear. The agent doesn't invent behaviour. If a requirement is ambiguous, I settle it in the relevant context file before anything is built. If it's missing, it goes into PROGRESS.md as an open question.
One thing at a time
Small steps are easier to check, so AI-WORKFLOW-RULES.md sets the work-in-progress limit to one. PROGRESS.md holds at most one item under In Progress. A new idea that appears halfway through goes to Next Steps or Open Questions, never into the current task. Each task has a "Done when", and it only moves to Done with evidence.
If a change can't be checked from start to finish quickly, it's too big, and I split it. The same file lists what to split on, such as UI changes mixed with backend changes.
Clock in, clock out
Handoffs only work when the next session can see where the last one stopped. I call the two ends of a session clocking in and clocking out, and AGENTS.md tells the agent to do both. To clock in at the start of every session, it reads PROGRESS.md to see the current state and the next task. To clock out at the end, it updates PROGRESS.md. Both steps also run make check, so the project is confirmed consistent before and after. So the next session, or a different agent, picks up from the same place.
Every instruction has a cost
Each request to the model carries the whole history with it, so an instruction I add early is sent again on every request. That costs tokens, and it costs attention too: every extra instruction makes the others a little quieter. I think of the two together as context load, and I weigh it each time I add a rule.
That's why I choose between pushing and pointing. Pushing means putting the content in front of the agent every time. Pointing means putting in one short line that says where the content is, and the agent opens it when the task needs it. AGENTS.md is mostly pointers. It links to each document in context/ and leaves the detail there.
It's also why I keep every file short. I keep each document between 100 and 150 lines once filled in. I settled on that range because published advice on instruction files varies from around 60 lines to 300, and 100 to 150 sits in the middle. The reason behind it matters more than the number. When a document grows, the detail moves into a linked document instead.
One source of truth
Every fact lives in one place, so there is only one thing to keep up to date. The versions of my packages live in package.json and nowhere else. If they were also written in an instruction file, I would have to keep the two in sync, and the agent can already find the versions in package.json on its own.
The bigger risk is sediment. When I forget to update an instruction, it keeps saying something that is no longer true. The agent has no way to tell, and it ends up confused by information I wrote for it. The fewer places a fact lives, the less can go stale.
Check the system regularly
A setup like this needs checkups. Agents keep improving, so an instruction that was necessary once may not be needed now, and every instruction I can remove lowers the context load. I review the documents from time to time with that question.
I also ask the agent what it learnt at the end of a session, and I look at whether anything in the setup can improve because of it.
It takes time, and it saves more
Setting this up takes time at the start. It saves time later, because a good foundation stops the agent drifting into guesses and hallucinations. It's easy to get lost in a lot of files, and this gives the project a structure, so the agent reads only what it needs for the task.
Structure first
This has changed the way I work greatly. Before, whenever I stopped and started a task over several days or sessions, I had to explain a lot to my agent again. Now everything is organised and logged, so the agent finds what it needs easily, and I can tell it to continue where we left off, however big or small the gap between sessions.