Agent integration

An effective agent integration is less about writing one enormous system prompt and more about maintaining a reliable path from orientation to action.

A layered context model

Agents need different kinds of context at different moments:

1. Workspace orientation explains the overall layout and operating rules.
2. Current goals identify what matters now.
3. Project orientation explains the selected project’s purpose and state.
4. Task context provides the files, issue, request, or failure being handled.
5. Verification evidence determines whether the work is actually complete.

Loading context in that order is faster and safer than asking an agent to scan everything.

The repeatable version of this process is the agent onboarding and bootstrap path.

Instructions are not memory

Instructions define behaviour: safety boundaries, editing conventions, tool use, and review expectations. Project memory records facts: why an architecture was chosen, what is currently blocked, and which experiment produced a result.

Mixing the two makes instructions grow indefinitely and allows stale project details to control unrelated work. Keep operational rules stable and record changing knowledge in project documents.

Safe autonomy

Good agent autonomy has a visible boundary. Read-only investigation can usually proceed freely. Normal edits inside the selected project can proceed when the task requests implementation. Publishing, deletion, credential use, and external communication deserve explicit controls and review.

The aim is not to interrupt every action. It is to make the consequential actions legible.

Handoffs

Chat history is useful working context but poor durable memory. At a handoff, preserve:

• what changed;
• what was verified;
• what remains unfinished;
• any decision whose reasoning would otherwise be lost;
• the exact files or commits that anchor the work.

The next agent should be able to continue from the repository and project notes even if the conversation is unavailable.

When a task uncovers context that is expensive to rediscover and too specific for a general project brief, preserve it in a landmark document.