dave/storkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Refocus workflow on TDD and reorganize stories

Browse Source
This commit is contained in:
Dave
2026-02-17 13:34:32 +00:00
parent 1f4f10930f
commit 4c887d93b5
42 changed files with 155 additions and 498 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
.story_kit/README.md
View File

@@ -13,7 +13,7 @@ Instead of ephemeral chat prompts ("Fix this", "Add that"), we work through pers
* **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.
**The Golden Rule:** You are not allowed to write code until the Acceptance Criteria are captured in a test TODO file and the test plan is approved.
---
@@ -25,7 +25,7 @@ When initializing a new project under this workflow, create the following struct
project_root/
.story_kit
|-- README.md # This document
├── stories/ # The "Inbox" of feature requests.
├── stories/ # Story workflow (upcoming/current/archived).
├── specs/ # The "Brain" of the project.
│ ├── README.md # Explains this workflow to future sessions.
│ ├── 00_CONTEXT.md # High-level goals, domain definition, and glossary.
@@ -45,31 +45,36 @@ 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`.
* **Action:** Create a file in `stories/upcoming/` (e.g., `stories/upcoming/XX_robot_dance.md`).
* **Move to Current:** Once the story is validated and ready for coding, move it to `stories/current/`.
* **Create Test TODOs:** Create `tests/todo/story-XX.todo` with one comment per Acceptance Criterion (e.g., `// AC: story-XX#1 - ...`).
* **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
* **Story Quality (INVEST):** Stories should be Independent, Negotiable, Valuable, Estimable, Small, and Testable.
* **Git:** Make a local feature branch for the story, named from the story (e.g., `feature/story-33-camera-format-auto-selection`). You must create and switch to the feature branch before making any edits.
### Step 2: The Spec (Digest)
* **Action:** Update the files in `specs/`.
### Step 2: Test Planning (TDD)
* **Action:** Define the test plan for the Story before any implementation.
* **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.**
* Identify required unit tests and integration tests.
* Confirm test frameworks and commands from `specs/tech/STACK.md`.
* Ensure Acceptance Criteria are testable and mapped to planned tests.
* Each Acceptance Criterion must appear as a single TODO comment in `tests/todo/story-XX.todo`.
* **Output:** Show the user the test plan. **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:** For each TODO comment, write a failing test (red), delete the comment, make the test pass (green), and refactor if needed. Keep only one failing test at a time.
* **Action:** Run compilation and make sure it succeeds without errors. Consult `specs/tech/STACK.md` and run all required linters listed there (treat warnings as errors). Run tests and make sure they all pass before proceeding. Ask questions here if needed.
* **Action:** Do not accept stories yourself. Ask the user if they accept the story. If they agree, move the story file to `stories/archive/`. Tell the user they should commit (this gives them the chance to exclude files via .gitignore if necessary).
* **Action:** Do not accept stories yourself. Ask the user if they accept the story. If they agree, move the story file to `stories/archived/`. Tell the user they should commit (this gives them the chance to exclude files via .gitignore if necessary).
* **Move to Archived:** After acceptance, move the story from `stories/current/` to `stories/archived/`.
* **Action:** When the user accepts:
1. Move the story file to `stories/archive/` (e.g., `mv stories/XX_story_name.md stories/archive/`)
1. Move the story file to `stories/archived/` (e.g., `mv stories/current/XX_story_name.md stories/archived/`)
2. Commit both changes to the feature branch
3. Perform the squash merge: `git merge --squash feature/story-name`
4. Commit to master with a comprehensive commit message
@@ -79,12 +84,12 @@ When the user asks for a feature, follow this 4-step loop strictly:
**CRITICAL - NO SUMMARY DOCUMENTS:**
* **NEVER** create a separate summary document (e.g., `STORY_XX_SUMMARY.md`, `IMPLEMENTATION_NOTES.md`, etc.)
* **NEVER** write terminal output to a markdown file for "documentation purposes"
* The `specs/` folder IS the documentation. Keep it updated after each story.
* Tests are the primary source of truth. Keep test coverage and Acceptance Criteria aligned after each story.
* If you find yourself typing `cat << 'EOF' > SUMMARY.md` or similar, **STOP IMMEDIATELY**.
* The only files that should exist after story completion:
* Updated code in `src/`
* Updated specs in `specs/`
* Archived story in `stories/archive/`
* Archived story in `stories/archived/`
---