AI Planner
The AI Planner turns a feature description and repository context into an editable specification that can be exported or converted into a ticket.
When to use the Planner
Use the Planner when work needs clarification, trade-off decisions, and acceptance criteria before implementation.
It is appropriate for cross-cutting features, incomplete stakeholder requests, and work supported by screenshots or existing specifications. Use a ticket directly when the requirements are already complete and approved.
Planning steps
The six steps move from configuration to an approved document.
| Step | Operator action | Result |
|---|---|---|
| Configuration | Select the workspace, model, starting branch per repository, description (up to 5,000 characters), and up to 5 attachments. | The plan receives repository and request context. |
| Understanding | Review the restated request. | Scope misunderstandings can be corrected early. |
| Clarifications | Answer open questions. | Requirements and boundaries become explicit. |
| Recommendations | Select or revise proposed directions. | Trade-off decisions are recorded. |
| Specifications | Wait while the document is generated (progress is shown; Retry on failure). | Requirements, user flows, technical constraints, acceptance criteria, failure cases, out-of-scope items, and page wireframes are assembled. |
| Review | Edit, compare versions, undo or redo changes, request assisted edits, and Finalize Plan. | The final plan is ready for export or ticket creation. |
Do not treat generated content as approved by default. Confirm repository assumptions, security requirements, deployment impact, and acceptance criteria before creating a ticket.
Auto-Answer modes
Auto-Answer can complete clarification and recommendation choices when an operator does not need to approve each answer.
| Mode | Behavior |
|---|---|
| Disabled | Requires operator answers. |
| MVP | Prefers the smallest viable scope. |
| Balanced | Balances scope and implementation cost. |
| Features Rich | Prefers broader functionality. |
| Custom | Applies your decision policy (up to 1,000 characters). |
Select the mode with the Auto Answer control. Use Disabled for security-sensitive, contractual, migration, or production-operability decisions. Review all automatically selected decisions before finalizing the plan.
Plan lifecycle
The lifecycle shows whether a plan is editable or closed. A temporary session-host disconnect during repository setup is recovered automatically; if setup cannot complete, the plan is canceled and hidden, and its attachments are removed.
| Status | Meaning |
|---|---|
| Draft | Planning is in progress. A failed step stays in Draft with Retry. |
| Completed | Finalize Plan was selected. |
| Canceled | Planning was stopped or setup failed. |
| Error | Ticket Plans only: generation failed; use Retry in Ticket Details. |
Your plans that are not hidden appear in My Work with progress. Updates appear automatically for connected viewers. Only one action can run on a plan at a time; a second one is rejected with "Another operation is in progress" — wait for the current action to finish. Models that run through a local command-line tool cannot be used by the Planner.
Ticket Plans
Ticket Plans use the same document generation, validation, version history, comparison, AI-assisted editing, undo, redo, and review experience inside Ticket Details.
- The planning session stays hidden from the general Session UI.
- Planning and Implementation use the same ticket branch, host, and working copy.
- Editing, undo, and redo are available only while the Plan is awaiting approval; they lock during generation, revisions, retries, failures, and after approval.
- Reviewer feedback remains attached to the Plan through revision failures and approval.
- Approval locks the document and advances the ticket to Implementation.
- Requesting changes resumes the same Plan with reviewer feedback.
- A failed Plan stays blocked until its retry succeeds.
- Workspaces can skip approval of successful Plans with Skip Plan Approval.
- Approving a Plan requires Approve Developer; retrying a failed Plan requires Manage Tickets.
Choose the Plan model when starting the ticket or in a Start Ticket Template. Configure Plan tools in Management → System → Plan, workspace guidance in Workspace Guidelines → Plan, and Plan Stage by Default / Skip Plan Approval on the workspace Tickets tab. See Tickets → Plan stage.
Repository isolation
Each plan uses an isolated working copy so repository inspection does not alter active development sessions.
Select the correct starting branch for every repository before starting. If the repository or branch is unavailable, correct workspace Git access and retry the plan action.
Attachments
Attachments provide source material for the plan.
Add up to 5 files (PNG, JPEG, GIF, WebP, PDF, TXT, or Markdown; 10 MB each) during configuration — attachments cannot be added after the plan starts. Remove secrets and unrelated customer data before upload, and verify that generated requirements accurately reflect the attachment.
Export and ticket creation
The Review step produces an operator-controlled handoff.
- Copy places the current specification on the clipboard.
- Download saves the current specification as Markdown.
- Create Ticket creates a Pending ticket from the plan immediately, linked to the plan; Create & Start also starts it.
The ticket is created without an intermediate form, so review the specification first and adjust the ticket's assignees, model, and approvals afterward in Ticket Details. See Ticket configuration.
Permissions
Permissions control plan creation and access to other users' plans.
| Permission | Capability |
|---|---|
| Create Plans | Start a plan. |
| View All Plans | Open other users' plans (read-only, by direct link). |
| Manage Plans | View, edit, and cancel other users' plans. |
Workspace membership and repository access still apply.
Troubleshooting
These checks address common planning failures.
| Symptom | Check |
|---|---|
| Plan cannot start | Confirm workspace membership, model availability, host availability, repository credentials, and selected branches. |
| Step appears stuck | Wait for the active action, refresh once, and review the visible failure message before retrying. |
| Ticket Plan failed | Open Ticket Details, review the Plan failure, confirm capacity and host availability, then select Retry. |
| Answers are not reflected | Return to the affected step, confirm the answer, and regenerate the specification. |
| Assisted edit is unsuitable | Undo to the previous version, narrow the instruction, and review the resulting comparison. |
| Ticket creation is unavailable | Confirm ticket permissions in the target workspace. |
| Attachment context is wrong | Attachments cannot be changed after start; start a new plan with the intended files. |
| Plan was canceled during setup | Repository setup failed; check repository credentials, branches, and host availability, then start a new plan. |
| Model is unavailable in Planner | Command-line models and tiers set to them cannot be used; pick a directly hosted model. |