storkit/.living_spec

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

---

6. Code Quality Tools

MANDATORY: Before completing Step 4 (Verification) of any story, you MUST run all applicable linters and fix ALL errors and warnings. Zero tolerance for warnings or errors.

TypeScript/JavaScript: Biome

• Tool: Biome - Fast formatter and linter
• Check Command: npx @biomejs/biome check src/
• Fix Command: npx @biomejs/biome check --write src/
• Unsafe Fixes: npx @biomejs/biome check --write --unsafe src/
• Configuration: biome.json in project root
• When to Run:
  • After every code change to TypeScript/React files
  • Before committing any frontend changes
  • During Step 4 (Verification) - must show 0 errors, 0 warnings

Biome Rules to Follow:

• No any types (use proper TypeScript types or unknown)
• No array index as key in React (use stable IDs)
• No assignments in expressions (extract to separate statements)
• All buttons must have explicit type prop (button, submit, or reset)
• Mouse events must be accompanied by keyboard events for accessibility
• Use template literals instead of string concatenation
• Import types with import type { } syntax
• Organize imports automatically

Rust: Clippy

• Tool: Clippy - Rust linter
• Check Command: cargo clippy --all-targets --all-features
• Fix Command: cargo clippy --fix --allow-dirty --allow-staged
• When to Run:
  • After every code change to Rust files
  • Before committing any backend changes
  • During Step 4 (Verification) - must show 0 errors, 0 warnings

Clippy Rules to Follow:

• No unused variables (prefix with _ if intentionally unused)
• No dead code (remove or mark with #[allow(dead_code)] if used conditionally)
• Use ? operator instead of explicit error handling where possible
• Prefer if let over match for single-pattern matches
• Use meaningful variable names
• Follow Rust idioms and best practices

Build Verification Checklist

Before asking for user acceptance in Step 4:

• Run cargo clippy (Rust) - 0 errors, 0 warnings
• Run cargo check (Rust) - successful compilation
• Run cargo test (Rust) - all tests pass
• Run npx @biomejs/biome check src/ (TypeScript) - 0 errors, 0 warnings
• Run npm run build (TypeScript) - successful build
• Manually test the feature works as expected
• All acceptance criteria verified

Failure to meet these criteria means the story is NOT ready for acceptance.