79 lines
4.9 KiB
Markdown
79 lines
4.9 KiB
Markdown
---
|
|
description: Epics deliver playable game features — prototype backlogs must pair server + client stories; forbid Bruno-only "optional UI" deferrals.
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Full-stack epic decomposition (CRITICAL)
|
|
|
|
Neon Sprawl is a **game**, not a headless server. Prototype backlogs and epic slices must ship **Godot presentation** for every **player-visible** feature.
|
|
|
|
## When this rule applies
|
|
|
|
- Writing or editing **`docs/plans/*backlog*.md`**, **`docs/plans/E*S*-client*.md`**, or **implementation slices** in **`docs/decomposition/epics/epic_*.md`**
|
|
- Creating **Linear issues** during decomposition (not at ad-hoc kickoff without client counterparts)
|
|
- Reviewing whether an epic/module slice is **“decomposed”** or **“prototype complete”**
|
|
|
|
Reference: [decomposition README — Full-stack epics](../../docs/decomposition/README.md#full-stack-epics), [prototype backlog template](../../docs/plans/_prototype-backlog-template.md).
|
|
|
|
## Canonical pattern
|
|
|
|
Mirror **Epic 1** ([E1M3-prototype-backlog](../../docs/plans/E1M3-prototype-backlog.md)): server contract story immediately followed by client HUD/wiring (e.g. NEO-23 → NEO-24).
|
|
|
|
For large epics, a dedicated **client slice** file is OK ([E3S5-client-prototype-backlog.md](../../docs/plans/E3S5-client-prototype-backlog.md)) — but **client Linear issues must exist in the same decomposition pass** as server issues, with `blockedBy` links.
|
|
|
|
## Story classification
|
|
|
|
| Type | Client story required? | Examples |
|
|
|------|------------------------|----------|
|
|
| **Infrastructure** | **No** | JSON Schema, CI gates, server catalog load, DB migrations, comment-only telemetry hooks |
|
|
| **Player-visible** | **Yes** | Inventory, gather/craft, quests, zone/PvP warnings, combat telegraphs, skill/perk UI, any AC with *player*, *visible*, *HUD*, *select*, *complete*, *understand* |
|
|
| **Capstone** | **Yes** | “Playable loop in Godot without Bruno” (e.g. NEO-75) |
|
|
|
|
Tag **infrastructure-only** stories explicitly in the backlog so agents do not skip UI for the wrong reasons.
|
|
|
|
## Mandatory backlog contents
|
|
|
|
When creating `docs/plans/E*M*-prototype-backlog.md` (copy [\_prototype-backlog-template.md](../../docs/plans/_prototype-backlog-template.md)):
|
|
|
|
1. **Server + client story tables** — every player-visible slug lists **`Client counterpart: NEO-XX`** or points to a client slice slug.
|
|
2. **Linear issues created together** — all server **and** client issues + **`blockedBy`** in one decomposition pass; label client issues **`client`** + module id (`E3.M1`, etc.).
|
|
3. **Capstone client story** — at least one issue proving the slice is **playable in Godot** (manual QA in `docs/manual-qa/{KEY}.md`), unless the entire epic slice is infrastructure-only (rare).
|
|
4. **Epic DoD updated** — prototype Definition of Done says **Godot**, not Bruno-only (see [epic_03 example](../../docs/decomposition/epics/epic_03_crafting_economy.md)).
|
|
|
|
## Forbidden language
|
|
|
|
Do **not** use in backlogs or Linear descriptions for player-visible work:
|
|
|
|
- “Godot HUD (**optional follow-up**)”
|
|
- “for manual QA and **future client**” (without a linked **NEO-XX** client issue)
|
|
- “client UI deferred” without a **created** client issue id
|
|
|
|
Use **Out of scope** only for genuinely non-prototype UX (e.g. drag-drop inventory, final art pass).
|
|
|
|
## Bruno vs Godot
|
|
|
|
- **Bruno** — proves HTTP contracts and server authority.
|
|
- **Godot** — proves [vision prototype gates](../../neon_sprawl_vision.plan.md) (fun, readability, progression visibility).
|
|
|
|
Do **not** mark a **player-facing** epic slice **complete** when only Bruno passes.
|
|
|
|
## Kickoff and implementation
|
|
|
|
- **Story kickoff** for a **server** issue on a player-visible path: plan must **cross-link** the **client counterpart** Linear issue (even if not started). See [story-kickoff](story-kickoff.md).
|
|
- **Manual QA** ([planning-implementation-docs](planning-implementation-docs.md)): player-visible **client** stories require `docs/manual-qa/{KEY}.md` with **Godot** steps, not API-only checks.
|
|
- **Client scripts:** thin `main.gd`, HTTP client nodes — [godot-client-script-organization](godot-client-script-organization.md).
|
|
|
|
## Decomposition complete checklist
|
|
|
|
Before calling an epic slice **decomposed**:
|
|
|
|
- [ ] Every player-visible acceptance criterion maps to a **`client`** Linear issue
|
|
- [ ] No forbidden deferral language in backlog
|
|
- [ ] Capstone or client slice issue exists for playable verification
|
|
- [ ] Epic / module docs and [documentation_and_implementation_alignment.md](../../docs/decomposition/modules/documentation_and_implementation_alignment.md) mention client backlog
|
|
- [ ] [module_dependency_register.md](../../docs/decomposition/modules/module_dependency_register.md) note updated when issues are created
|
|
|
|
## Code review
|
|
|
|
Reviewers (human or [code-review-agent](code-review-agent.md)) **should fix** or **block** claims that a **player-facing** prototype slice is done when backlog has **no client issue** or manual QA is Bruno-only.
|