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:

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. Move to stories/archive/. Tell the user to Squash Merge the feature branch (e.g. git merge --squash feature/story-name) and commit. This ensures the main history reflects one atomic commit per Story.

4. Context Reset Protocol

When the LLM context window fills up (or the chat gets slow/confused):

Stop Coding.
Instruction: Tell the user to open a new chat.
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":

Analyze the Request: Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?").
Git Check: Check if the directory is a git repository (git status). If not, run git init.
Scaffold: Run commands to create the specs/ and stories/ folders.
Draft Context: Write specs/00_CONTEXT.md based on the user's answer.
Draft Stack: Write specs/tech/STACK.md based on best practices for that language.
Wait: Ask the user for "Story #1".