> 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/docs/game-design/01-product-vision-brief.md).

# Product Vision Brief — The War Effort

**Project:** FactionOS **Design package:** The War Effort **Document role:** Product vision brief / creative pillars

## FactionOS Game Design — "The War Effort"

**Status:** Living design document — update as research/ideation continues. **Date started:** 2026-07-03 **Author:** Claude (game-design ideation session), directed by Mosheh **Location note:** This is the conceptual game design. Runtime/visual facts live in `docs/battlefield.md`; theme/data inventory below is source-backed from `packages/protocol/` and `apps/web/src/lib/`. Production-generated game-design visual assets are tracked in `docs/game-design/manifest.md`.

***

## 0. The One-Sentence Pitch

**Your real AI coding agents are heroes in a living fantasy war — every tool call, mission, and merge they perform in the real world fuels a strategy game you can never grind, only *****command*****.**

The player's job is not to click cookies. The player's job is to be a **Warchief**: spawn agents, aim them at real work, respond when they call for orders, and watch the war effort compound. The game is fun *because* the work is real — and the work gets better *because* the game makes you want to engage with it.

***

## 1. The Fun Thesis (read this first)

Everything in this document serves one conversion:

> **Real agent work → legible, juicy, escalating game consequence.**

The critical design insight: FactionOS is **not an idle game with fake numbers** and **not a dashboard with hats on**. It occupies a genre gap we get to define:

### The genre: "Command Idle" / Real-Work Strategy

| Genre we borrow from | What we take                                                       | What we reject                                                  |
| -------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- |
| RTS (WC3/SC)         | Faction fantasy, hero units, bases, fog-of-war reveal, voice barks | Real-time micromanagement (the agents micro themselves)         |
| Idle/Incremental     | Numbers-go-up compulsion, offline progress, prestige               | Fake work; clicking for the sake of clicking                    |
| Raid/MMO             | Boss fights, roles, loot, guild seasons                            | Grinding; time-gating                                           |
| Tamagotchi/Pikmin    | Attachment to units, "they need you" moments                       | Punishing neglect (real work must never be hostage to the game) |
| Roguelite            | Run structure (a session is a run), unlock meta-layer              | Permadeath of anything the user values                          |

### The five Fun Laws (design constraints, non-negotiable)

1. **The forge only burns real fire.** No game resource is ever generated by in-game clicking. Every point of progress traces to a real agent event (tool\_use, mission\_complete, plan\_completed, etc.). This is the entire moat: the numbers *mean something*.
2. **Fun-per-glance.** The primary play pattern is peripheral: the cockpit sits on a second monitor while the player works. Every glance must deliver state ("my orcs are winning"), and every real event must be *legible within 1 second* of looking. Big sessions of active play are the exception, not the requirement.
3. **The game asks for exactly the attention the work deserves.** The highest-value real actions (answering `awaiting_input`, approving plans, reviewing guarded actions, accepting quests) are the highest-value *game* actions. Game urgency ≡ work urgency. Never invent fake urgency.
4. **Never reward waste.** Tokens burned ≠ score. All scoring is *outcome-weighted and efficiency-tempered* (see §9, Anti-Goodhart). A player optimizing the game score should accidentally be optimizing their real engineering workflow.
5. **Losing is content.** Errors, failed missions, and stalled tasks don't punish — they *spawn enemies*. Real-world friction becomes the antagonist, which converts frustration ("my agent errored") into motivation ("the Blight took the west ridge — send a hero").

***

## 2. The Core Fantasy & The Antagonist

### You are the Warchief

The player picks a faction (existing: **Crimson Horde** orcs, **Vanguard Alliance** humans, **Verdant Circle** elves, **Whispering Necropolis** undead, plus hidden **Brine Cabal** lobsters unlocked via the five fundamental tomes). Agents they spawn become named heroes of that faction (existing: archetypes, race-themed names, voice barks, standees on the 2D battlefield).

**Implemented faction substrate.** Code references: `packages/protocol/src/factions.ts`, `apps/web/src/data/factionStyles.ts`, `apps/web/src/components/FactionPicker.tsx`, `apps/web/src/store/useSettingsStore.ts`, `apps/web/src/store/useFactionVoiceLine.ts`, `apps/web/src/lib/factionVoiceLines.ts`, `apps/web/src/components/battlefield/Battlefield.tsx`. Focused tests: `packages/protocol/tests/factions.test.ts`, `apps/web/tests/FactionVoiceLine.test.tsx`, `apps/web/tests/factionVoiceLines.test.ts`.

* First-run faction selection ships for Orcs, Humans, Elves, and Undead.
* The hidden Lobster faction unlocks after all five fundamental tomes are collected, giving the "secret faction" fantasy an existing progression gate.
* Selected faction persists locally and can be switched later from settings among selectable factions.
* Faction identity data already covers name, motto, sigil, accent color, voice style, hero archetypes, and building names.
* Faction choice drives spawned hero faction, portrait/standee selection, roster and battlefield styling, ranking bucket, visual accent, and the confirmation bark/recorded faction voice line when audio is enabled.

### The enemy: **The Null Legion** (new)

The game needs an antagonist that maps to real-world entropy. The Null Legion is the personification of everything broken, unfinished, and rotting in the player's actual codebase and workflow:

| Real-world signal (already captured)                                          | Null Legion manifestation                                                     |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Quest Board codebase-issue scan findings (Phase 18 scanners: full/diff/daily) | **Blight camps** on the battlefield — each open issue is a visible enemy camp |
| A mission fails / hero hits `error` state                                     | A **Wraith** spawns near that hero's position                                 |
| Task stalls (`task_stalled`, `task_near_stall` events exist)                  | A **Siege engine** slowly advancing on your keep                              |
| Unresolved Notice Board items                                                 | **Spies** — small skulking units near your buildings                          |
| Long-idle heroes with pending suggestions                                     | **Creeping fog** re-covering cleared territory                                |
| Failing tests / lint findings (from scanners)                                 | **Blight tendrils** on the map region tied to that directory                  |

**Why this is the single funnest idea in this document:** the enemy army is *procedurally generated from your actual tech debt*. Clearing the map and fixing your codebase are the same action. The daily scanner (already built) becomes the game's **dawn patrol**: every morning the Legion's overnight moves are revealed, giving the player a reason to open the cockpit that is both game-motivated and work-productive.

Defeating Legion units requires the corresponding real fix: accept the quest (existing Quest Board accept flow), a hero completes the mission, the camp burns down with the existing celebration burst + faction bark.

***


---

# 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/docs/game-design/01-product-vision-brief.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.