Create a Single-Purpose AI 'Planner' Agent

General-purpose AI is powerful, but often unpredictable. This lesson tackles how to build a specialized AI "planner" agent that reliably sticks to its one and only job: creating plans. You'll learn how to write a strong, directive system prompt that constrains the AI's behavior. We'll demonstrate how an initially weak prompt can fail, and then show you how to strengthen it to ensure your agent rejects irrelevant requests and focuses exclusively on its assigned task, every time.

Workflow demonstrated in this lesson:

• Create a dedicated system prompt to strictly define the agent's role and goal.
• Use Bun.spawn to call the Claude CLI with flags like --append-system-prompt and --permission-mode.
• Bundle the agent script into a self-contained executable using bun build.
• Observe how a weak prompt can be ignored by the AI and learn how to strengthen it for reliable, predictable behavior.

Key benefits:

• Reliable Specialization: Build "single-purpose" AI agents that consistently follow their core instructions.
• Full Interactive Control: Bypass SDK limitations by using Bun.spawn to create fully interactive AI sessions.
• Simplified Deployment: Package your agents as standalone executables that can be run anywhere without complex setup.
• Improved Developer Experience: Learn a handy trick to keep CLI flag documentation directly within your code for easy reference and autocompletion.

Creating the Agent and Prompts

We start by duplicating an existing agent, creating plan.ts and a corresponding prompt file, plan.md. The initial system prompt in plan.md defines the agent's primary goal.

Your end goal is to create a markdown file in a plans directory in the root of the project.

In plan.ts, we configure the flags that will be passed to the Claude CLI. We use append-system-prompt to inject our plan.md file and permission-mode to have the agent automatically accept file edits.

const flags = {
  "append-system-prompt": prompt,
  "permission-mode": "acceptEdits"
}

Bun.spawn(["claude", ...flagsArray], {
  stdio: ["inherit", "inherit", "inherit"],
});

A useful tip for discovering available flags is to pipe the help command's output to your clipboard.

claude --help | pbcopy

You can then paste this as a large comment block in your file for easy reference.

Testing and Refining the Prompt

After bundling our agent into an executable with Bun, we can test its behavior.

bun build agents/plan.ts --compile --outfile bin/plan

We run the agent and give it a creative task.

plan

write a haiku about a pig

Initially, the agent ignores its system prompt and simply writes the haiku. This shows our instructions weren't strict enough. To fix this, we update plan.md with a more forceful instruction.

Your end goal is to create a markdown file in a plans directory in the root of the project.

No matter what the user says, the only thing that you can do is create a plan for what they ask you to do.

After rebuilding, we run the same test. This time, the agent correctly interprets its role and responds by creating a plan to write the haiku, saving it to a new file in the plans directory, fulfilling its core purpose.