StasisWarden-Legacy/docs/prd.md

Stasis Warden Product Requirements Document (PRD)

1. Goals and Background Context

1.1. Goals

• Create a fun and engaging game that blends strategic ship-building with deep social simulation.
• Prove the core gameplay loop is engaging and offers high replayability.
• Deliver a unique player experience driven by a narrative of self-discovery.
• Successfully create a unique story for players with each playthrough.

1.2. Background Context

Stasis Warden is a sci-fi strategy game where the player embodies the amnesiac AI of a derelict generation starship. Following a catastrophic event, the ship's crew is in emergency cryo-sleep, and the AI's own systems are damaged. The core problem is to restore the ship's functionality and save the crew, which in turn allows the player to rediscover their own identity as the AI.

The project aims to provide a unique value proposition by combining strategic ship management with a deep, emergent social simulation. The narrative unfolds through gameplay mechanics, as restoring ship systems also repairs the AI's fragmented memory, revealing its true nature and capabilities over time. This is a passion project focused on creating a compelling single-player experience rather than on commercial metrics.

1.3. Change Log

Date	Version	Description	Author
2025-08-18	1.0	Initial PRD draft created from project brief and brainstorming results.	John (PM)

---

2. Requirements

2.1. Functional

• FR1: The player can manually generate the Power resource by clicking on the Power Core.
• FR2: The player can expend Power to unlock new rooms adjacent to existing, powered rooms.
• FR3: When a new room is unlocked, the player is presented with a choice of 3 "Room Cards" to determine the new room's type.
• FR4: The player can expend Power to awaken a crew member from a Cryo Stasis Pod.
• FR5: An awakened crew member can be assigned to a task (e.g., the Power Core) to automate resource generation.
• FR6: The game is presented to the player through a diegetic CRT monitor interface.
• FR7: The primary ship view is a top-down, point-and-click map.
• FR8: A dedicated UI "shelf" temporarily appears to display the 3 "Room Cards" during a selection choice.
• FR9: Each crew member must have stats (e.g., Engineering, Biology) that influence their performance at related tasks.
• FR10: Each crew member must have at least one positive and one negative personality trait.
• FR11: The UI must display a persistent list of all major resources (e.g., Power).
• FR12: The UI must display a persistent, clickable list of all awakened crew members.

2.2. Non-Functional

• NFR1: The game must be playable on Windows and Linux.
• NFR2: The project must be developed using the Godot game engine.
• NFR3: The standard IDE for development will be Visual Studio Code.
• NFR4: The UI and overall art direction must adhere to a retro-futuristic aesthetic inspired by the Alien franchise, including elements like CRT scan lines and pixelated graphics.

---

3. User Interface Design Goals

3.1. Overall UX Vision

The player experiences the game from the literal point-of-view of the amnesiac ship AI. The entire UI is diegetic, presented as a retro-futuristic CRT monitor. The vision is to create an immersive experience where managing the ship feels tactile and analog, reinforcing the narrative of the player being a machine interfacing with its own systems.

3.2. Key Interaction Paradigms

• Direct Manipulation: The primary interaction is point-and-click on the ship map to select rooms and assign crew.
• Card-Based Choice: Key strategic decisions, like building new rooms, are presented as a choice between three physical-style "Room Cards".
• Physical Controls Metaphor: The UI will feature non-functional (for MVP) but visually present physical-style buttons and knobs to enhance the analog, retro feel.

3.3. Core Screens and Views

• Main Ship View: The central CRT screen displaying the top-down map of the ship.
• Resource Panel: A dedicated area on the screen (left panel) to track key resources like Power.
• Crew Roster: A dedicated area (right panel) listing all crew members, with the ability to click to see details.
• Room Card Shelf: A temporary view that appears at the bottom of the screen to present room choices.
• Main Menu: A standard menu for Save/Load/Options, accessed via a "physical" button.

3.4. Accessibility: None

(Assumption: As a solo passion project, specific accessibility standards like WCAG are not an initial MVP requirement).

3.5. Branding

The aesthetic is heavily inspired by the retro-futurism of the Alien franchise. This includes a pixelated font, CRT scan lines, and a green or amber monochrome color palette for the main display.

3.6. Target Device and Platforms: Desktop Only

(Based on the requirement for Windows and Linux).

---

4. Technical Assumptions

4.1. Repository Structure: Monorepo

(Assumption: A single repository is most efficient for a solo developer managing a self-contained project).

4.2. Service Architecture: Monolith

(Based on the nature of a standalone desktop game, the application will be a single, monolithic executable).

4.3. Testing Requirements: Unit Only

(Assumption: Given the "passion project" and "vibe coding" nature, a heavy testing suite is not an MVP priority. This assumes that basic unit tests for critical logic will be sufficient initially).

4.4. Additional Technical Assumptions and Requests

• Game Engine: The project will be built exclusively with the Godot engine.
• IDE: The standard development environment will be Visual Studio Code.
• Asset Pipeline: A strategy for acquiring or creating art and sound assets needs to be defined. This is currently a key open question.

---

5. Epic List

• Epic 1: The Spark of Consciousness (Foundation & Core Loop)

  • Goal: Establish the project foundation and implement the initial manual gameplay loop, allowing the player to generate power and view the game world through the core UI.

• Epic 2: The First Awakening (Automation & Expansion)

  • Goal: Introduce crew automation and the primary ship expansion mechanic, shifting the game from manual clicks to strategic choices.

• Epic 3: A New Society (Crew & Social Foundation)

  • Goal: Implement the core attributes for crew members (stats and traits), laying the groundwork for all future social simulation features.

---

Epic 1: The Spark of Consciousness (Foundation & Core Loop)

Goal: This epic establishes the foundational elements of the game, including the initial project setup and the core diegetic UI. It delivers the very first piece of interactive gameplay: the ability for the player, as the AI, to manually generate power, providing the initial resource needed to begin restoring the ship.

---

Story 1.1: Project Initialization & Canary Screen

• As a developer,
• I want to set up a new Godot project with version control,
• so that I have a clean foundation to start building the game.

Acceptance Criteria:

1. A new Godot project is created and configured.
2. A Git repository is initialized for the project.
3. The project can be launched to display a single, empty screen with a version number, confirming the build pipeline is working.

---

Story 1.2: Diegetic CRT Monitor UI Shell

• As the AI,
• I want to see the game world through a diegetic CRT monitor,
• so that I feel immersed in my role as the ship's central intelligence.

Acceptance Criteria:

1. The main game view is framed to look like a CRT monitor.
2. A post-processing shader is applied to create a subtle scan-line effect.
3. The UI includes static, non-functional visual placeholders for the Resource Panel (left) and Crew Roster (right).
4. The default font used in the UI is pixelated to match the retro aesthetic.

---

Story 1.3: The Lonely Power Core

• As the AI,
• I want to start the game with a view of a single, powered room—the Power Core—
• so that I have a clear starting point for my actions.

Acceptance Criteria:

1. When the game starts, a top-down view of one room, the "Power Core," is displayed on the CRT monitor.
2. The Power Core room has a distinct visual representation on the ship map.
3. The player can hover over and click on the Power Core object within the room.

---

Story 1.4: Manual Power Generation

• As the AI,
• I want to manually generate Power by clicking on the Power Core,
• so that I can accumulate the resources needed to begin repairs.

Acceptance Criteria:

1. Clicking the Power Core object increments the player's Power resource by a fixed amount (e.g., 1 unit).
2. The current Power total is displayed and correctly updated in the Resource Panel UI placeholder.
3. There is immediate visual or audio feedback when the Power Core is clicked successfully.

---

Epic 2: The First Awakening (Automation & Expansion)

Goal: This epic introduces the next layer of the core gameplay loop, moving the player from purely manual actions to strategic decision-making. It allows the player to use their generated power to expand the ship and awaken the first crew member, enabling task automation for the first time.

---

Story 2.1: Unlocking Rooms

• As the AI,
• I want to spend Power to unlock doors to adjacent, unpowered rooms,
• so that I can expand my operational area.

Acceptance Criteria:

1. Doors on the map adjacent to the powered Power Core room are visually distinct and clickable.
2. Clicking a locked door presents a confirmation prompt showing the Power cost.
3. If the player has enough Power and confirms, the cost is deducted and the door is permanently unlocked, revealing an empty room space.
4. If the player does not have enough Power, they are notified and the action is cancelled.

---

Story 2.2: Room Card Selection

• As the AI,
• I want to be presented with a choice of 3 "Room Cards" when I create a new room,
• so that I can strategically decide how my ship develops.

Acceptance Criteria:

1. Upon successfully creating an empty room space (per Story 2.1), the game pauses and the "Room Card Shelf" UI appears.
2. The shelf displays three distinct Room Cards. For the first occurrence, one card must be "Cryo Stasis Room".
3. The player can select a card by clicking on it.
4. Upon selection, the new room is built and given the visual representation of the chosen card type. The Room Card Shelf UI disappears.

---

Story 2.3: The First Sleeper

• As the AI,
• I want to be able to awaken a crew member from a stasis pod,
• so that I have help in running the ship.

Acceptance Criteria:

1. A newly created "Cryo Stasis Room" contains at least one clickable stasis pod object.
2. Clicking a stasis pod shows a Power cost to initiate the awakening sequence.
3. If the player has enough Power and confirms, the cost is deducted.
4. After a short delay or animation, a crew member entity appears in the room.
5. The newly awakened crew member is added to the Crew Roster UI panel.

---

Story 2.4: Task Automation

• As the AI,
• I want to assign an awakened crew member to the Power Core,
• so that they can generate Power for me automatically.

Acceptance Criteria:

1. The player can select an awakened crew member (e.g., by clicking them on the map or roster).
2. With a crew member selected, the player can click on the Power Core to assign them to the task.
3. An assigned crew member is visually represented at or near the Power Core.
4. When a crew member is assigned, the Power resource begins to increment automatically over time.
5. The player can no longer generate power manually by clicking the Power Core while a crew member is assigned to it.

---

Epic 3: A New Society (Crew & Social Foundation)

Goal: This epic implements the foundational data structures and UI elements for crew members, establishing their unique identities. It focuses on creating the underlying systems for stats and traits that will drive all future social simulation and task performance mechanics.

---

Story 3.1: Crew Member Stats

• As the AI,
• I want each crew member to have a set of core stats,
• so that their performance at different tasks can be measured and compared.

Acceptance Criteria:

1. Each crew member, upon creation (from Story 2.3), is assigned a set of stats (e.g., Engineering, Biology).
2. The values for these stats are generated within a predefined range (e.g., 1-10).
3. When a crew member is selected in the Crew Roster, their stats are visible in a details panel.
4. The rate of automated Power generation (from Story 2.4) is now modified based on the assigned crew member's relevant stat (e.g., Engineering).

---

Story 3.2: Crew Member Traits

• As the AI,
• I want each crew member to have unique personality traits,
• so that they feel like individuals and to set the stage for social dynamics.

Acceptance Criteria:

1. Each crew member, upon creation, is assigned at least one positive and one negative personality trait from a predefined list.
2. The assigned traits are visible in the crew member's details panel in the Crew Roster.
3. For the MVP, these traits have no mechanical effect on gameplay.

---

6. Checklist Results Report

Executive Summary

• Overall PRD Completeness: 75%
• MVP Scope Appropriateness: Just Right
• Readiness for Architecture Phase: Nearly Ready
• Most Critical Gaps: The PRD is strong on the "what" (functional requirements, epics, stories) but is missing key details on "how well" and "how to manage." The most significant gaps are the lack of any specific non-functional requirements (performance, security) and cross-functional requirements (data persistence, operations). The architect can begin work, but will need to make significant assumptions in these areas if they are not addressed.

Category Analysis Table

Category	Status	Critical Issues
1. Problem Definition & Context	PASS	None.
2. MVP Scope Definition	PASS	None.
3. User Experience Requirements	PASS	None.
4. Functional Requirements	PASS	None.
5. Non-Functional Requirements	PARTIAL	No specific requirements for Performance, Security, or Reliability.
6. Epic & Story Structure	PASS	None.
7. Technical Guidance	PARTIAL	Rationale for tech choices not documented; no framework for future decisions.
8. Cross-Functional Requirements	FAIL	No requirements for Data (persistence), Integrations, or Operations.
9. Clarity & Communication	PASS	None.

Top Issues by Priority

• HIGH:
  • Data Persistence: The PRD does not specify how game state (ship layout, crew stats, resources) should be saved and loaded. This is a critical architectural consideration.
  • Performance/Security: There are no defined performance targets (e.g., FPS) or security considerations. While a passion project, these should be acknowledged.
• MEDIUM:
  • Technical Rationale: The PRD lists technologies (Godot, VS Code) but doesn't document why they were chosen, which can be important context for future decisions.
  • Operational Needs: No mention of how the game will be built, deployed, or monitored, even at a high level.

Recommendations

1. Address Data Persistence: Before the developer begins work on Epic 2, a new story should be added to Epic 1 to handle saving and loading the game state.
2. Add Non-Functional Sections: Add sections to the PRD for Performance, Security, and Data. Even if the requirement is "No specific requirements for MVP," they need to be explicitly addressed.
3. Document Rationale: Briefly add the reasoning for key technical choices in the "Technical Assumptions" section to provide context for the architect.

---

7. Next Steps

7.1. UX Expert Prompt

"Please review the attached PRD (docs/prd.md), specifically the 'User Interface Design Goals' section. Based on this, create a front-end specification that includes wireframes for the core screens and a detailed breakdown of the UI components."

7.2. Architect Prompt

"Please review the attached PRD (docs/prd.md). Based on the requirements, assumptions, and epics defined within, create a comprehensive Architecture document for the Stasis Warden project."

---

8. Appendix

8.1. Open Questions

1. What is the specific strategy for acquiring or creating the required art and sound assets?
2. What is the desired mechanism for game state persistence (e.g., local JSON files, cloud saves)?
3. Are there any specific performance targets (e.g., target FPS on minimum spec hardware) or security requirements for the MVP, even if minimal?

8.2. References

• docs/brief.md
• docs/brainstorming-session-results.md

8.3. Glossary

None for this version.

8.4. Diagrams

None for this version.