AI Goal Decomposition (/make-note)

Relevant source files

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

• README.md
• src/main.ts
• src/queue-controller.ts
• CHANGELOG.md
• package.json
• SECURITY.md

AI Goal Decomposition is a feature in PlanQueue that allows a user to provide a high-level goal which the AI agent then breaks down into a sequential, actionable prompt queue. This process is triggered via the /make-note slash command and executed through a specialized LLM tool called make_note.

The feature transitions a broad objective into a structured Markdown-based list of tasks (the "queue"), complete with detailed sub-instructions and human-in-the-loop barriers where review is necessary. Once decomposed, these tasks can be dispatched to the agent one by one or via the auto-run mechanism.

Sources: README.md:89-94, src/main.ts:258-271, CHANGELOG.md:28-29

Workflow Architecture

The decomposition process follows a specific lifecycle from the user's initial command to the final persistence of the prompt queue.

Command and Meta-Prompting

The feature is initiated by the registerNoteCommands function which sets up the /make-note command. When a user provides a <goal>, the extension wraps this goal in a meta-prompt designed to instruct the LLM on how to structure its response.

Meta-Prompt Logic

The makeNotePrompt function generates the following instructions for the agent:

1. Decompose the goal into a sequential prompt queue.
2. Call the make_note tool to write the plan.
3. Use the details field for supporting information (sent as one multi-line message with the prompt).
4. Use barrierAfter: true to insert --- lines for manual review.

Sources: src/main.ts:258-271, src/main.ts:348-356

The make_note Tool

The make_note tool is the primary mechanism the agent uses to commit the decomposed plan to the session note. It is registered via registerMakeNoteTool.

Tool Parameters

Parameter	Type	Description
heading	string (Optional)	A summary of the session topic, rendered as a # heading.
steps	QueueStep[]	An ordered array of prompts forming the queue.

QueueStep Schema

Field	Type	Description
prompt	string	The primary instruction (becomes a - [ ] line).
details	string[] (Optional)	Indented continuation lines for the prompt.
barrierAfter	boolean (Optional)	If true, appends a --- human-in-the-loop barrier.

Sources: src/main.ts:276-310, SECURITY.md:28-31

Logic and Persistence

When the make_note tool is executed, it processes the steps array and transforms them into Markdown syntax.

1. Validation: The tool ensures that at least one non-empty prompt is provided.
2. Formatting:
   • prompt becomes a - [ ] task line.
   • details are appended as indented lines immediately below the task.
   • barrierAfter: true appends a --- line.
3. Appending: The new content is appended to the existing session note using appendQueue.
4. Persistence: The updated content is saved to the file system (typically ~/.planqueue/{repo}/{branch}/{session-id}.md) and the UI widget is refreshed.

Sources: src/main.ts:312-343, src/main.ts:405-415, README.md:99-105

Automatic Bootstrapping

In addition to the manual /make-note command, PlanQueue includes a "bootstrap" feature. If a session starts and the note is empty, after the first turn settles, the extension automatically sends a follow-up message to the agent requesting it to call make_note. This provides a summary heading and at least two follow-up tasks based on the initial conversation context.

Sources: src/main.ts:466-478

Summary

The AI Goal Decomposition feature streamlines complex tasks by allowing the agent to architect its own execution plan. By utilizing the /make-note command and the make_note tool, the system ensures that high-level goals are transformed into a trackable, sequential Markdown-based queue that supports multi-line prompts and human-in-the-loop checkpoints.

Sources: README.md:19-25, CHANGELOG.md:28-29