Plan work with Task Builder
Plan work with Task Builder
Use a local AI planning conversation to prepare and publish proposed Plans and task drafts for review.
Use Task Builder when you want to turn a local AI conversation into proposed Plans and structured task drafts before creating project work. Create a task directly when one implementation-ready task is already clear; use Task Builder for related new work, many tasks prepared together, or a proposed Plan.
Task Builder is a good default when you build tasks with a local AI tool. Create a task directly when you already know exactly what to write and prefer to enter it yourself; complete your first task takes that shorter path. A Task Builder Session can improve the quality of the resulting tasks by making proposed work visible and reviewable; it does not guarantee that every suggestion is correct.
| If you need to... | Use | What happens |
|---|---|---|
| Create one known, implementation-ready task | Create and edit a task | One Backlog task is created immediately. |
| Inspect, change, or delete a published task | Task and work-run commands | Direct commands operate on published records immediately. |
| Inspect the current tasks in a published Plan | Task and work-run commands | You can see the current members and update each task individually. |
| Prepare related new tasks, many one-off tasks together, or proposed Plans | Task Builder | Your local AI tool creates Building drafts for you to review and explicitly publish together. |
| Explore an idea without committing to a plan | Continue the conversation | No task or draft is created until you explicitly want durable planning. |
Direct commands inspect or operate on published project records. task list and task get are read-only; task create, task update, and task delete change published records immediately. Direct write commands do not create a review-before-publication stage or bulk-edit the members of a Plan. Task Builder only changes draft Plans and draft tasks in a Building session; it cannot import, revise, regroup, or republish existing published tasks or Plans.
Published task, Plan, and Task Builder identifiers have different scopes. taskNumber and planNumber identify published records within one project. sessionNumber identifies a Task Builder Session. Stable draftPlanId and draftId identify drafts; displayed positions can change and are not mutation identifiers. See Read CLI output and identifiers for the complete reference.
Your local AI tool owns the planning conversation. It can help you explore a goal, split work into drafts, and revise the plan. alterac.ai stores the structured results in a Task Builder Session and gives you the review and publication controls.
This separation is deliberate. A useful conversation does not create project work by itself, and a local AI tool cannot publish Plans or tasks for you. You choose the visible Publish action in alterac.ai only after you have reviewed the whole session. Its label describes the session contents, such as Publish Tasks for a task-only session.
A Task Builder Session is one project-scoped drafting workspace. A session contains a summary, zero or more proposed Plans, and zero or more draft tasks. A draft task belongs to one proposed Plan or remains Standalone, and a proposed Plan may remain empty.
A session has two lifecycle states:
- Building means the session is still a set of proposed Plans and tasks. Its drafts are not project Plans or tasks and do not appear in normal project workflows.
- Published means you chose to publish the complete reviewed session. The session becomes a historical record of the drafts that created normal project Plans and tasks.
IsArchived is a visibility setting, not another lifecycle state. You can archive either a Building or Published session to hide it from the usual view without publishing, unpublishing, or canceling anything.
A proposed Plan has a title, optional Markdown, labels, a deterministic session-local position, and zero or more member tasks. Plan membership organizes work for review and publication; it does not create dependencies or execution order.
Each draft task can have a title, Markdown description, Mass, labels, direct dependencies, an optional proposed Plan membership, and a place in the session’s display order.
The Task Builder Session number identifies the session for people. Each proposed Plan and draft task also has its own stable ID for changes made from the local AI conversation. Plan and task positions are separate session-local display sequences that can change when drafts are removed or reordered. A position is not an ID, is not execution order, and does not create a dependency.
Start or continue a local planning conversation, then start a planning session. The local AI tool follows the repository guidance for supported session, proposed Plan, and draft-task changes. After publication, the resulting Plans and tasks follow their normal project workflows.