Folder-as-program is not one more instruction file
Folder-as-program: structure agent-ready folders with entry files, source truth, state, tools, checks, outputs, and human decisions.
A fresh agent session can feel weirdly close and useless at the same time.
It can search the repo. It can run commands. It can edit the file in front of it. But it does not know the decision from yesterday, the approach that already failed, which source-truth file wins, or what artifact proves the work is actually done.
So the human starts to “re-brief the AI.” The complaint is usually some version of “the agent forgets everything.” Then another paragraph gets added to AGENTS.md, CLAUDE.md, INSTRUCTIONS.md, a README, or a Cursor rule.
It helps for a while.
Then the file turns into a junk drawer.
Stable rules, volatile state, stale notes, source paths, one-off debugging context, examples, check commands, and “never do this again” warnings all land in the same place. One file is being asked to carry source truth, memory, proof, and handoff at once. The next session has more context, but less precision.
The problem is not that the agent needs a larger instruction dump. It needs a folder that can carry the work contract.
Folder-as-program is a way to design an agent-ready folder so the folder itself carries the entry point, source truth, state, tools, examples, checks, output contract, and human decision boundaries a fresh agent needs to execute work. The instruction file is the entry point. It is not the whole program.
The entry file is real. It is also not enough.
The ecosystem has already admitted the first part. Agent context is becoming local, scoped, and inspectable. Claude Code has CLAUDE.md and related project memory files in its memory docs. Codex has AGENTS.md, nested guidance, fallback filenames, and a combined guidance cap in the AGENTS.md guide. Cursor has Project Rules, User Rules, and nested AGENTS.md behavior in its Rules docs. GitHub Copilot has repository-wide and path-specific instructions in its repository instructions docs.
But that first part is not the whole program. Instructions are guidance. They are not compiled enforcement. Anthropic warns that vague or conflicting CLAUDE.md content may not be followed, and its hooks guide points to deterministic shell commands when an action has to happen at a lifecycle point.
The entry file should tell the agent where to begin. It should not carry every fact the folder needs to function.
What the folder has to carry
A program-shaped folder has eight jobs.
The entry point is the local file the agent should read first: AGENTS.md, CLAUDE.md, INSTRUCTIONS.md, SKILL.md, a workflow contract, or a project rule. It answers: what work does this folder perform?
The imports are source-truth files, schemas, policies, config, product docs, client constraints, prior research, and any other authority the agent is not allowed to invent from memory. This is the difference between “write in our voice” and “read these exact voice exemplars before drafting.”
The state is what survives the session. Run manifests, ledgers, decisions, current work notes, rejected paths, and unresolved blockers belong somewhere inspectable. If the next agent needs to know it, it should not live only in chat history.
The tools are commands, scripts, MCP tools, package tasks, browser checks, API calls, or search patterns the folder expects the agent to use. MCP is helpful here because it separates invokable tools, URI-addressed resources, and reusable prompts. But MCP is one ingredient. It does not decide the folder’s intent, preserve workflow state, run verification, or define completion by itself.
The examples are fixtures, prior outputs, sample packets, accepted drafts, rejected drafts, or shape references. They show the output standard faster than another paragraph of abstract guidance.
The checks are tests, linters, hooks, review gates, or explicit commands. This is where the folder stops hoping. An instruction can ask the agent not to break the build. bun run verify can show whether it did. A schema check or a required review report changes “looks done” into evidence.
Only passing tests count as evidence.
The return values are the files, records, exports, or summaries downstream work consumes. A folder program should make those obvious. If the expected output is claim-map-v3.json, say that. If the only acceptable result is a compact JSON completion message, say that too.
The judgment boundary names where the human has to decide. Some things should not be automated away: legal approval, brand judgment, source-truth conflicts, publication, destructive commands, or commercial claims. A good folder records how the decision gets made and where it persists.
You do not need a grand architecture to see it. Take a draft folder. AGENTS.md tells the session where to start. A source-truth file names the claims it may use. A state or ledger file records what survived the last run. A script proves the draft still passes checks. An example shows the shape. The return value is named: draft-v3.md, claim-map-v3.json, or a review report.
Now the instruction file has one job again.
That is the practical inspection test. Can a fresh agent enter this folder and know what to do, what not to do, what to read, what to run, what to produce, and when to stop?
Three levels are enough
Level one is a storage folder. It has files. Maybe they are well named. Maybe a human understands them. The agent still needs a tour.
Level two is an instruction dump. It has a large local guidance file. This is better, but it usually fails at state and verification. The file starts carrying current work, durable rules, examples, source truth, and handoff notes at once.
Level three is a folder program. The instruction file points to the rest of the operating surface. Source truth has its own place. State has its own place. Tools and checks are callable. Examples are nearby. Outputs are declared. Human judgment is explicit.
The agent does the work. The folder carries the work contract.
You can see the same operating lesson in a good agentic research workflow. The value is not that an agent was prompted to research. The value is that sources, decisions, gaps, and artifacts survive the run. You can see it in Content QA-as-Code, where quality rules stop being vibes and become checkable assets. You can see it in ESLint for content and rules-to-rulepacks: prose standards become more useful when they can be loaded, checked, and reused.
The folder-as-program frame is the developer version of that same operating lesson.
The limit is the point
This is not a standard. It is not a protocol. It is not a claim that every agent reads every file the same way.
It is also not an argument against AGENTS.md, CLAUDE.md, Cursor rules, README files, MCP, or hooks. Those are useful modules. The mistake is asking one module to do the whole job.
A folder with no entry point is vague. A folder with only an entry point is brittle. A folder with tools but no state loses decisions. A folder with state but no checks becomes a diary. A folder with checks but no judgment boundary can still automate the wrong thing.
The useful version is boring in the best way: clear entry, clear imports, clear state, clear tools, clear examples, clear checks, clear returns, clear human calls.
That is what makes a fresh agent less dependent on the human rebuilding the world by hand.
The same failure shows up in review
Content review has the same inheritance problem.
If an editor says “this claim needs the primary source” in a comment thread, the current draft may improve. But unless that decision becomes structured memory, the next agent will make the same mistake. The correction lived in a place the workflow could not inherit.
A comment fixes the current draft. A structured finding and decision give the next workflow something to inherit.
That is the product reason Typescape cares about this pattern. External agents own semantic judgment; Typescape owns the review lifecycle. A review becomes a finding. A finding gets a decision. A decision can become a rule. Rules compile into rulepacks and schema-versioned exports future agents can consume.
The point is not that Typescape makes coding agents reliable. It does not. The point is narrower and more useful: important human judgment should not vanish into comments, approvals, or transcripts.
Start with one folder. Ask what it imports, what it remembers, what it can run, what it returns, and which human decisions it preserves. Then ask where source truth, decisions, reusable rules, and proof artifacts fall out of the workflow. If you want us to inspect that system, start with the audit.