Agent Planning — See What Your AI Agent Will Do Before It Does It

The Trust Problem

You ask your AI agent to add a README, LICENSE, and copyright headers to a project. It starts running tool calls. You see file reads scrolling by, then writes, then more reads. Is it doing the right thing? Did it miss anything? Is it halfway done or almost finished?

You have no idea. The agent is a black box — you see individual actions but never the full picture. You can't review its plan before it acts, and you can't track its progress while it works. You just have to trust it and wait.

Plan First, Then Execute

Aii CLI v0.16.1 introduces Agent Planning — built-in tools that make the agent's intent visible before any code is touched. The agent creates a checklist, shows it to you, then tracks each task as it progresses.

Let's see it with TaskPilot — a CLI task board built with TypeScript.

> add README.md, LICENSE, and copyright headers to all source files

● I'll help you add the missing project files. Let me explore
  the project structure first.

● Glob(.)
└ Found 117 files

● Read(package.json)
└ 45 lines

● Now let me create a plan:

● TodoWrite(4 tasks)
└ (No content)
☐ Create README.md with project documentation
☐ Create MIT LICENSE file
☐ Add copyright headers to all TypeScript source files
☐ Add copyright headers to all test files

The agent calls TodoWrite before starting any work. Four tasks appear as a visible checklist with ☐ checkboxes. You can see exactly what it plans to do — and interrupt if something looks wrong.

Real-Time Progress Tracking

As the agent works through each task, it marks them in progress and completed:

● TaskUpdate(task-1 → in_progress)
└ (No content)
▪ Creating README.md with project documentation
☐ Create MIT LICENSE file
☐ Add copyright headers to all TypeScript source files
☐ Add copyright headers to all test files

The ▪ indicator shows which task is active, in your theme's accent color. When a task finishes:

● TaskUpdate(task-1 → completed)
└ (No content)
☐ Create MIT LICENSE file
☐ Add copyright headers to all TypeScript source files
☐ Add copyright headers to all test files
✓ Create README.md with project documentation

Green ✓ for completed. The checklist re-renders at every transition — each snapshot stays permanently in your scrollback as an audit trail.

Every Render Is a Snapshot

Unlike ephemeral progress bars that disappear, every task panel render is permanent. Scroll up and you can see exactly when each task started and finished. This matters for reviewing what the agent actually did — especially on long sessions with many file changes.

Five Capabilities

1. Plan Before Execution

The server prompt teaches the agent: for multi-step tasks (3+ steps), always create a plan first. Single-step tasks skip the overhead. The agent uses judgment, not rigid rules.

2. Dependencies

Tasks can declare what they depend on:

✓ Add copyright headers to all .go files
▪ Creating LICENSE file...
☐ Create README.md (blocked by: LICENSE file)

The blockedBy hint shows the user why a task is waiting. The system includes cycle detection — circular dependencies are rejected with a clear error message.

3. Multi-Agent Ownership

When the agent delegates to subagents, you can see who owns each task:

▪ Adding headers... (@explore)
▪ Creating LICENSE... (@plan)
☐ Create README.md

Multiple tasks can be in-progress simultaneously when owned by different agents.

4. Completion Hooks

Configure automated actions when tasks complete:

// .aii/hooks.json
{
  "hooks": {
    "TaskCompleted": [
      { "type": "script", "command": "npm test" }
    ]
  }
}

Every task completion fires the hook. Same pattern as SubagentStop hooks — async, non-blocking.

5. Verification Nudge

After three consecutive task completions without running a verification command (like tests or file reads), the agent gets a gentle nudge:

[System] Consider verifying your recent changes
(e.g., run tests) before continuing.

This prevents the agent from rushing through a plan without checking its work.

Try It

npm install -g @aiiware/aii@latest

Ask your agent to do anything multi-step:

> refactor the auth module to use JWT tokens instead of session cookies
> add unit tests for all exported functions in src/utils/
> set up CI/CD with GitHub Actions, including lint, test, and deploy stages

The plan appears before any code is touched. You stay informed, you can redirect, and you have a full audit trail when it's done.

Agent Planning ships in Aii CLI v0.16.1. Works with all supported LLM providers — Claude, GPT, Gemini, DeepSeek, and any OpenRouter model.