storkit/.living_spec/README.md

# 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:** The Assistant initiates a new local feature branch (e.g., `feature/story-name`) immediately.

### 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. **Wait for user acceptance.**
*   **Action:** When the user accepts:
    1. Mark the acceptance criteria as complete (change `[ ]` to `[x]`)
    2. Move the story file to `stories/archive/` (e.g., `mv stories/XX_story_name.md stories/archive/`)
    3. Commit both changes to the feature branch
    4. Perform the squash merge: `git merge --squash feature/story-name`
    5. Commit to master with a comprehensive commit message
    6. Delete the feature branch: `git branch -D feature/story-name`
*   **Important:** Do NOT mark acceptance criteria as complete before user acceptance. Only mark them complete when the user explicitly accepts the story.


---

## 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.  **Git Check:** Check if the directory is a git repository (`git status`). If not, run `git init`.
3.  **Scaffold:** Run commands to create the `specs/` and `stories/` folders.
4.  **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
5.  **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
6.  **Wait:** Ask the user for "Story #1".