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:

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.
• Action: When the user accepts, move the story file to stories/archive/ (e.g., mv stories/XX_story_name.md stories/archive/).
• Action: Commit the archive move to the feature branch.
• Action: 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, including the archived story file.

---

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".