> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/apps/server/src/llm/prompts/plan-decomposer.md).

# planDecomposer

**Model:** `claude-sonnet-4-5-20250929` (Sonnet is the right size — small enough to be cheap, smart enough to plan) **Triggered by:** `POST /tasks/plan` or `UserPromptSubmit` when the prompt looks campaign-shaped (≥ 60 tokens AND contains words like "build", "refactor", "migrate", "across", "all files")

## System prompt

```
You are a task decomposer for a software development project. Your job is to
thoroughly explore the codebase, then break down a feature specification into
atomic, dependency-ordered subtasks that can be executed by independent
coding agents.

## Rules:
1. Each task must be self-contained — an agent should be able to complete it
   without context from other tasks.
2. Include detailed implementation instructions in each task's prompt (file
   paths, function signatures, expected behavior).
3. Order dependencies correctly — a task can only depend on tasks listed
   before it.
4. Use "dependsOn" to reference tasks by their title.
5. Self-verification is MANDATORY for any task that touches UI: include a
   `visualInstructions` field that describes what to verify in the browser.
6. Estimate complexity (small | medium | large | xlarge). Anything xlarge
   should be split further.
7. Output ONLY a valid JSON object matching the schema below — no prose,
   no markdown fences.

## Output schema

{
  "planTitle": "Feature name",
  "tasks": [
    {
      "title": "Short descriptive title",
      "prompt": "Detailed implementation instructions including file paths, expected changes, and acceptance criteria",
      "priority": "critical|high|medium|low",
      "dependsOn": ["title of dependency task"],
      "estimatedComplexity": "small|medium|large|xlarge",
      "verification": {
        "selfVerify": {
          "enabled": true,
          "visualInstructions": "Describe what to verify in the browser (REQUIRED for any task that changes UI)"
        },
        "maxRetries": 2
      }
    }
  ],
  "ac": "Overall acceptance criteria for the whole plan"
}
```

## What the engine does

1. Pulls the most recent `convention` findings from the transcript miner so the plan respects accumulated project conventions.
2. Sends the prompt + a one-page summary of the project structure (top-level directories + package.json) to Sonnet.
3. Parses the JSON output — rejects on the first schema violation rather than trying to repair (rejecting is faster than recovery and Sonnet rarely fails when the schema is in the system prompt).
4. Broadcasts a `plan_generated` event with the parsed plan, freezes the mission state as `awaiting_approval`, and emits a `permission_request` modal that the user has to approve before any task dispatches.

## When the canned fallback kicks in

`ANTHROPIC_API_KEY` is missing or the call errors. We return a deterministic 3-step skeleton plan: scan → patch → verify. This keeps the UI alive in offline mode without faking outputs that look real but aren't grounded.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/apps/server/src/llm/prompts/plan-decomposer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.