Task States & Normalization

Relevant source files

The following files were used as context for generating this wiki page:

• src/queue-controller.ts
• README.md
• src/main.ts
• CHANGELOG.md
• tests/core-integration.test.ts

PlanQueue manages a FIFO prompt queue by interpreting and transforming plain text Markdown notes into actionable agent tasks. The system relies on a normalization process that converts user-written lines into structured checkboxes, which then transition through various lifecycle states as they are dispatched to and processed by a coding agent.

The core philosophy of PlanQueue is that "the note IS the queue." Task states are represented directly within the Markdown buffer using specific checkbox markers, ensuring that the visual representation in the editor or widget remains synchronized with the internal logic of the queue controller.

Sources: README.md:28-30, src/queue-controller.ts:4-10

Task Lifecycle and States

Tasks in PlanQueue move through a linear lifecycle driven by user actions (Ctrl+↓) or automated progression. These states are represented by distinct Markdown markers and rendered as specific glyphs in the UI widget.

State	Markdown Marker	UI Glyph	Description
Pending	- [ ]	☐	The task is in the queue and waiting to be dispatched.
In-flight	- [>]	▸	The task has been sent to the agent and the turn is currently active.
Done	- [x]	✓	The agent turn has settled (completed), and the task is marked as finished.

Sources: README.md:61-63, CHANGELOG.md:18-20, src/main.ts:153-155

State Transitions

Transitions occur based on event triggers within the OMP environment. When a pending task is dispatched via sendUserMessage, it is immediately marked as "In-flight". Once the agent turn settles (indicated by the session_stop event), the controller completes the in-flight task by marking it as "Done".

The diagram above shows the sequential progression of a single task line within the Markdown note.
Sources: src/queue-controller.ts:80-82, src/queue-controller.ts:133-138

Normalization Logic

Normalization is the process of automatically converting informal user input into valid queue tasks. This ensures users do not have to manually type checkbox syntax ([ ]).

• Auto-Normalization on Save: When a note is saved, plain lines or lines starting with - bullets are automatically converted to - [ ] pending tasks.
• Prose Preservation: Certain Markdown elements are ignored by the queue and remain as prose:
  • # Headings (used for organization).
  • > Quotes.
• Continuation Lines: Lines indented under a task are treated as "continuation lines." They do not receive their own checkboxes but are bundled and sent together with the parent task as a single multi-line prompt.
• Barriers: A line consisting of three or more dashes (---) is normalized as a human-in-the-loop barrier, which explicitly pauses automated execution.

Sources: README.md:61-68, CHANGELOG.md:20-22, src/main.ts:241-243

Barrier Handling and Human-in-the-Loop

Barriers (---) act as logical "stop" points within the queue state machine. Unlike standard tasks, they do not transition to "Done"; instead, they must be manually removed to allow the queue to proceed.

• Detection: The queue controller identifies the "head" of the queue. If the head is a barrier, auto-run is disabled and the system enters a "blocked" state.
• Resolution: Pressing the queueStep shortcut (default Ctrl+↓) while at a barrier deletes the --- line from the note instead of sending a message. This "unlocks" the queue for the next task.

The sequence diagram illustrates how a barrier interrupts the flow until explicit user intervention removes it.
Sources: src/queue-controller.ts:84-90, src/queue-controller.ts:107-111, README.md:70-74

Automated State Management

The QueueController manages states through OMP event subscriptions. The primary hook for state transition is the session_stop event, which triggers the completeInflight logic.

Auto-run Progression

In auto-run mode (Ctrl+Shift+↓), the system automatically feeds the next pending task after a turn settles, provided certain conditions are met:

1. No Errors: The previous turn must not have failed or been aborted.
2. No Barriers: The next line in the queue must not be a --- barrier.
3. Editor Closed: Auto-run pauses while the notes editor is open to prevent write conflicts.

Sources: src/queue-controller.ts:13-22, src/queue-controller.ts:117-130, src/main.ts:403-408

Implementation Reference

Key functions and paths involved in the state and normalization logic:

• normalizeQueue(text): Found in @aryrabelo/planqueue-core, used in src/main.ts to transform raw editor text before persistence.
• markInflight(content, line): Updates a specific line to the - [>] state.
• completeInflight(content): Scans the buffer and converts - [>] to - [x].
• findHead(content): Determines the next actionable item (prompt, barrier, or empty).
• parseTaskLine(line): Logic used to determine the current state of a Markdown line.

Sources: src/main.ts:241, src/queue-controller.ts:82, src/queue-controller.ts:134, tests/core-integration.test.ts:21-22

The Task State & Normalization system ensures that PlanQueue can maintain a robust, persistent prompt queue using nothing more than a standard Markdown file, allowing for both manual control and seamless automation.