zfinix/aster/aster-planning

Planning and executing multi-step tasks

When a task is too large for a single turn, break it into a plan, get approval, then execute step by step, marking progress as you go.

When to plan

Plan when any of these are true:

• The task spans three or more files.
• The user asks for a plan, roadmap, or breakdown.
• The user says "how would you approach" or similar.
• The task has dependencies between steps.
• You are unsure of the approach and want confirmation before acting.
• A prior attempt failed and you need to regroup.

Do not plan for single-file, single-step changes. Just do them.

The plan file

Plans live at .aster/plans/<slug>.md. The slug is a short kebab-case description: add-rate-limiting, split-app-component. If .aster/plans/ does not exist, create it with edit_file (the directory is created automatically).

Format

---
status: draft
created: <ISO 8601>
updated: <ISO 8601>
---
 
# Plan: <one-line goal>
 
## 1. <phase name>
-[ ] <concrete, verifiable task>
-[ ] <another task>
 
## 2. <next phase>
-[ ] <task>

Rules

• status: draft (not yet approved), active (approved, executing), done

(all tasks complete), abandoned (no longer pursuing).

• Phases are ordered groups of related tasks. Most plans have 2–5 phases.
• Tasks are concrete and verifiable. "Refactor the auth module" is vague;

"Extract validate_token from auth.rs into auth/validation.rs" is concrete. Every task should produce a visible change: a file exists, a test passes, a function is extracted.

• Checkboxes: [ ] pending, [~] in progress, [x] done, [!] blocked.

Only one task in progress at a time.

The planning loop

1. Create

Write the plan file with status: draft. Include enough detail that the user can judge the approach without reading your mind. Keep it at the level of "what changes and in what order," not "which key I'll press."

2. Present

Show the plan to the user in a few lines: the goal, the phases, and one sentence on the approach. Ask whether to proceed. Do not begin executing until they confirm.

3. Execute

For each task, in order:

1. Mark it [~] (in progress). Update updated in frontmatter.
2. Do the work. Keep changes scoped to the task.
3. When the task is done and verifiable, mark it [x] and report what changed in

one line.

1. Move to the next task.

After each phase completes, pause briefly to report: "Phase N done: <summary>. Continuing to phase N+1." This gives the user a natural place to intervene.

4. Complete

When every task is [x], set status: done, update updated, and report a one-paragraph summary: what was done, what files changed, any follow-ups the user should know about.

Handling deviations

• A task turns out to be unnecessary. Mark it [x] with a strikethrough and a

note: ~~extract the parser~~ — parser is already reusable.

• A task needs more work than expected. Add sub-tasks under it, indented.

Keep the parent as [~] until all sub-tasks are done.

• The plan is wrong. Stop. Explain what you learned and propose a revised

plan (a new phase, reordered tasks, or a different approach). Do not silently deviate.

• Something is blocked. Mark it [!] with the reason and continue with the

next unblocked task. Return to blocked tasks when the blocker clears.

Abandoning a plan

If the user changes direction or the plan no longer makes sense, set status: abandoned, add a one-line reason at the top of the body, and stop. Do not delete the file — it is a record of what was considered.

Cleanup

When a plan is done or abandoned, leave the file in place. The user can delete .aster/plans/ whenever they want; do not do it unprompted.