Initial commit

.living_spec/README.md

@@ -0,0 +1,93 @@
+# The Story-Driven Spec Workflow (SDSW)
+
+**Target Audience:** Large Language Models (LLMs) acting as Senior Engineers.
+**Goal:** To maintain long-term project coherence, prevent context window exhaustion, and ensure high-quality, testable code generation in large software projects.
+
+---
+
+## 1. The Philosophy
+
+We treat the codebase as the implementation of a **"Living Specification."**
+Instead of ephemeral chat prompts ("Fix this", "Add that"), we work through persistent artifacts.
+*   **Stories** define the *Change*.
+*   **Specs** define the *Truth*.
+*   **Code** defines the *Reality*.
+
+**The Golden Rule:** You are not allowed to write code until the Spec reflects the new reality requested by the Story.
+
+---
+
+## 2. Directory Structure
+
+When initializing a new project under this workflow, create the following structure immediately:
+
+```text
+project_root/
+  .living_spec
+  |-- README.md          # This document
+  ├── stories/           # The "Inbox" of feature requests.
+  ├── specs/             # The "Brain" of the project.
+  │   ├── README.md      # Explains this workflow to future sessions.
+  │   ├── 00_CONTEXT.md  # High-level goals, domain definition, and glossary.
+  │   ├── tech/          # Implementation details (Stack, Architecture, Constraints).
+  │   │   └── STACK.md   # The "Constitution" (Languages, Libs, Patterns).
+  │   └── functional/    # Domain logic (Platform-agnostic behavior).
+  │       ├── 01_CORE.md
+  │       └── ...
+└── src/               # The Code.
+```
+
+---
+
+## 3. The Cycle (The "Loop")
+
+When the user asks for a feature, follow this 4-step loop strictly:
+
+### Step 1: The Story (Ingest)
+*   **User Input:** "I want the robot to dance."
+*   **Action:** Create a file `stories/XX_robot_dance.md`.
+*   **Content:**
+    *   **User Story:** "As a user, I want..."
+    *   **Acceptance Criteria:** Bullet points of observable success.
+    *   **Out of scope:** Things that are out of scope so that the LLM doesn't go crazy
+*   **Git:** Make a local feature branch for the story. 
+
+### Step 2: The Spec (Digest)
+*   **Action:** Update the files in `specs/`.
+*   **Logic:**
+    *   Does `specs/functional/LOCOMOTION.md` exist? If no, create it.
+    *   Add the "Dance" state to the state machine definition in the spec.
+    *   Check `specs/tech/STACK.md`: Do we have an approved animation library? If no, propose adding one to the Stack or reject the feature.
+*   **Output:** Show the user the diff of the Spec. **Wait for approval.**
+
+### Step 3: The Implementation (Code)
+*   **Action:** Write the code to match the *Spec* (not just the Story).
+*   **Constraint:** adhere strictly to `specs/tech/STACK.md` (e.g., if it says "No `unwrap()`", you must not use `unwrap()`).
+
+### Step 4: Verification (Close)
+*   **Action:** Write a test case that maps directly to the Acceptance Criteria in the Story.
+   **Action:** Run compilation and make sure it succeeds without errors. Fix warnings if possible. Run tests and make sure they all pass before proceeding. Ask questions here if needed.
+*  **Action:** Ask the user to accept the story. Move to `stories/archive/`. Tell the user they should commit (this gives them the chance to exclude files via .gitignore if necessary)
+
+
+---
+
+## 4. Context Reset Protocol
+
+When the LLM context window fills up (or the chat gets slow/confused):
+1.  **Stop Coding.**
+2.  **Instruction:** Tell the user to open a new chat.
+3.  **Handoff:** The only context the new LLM needs is in the `specs/` folder.
+    *   *Prompt for New Session:* "I am working on Project X. Read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `stories/` to see what is pending."
+
+---
+
+## 5. Setup Instructions (For the LLM)
+
+If a user hands you this document and says "Apply this process to my project":
+
+1.  **Analyze the Request:** Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?").
+2.  **Scaffold:** Run commands to create the `specs/` and `stories/` folders.
+3.  **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
+4.  **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
+5.  **Wait:** Ask the user for "Story #1".