@agimon-ai/po-plan

Create and review stored plans in Po with file edits withheld, explicit completion, and normal, debug, or code review flows.

Part of the Po distribution.

Plan mode withholds the edit and write tools while it is active, and adds its own tools without removing anything else other packages supply. Planning instructions still require read-only exploration until the user approves implementation, except for saving the plan through write_plan. bash stays available, so Plan raises the cost of an accidental write rather than preventing one. Plan is not a sandbox or a repository permission boundary.

Alpha: planning flows and tool contracts may change between releases.

Requirements

• Node.js 24 or newer

Install

The seeded modes.yaml selects Plan in default.packages. Keep it there or select it through a layer; Plan remains inactive until requested.

Start and exit

Normal planning expects repository exploration and delegation where available. Debug planning separates verified evidence from hypotheses. Code Review planning inspects changes read-only, reports actionable findings with severity and file references, and proposes scoped fixes with validation steps. All three flavors use the same stored-plan and explicit approval workflow. Saved Fable sessions resume as normal planning while retaining their original model settings. The child capability ceiling comes from po/subagent-policy and is removed when either provider or Plan unloads.

A model restoration failure leaves Plan active and reports the failure rather than pretending the session was restored.

Write and complete a plan

write_plan accepts visible Markdown plan content and writes a unique file under ~/.po/plans by default. It refuses a plan that is empty or was not presented in visible assistant output, and it validates the destination before writing. The plan path and content become visible session state.

After a plan exists, complete_plan asks whether to exit or continue planning. The user must explicitly approve exit. If the selected mode already exposes ask_user_question, Plan reuses it; it does not activate an omitted feedback layer.

Read and edit the plan in the cockpit

Once write_plan succeeds, a plan group appears in the cockpit's activity dock and stays for the rest of the session, including after Plan mode is exited: that is when the agent starts implementing, which is when the plan is most worth having open. The row opens a temporary tab that renders the plan as Markdown, with a source view that edits it and saves back to the plan file.

The agent reads the plan file at the start of every turn, so a saved edit is what it implements. A save carries the hash the reader loaded and is refused if the agent rewrote the plan in the meantime, rather than overwriting it.

The cockpit reaches the plan through this package's session API, mounted at /api/plugin/plans. Because a host imports the built entry, a change here needs pnpm build and po sync before a running cockpit sees it.

Configure models and storage

Put planning settings in the repository's .po/config.yaml or the global ~/.po/config.yaml:

modes:
  planning:
    main:
      model: provider/planning-model
      thinking: high
    subagents:
      model: provider/research-model
      thinking: medium
    plansDirectory: ~/.po/plans

main controls the planning model, subagents controls delegated research defaults, and plansDirectory can be absolute, repository-relative, or under ~. When session artifacts are available, plans are stored under <artifactRoot>/plans/ instead; plansDirectory is the fallback. Planning and delegated model calls consume provider quota.

Public API

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint

Maintained by Agimon.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.