AI-native development
Use one agent contract, then teach tools to point at it.
The goal is boring in the best way: every coding assistant sees the same project expectations, and tool-specific files stay tiny. That keeps instructions easy to audit, easy to teach, and hard to accidentally contradict.
AI_THESIS.md is the canonical north star. AGENTS.md is the operational repo contract. Tool-specific files should be thin adapters or rendered wrappers, not parallel policy documents.
This is where agentic engineering becomes repeatable. A vibe-coding session depends on what you remember to say. An agentic workflow gives every agent the same project contract, verification habits, and boundaries before the work starts.
#The file layout
AI_THESIS.md | The canonical AI-native north star. It points to home/.chezmoitemplates/ai-thesis.md, so the same source can render into global agent adapters. |
AGENTS.md | The operational project contract: how to work, how to verify, what not to break, and what a good finish looks like. |
home/dot_claude/CLAUDE.md.tmpl | Renders the shared thesis plus a short Claude-only adapter into ~/.claude/CLAUDE.md. |
home/dot_codex/AGENTS.md.tmpl | Renders the shared thesis plus a short Codex-only adapter into ~/.codex/AGENTS.md. |
home/dot_codex/modify_private_config.toml | Preserves Codex's private, app-managed settings while enabling the user shell profile, so repository tool versions resolve normally in agent commands. |
skills/ | The canonical repo-local procedures. Each skill is a folder with a SKILL.md entrypoint, used for work that is repeated and easy to get subtly wrong. |
.claude/skills | A symlink to skills/ so Claude Code can discover project skills through its normal project-skill path. |
.codex/skills | A symlink to skills/ for tools that support a Codex-style skill directory. Keep the source in skills/, not copied per tool. |
AI_RULES.md | Not needed here. Add it only in larger repos where durable policy grows too large for AGENTS.md. |
Groundwork also puts mise shims on the login-shell path through ~/.zprofile. Codex and IDE commands can therefore select the current repository's declared Node, Python, or other tool version without hardcoding an installation path. The full interactive mise hook remains in ~/.zshrc; mise exec is a fallback, not the permanent command style.
#What belongs where
Use the narrowest durable home for each kind of guidance:
AI_THESIS.md | Product direction: what Groundwork is, why it is AI-native, and the operating principles that prevent drift. |
AGENTS.md | Repo operations: working style, safety, Git, verification, docs style, and source-of-truth rules. |
skills/ | Repeatable procedures such as docs alignment, validation, chezmoi changes, and macOS defaults. |
| Tool adapters | Only tool-specific discovery or display notes. Shared policy, prompts, and procedures belong elsewhere. |
#What belongs in AGENTS.md
Write the things you would tell a capable new teammate before they make their first change:
- How the project is organized.
- How to install, build, test, lint, and preview changes.
- Code style, doc style, naming conventions, and commit conventions.
- Safety rules: secrets, destructive commands, migrations, production data, and generated files.
- What verification means before the agent says it is done.
Keep it short enough that an agent can read it every time. If a section turns into a long procedure, move that procedure into a skill or a normal doc and link to it. If it is about Groundwork's long-term AI-native direction, put it in AI_THESIS.md instead.
#When a skill is worth creating
A skill is useful when the workflow is repeated, procedural, and easy to get subtly wrong — and it is not a second rulebook: anything the agent must always obey belongs in AGENTS.md. The full treatment, with worked examples from this repo, lives on Skills & playbooks.
#Direct one agent well, then direct many
Once you can hand a single agent a clean task and review the result, the next move is to stop being the only worker. In an orchestrated setup you become the orchestrator: one agent plans and delegates, and other agents (subagents, workers) each own a piece. This is not a new skill so much as three you already practice — decomposition, verification, and context economy — pointed at other agents. Learn to run one agent first; a beginner should not be commanding a fleet before they can direct a pair.
The reason it works is context isolation: each subagent gets its own context window, so you can hand off a big search or a noisy read and get back only the conclusion, keeping your main thread clean. The patterns are tool-independent — the vocabulary below outlives any product's buttons.
| Fan-out | Split independent subtasks across parallel agents, then gather. Worth it for breadth and speed when the subtasks do not depend on each other. |
| Pipeline | Each item flows through ordered stages, such as draft then verify. Worth it for staged work repeated over many items. |
| Supervisor | One agent plans and delegates; workers execute in isolation. The most predictable pattern and a common production default — the workflow controls the agents, not the reverse. |
| Debate / verify | Separate agents critique or verify each other's work before you trust it. Your "verify before done" habit, with more independent hands. |
| Swarm | Many peer agents self-coordinate. The frontier: most capable, least predictable, hardest to supervise. Reach for it last. |
A few rules separate an orchestration that works from one that quietly lies to you:
- Tell every subagent it is a subagent. Left unsaid, it behaves as a standalone assistant and talks to the user instead of returning results to the orchestrator.
- Build and test workers in isolation first, then wire the orchestrator to them. Constraint and predictability are features, not limitations.
- Keep it observable. If you cannot watch what each agent did, you cannot review or debug it — and reviewing it is still your job.
- Test off-target. Ask for something no worker owns. A sound system returns "nothing found"; a broken one invents a confident answer.
- Isolate writes. When agents edit files in parallel, give each its own branch or worktree so they do not clobber each other.
The mechanism moves fast and differs per tool, so learn your tool's current surface the same way you learn its usage gauge. Today that means subagents and /agents in Claude Code, background agents in Cursor, and delegation through their own agent or session configuration in Codex and opencode. The commands will change; the patterns above will not.
A single agent is the right default for any task that follows a linear path, fits in one context window, and crosses no hard security boundary. Multi-agent systems burn materially more tokens — Anthropic reports a single agent at roughly 4x the token use of a chat and a multi-agent system around 15x — so only pay that cost when the task genuinely decomposes into independent, high-value work. And more agents means more diffs to review: orchestration moves work off your keyboard and onto your judgment, it never removes the human. If step B needs step A's output, or the task is small, keep it one agent.
Take one real task. Do it with a single agent and review the diff. Then redo it as a delegate-and-verify pair: one agent makes the change, a second, told it is a reviewer, tries to break it. Compare the result and your review effort. You are learning the judgment of when the second agent earned its cost — not the buttons.
#Thesis, goals, specs, playbooks: the context agents share
Orchestration only turns "many agents" into "a team" if every agent runs on the same written context. Four layers carry that context, and Groundwork already has a home for each. They overlap on purpose, and sharpening one raises the value of the others.
| Thesis | AI_THESIS.md | Why the work exists and the direction no agent may drift from. |
| Goals | The objective you set per task | What "done" means for this specific piece of work. |
| Specs | A checkable target — a failing test, a mock, acceptance criteria (see Specs & targets) | The precise contract each agent verifies its own output against. |
| Playbooks | skills/ (see Skills & playbooks) | The repeatable how, so every agent runs a procedure the same way. |
Why this matters more as you add agents, not less: vagueness that costs you one wrong diff with one agent costs you five diverging diffs with five. A sharper spec makes delegation safe, a good playbook makes a worker reliable, and the thesis keeps a swarm from optimizing the wrong thing. The spec habit — and a full worked example from request to shipped — lives on Specs & targets.
The thesis layer deserves one concrete illustration, because it is the easiest to dismiss as paperwork. Groundwork's own thesis (AI_THESIS.md) states, among other things, that every tool page must answer how an agent uses the tool or how it helps a human direct and verify one — and that interface tools are choices, not purity tests. Those two sentences have quietly shaped hundreds of edits by many agents across this site: pages that drifted toward tooling-for-its-own-sake got caught, and nothing ships that talks down to a reader for their editor choice. That is what a thesis is for — not describing the product, but giving every future contributor, human or agent, the same test for "does this belong."
#Know your AI budget
Every serious AI tool runs inside limits — a context window, plan or rate limits, sometimes a spend budget — and long work fails in confusing ways when you hit them blind. The habit and where each tool's gauge lives now have their own page: Know your AI budget. The short version: check your tool's gauge before long work, start big work with room, and reset context deliberately when it's polluted.
#Sessions: pick up, hand off, clean up
Three days into the browser FPS track, the terminal window running your agent session closes by accident, or the laptop sleeps overnight, or you simply hit a rate limit before finishing for the day. The next session you open has no memory of the last one: no chat history, no sense of what you decided or why. If the work survives that gap anyway, it is because the state was never really in the conversation. It was in the repo: the plan you wrote down, the commits with real messages, the notes in AGENTS.md about what is verified and what is next. A session is the live back-and-forth with the model; it is compute, not memory. The repo is the memory.
That gives you a test for whether you packaged the work well: could a brand-new session, with no access to the old chat transcript, read your repo and know what is true? If the honest answer is "only if it reads the transcript too," the work was not handed off, it was just left sitting in a chat window. Write the decision, the progress, and the next step down somewhere a fresh session, or a different tool entirely, can find it.
| Claude Code | claude --continue reopens the most recent session for the current directory. claude --resume opens a session picker across all of them, so name your active sessions before you have several to tell apart. Transcripts are stored as JSONL under ~/.claude/projects/. /compact <instructions> summarizes deliberately, telling the model what to keep; automatic compaction also happens on its own once the window fills. The cleanupPeriodDays setting (in settings.json) auto-deletes transcripts older than N days. |
| Codex CLI | codex resume reopens a previous session. Sessions are saved as JSONL under ~/.codex/sessions/, and /export saves a readable transcript. There is no automatic cleanup yet, so the sessions directory grows until you prune it yourself. |
| Other tools | Cursor, Grok, and the rest ship the same shape under different keystrokes: some resume command, a session store on disk, some way to export or summarize. Learn your tool's version the same way you learn its usage gauge: the mechanism moves fast, the pattern does not. |
When a session fills up mid-task, the default move is not to compact and keep limping along: start a fresh session and re-onboard it from repo state, the same way you would want a teammate to. Compact deliberately, with focus instructions, only when the in-session continuity itself is what you need to keep, such as a long debugging thread where the reasoning matters as much as the code. Starting big work with room, as above, heads off most of this before it starts.
If the work was packaged the way the handoff test above asks for, an old transcript is disposable. It never touches your code, your commits, or your docs; it is a log of how you got there, not the record of what is true. Clearing it, letting cleanupPeriodDays sweep it, or pruning ~/.codex/sessions/ by hand costs you nothing but the execution log.
Reconstruct without the transcript
Run claude --resume (or codex resume) in a project you have worked in before, find an old session, and reopen it. Then ask yourself: could you have rebuilt the same context from the repo alone, without reading that transcript? If not, that is the gap. Go fix your project's instruction files so the next session does not need the old chat to know what is correct.
#Daily agent practice
Practice with agents the same way you practice Vim or tmux: small loops, repeated often, with a human checking the result.
Read first
Ask the agent to inspect a config or doc and summarize how it works. Then open the file yourself and see what it missed.
Make one small change
Ask for a narrow edit, review the diff, run the check, and ask the agent to explain the risk in one paragraph.
Extract a durable rule
If the same correction happens twice, decide whether it belongs in AGENTS.md, a doc, a test, or nowhere. Most preferences do not deserve a permanent rule.
#External references
- AGENTS.md — the open cross-tool format for coding-agent instructions.
- Claude Code skills — project skills,
SKILL.md, and skill discovery paths. - Claude Code common workflows — how Claude Code references files and uses project memory.
- Claude Code usage monitoring — the first-party gauge pattern: context, plan limits, and org telemetry.
- OpenAI Codex docs — OpenAI's coding-agent docs and workflows.
- When to use multi-agent systems (and when not to) — Anthropic on the patterns, the costs, and the single-agent default.
- How we built our multi-agent research system — Anthropic's token-cost figures (agents ~4x a chat, multi-agent ~15x) and when the cost is justified.
- Spec-driven development best practices — a working engineering team on the spec-first approach that grounds agents in a checkable contract before they build.