diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 467ad8a..4de156e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -101,9 +101,19 @@ For MVP, prioritize tests for: Do not block MVP on broad coverage targets. +## Narrative and mechanics separation + +- Create and maintain story canon in `docs/FABULA.md` before final mechanics are locked. +- Keep `docs/GAME_BRIEF.md` and `docs/GDD.md` aligned with the current story and scope. +- Treat `mechanika/` as the place for gameplay rules, not for raw worldbuilding. + ## Copilot workflow - Use `/game-dev` for project orchestration. +- Use `/game-brief` for the durable product and mission brief. +- Use `/fabula` for story bible work before mechanics solidify. +- Use `/gdd` for structured design-document updates. +- Use `/investigate` for focused repo analysis and blocker discovery. - Use `/new-scene` for Phaser scenes. - Use `/new-system` for systems. - Use `/new-event` for event data. diff --git a/.github/prompts/fabula.prompt.md b/.github/prompts/fabula.prompt.md new file mode 100644 index 0000000..ad7b811 --- /dev/null +++ b/.github/prompts/fabula.prompt.md @@ -0,0 +1,56 @@ +--- +name: fabula +description: 'Creates or updates the story bible and narrative foundation before mechanics are finalized.' +agent: agent +model: gpt-5.4 +tools: + - search/codebase + - edit/editFiles + - read/problems + - execute/runInTerminal + - execute/runTests +--- + +# /fabula + +Use this prompt to create or refine the project story bible in `docs/FABULA.md`. + +## Read first + +- `README.md` +- `docs/GAME_BRIEF.md` +- `docs/GDD.md` if it exists +- `docs/SCOPE.md` +- `docs/IDEAS_LATER.md` +- `mechanika/README.md` +- `mechanika/00-template-do-wypelnienia.md` + +## Narrative scope + +Focus on: + +- mission premise, +- tone, +- world assumptions, +- crew roles as characters, +- factions only as story mentions if needed, +- intro text, recurring motifs, event themes, and discovery mystery. + +## Rules + +- Do not define gameplay formulas or hidden mechanics here. +- Do not turn narrative ideas into combat, XP, morale, or quest systems. +- Keep canon easy to reuse later in events, UI text, and mission content. +- Write concise, production-friendly material that can guide future content generation. + +## Output + +Update `docs/FABULA.md` and end with: + +```md +## Fabula update +Completed: +Open questions: +Future hooks: +Files changed: +``` diff --git a/.github/prompts/game-brief.prompt.md b/.github/prompts/game-brief.prompt.md new file mode 100644 index 0000000..47b5edf --- /dev/null +++ b/.github/prompts/game-brief.prompt.md @@ -0,0 +1,50 @@ +--- +name: game-brief +description: 'Creates or updates the durable game brief before implementation expands.' +agent: agent +model: gpt-5.4 +tools: + - search/codebase + - edit/editFiles + - read/problems + - execute/runInTerminal + - execute/runTests +--- + +# /game-brief + +Use this prompt to create or refine the durable project brief in `docs/GAME_BRIEF.md`. + +## Read first + +- `README.md` +- `docs/ARCHITECTURE.md` +- `docs/SCOPE.md` +- `docs/IDEAS_LATER.md` +- `docs/FABULA.md` if it exists +- `mechanika/README.md` +- `mechanika/00-template-do-wypelnienia.md` + +## Goals + +- Keep one short source of truth for the fantasy, player role, mission, tone, and product promise. +- Support later mechanics and content decisions without inventing gated `mechanika/` rules. +- Keep the brief stable enough to guide future scenes, systems, events, and story writing. + +## Rules + +- Do not invent combat formulas, progression curves, trait effects, faction systems, or quest-chain logic. +- Keep this document high-level and durable. +- If a detail belongs to narrative canon, place or link it in `docs/FABULA.md`. +- If a detail belongs to gameplay rules, leave a note pointing to `mechanika/`. + +## Output + +Update `docs/GAME_BRIEF.md` and end with: + +```md +## Game brief update +Completed: +Open questions: +Files changed: +``` diff --git a/.github/prompts/gdd.prompt.md b/.github/prompts/gdd.prompt.md new file mode 100644 index 0000000..548761d --- /dev/null +++ b/.github/prompts/gdd.prompt.md @@ -0,0 +1,52 @@ +--- +name: gdd +description: 'Builds or updates the Game Design Document while respecting mechanika gates.' +agent: agent +model: gpt-5.4 +tools: + - search/codebase + - edit/editFiles + - read/problems + - execute/runInTerminal + - execute/runTests +--- + +# /gdd + +Use this prompt to maintain `docs/GDD.md` as the structured design reference. + +## Read first + +- `README.md` +- `docs/GAME_BRIEF.md` +- `docs/FABULA.md` +- `docs/ARCHITECTURE.md` +- `docs/SCOPE.md` +- `mechanika/README.md` +- `mechanika/00-template-do-wypelnienia.md` +- any refined files inside `mechanika/` + +## Goals + +- Translate the current project intent into a structured design doc. +- Keep narrative, UX, scope, and content plans aligned. +- Record placeholders and open questions instead of inventing blocked mechanics. + +## Rules + +- Treat `mechanika/` as the future gameplay source of truth. +- Keep sections explicit about status: approved now, reserved, or open question. +- Prefer tables, bullet lists, and short sections over long prose. +- Link to `docs/FABULA.md` for worldbuilding and story canon. + +## Output + +Update `docs/GDD.md` and end with: + +```md +## GDD update +Completed: +Blocked by mechanika: +Open questions: +Files changed: +``` diff --git a/.github/prompts/investigate.prompt.md b/.github/prompts/investigate.prompt.md new file mode 100644 index 0000000..ce7a77e --- /dev/null +++ b/.github/prompts/investigate.prompt.md @@ -0,0 +1,53 @@ +--- +name: investigate +description: 'Investigates repository state, docs, content gaps, or implementation blockers before making changes.' +agent: agent +model: gpt-5.4 +tools: + - search/codebase + - edit/editFiles + - read/problems + - execute/runInTerminal + - execute/runTests +--- + +# /investigate + +Use this prompt when you need a focused repo investigation before planning or implementation. + +## Read first + +Inspect only the files needed for the request, but prefer these sources first: + +- `README.md` +- `docs/ARCHITECTURE.md` +- `docs/SCOPE.md` +- `docs/COPILOT_WORKFLOW.md` +- `mechanika/` +- `.github/prompts/` +- `.github/skills/` + +## Goals + +- Find the current source of truth for the requested area. +- Identify blockers, missing assets, or contradictory docs. +- Recommend the next 1-3 safe actions. + +## Rules + +- Do not make speculative architecture changes unless asked. +- Do not invent gated mechanics. +- When the repo is still docs-only, prefer docs, prompts, and skill updates over code scaffolding. + +## Output + +Return: + +```md +## Investigation result +Question: +Sources checked: +What is true now: +Blockers: +Recommended next action: +``` diff --git a/.github/skills/README.md b/.github/skills/README.md new file mode 100644 index 0000000..803cdb4 --- /dev/null +++ b/.github/skills/README.md @@ -0,0 +1,25 @@ +# Local skills + +This directory contains the repository-local skills that Copilot can use for SpaceshipGame. + +## Active local skills + +- `scaffold-scene` — Phaser 4 scene scaffolding aligned with repo architecture. +- `scaffold-system` — pure TypeScript system scaffolding with serializable state. +- `mechanika-spec` — controlled work inside `mechanika/`. +- `story-bible` — narrative canon and story foundation in `docs/FABULA.md`. +- `skill-creator` — local skill adaptation workflow for this repo. +- `content-research-writer` — grounded documentation authoring for Sprint 0 and beyond. + +## Intake flow for additional skills + +1. Drop raw or draft material into `.github/skills/incoming/`. +2. Review whether it fits the repo rules, stack, and current gate. +3. Adapt it into a clean local skill package under `.github/skills/{skill-name}/`. +4. Update `README.md`, `docs/COPILOT_WORKFLOW.md`, and adoption docs if the skill becomes part of the standard workflow. + +## Rules + +- Prefer adapted local skills over bulk imports. +- Do not treat `incoming/` content as active by default. +- Record activation gates and blockers for every non-trivial skill. diff --git a/.github/skills/content-research-writer/SKILL.md b/.github/skills/content-research-writer/SKILL.md new file mode 100644 index 0000000..59b110a --- /dev/null +++ b/.github/skills/content-research-writer/SKILL.md @@ -0,0 +1,21 @@ +--- +name: content-research-writer +description: 'Creates grounded design, narrative, and workflow documentation for the repository.' +--- + +# Content Research Writer + +Use this skill when creating or revising repository documentation such as: + +- `docs/GAME_BRIEF.md`, +- `docs/GDD.md`, +- `docs/FABULA.md`, +- ADR notes, +- workflow and adoption docs. + +Rules: + +- Ground every update in current repo docs first. +- Keep language concise and easy to maintain. +- Separate story canon, gameplay rules, and technical architecture into the correct files. +- When information is missing, write an open question or blocker instead of filling gaps with invented mechanics. diff --git a/.github/skills/incoming/README.md b/.github/skills/incoming/README.md new file mode 100644 index 0000000..5c8d66f --- /dev/null +++ b/.github/skills/incoming/README.md @@ -0,0 +1,23 @@ +# Skill intake / upload area + +Use this directory as the staging area for additional skills before they become active repository skills. + +## What goes here + +- draft skills copied in for review, +- external skill references, +- partially adapted skill packages, +- notes about source, purpose, and gate. + +## Required note for each incoming skill + +Include at least: + +- original source, +- intended use in SpaceshipGame, +- current gate (`Sprint 0 docs`, `app scaffold`, `CI`, `design pipeline`, or `external tool`), +- blockers or open questions. + +## Promotion rule + +A skill moves from `incoming/` to an active folder in `.github/skills/` only after it is adapted to repository conventions and documented in the workflow docs. diff --git a/.github/skills/mechanika-spec/SKILL.md b/.github/skills/mechanika-spec/SKILL.md new file mode 100644 index 0000000..422da2e --- /dev/null +++ b/.github/skills/mechanika-spec/SKILL.md @@ -0,0 +1,22 @@ +--- +name: mechanika-spec +description: 'Refines one mechanic spec at a time inside mechanika/ without over-inventing blocked systems.' +--- + +# Mechanika Spec + +Use this skill when filling in or refining files inside `mechanika/`. + +Rules: + +- Start from `mechanika/00-template-do-wypelnienia.md` or the closest numbered file. +- Work on one mechanic area at a time. +- Use natural language for intent and tables for values or rule summaries. +- If the source information is missing, record an open question instead of inventing a final rule. +- Keep combat, traits, progression, morale formulas, factions, and quest chains evidence-based. + +Expected outputs: + +- updated `mechanika/` file, +- any linked note in `99-open-questions.md`, +- no production-code changes unless explicitly requested later. diff --git a/.github/skills/skill-creator/SKILL.md b/.github/skills/skill-creator/SKILL.md new file mode 100644 index 0000000..e85b288 --- /dev/null +++ b/.github/skills/skill-creator/SKILL.md @@ -0,0 +1,23 @@ +--- +name: skill-creator +description: 'Creates or adapts local repository skills using the SpaceshipGame conventions and activation gates.' +--- + +# Skill Creator + +Use this skill when adding a new package under `.github/skills/`. + +Checklist: + +- Confirm the skill supports the approved stack, docs workflow, narrative work, or future gated workflows. +- Write a short `name` and `description` in frontmatter. +- Explain when to use the skill and what files it may touch. +- Record any gate such as Sprint 0 docs-only, app scaffold required, CI required, or external tool required. +- If the skill comes from an external pattern, adapt it instead of bulk-copying it. +- If the skill is not ready for active use, stage it under `.github/skills/incoming/` first. + +Do not: + +- commit secrets or personal tokens, +- assume external MCP configuration already exists, +- invent blocked game mechanics. diff --git a/.github/skills/story-bible/SKILL.md b/.github/skills/story-bible/SKILL.md new file mode 100644 index 0000000..eb1c8f5 --- /dev/null +++ b/.github/skills/story-bible/SKILL.md @@ -0,0 +1,24 @@ +--- +name: story-bible +description: 'Builds and maintains the narrative canon in docs/FABULA.md without turning it into gameplay rules.' +--- + +# Story Bible + +Use this skill when creating or revising `docs/FABULA.md`. + +Focus areas: + +- premise and mission context, +- tone and style, +- worldbuilding assumptions, +- crew as characters, +- intro text and recurring motifs, +- event-theme hooks for future content. + +Rules: + +- Keep story canon separate from gameplay formulas. +- Do not define combat, XP, morale, trait, faction, or quest mechanics here. +- Prefer concise sections that are easy to reuse in event writing and UI text. +- Flag unresolved canon questions explicitly. diff --git a/README.md b/README.md index 1315d0d..67c0e75 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,12 @@ Pre-initialization / Sprint 0. No production code has been scaffolded yet. The ` ## Documentation - `docs/ARCHITECTURE.md` — approved architecture and integration points for future mechanics. +- `docs/GAME_BRIEF.md` — durable product and mission brief before implementation expands. +- `docs/FABULA.md` — story bible and narrative canon kept separate from gameplay rules. +- `docs/GDD.md` — structured design document linking brief, fabula, scope, and mechanika placeholders. - `docs/SCOPE.md` — what is and is not in the MVP. - `docs/IDEAS_LATER.md` — deferred ideas and scope-control list. -- `docs/COPILOT_WORKFLOW.md` — natural-language guide for using `/game-dev`, `/new-scene`, `/new-system`, and related prompts. +- `docs/COPILOT_WORKFLOW.md` — natural-language guide for using `/game-dev`, `/game-brief`, `/fabula`, `/gdd`, and related prompts. - `docs/ADRs/ADR-001-stack.md` — stack decision record. - `SKILLS_RECOMMENDATIONS.txt` — curated good-plus set of recommended skills and MCP servers for the repo. - `docs/skills-adoption/README.md` — expanded research and adoption order for skills/MCP rollout. @@ -38,14 +41,19 @@ Use the project Copilot assets first, then scaffold the codebase: 1. Open this folder in VS Code with GitHub Copilot Chat enabled. 2. Use the custom prompt slash commands that match each prompt file `name:` field: - `/game-dev` — check repo state and ask for the next 1-3 steps + - `/game-brief` — create or refine the durable project brief + - `/fabula` — build the story bible before mechanics solidify + - `/gdd` — keep the structured design document in sync - `/skills-adoption` — execute the approved skills/MCP rollout from the research docs - - `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, `/code-review` -3. Start with `/game-dev`, let it verify project foundations, and only scaffold the Vite + Phaser project after the documentation and `.github/` assets are in place. -4. Because this repository is still in Sprint 0, there is no `package.json`, no `src/`, and no runnable npm command yet. + - `/investigate`, `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, `/code-review` +3. In Sprint 0, stabilize the docs flow in this order: `/game-dev` → `/game-brief` → `/fabula` → `/gdd` → `/skills-adoption`. +4. Only scaffold the Vite + Phaser project after the documentation and `.github/` assets are in place. +5. Because this repository is still in Sprint 0, there is no `package.json`, no `src/`, and no runnable npm command yet. ## If the slash commands do not appear 1. Make sure you opened the repository root in VS Code, not a parent folder. 2. Confirm the prompt files exist in `.github/prompts/`. 3. Use the command names above without the `prompt-` prefix, because Copilot takes the slash command name from each prompt file's `name:` field. -4. If VS Code still does not list them, reload the window and try again; as a fallback, open the matching file in `.github/prompts/` and paste its instructions into chat manually. +4. Additional draft skills should be staged in `.github/skills/incoming/` before they become active local skills. +5. If VS Code still does not list them, reload the window and try again; as a fallback, open the matching file in `.github/prompts/` and paste its instructions into chat manually. diff --git a/SKILLS_RECOMMENDATIONS.txt b/SKILLS_RECOMMENDATIONS.txt index b09b584..1a8158c 100644 --- a/SKILLS_RECOMMENDATIONS.txt +++ b/SKILLS_RECOMMENDATIONS.txt @@ -43,16 +43,24 @@ B) ADAPT FROM diwad-code/bmad-module-game-dev-studio NOW - establishes a durable product/vision reference before implementation expands - gives every later mechanic and narrative decision a common anchor -2) gdd package +2) fabula package Target form: - - .github/prompts/gdd.prompt.md - - docs/GDD.md - - optionally docs/EPICS.md + - .github/prompts/fabula.prompt.md + - docs/FABULA.md Why it belongs: - - turns the repo from idea notes into a structured design system - - supports mechanics, event logic, UX, and production sequencing + - story and worldbuilding need a durable home before mechanics lock in + - gives AI-assisted writing a safe place to work without inventing gameplay rules -3) mechanika-spec +3) gdd package + Target form: + - .github/prompts/gdd.prompt.md + - docs/GDD.md + - optionally docs/EPICS.md + Why it belongs: + - turns the repo from idea notes into a structured design system + - supports mechanics, event logic, UX, and production sequencing + +4) mechanika-spec Target form: - .github/skills/mechanika-spec/SKILL.md Why it belongs: @@ -60,7 +68,7 @@ B) ADAPT FROM diwad-code/bmad-module-game-dev-studio NOW - best tactical tool for creating/refining one mechanic spec at a time - protects against random over-invention in pending mechanics areas -4) architecture package +5) architecture package Target form: - .github/prompts/architecture.prompt.md or equivalent - docs/ARCHITECTURE.md extensions @@ -68,7 +76,7 @@ B) ADAPT FROM diwad-code/bmad-module-game-dev-studio NOW - we should not stop at brief + GDD; the repo also needs a deeper technical decision layer - useful before real Phaser/Vite/PWA scaffolding starts -5) investigate package +6) investigate package Target form: - .github/prompts/investigate.prompt.md or a lightweight skill Why it belongs: @@ -213,8 +221,10 @@ PHASE 1 — DESIGN AND DESIGN-CONTEXT LAYER - keep scaffold-scene - keep scaffold-system - adapt game-brief package +- adapt fabula package - adapt gdd package - adapt mechanika-spec +- adapt story-bible support - adapt architecture package PHASE 2 — DOCUMENTATION / AUTHORING SUPPORT @@ -246,8 +256,10 @@ PROJECT-SIDE / ADAPTED - scaffold-scene - scaffold-system - game-brief package +- fabula package - gdd package - mechanika-spec +- story-bible support - architecture package - investigate package @@ -280,8 +292,14 @@ MCP SERVERS SHORT DECISION If we want a stronger non-minimum stack for this repo, the best direction is: -1. Build the design layer first: game-brief, gdd, mechanika-spec, architecture. +1. Build the design layer first: game-brief, fabula, gdd, mechanika-spec, architecture. 2. Add authoring support next: skill-creator, content-research-writer, changelog-generator. 3. Add Phaser- and UI-aligned MCPs next: Phaser MCP, Phaser Editor MCP Server, Figma MCP Server. 4. Add testing/CI/PWA delivery support as soon as the app and workflows actually exist. 5. Use docs/skills-adoption/README.md plus /skills-adoption as the autonomous adoption mechanism for executing this order. + + +CURRENT LOCAL AVAILABILITY AFTER SPRINT 0 DOCS ADOPTION +- available locally now: scaffold-scene, scaffold-system, game-brief prompt, fabula prompt, gdd prompt, investigate prompt, mechanika-spec, story-bible, skill-creator, content-research-writer +- staged intake area for future additions: .github/skills/incoming/ +- still gated until later: external MCP servers, app-only testing skills, CI/release skills that need a runnable app or workflows diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c1584a3..cd96e8f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -40,6 +40,10 @@ SpaceshipGame/ │ ├── prompts/ │ │ ├── game-dev.prompt.md │ │ ├── skills-adoption.prompt.md +│ │ ├── game-brief.prompt.md +│ │ ├── fabula.prompt.md +│ │ ├── gdd.prompt.md +│ │ ├── investigate.prompt.md │ │ ├── new-scene.prompt.md │ │ ├── new-system.prompt.md │ │ ├── new-event.prompt.md @@ -54,8 +58,19 @@ SpaceshipGame/ │ └── skills/ │ ├── scaffold-scene/ │ │ └── SKILL.md -│ └── scaffold-system/ -│ └── SKILL.md +│ ├── scaffold-system/ +│ │ └── SKILL.md +│ ├── mechanika-spec/ +│ │ └── SKILL.md +│ ├── story-bible/ +│ │ └── SKILL.md +│ ├── skill-creator/ +│ │ └── SKILL.md +│ ├── content-research-writer/ +│ │ └── SKILL.md +│ ├── incoming/ +│ │ └── README.md +│ └── README.md ├── public/ │ ├── manifest.json │ └── assets/ @@ -76,22 +91,26 @@ SpaceshipGame/ │ ├── types/ │ └── utils/ ├── docs/ +│ ├── GAME_BRIEF.md +│ ├── FABULA.md +│ └── GDD.md ├── mechanika/ └── claude_tips/ ``` ## Source of truth order -Custom Copilot slash commands come from each prompt file `name:` field, so the active commands are `/game-dev`, `/skills-adoption`, `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, and `/code-review`. +Custom Copilot slash commands come from each prompt file `name:` field, so the active commands are `/game-dev`, `/game-brief`, `/fabula`, `/gdd`, `/skills-adoption`, `/investigate`, `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, and `/code-review`. When documents overlap, resolve conflicts in this order: 1. `mechanika/` for final gameplay mechanics. -2. `docs/SCOPE.md` for MVP boundaries and post-MVP exclusions. -3. `docs/ADRs/` for accepted technical decisions. -4. `docs/ARCHITECTURE.md` for project structure and system boundaries. -5. `.github/copilot-instructions.md` for day-to-day Copilot behavior. -6. `claude_tips/` as reference material only; it is not authoritative. +2. `docs/FABULA.md` for narrative canon and story direction. +3. `docs/SCOPE.md` for MVP boundaries and post-MVP exclusions. +4. `docs/ADRs/` for accepted technical decisions. +5. `docs/ARCHITECTURE.md` for project structure and system boundaries. +6. `.github/copilot-instructions.md` for day-to-day Copilot behavior. +7. `claude_tips/` as reference material only; it is not authoritative. ## Core systems @@ -173,3 +192,7 @@ graph TB Systems -. integration points .-> Future ``` + +## Narrative foundation before mechanics + +Before detailed mechanics are finalized, the repository now keeps story canon in `docs/FABULA.md`, product intent in `docs/GAME_BRIEF.md`, and structured design state in `docs/GDD.md`. This keeps worldbuilding and content direction available to AI-assisted writing without forcing premature gameplay rules into `mechanika/`. Additional skill packages should be staged in `.github/skills/incoming/` before they become active local skills. diff --git a/docs/COPILOT_WORKFLOW.md b/docs/COPILOT_WORKFLOW.md index dfe3099..a944b5e 100644 --- a/docs/COPILOT_WORKFLOW.md +++ b/docs/COPILOT_WORKFLOW.md @@ -1,6 +1,6 @@ # Instrukcja korzystania z promptów Copilota -English summary: the working custom slash commands are `/game-dev`, `/skills-adoption`, `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, and `/code-review`. Start with `/game-dev`. The detailed guide below is in Polish. +English summary: the working custom slash commands are `/game-dev`, `/game-brief`, `/fabula`, `/gdd`, `/skills-adoption`, `/investigate`, `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, and `/code-review`. Start with `/game-dev`, then lock the brief and story before mechanics-heavy implementation. The detailed guide below is in Polish. Ten dokument jest prostą instrukcją pracy w VS Code z przygotowanymi promptami projektu SpaceshipGame. Traktuj go jak kolejność rozmowy z Copilotem. @@ -10,12 +10,18 @@ Najpierw używaj promptu **`/game-dev`**. To główny przełącznik projektu. On Nie zaczynaj od `/new-scene` albo `/new-system`, jeśli nie masz jeszcze gotowego projektu Vite/Phaser i podstawowych folderów. +W obecnym Sprint 0 przed mechaniką najpierw porządkuj: **brief → fabułę → GDD → adoption skills**. + ## Co oznaczają nasze przełączniki | Prompt | Kiedy używać | Co robi | |---|---|---| | `/game-dev` | Zawsze na początku sesji albo gdy nie wiesz, co dalej | Sprawdza projekt, dokumenty, braki i proponuje następne kroki | +| `/game-brief` | Gdy chcesz ustabilizować wizję projektu | Tworzy lub aktualizuje `docs/GAME_BRIEF.md` bez wchodzenia w szczegółowe mechaniki | +| `/fabula` | Gdy tworzysz historię przed mechaniką | Buduje `docs/FABULA.md`: premisę, ton, świat i haki narracyjne | +| `/gdd` | Gdy chcesz utrzymać główny design doc | Aktualizuje `docs/GDD.md` i oznacza sekcje jako approved/reserved/open question | | `/skills-adoption` | Gdy chcesz wdrożyć zatwierdzony zestaw skills/MCP | Czyta `SKILLS_RECOMMENDATIONS.txt` i `docs/skills-adoption/README.md`, wykonuje odblokowane kroki i raportuje blokery | +| `/investigate` | Gdy najpierw trzeba coś sprawdzić | Robi ukierunkowany research repozytorium, konfliktów i blokerów | | `/new-scene` | Gdy potrzebujesz nowego ekranu/sceny gry | Tworzy lub planuje scenę Phaser 4, np. `BootScene`, `BridgeScene` | | `/new-system` | Gdy potrzebujesz nowego modułu logiki gry | Tworzy system TypeScript, np. `CrewSystem`, `ResourceSystem` | | `/new-event` | Gdy chcesz dodać losowe zdarzenie do gry | Tworzy event data-driven z wyborami i ważonymi wynikami | @@ -106,6 +112,24 @@ Do czasu dostarczenia `mechanika/` eventy mają być proste: zasoby, proste uszk Cel: Copilot ma przypomnieć sobie dokumentację i sprawdzić, czego brakuje. +### Etap 0.25 — brief i fabuła przed mechaniką + +Zanim zaczniesz uszczegóławiać mechanikę, ustaw fundament narracyjny: + +```text +/game-brief uporządkuj krótki brief projektu i misji +``` + +```text +/fabula przygotuj bazę fabularną, ton i haki narracyjne do docs/FABULA.md +``` + +```text +/gdd zsynchronizuj brief, fabułę i aktualny scope +``` + +Cel: repo ma mieć osobne miejsce na wizję produktu, fabułę i design doc zanim zacznie powstawać kod i finalna mechanika. + ### Etap 0.5 — research i wdrażanie skills/MCP Gdy chcesz wykonać zatwierdzony rollout skills/MCP: @@ -114,7 +138,7 @@ Gdy chcesz wykonać zatwierdzony rollout skills/MCP: /skills-adoption wykonaj odblokowane kroki z listy rekomendacji ``` -Cel: Copilot ma przejść przez listę, wykonać tylko kroki zgodne z aktualnym stanem repozytorium i zapisać blokery dla etapów wymagających aplikacji, CI albo zewnętrznych usług. +Cel: Copilot ma przejść przez listę, wykonać tylko kroki zgodne z aktualnym stanem repozytorium i zapisać blokery dla etapów wymagających aplikacji, CI albo zewnętrznych usług. Dodatkowe drafty skills wrzucaj najpierw do `.github/skills/incoming/`. ### Etap 1 — przygotowanie projektu technicznego diff --git a/docs/FABULA.md b/docs/FABULA.md new file mode 100644 index 0000000..5321401 --- /dev/null +++ b/docs/FABULA.md @@ -0,0 +1,77 @@ +# FABUŁA / Story Bible + +## Cel dokumentu + +To jest miejsce na fabułę, ton, świat, motywy i kanon narracyjny projektu przed finalizacją mechaniki. + +## Granice + +Ten dokument może zawierać: + +- premisę misji, +- tło świata, +- ton i styl tekstów, +- role załogi jako postaci, +- motywy eventów, +- intro i ważne komunikaty fabularne. + +Ten dokument nie powinien definiować: + +- formuł gameplayowych, +- reguł walki, +- progresji XP, +- efektów traits, +- systemów frakcji, +- quest-chain logic. + +## Szkielet do uzupełniania + +### 1. Premisa + +```text +TU WPISZ KRÓTKĄ PREMISĘ MISJI I GŁÓWNY POWÓD, DLA KTÓREGO STATEK SZUKA ŻYCIA. +``` + +### 2. Ton i klimat + +```text +TU WPISZ JAK MA SIĘ CZUĆ GRA: SAMOTNOŚĆ, CIEKAWOŚĆ, NIEPOKÓJ, HUMOR, NADZIEJA ITD. +``` + +### 3. Świat i tło + +```text +TU WPISZ NAJWAŻNIEJSZE FAKTY O ŚWIECIE, ALE TYLKO TE, KTÓRE MUSZĄ BYĆ KANONEM. +``` + +### 4. Załoga jako postacie + +| Rola | Funkcja fabularna | Styl wypowiedzi | Konflikty / napięcia | Notatki | +|---|---|---|---|---| +| Captain | | | | | +| Pilot | | | | | +| Engineer | | | | | +| Scientist | | | | | +| Medic | | | | | +| Security | | | | | + +### 5. Intro + +```text +TU WPISZ TEKST INTRO LUB JEGO PIERWSZĄ WERSJĘ. +``` + +### 6. Motywy eventów + +- [ ] opuszczone miejsca +- [ ] ślady życia +- [ ] błędne odczyty +- [ ] napięcia w załodze +- [ ] decyzje o ryzyku +- [ ] anomalie i tajemnice + +### 7. Pytania otwarte + +- [ ] Jakie odkrycie ma najmocniej definiować główną tajemnicę? +- [ ] Jak bardzo osobista ma być relacja gracza z załogą? +- [ ] Czy narracja ma być bardziej suchym logbookiem czy dialogową opowieścią? diff --git a/docs/GAME_BRIEF.md b/docs/GAME_BRIEF.md new file mode 100644 index 0000000..99a71a4 --- /dev/null +++ b/docs/GAME_BRIEF.md @@ -0,0 +1,52 @@ +# GAME BRIEF + +## Working title + +- **SpaceshipGame / Star Search** + +## High concept + +A retro pixel-art spaceship management game about leading a fragile mission searching for signs of life far from home. + +## Player fantasy + +- command a small ship, +- keep the crew alive and functional, +- make tense expedition decisions, +- slowly uncover whether life exists in the unknown sectors. + +## Product pillars + +1. **Ship management under pressure** +2. **Readable, data-driven content** +3. **Narrative mystery before combat spectacle** +4. **Browser-first, mobile-aware play** + +## Tone + +- retro sci-fi, +- isolation, +- curiosity, +- controlled tension. + +## What this brief should stabilize + +- who the player is, +- what success feels like, +- what the mission is about, +- what kind of story tone later content should follow. + +## Out of scope for this brief + +- combat formulas, +- progression curves, +- trait effects, +- detailed morale logic, +- quest chains, +- faction systems. + +## Related documents + +- Narrative canon: `docs/FABULA.md` +- Structured design: `docs/GDD.md` +- Gameplay rules and tables: `mechanika/` diff --git a/docs/GDD.md b/docs/GDD.md new file mode 100644 index 0000000..c020508 --- /dev/null +++ b/docs/GDD.md @@ -0,0 +1,51 @@ +# Game Design Document + +## Status model + +- **Approved now** — safe to use before the final mechanika pass. +- **Reserved** — known placeholder that must not be fully implemented yet. +- **Open question** — needs user decision or later spec work. + +## Product frame + +- Brief source: `docs/GAME_BRIEF.md` +- Narrative source: `docs/FABULA.md` +- Mechanics source: `mechanika/` + +## Core player loop + +- **Approved now:** manage ship state, review crew, travel, resolve events, track mission progress. +- **Reserved:** advanced combat, progression, and quest-chain loops. + +## Content tracks + +### Narrative and worldbuilding + +- **Approved now:** create and maintain the story baseline in `docs/FABULA.md`. +- **Open question:** which story beats should be mandatory in MVP events. + +### Mechanics and balance + +- **Reserved:** final formulas and balance values until `mechanika/` is filled. + +### UI and scene planning + +- **Approved now:** document scene order, overlays, and mobile-first priorities. + +## Crew and content placeholders + +- **Approved now:** crew roles, skills fields, morale fields, and event hooks may be described at a high level. +- **Reserved:** trait effects, XP curves, faction behaviors, and quest logic. + +## Documentation workflow + +1. Stabilize `docs/GAME_BRIEF.md`. +2. Build or revise `docs/FABULA.md`. +3. Keep `docs/GDD.md` aligned with the brief, fabula, and scope. +4. Move final gameplay rules into `mechanika/` as they are approved. + +## Open questions + +- What is the first narrative revelation the player should encounter? +- Which event themes must exist before the first playable prototype? +- Which crew relationships are canon versus left systemic/open? diff --git a/docs/IDEAS_LATER.md b/docs/IDEAS_LATER.md index 4f837a7..1b48932 100644 --- a/docs/IDEAS_LATER.md +++ b/docs/IDEAS_LATER.md @@ -12,7 +12,7 @@ Anything here is explicitly outside the MVP unless moved into `docs/SCOPE.md` by - [ ] Factions and diplomacy. - [ ] Multiple starting ships. - [ ] 50+ events after the MVP proves the loop. -- [ ] Main story arc. +- [ ] Expanded multi-act story arc after the baseline canon is established in `docs/FABULA.md`. ## Technology diff --git a/docs/skills-adoption/README.md b/docs/skills-adoption/README.md index e4e1ebb..fecac9e 100644 --- a/docs/skills-adoption/README.md +++ b/docs/skills-adoption/README.md @@ -148,8 +148,10 @@ These are additions to the previous target set, grouped by adoption value. - Existing `scaffold-scene` skill. - Existing `scaffold-system` skill. - BMad-adapted `game-brief` package. +- BMad-adapted `fabula` package for story-first work. - BMad-adapted `gdd` package. - BMad-adapted `mechanika-spec` skill. +- BMad-adapted `story-bible` skill. - BMad-adapted `architecture` package. - `skill-creator` / `agent-skill-creator` pattern. - `content-research-writer` or equivalent documentation authoring skill. @@ -200,12 +202,14 @@ These are additions to the previous target set, grouped by adoption value. - Art/design pipeline gate. 3. **Execute unblocked docs/design work first**: - create or update game brief prompt/docs, + - create or update fabula prompt/docs, - create or update GDD prompt/docs, - - create or update mechanika-spec skill, + - create or update mechanika-spec and story-bible skills, - create or update architecture/investigate prompts, - keep README/docs indexes current. 4. **Prepare skills before MCP installs**: - create local skills from selected patterns, + - stage raw or draft imports in `.github/skills/incoming/`, - document source, purpose, acceptance criteria, and activation gate, - avoid bulk imports. 5. **Only then configure MCPs**: diff --git a/mechanika/README.md b/mechanika/README.md index f984fff..e7b229e 100644 --- a/mechanika/README.md +++ b/mechanika/README.md @@ -2,7 +2,7 @@ English summary: start with `00-template-do-wypelnienia.md`, then move refined sections into the numbered files in this folder. The detailed guide below is in Polish. -Ten folder jest miejscem na Twoją specyfikację mechaniki gry. To ona będzie później podstawą dla implementacji systemów takich jak `CrewSystem`, `MissionSystem`, `EventSystem`, `BattleSystem`, `TraitSystem` i `ProgressionSystem`. +Ten folder jest miejscem na Twoją specyfikację mechaniki gry. To ona będzie później podstawą dla implementacji systemów takich jak `CrewSystem`, `MissionSystem`, `EventSystem`, `BattleSystem`, `TraitSystem` i `ProgressionSystem`. Fabuła, ton i kanon narracyjny mają teraz osobny dom w `docs/FABULA.md`. ## Jak pracować