Refine proposed Plans and draft tasks

Refine a Building Task Builder Session until its proposed Plans and draft tasks describe the organization and work you want to publish. Use the browser to edit an existing draft’s type, title, Markdown, Mass or Weight, Plan membership, labels, and dependencies. Plan and dependency choices come only from that same session. Your local AI conversation and CLI handle draft creation, proposed Plan definitions, display order, metric exclusion, and Sprint/Milestone assignments.

Ask your local AI tool to follow the repository guidance for the supported session and draft changes.

1. Ask your local AI tool to select the Building session you want to refine.
2. Ask it to add or revise proposed Plans and draft tasks, assign tasks to Plans or leave them Standalone, then set labels, dependencies, and display order.
3. Open the Building session in Task Builder and inspect the updated Plans, empty Plans, assigned tasks, and Standalone tasks.

Expected result: the session remains Building and contains the proposed Plans and draft tasks you want to review before publication.

Ask your local AI tool to update the session title or summary when the plan’s purpose has changed or needs more context. Keep the session in Building while you revise it.

You can select a different Building session as the active local session, or identify a specific session in a command. If the selected session was published or is no longer available, select a current Building session before asking the AI tool to make changes.

Ask the AI tool to create proposed Plans for useful workstreams or outcomes. A proposed Plan has a stable ID, title, optional Markdown, labels, and zero or more member tasks. Empty Plans are valid, so the AI can establish a grouping before its task breakdown is complete.

Assign or move a draft task using Plan in its browser editor, or ask the local AI tool to use stable task and Plan IDs. Only proposed Plans from the same session are available. Choose Standalone to clear the assignment. Plan membership is organization only: it does not order tasks or create dependencies. Editing a proposed Plan's title, Markdown, or labels still uses the CLI.

Removing a proposed Plan does not remove its tasks. Every former member becomes Standalone, and the remaining Plan display positions compact.

Ask the AI tool to add, remove, or revise draft tasks. A useful draft task has a clear title and Markdown that explains the expected result. Choose Task type when the draft is created: omitted types default to Coding agent, while Person drafts can be prepared for review. You can change the type in a Building draft's browser editor; changing it clears the previous size so you can estimate the work with its new meaning. Optionally supply Mass for a Coding agent draft or Weight for a Person draft; the CLI uses --mass or --weight to match the draft’s current type and does not change that type. Size is optional when saving and publishing. The publication confirmation reminds you to review missing estimates without blocking publication. Published task types are fixed.

Mark a draft excluded from metrics to record that its eventual published task should be omitted from task-derived metrics. The CLI can set the choice when adding the draft or change it independently later with task-builder task set-metric-exclusion; publication preserves the choice. The browser hides the draft metrics row and has no metric-exclusion control. Current metric reports do not apply the persisted choice yet.

Set labels to make the planned work easier to find after publication. Labels must be available to the project; unavailable, conflicting, or ambiguous labels need to be corrected before publication.

Keep unrelated and related task ideas in the same session when that makes them easier to review together. Their display order is for review, not an execution order.

1. Open the Building session and follow a draft task to its detail page.
2. Choose Edit to open the draft’s /edit page. It uses the same task form as published tasks, with Task type, Task title, Task details (Markdown with Edit/Preview), Mass or Weight, Plan, Labels, and Dependencies enabled.
3. Choose Save changes to return to the draft’s detail page. The saved content appears in the draft and session review, and readiness is refreshed.

Plan offers only proposed Plans in this session and Standalone. Dependencies offers other draft tasks in the same session, excluding this draft; published tasks and drafts from other sessions cannot be selected. Labels uses project labels, including inherited organization labels. You cannot create or edit a proposed Plan here, reorder the session, or change Sprint/Milestone assignments.

Changing Task type clears the old size for re-estimation. Enter the new Mass or Weight, or leave it empty; size is optional when saving and publishing. The draft metrics row is hidden; metric exclusion still uses the CLI.

Draft editing uses the same project access as existing Task Builder operations, including inherited organization access and authorized platform support. It does not require a new project role. Published session snapshots remain read-only.

You can leave size empty when saving and publishing. The published task retains that empty estimate, and the publication confirmation includes a nonblocking reminder to review missing Mass or Weight. Save and review your changes before publishing.

Cancel or navigation away from changed content asks whether to discard your unsaved changes. Closing the tab or refreshing uses the browser’s standard unsaved-changes prompt. Keeping the editor open does not save it automatically.

If another browser or CLI update changed the draft, Save is rejected and all unsaved fields stay in the editor. Review and merge the latest saved content before trying again. Reload saved draft replaces your editor with the saved version only after you confirm discarding changed content. If the session was published while you were editing, Save is rejected and all unsaved fields are preserved; the Published snapshot cannot be changed.

Read the Building session with alterac-ai task-builder show <SESSION-NUMBER> before replacing content, Plan membership, labels, or dependencies. Review the draft’s current type, title, Markdown, size, Plan, labels, dependencies, and updatedAt. Human output includes a copyable --expected-updated-at value for each draft; use that draft’s timestamp, not the session timestamp.

For stale-write protection, supply the optional --expected-updated-at <TIMESTAMP> copied from that earlier reviewed draft read. The update replaces title, Markdown, and size together while preserving the current type, Plan, labels, and dependencies; include --mass or --weight to retain a size because omitting the matching option clears it. When a version is supplied and the draft changed, the command rejects the stale version. Run show again, review the current draft, merge your intended changes, then retry with the latest reviewed timestamp. Do not automatically substitute a newer token or retry without reviewing the saved content.

The task set-plan, set-labels, and set-dependencies commands also accept optional --expected-updated-at from that earlier reviewed draft read, including when clearing a relationship. They replace the entire selected field and preserve the other fields. A version fetched internally by a command does not replace the version you reviewed. After any stale replacement, read show again, review the current type, content, and relationships, merge the intended changes, and retry with the newly reviewed token.

Existing commands and older CLIs continue to work without this option. Unversioned replacements keep their previous last-write-wins behavior and can overwrite changes saved since your read. Browser saves always send the reviewed version. Check each command’s --help for --expected-updated-at before using it; install an available release if you want version-checked CLI updates and your executable lacks the option. The command reference owns the syntax for draft content and draft labels, dependencies, and Plan membership.

Ask your local AI tool to assign, replace, or clear a draft's future Sprint membership independently of Plan membership and dependencies. Choose the Sprint number from this project's Sprints page. The target must be Planned, and Sprints must be enabled.

These are draft commands for a Building session. Published task membership instead uses direct task commands, which take task numbers and change live records immediately. Check scheduling command availability if your executable does not recognize either draft scheduling command.

alterac-ai task-builder task set-sprint <DRAFT-ID> --sprint <SPRINT-NUMBER> --session <SESSION-NUMBER>
alterac-ai task-builder task set-sprint <DRAFT-ID> --session <SESSION-NUMBER>
alterac-ai task-builder show <SESSION-NUMBER> --json

The second command clears membership. Omit --session to use the active Building session; an explicit session does not change local selection. Use the stable draft ID and a positive same-project Sprint number. These commands work for Coding agent and Person drafts and do not create Sprints, open them, or change live scope before publication.

Human and JSON output report the assigned Sprint number, title, stable ID, and current state. A failed replacement preserves the previous assignment. Current or Complete targets (reported as Started or Complete by current APIs) must be replaced with a future Planned Sprint or cleared before publication. When Sprints are disabled, clear the assignment or ask a Team Lead to re-enable Sprints in Project Settings. If target details are unavailable, output retains the saved Sprint ID for recovery.

The review website does not provide Sprint assignment controls. Use the CLI to correct saved intent, then check session readiness again. The server rechecks target eligibility at publication; an earlier successful command does not guarantee publication will succeed. See the command reference.

Ask your local AI tool to assign, replace, or clear a draft's optional Milestone target through the CLI, independently of its Plan and Sprint. Choose a positive Milestone number from this project's Milestones page and the stable draft ID from the session. Targets must be enabled and Planned or Started (Current in scheduling rules). Planned assignment needs no classification; Started assignment requires an explicit Correction or Scope change choice.

alterac-ai task-builder task set-milestone <DRAFT-ID> --milestone <MILESTONE-NUMBER> --session <SESSION-NUMBER>
alterac-ai task-builder task set-milestone <DRAFT-ID> --milestone <MILESTONE-NUMBER> --milestone-change scope-change --session <SESSION-NUMBER>
alterac-ai task-builder task set-milestone <DRAFT-ID> --session <SESSION-NUMBER>

Use the first command for Planned targets, the second for Started targets, and the third to clear both target and intent. Omit --session to use the active Building session; explicit selection leaves local selection unchanged. Both draft task types are supported. Human and JSON output show the target identity, number, title, current lifecycle, and saved intent; unavailable details retain the saved ID and intent. Draft intent does not change live Milestone scope before publication.

Correction requires Team Lead authority and counts newly published work as part of the Milestone opening plan. The new task still keeps its real creation, state, and completion times. Choose Scope change when the work should enter scope at publication time.

The review website appends (Planned), (Current), or (Complete) to accessible Sprint and Milestone number/title links. A Current Milestone's saved intent appears separately alongside independent Plan and Sprint metadata. It remains read-only. If session readiness reports a saved Milestone problem, ask your AI tool to use set-milestone to choose an eligible target, save explicit Current intent, remove unused intent from a Planned assignment, or clear both the target and intent. Complete targets are ineligible. If a Planned target becomes Current, explicitly supply intent; the earlier selection does not infer it. Planned assignment and clearing reject --milestone-change. Clearing remains available when Milestones are disabled or the target is unavailable, without enabling or mutating the live feature. A failed assignment or replacement preserves the previous choice. A Team Lead can re-enable Milestones in Project Settings when you want to retain the target.

Review readiness again after the tool saves the change. The server checks access, feature settings, target eligibility, and intent again at publication, so an earlier valid assignment or ready result does not guarantee a later attempt will succeed. See the command reference and Review and publish a session.

Add direct dependencies when one draft must be completed before another can start. Dependencies use stable draft IDs, not display positions. A draft cannot depend on itself, duplicate a dependency, refer to an unavailable draft, or create a cycle.

Reorder draft tasks when a different presentation makes the session easier to review. Task positions are session-local and mutable. Reordering does not change dependencies, and it does not create an execution order.

Use the session number when discussing or selecting a Task Builder Session. Use a stable proposed Plan ID when changing Plan content, labels, or task membership. Use a stable draft ID when changing a particular draft task. Save IDs returned when Plans and tasks are added, or get them from the session’s detailed CLI output.

Do not treat a Plan or task position as an ID. Positions are session-local display context, while stable IDs remain the reliable mutation references.

Open the Building session in Task Builder and inspect the updated summary, proposed Plans, empty Plans, assigned and Standalone draft tasks, task types, labels, dependencies, and order. When the complete set looks right, review its readiness and publish it. Coding agent and Person drafts can publish together once the session is ready.