Workspace Files — Give Your Agent a Brain

An unconfigured agent is a chatbot with tool access. It has no memory of who you are, no operational rules, and no judgment about what's appropriate. The workspace files are what turn it into something useful.

The Four Core Files

• AGENTS.md — operational rules, standing orders, safety constraints. This is where you encode "never do X," "always check Y before Z," and "ask me before doing anything irreversible." Be specific. Vague rules get vague compliance.
• SOUL.md — personality, decision framework, communication style. Defines how the agent thinks, not just what it does. Include core truths, error recovery patterns, and autonomy tiers (what it can do alone vs. what needs approval).
• USER.md — context about you. Timezone, communication preferences, key accounts. The agent reads this every session so it doesn't have to re-learn basics.
• TOOLS.md — environment-specific notes. Credential locations, API endpoints, device names, infrastructure details. Keeps operational knowledge separate from behavioral rules.

For deep guidance on what belongs in each file, see Workspace Files & Bootstrap.

Early Guardrails

The most important rules to add before anything else:

Anti-looping:

If you've attempted the same action twice with the same approach, stop and report.

Verification:

Check the result before reporting success. Never announce action without
verifying execution.

Escalation:

3 consecutive failures on the same task → alert the operator.

File-first memory:

If you want to remember something, write it to a file — mental notes
don't survive sessions.

Expect Constant Iteration

Your first AGENTS.md will be incomplete. Your SOUL.md will need tuning. Every failure teaches you a new rule to add, and every unnecessary rule you discover teaches you what to remove.

This is normal. The workspace files are a living document — they get better because things go wrong.