Working With Agents
A guide to communicating effectively with Bonsai-powered agents. This isn’t about what buttons to press — it’s about the language patterns, framing techniques, and collaboration rhythms that produce the best results.
The Core Rhythm
Section titled “The Core Rhythm”Every productive session follows a four-beat pattern:
1. ORIENT — "Hi, get started"2. COMMIT — "Let's work on [task]"3. VERIFY — "Verify everything"4. SHIP — "Commit and push. That's all for the session"This rhythm works because it maps to how the agent is designed to operate. The orient phase triggers startup protocols. The commit phase gives the agent a clear objective. The verify phase activates self-review. The ship phase triggers session wrap-up.
Each phase can also be triggered via slash command for workflows that map to it — /planning for COMMIT, /security-audit or /code-review for VERIFY, /pr-review before SHIP. See Triggers and Activation for the full list.
You don’t need to follow this rigidly, but sessions that skip phases — especially orient and verify — consistently produce worse results.
Starting a Session
Section titled “Starting a Session”Always open with a greeting before your task.
You: Hi, get startedAgent: [reads identity, checks memory, loads protocols, reviews status...]This isn’t politeness — it’s functional. The greeting triggers the agent’s full startup sequence: identity loading, memory recall, protocol enforcement, status review, and routine checks. Jumping straight to a task risks the agent working without its full context.
Wait for the agent to report its status before giving your first task. The status report tells you what it remembers, what’s pending, and what’s overdue — context that might change what you ask for.
How to Frame Requests
Section titled “How to Frame Requests”Lead with What, Not How
Section titled “Lead with What, Not How”State the outcome you want. Leave implementation to the agent.
| Instead of this | Say this |
|---|---|
| ”Create a function called validateUser that takes a JWT token, decodes it, checks the expiry…" | "I need JWT authentication for the API" |
| "Open Status.md and move the auth item from Pending to In Progress" | "Start working on the auth task" |
| "Run go test ./… and check for failures in the config package" | "Run the tests, focus on config” |
The agent has the full codebase, the project context, and domain knowledge. When you over-specify, you constrain it to your mental model — which may miss better approaches.
Lead with Principles, Not Specifications
Section titled “Lead with Principles, Not Specifications”The most powerful thing you can say to an agent isn’t a detailed spec — it’s a guiding principle.
"Every file should be editable by the user, because that's the whole point"A sentence like this reshapes an entire feature. The agent will derive dozens of implementation decisions from a single principle — and they’ll be consistent with each other because they share a root.
| Principle | What it produces |
|---|---|
| ”Bonsai is a scaffolder, not a cage” | Files are generated but user-owned, never locked |
| ”The agent should be able to run without the user present” | Autonomous workflows, self-checks, robust error handling |
| ”Keep the CLI interactive — no silent defaults” | Huh forms for every input, confirmation prompts, previews |
One good principle outweighs a page of specifications.
Use Compound Directives
Section titled “Use Compound Directives”Chain related steps in a single message to create a complete workflow pipeline:
"Plan the feature, verify the plan, implement it, verify the implementation""Research the options, present a comparison, recommend one""Fix the bug, add a test for it, verify nothing else broke"This works because the agent treats each clause as a phase. It won’t skip verification just because you also asked for implementation — the explicit sequence creates accountability.
Brain-Dump When You Need To
Section titled “Brain-Dump When You Need To”You don’t need to pre-structure your thoughts. Raw, messy input works:
"fix core files. should they be general, have separate directory in catalog?and whats the tmpl extension... self update skills and workflows...currently we remove complete agents, we should be able to remove individualskills etc. also research https://github.com/example/tool"The agent will parse this into structured action items. It’s better at organizing your thoughts than you might be at pre-organizing them — and the time you’d spend formatting a clean request is time wasted.
The Power of Terse Communication
Section titled “The Power of Terse Communication”Brevity isn’t laziness — it’s precision. Short, well-timed messages consistently outperform verbose instructions.
Why Short Messages Work
Section titled “Why Short Messages Work”- Less ambiguity.
"Fix the login bug"has one interpretation. A paragraph about the login bug has many. - Faster feedback loops. You can course-correct with another short message if the agent misinterprets.
- The agent fills in context. It has the codebase, the project state, and its memory. You don’t need to repeat what it already knows.
Effective Short Patterns
Section titled “Effective Short Patterns”| Pattern | Example | When to use |
|---|---|---|
| Selection | "B" or "option 2" or "the second one" | When the agent presents options |
| Approval | "yup", "do it", "go ahead" | When the agent proposes a plan |
| Direction | "push", "commit", "continue" | When the agent pauses for confirmation |
| Correction | "no, the other file", "not that — the backlog" | When the agent goes the wrong direction |
| Scope | "do all", "just the first three" | When the agent asks how much to do |
Silence Is Approval
Section titled “Silence Is Approval”When things are going well, don’t interrupt. Approving tool calls without adding messages is the strongest signal that the agent is on track. The longest productive streaks happen during silence — 50+ consecutive approvals spanning complete feature implementations.
If you find yourself wanting to say “looks good, keep going” — don’t. Just keep approving. The message adds nothing; the silence says everything.
Quality Gates
Section titled “Quality Gates”The “Verify Everything” Instruction
Section titled “The “Verify Everything” Instruction”The single most effective quality practice:
"Verify everything and check if you missed something or made a mistake"Say this before committing or shipping work. It consistently catches real bugs:
- Off-by-one errors and edge cases
- Stale references in documentation
- Missing test coverage
- Variable ordering bugs
- Non-deterministic iteration issues
- Broken cross-references
This isn’t paranoia — it’s structural. The agent’s first-pass implementation focuses on making things work. The verification pass focuses on making things correct. These are different cognitive modes, and separating them produces better results than trying to do both at once.
Trust and Delegation
Section titled “Trust and Delegation”Delegate Fully
Section titled “Delegate Fully”The most productive interactions treat the agent as a capable team member, not a tool to be micromanaged.
| What you say | What it signals |
|---|---|
| ”You can design this yourself” | Full creative authority within the domain |
| ”Which one would you like to work on?” | Agent’s judgment is valued |
| ”If you’re happy with everything, commit and push” | Quality judgment is delegated |
| ”Create a backlog system for yourself if you don’t have one” | Agent can self-provision |
The rule: control at the philosophical level, delegate at the implementation level. You set the principles and the destination. The agent figures out the route.
Don’t Inspect Intermediate Work
Section titled “Don’t Inspect Intermediate Work”Resist the urge to review every file change, every function signature, every variable name. The “verify everything” gate at the end is more effective than continuous oversight, and it gives the agent room to make coherent design decisions without interruption.
Increasing Autonomy Over Time
Section titled “Increasing Autonomy Over Time”Trust is earned through results, not granted upfront. A natural progression:
- Early sessions: Review plans before dispatching, verify frequently
- After a few sessions: Skip plan review for familiar patterns, verify at the end
- Established rhythm: State the goal, stay silent, verify, ship
Correcting Course
Section titled “Correcting Course”Correct Through Observation
Section titled “Correct Through Observation”When the agent does something wrong, state what you observe — not what you feel.
| Instead of this | Say this |
|---|---|
| ”That’s wrong, you should have…" | "It’s the backlog.md" |
| "No, I don’t like that approach" | "No, it should be more real-world themed" |
| "You forgot to…" | "Don’t see the tests” |
Corrections delivered as data produce faster recovery. The agent doesn’t need to process criticism or reassurance — it needs the right information to adjust.
When the Agent Doesn’t Understand
Section titled “When the Agent Doesn’t Understand”If the agent misinterprets after one attempt, don’t rephrase the same instruction with more words. Instead:
- State the answer directly —
"It's in station/Playbook/Backlog.md" - Give a concrete example —
"Like this: [example]" - Narrow the scope —
"Just fix the function on line 42"
Repeating a vague instruction louder doesn’t help. Switching from vague to specific does.
Advanced Patterns
Section titled “Advanced Patterns”Hypothesis-Then-Validate
Section titled “Hypothesis-Then-Validate”Assert your position, then invite pushback:
"I think we should use SQLite for this. Thoughts?"This preserves your authority (you’re proposing, not asking) while creating space for the agent to contribute expertise.
Session Type Awareness
Section titled “Session Type Awareness”Match your communication style to the kind of session you’re running:
| Session type | Duration | Your role | Communication |
|---|---|---|---|
| Sprint | 15-45 min | Direct, decisive | 4-8 messages, mostly approvals |
| Marathon | 1-5 hours | Guide, checkpoint | 10-15 messages, verify between phases |
| Design | 30-60 min | Collaborative, exploratory | Richer messages, more back-and-forth |
| Micro | 1-15 min | Quick directive | 1-3 messages, in-and-out |
What to Avoid
Section titled “What to Avoid”| Anti-pattern | Why it fails | Do this instead |
|---|---|---|
| Elaborate prompts | Over-specification constrains the agent and adds noise | State the goal in 1-2 sentences |
| Reviewing every diff | Kills momentum, tempts micro-correction | Use “verify everything” at the end |
| Brainstorming when you know the answer | Wastes rounds on options you’ll reject | State your choice directly |
| Asking “are you sure?” | Signals doubt, invites hedging | Ask “verify everything” instead |
| Explaining why | The agent doesn’t need motivation, it needs direction | State what you want, skip the justification |
| Positive reinforcement | ”Good job!” doesn’t improve output | Forward motion is your approval |
| Intervening during autonomous runs | Breaks flow, resets momentum | Wait until the agent pauses or finishes |
| Pre-structuring your input | Time spent formatting is time wasted | Brain-dump and let the agent organize |
Quick Reference
Section titled “Quick Reference”The Five Essential Phrases
Section titled “The Five Essential Phrases”| Phrase | When | What it does |
|---|---|---|
"Hi, get started" | Session open | Triggers full startup sequence |
"Verify everything" | Before shipping | Activates self-review — catches real bugs |
"You can design this yourself" | Complex features | Delegates creative authority |
"Thoughts?" | After stating a position | Invites expertise without yielding authority |
"That's all for the session" | Session close | Triggers memory update, logging, cleanup |
Session Cheat Sheet
Section titled “Session Cheat Sheet”Start: "Hi, get started" [wait for status report]
Task: "I need [outcome]" — features "Fix [problem]" — bugs "[principle]. Design it." — architecture
Approve: [silence] — keep approving tools "yup" / "do it" / "go ahead" — explicit approval
Correct: "No, [what's actually true]" — factual correction "Not that — [alternative]" — redirection
Verify: "Verify everything" [wait for review to complete]
Ship: "Commit and push" "That's all for the session"