Skip to main content

​
Planner Agent

A triage agent that reads new GitHub issues, assesses whether they have enough detail, asks clarifying questions, and writes detailed implementation plans for the dev agent to follow.

​
Setup

  1. Copy agent-config.toml and ACTIONS.md into agents/planner/ in your project
  2. Edit agent-config.toml:
    • Set orgs to your GitHub organization
    • Set author to the GitHub username whose issues should be triaged
    • Set triggerLabel to the label that marks issues as needing planning
  3. Run al doctor to verify credentials

​
Trigger modes

Webhook (recommended): Fires when an issue is labeled with plan (configurable via triggerLabel) or when a new comment is added to a labeled issue. Requires a GitHub webhook configured in config.toml — see Webhooks docs. Scheduled: Runs on a cron schedule (default: hourly). Searches for open issues matching the configured org, author, and triggerLabel.

​
How it works

Each run, the agent works on one issue:
  1. Finds an issue to triage (from webhook trigger or scheduled search)
  2. Acquires a resource lock to prevent duplicate work
  3. Reads the issue and all comments for full context
  4. Clones the repo to understand the codebase and project conventions
  5. Assesses whether the issue has enough detail to begin development
  6. Either asks clarifying questions or posts a detailed implementation plan
  7. When the plan is posted, the issue is ready for the dev agent to pick up

​
Pairing with the dev agent

The planner and dev agents work together:
  1. A human creates an issue and labels it plan
  2. The planner agent triages it — asks questions or writes an implementation plan
  3. A human reviews the plan and labels the issue ready-for-dev
  4. The dev agent picks it up and implements the plan