Plans¶
Plans are durable, append-only task ledgers the agent can create and update
through the plan_* tools. A plan records a goal, the facts and assumptions it
rests on, the decisions taken, and a set of tasks that may depend on one another
to form a DAG. It outlives any session: it is stored in the Wallah data
directory and can be read and updated by any session, including concurrently.
A plan is referenced by its P<n> id (e.g. P3) or by its human name. Tasks
and other entries are referenced by their own ids: T<n>, F<n> (facts),
A<n> (assumptions), and D<n> (decisions). Ids are assigned when an entry is
added and are never reused, so a reference stays valid even after an entry is
removed.
| Tool | Purpose |
|---|---|
plan_create |
Create a new plan with a goal and a name. It starts with no tasks |
plan_get |
Show a plan's summary: goal, revision, counts, recent tasks, count of tasks ready to run |
plan_next |
Show the tasks that can be done right now |
plan_show |
Show a plan in full, one entry by id, or the pending frontier |
plan_add |
Add a task, with dependencies and acceptance criteria |
plan_update |
Move a task to pending, in_progress, or blocked, with an optional note |
plan_block |
Block a task, recording the reason |
plan_finish |
Finish a task, recording the evidence |
plan_edit |
Edit a task's title, dependencies, and/or acceptance |
plan_remove |
Remove (tombstone) a task, fact, assumption, or decision |
plan_fact |
Record a fact about the world the plan works in |
plan_assume |
Record an assumption the plan rests on |
plan_invalidate |
Invalidate an assumption, recording the reason |
plan_validate |
Re-validate an assumption |
plan_decide |
Record a decision, with an optional reason |
plan_rename |
Rename a plan, or clear its name |
plan_goal |
Revise a plan's goal |
What is doable¶
plan_next returns the tasks that are ready right now: a task is ready when
it is not removed, its status is pending, and every task it depends on is
done or removed. A task whose dependencies are not yet done is simply not
ready. That is distinct from a task that is explicitly blocked, which carries
a reason.
A task's dependencies are the ids of existing tasks (like T1), not titles,
and must not form a cycle. Both are checked when a task is added or edited. A
removed task counts as a satisfied dependency for its dependents.
The journal¶
Each plan is an append-only JSONL file of events, stored under the Wallah data
directory. The current view (the plan you see from plan_get, plan_show, and
plan_next) is derived by replaying that journal. Nothing about a plan is
stored as mutable state. Every plan_* tool appends one event.
The same operations are available outside an agent session through the
wa-plan binary, for debugging and scripting:
wa-plan create | list | get | show | add | edit | update | block | finish
| remove | fact | assume | invalidate | validate | decide
| goal | rename | log
wa-plan log P<n> dumps a plan's raw journal, one record per line.