> 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/auto-improver.md).

# autoImprover — FactionOS Improving Itself

**Model:** `claude-opus-4-1-20250805` (deserves the strongest model — it's editing the running system) **Triggered by:** Metrics threshold (failure rate ≥ 20% over rolling 20 tasks, OR ≥ 3 long-running tasks)

## The recursive bit

This is the most ambitious self-improvement prompt. **FactionOS uses FactionOS to fix FactionOS.** When the running system observes that recent campaigns are failing too often, or that tasks are stalling, it spawns an internal hero inside its own running instance and asks that hero to modify the FactionOS codebase.

## Variant 1 — failure-rate trigger

```
Investigate and reduce the high task failure rate in FactionOS. Recent failure
rate: ${Math.round(g/n*100)}%. Analyze common failure patterns in agent
outcomes and implement fixes to improve reliability. Focus on error handling,
retry logic, and agent prompt quality.

CRITICAL CONSTRAINTS:
- Do not modify the @factionos/protocol package or any file under packages/.
- Do not change the public REST API surface (the routes documented in
  docs/api/README_api.md). New routes may be added.
- Every change must be in a NEW commit on a `auto-improve/<unix>` branch.
  Open a PR — do not push directly to main.
- Limit yourself to 5 file edits per pass. If a fix needs more, post a
  notice_board_message and stop.
```

## Variant 2 — long-running task trigger

```
Optimize FactionOS task decomposition to reduce long-running tasks.
${l.length} tasks have exceeded 30 minutes. Review the PlanDecomposer prompts
and task granularity to ensure tasks are appropriately sized and can be
completed efficiently.

CRITICAL CONSTRAINTS:
- Same constraints as the failure-rate trigger.
- Additionally: any change to a system prompt must be paired with a test
  case demonstrating the new behavior. Add the test under
  apps/server/test/prompts/.
```

## Safety rails

The historical notes did not include the safety rails. We add them explicitly to limit the recursive blast radius:

1. **PR-only, never direct commit.** The auto-improver spawns a hero with `--branch auto-improve/<unix>` and `--open-pr` — the hero can land code only via a PR for human review.
2. **Protocol freeze.** `packages/protocol/` is off-limits. Changes there would cascade through every app.
3. **Public API freeze.** New REST routes allowed, removing or changing existing ones blocked.
4. **5-file budget per pass.** Forces the improver to stay narrow. If a bigger change is warranted, the improver has to post a notice and stop.
5. **Cool-down.** After an auto-improvement triggers, the engine sleeps for 24h to prevent feedback loops where the improver itself introduces regressions that re-trigger the improver.

## What the engine does

1. Every 5 min, compute rolling failure rate + count of tasks > 30 min.
2. If a threshold is breached AND we're outside the cool-down, pick the relevant variant and dispatch a self-improvement hero.
3. Emit `notice_board_message` (severity `warn`) so the user sees what the system is doing.
4. Unlock the `auto-improver` achievement (per `BASELINE_ACHIEVEMENTS`) the first time the improver opens a real PR.

## Where this lives

`apps/server/src/llm/engines/autoImprover.ts`. The engine is **disabled by default**. Enable with `FACTIONOS_AUTO_IMPROVE=true` in `~/.factionos/settings.json`.


---

# 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/auto-improver.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.