Phase Planner

The Phase Planner is where you split a project into phases and decide which ones are in progress. Connected agents read these phases to learn what work is in scope right now.

A phase is a scoped unit of work. It has a name, a status, a position in the project order, an optional description, and optional path globs that tell the drift engine which files belong to it. Each phase holds tickets, the individual pieces of work you track on the Tickets board.

Where to find it

Select Phase Planner in the sidebar (item 3), or press Ctrl+3. The panel works on the project you have open. If no project is selected, it shows "No project selected."

What you see

The panel header shows 2 buttons: Generate from Architecture and Add Phase. Below them are 2 tabs, List and Dependency Graph.

The List tab shows one card per phase, in project order. Each card has, from left to right:

• A drag handle for reordering.
• An arrow that expands or collapses the card.
• The phase name.
• A status badge that is also a menu (pending, active, complete, skipped).
• The phase's position number, such as #2.
• A trash icon that deletes the phase.

An expanded card shows 3 more sections:

• Description, a text box you can resize by dragging its bottom edge. Edits are kept only when you click Save, which stays disabled until the text changes.
• Path Globs, the list of file patterns that belong to the phase.
• Tasks (N), a read-only list of the phase's tickets with each ticket's status. You manage the tickets themselves on the Tickets board.

The Dependency Graph tab draws each phase as a box with its name, status, and "Phase N" position. Arrows connect phases that record a dependency on another phase. You can drag boxes, zoom, and pan. Clicking a box opens the Tickets panel with that phase selected. The panel has no control for editing dependencies.

How to use it

Create a phase

1. Click Add Phase.
2. Enter a Name. The phase is not created without one.
3. Optionally write a Description. The placeholder suggests what to cover: what the phase delivers, its boundary, and its acceptance criteria.
4. Click Create Phase.

A new phase starts as pending and goes to the end of the list.

Reorder phases

Drag a card by its handle to a new position. The app renumbers every phase whose position changed. Order matters to agents, as described under "How agents use phases" below.

Change a phase's status

Click the status badge on a card and pick a status:

More than one phase can be active at the same time. A planned feature phase and an urgent bugfix phase can run side by side, and the app never forces a single active phase.

When a phase changes to complete, Vibeless saves a milestone snapshot. You can find it under Logs on the Version History tab.

Set path globs

Path globs are file patterns, written relative to the repository root, that mark which files belong to the phase.

1. Expand the phase card.
2. In Path Globs, type a pattern into the box, for example src/**.
3. Click the plus button. The pattern saves immediately.
4. To remove a pattern, click the trash icon next to it.

Use ** to match any number of folders, as in src/billing/**. Use * for any characters within a name, as in docs/*.md. Adding a pattern that is already in the list does nothing.

The editor does not check pattern syntax when you add it. The drift engine checks each pattern when it runs. It skips a malformed pattern and records a diagnostic for it. If every pattern in a phase is malformed, or the list is empty, the phase boundary is reported as not enforceable instead of producing drift findings. If the stored value itself cannot be read, the editor shows "Could not parse existing globs; starting from an empty list." Your next add or remove replaces the unreadable value.

Delete a phase

1. Click the trash icon on the card.
2. Read the confirmation. Deleting a phase permanently deletes every ticket in it, along with those tickets' comments and attached reports.
3. Click Delete Phase to confirm, or Cancel.

Deletion cannot be undone.

Generate phases from your architecture document

Generate from Architecture asks an LLM to propose phases based on the project's architecture document. It is an LLM feature, so it needs a paid plan and spends credits from your plan's budget each time you run it. The free plan has no LLM features.

1. Make sure the project has an architecture document. If it does not, the app shows "No architecture document yet. Add one in the Spec Editor first."
2. Click Generate from Architecture.
3. If the project already has phases, choose how to apply the results, then click Generate. If it has none, generation starts on its own.
   • Append (keep existing) adds new phases after your current ones.
   • Replace all builds a fresh list.
4. Wait while the app reads the architecture document.
5. Review the proposed phases. Nothing has been created yet. For each phase you can:
   • Clear its checkbox to leave it out.
   • Edit its name.
   • Edit its description.
   • Read the proposed tickets, listed after "Tasks:".
6. Click Create selected phases.

The app creates each selected phase, numbers them in the order shown, and creates its proposed tickets. The model's acceptance criteria, deliverables, and dependencies are stored with each phase. Generated phases start as pending and have no path globs. Add path globs yourself before you rely on phase drift.

With Replace all, the app creates the new phases first and deletes the old ones only after every new phase is created. Deleting the old phases also deletes their tickets. If something fails partway, your existing phases stay, and you may see duplicates to remove by hand. If a single proposed ticket fails to save, its phase is still created.

Clicking outside the dialog during review does not close it. Use Cancel to discard the proposal.

How agents use phases

Agents connected through MCP can read phases but never change them. No agent tool sets a phase's status, order, description, or path globs. Phase status is set only by a person in this panel.

• vibeless_get_phase_spec returns one phase with its description, acceptance criteria, deliverables, dependencies, boundary, and full ticket list. An agent can pass a phase id or the word current.
• current resolution. current means the active phase with the lowest position number. If other phases are also active, the response lists them by name so the agent can request them explicitly. If no phase is active, the agent gets an error telling it to ask you to activate one in the Phase Planner.
• vibeless_list_open_tasks returns open tickets across all phases, and each row carries its phase name. An agent can pass a phase id to see one phase only.
• SessionStart digest. The project summary that Claude Code and Codex receive at session start does not include phases or the active ticket. Agents fetch that workflow state on demand with the tools above.

Agents can create tickets inside a phase and change ticket status.

How it connects to the rest of Vibeless

Path globs drive the phase boundary drift check. Drift is a gap between what the project record says and what the code does. The check flags each changed file that falls outside the path globs of the lowest-numbered active phase as a medium-severity finding. It runs in 2 places. When the file watcher sees a change in the open project, the app shows a "Drift detected" message. When an agent runs vibeless_run_drift_check, the finding appears in the agent's report. The Drift Log tab in Logs lists file changes for review, not these findings. See Logs.

The drift check uses only that one phase. If several phases are active, files that belong to a higher-numbered active phase are still reported as outside. Order your phases so the one whose boundary you want enforced has the lowest number.

The Tickets board shows the tickets that live inside these phases. See Tickets.

Rules and limits

• Phase status, order, and path globs are changed only by people in the app. Agents have read access only.
• On a shared project, only a maintainer can change a phase's path globs. When an editor tries, the app refuses the change and tells them to ask a maintainer.
• Generate from Architecture needs a paid plan and spends credits.
• Deleting a phase deletes its tickets, their comments, and their reports.

If something looks wrong

• An agent says no phase is active. No phase has the active status. Set one to active, or give the agent a specific phase.
• The agent works on the wrong phase. current picks the active phase with the lowest number. Drag the phase you want to the top of the active ones, or tell the agent which phase to use.
• Drift flags files that belong to another active phase. The phase boundary check uses only the lowest-numbered active phase. Reorder phases, or widen that phase's path globs.
• No phase drift appears at all. The lowest-numbered active phase may have no path globs, or only malformed ones. Add valid patterns such as src/**. For vibeless_run_drift_check, the project also needs a drift baseline, which is captured when a project import is applied.
• The dependency graph shows no arrows. Arrows appear only when a phase's stored dependencies point at another phase in the project. Boxes still appear for every phase.
• Generation fails with "The model returned no phases." Add more detail to the architecture document in the Spec Editor and try again.