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

Bringing README up to date.

Browse Source
This commit is contained in:
Dave
2026-02-23 11:51:35 +00:00
parent 4e83b30f8b
commit 83b2e0e700
1 changed files with 53 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
.story_kit/README.md
View File

@@ -12,7 +12,7 @@ When you start a new session with this project:
1. **Check for MCP Tools:** Read `.mcp.json` to discover available programmatic tools. If it exists, you have direct access to workflow automation tools (create stories, spawn agents, record tests, etc.) via the MCP server. 1. **Check for MCP Tools:** Read `.mcp.json` to discover available programmatic tools. If it exists, you have direct access to workflow automation tools (create stories, spawn agents, record tests, etc.) via the MCP server.
2. **Read Context:** Check `.story_kit/specs/00_CONTEXT.md` for high-level project goals. 2. **Read Context:** Check `.story_kit/specs/00_CONTEXT.md` for high-level project goals.
3. **Read Stack:** Check `.story_kit/specs/tech/STACK.md` for technical constraints and patterns. 3. **Read Stack:** Check `.story_kit/specs/tech/STACK.md` for technical constraints and patterns.
4. **Check Stories:** Look at `.story_kit/stories/upcoming/` and `.story_kit/stories/current/` to see what work is pending. 4. **Check Work Items:** Look at `.story_kit/work/1_upcoming/` and `.story_kit/work/2_current/` to see what work is pending.
**Why This Matters:** The `.mcp.json` file indicates that you have programmatic access to tools like `create_story`, `start_agent`, `list_agents`, `get_agent_output`, and more. These tools allow you to directly manipulate the workflow and spawn subsidiary agents without manual file manipulation. **Why This Matters:** The `.mcp.json` file indicates that you have programmatic access to tools like `create_story`, `start_agent`, `list_agents`, `get_agent_output`, and more. These tools allow you to directly manipulate the workflow and spawn subsidiary agents without manual file manipulation.
@@ -40,25 +40,48 @@ Agents have programmatic access to the workflow via MCP tools served at `POST /m
## 2. Directory Structure ## 2. Directory Structure
When initializing a new project under this workflow, create the following structure immediately:
```text ```text
project_root/ project_root/
.mcp.json # MCP server configuration (if MCP tools are available) .mcp.json # MCP server configuration (if MCP tools are available)
.story_kit/ .story_kit/
|-- README.md # This document ├── README.md # This document
├── stories/ # Story workflow (upcoming/current/archived). ├── project.toml # Agent configuration (roles, models, prompts)
├── specs/ # Minimal guardrails (context + stack). ├── work/ # Unified work item pipeline (stories, bugs, spikes)
│ ├── README.md # Explains this workflow to future sessions. │ ├── 1_upcoming/ # New work items awaiting implementation
│ ├── 00_CONTEXT.md # High-level goals, domain definition, and glossary. │ ├── 2_current/ # Work in progress
│ ├── tech/ # Implementation details (Stack, Architecture, Constraints). │ ├── 3_qa/ # QA review
│ │ └── STACK.md # The "Constitution" (Languages, Libs, Patterns). │ ├── 4_merge/ # Ready to merge to master
│ └── functional/ # Domain logic (Platform-agnostic behavior). │ └── 5_archived/ # Completed work
│ ├── 01_CORE.md ├── worktrees/ # Agent worktrees (managed by the server)
├── specs/ # Minimal guardrails (context + stack)
│ ├── 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)
│ └── ... │ └── ...
└── src/ # The Code. └── src/ # The Code
``` ```
### Work Items
All work items (stories, bugs, spikes) live in the same `work/` pipeline. Items are named: `{id}_{type}_{slug}.md`
* Stories: `57_story_live_test_gate_updates.md`
* Bugs: `4_bug_run_button_does_not_start_agent.md`
* Spikes: `61_spike_filesystem_watcher_architecture.md`
Items move through stages by moving the file between directories:
`1_upcoming` → `2_current` → `3_qa` → `4_merge` → `5_archived`
### Filesystem Watcher
The server watches `.story_kit/work/` for changes. When a file is created, moved, or modified, the watcher auto-commits with a deterministic message and broadcasts a WebSocket notification to the frontend. This means:
* MCP tools only need to write/move files — the watcher handles git commits
* IDE drag-and-drop works (drag a story from `1_upcoming/` to `2_current/`)
* The frontend updates automatically without manual refresh
--- ---
## 3. The Cycle (The "Loop") ## 3. The Cycle (The "Loop")
@@ -67,8 +90,8 @@ When the user asks for a feature, follow this 4-step loop strictly:
### Step 1: The Story (Ingest) ### Step 1: The Story (Ingest)
* **User Input:** "I want the robot to dance." * **User Input:** "I want the robot to dance."
* **Action:** Create a story via MCP tool `create_story` (preferred — guarantees correct front matter and auto-assigns the story number). Alternatively, create a file manually in `stories/upcoming/` (e.g., `stories/upcoming/XX_robot_dance.md`). * **Action:** Create a story via MCP tool `create_story` (guarantees correct front matter and auto-assigns the story number).
* **Front Matter (Required):** Every story file MUST begin with YAML front matter containing `name` and `test_plan` fields: * **Front Matter (Required):** Every work item file MUST begin with YAML front matter containing `name` and `test_plan` fields:
```yaml ```yaml
--- ---
name: Short Human-Readable Story Name name: Short Human-Readable Story Name
@@ -76,14 +99,14 @@ When the user asks for a feature, follow this 4-step loop strictly:
--- ---
``` ```
The `test_plan` field tracks approval status: `pending` → `approved` (after Step 2). The `test_plan` field tracks approval status: `pending` → `approved` (after Step 2).
* **Move to Current:** Once the story is validated and ready for coding, move it to `stories/current/`. * **Move to Current:** Once the story is validated and ready for coding, move it to `work/2_current/`.
* **Tracking:** Mark Acceptance Criteria as tested directly in the story file as tests are completed. * **Tracking:** Mark Acceptance Criteria as tested directly in the story file as tests are completed.
* **Content:** * **Content:**
* **User Story:** "As a user, I want..." * **User Story:** "As a user, I want..."
* **Acceptance Criteria:** Bullet points of observable success. * **Acceptance Criteria:** Bullet points of observable success.
* **Out of scope:** Things that are out of scope so that the LLM doesn't go crazy * **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. * **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. * **Git:** The `start_agent` MCP tool automatically creates a worktree under `.story_kit/worktrees/`, checks out a feature branch, moves the story to `work/2_current/`, and spawns the agent. No manual branch or worktree creation is needed.
### Step 2: Test Planning (TDD) ### Step 2: Test Planning (TDD)
* **Action:** Define the test plan for the Story before any implementation. * **Action:** Define the test plan for the Story before any implementation.
@@ -102,10 +125,10 @@ When the user asks for a feature, follow this 4-step loop strictly:
### Step 4: Verification (Close) ### Step 4: Verification (Close)
* **Action:** For each Acceptance Criterion in the story, write a failing test (red), mark the criterion as tested, make the test pass (green), and refactor if needed. Keep only one failing test at a time. * **Action:** For each Acceptance Criterion in the story, write a failing test (red), mark the criterion as tested, 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:** 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/archived/`. 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 `work/5_archived/`.
* **Move to Archived:** After acceptance, move the story from `stories/current/` to `stories/archived/`. * **Move to Archived:** After acceptance, move the story from `work/2_current/` (or `work/4_merge/`) to `work/5_archived/`.
* **Action:** When the user accepts: * **Action:** When the user accepts:
1. Move the story file to `stories/archived/` (e.g., `mv stories/current/XX_story_name.md stories/archived/`) 1. Move the story file to `work/5_archived/`
2. Commit both changes to the feature branch 2. Commit both changes to the feature branch
3. Perform the squash merge: `git merge --squash feature/story-name` 3. Perform the squash merge: `git merge --squash feature/story-name`
4. Commit to master with a comprehensive commit message 4. Commit to master with a comprehensive commit message
@@ -120,7 +143,7 @@ When the user asks for a feature, follow this 4-step loop strictly:
* The only files that should exist after story completion: * The only files that should exist after story completion:
* Updated code in `src/` * Updated code in `src/`
* Updated guardrails in `specs/` (if needed) * Updated guardrails in `specs/` (if needed)
* Archived story in `stories/archived/` * Archived work item in `work/5_archived/`
--- ---
@@ -136,7 +159,7 @@ Not everything needs to be a full story. Simple bugs can skip the story process:
* Performance issues with known fixes * Performance issues with known fixes
### Bug Process ### Bug Process
1. **Document Bug:** Create `bugs/bug-N-short-description.md` with: 1. **Document Bug:** Create a bug file in `work/1_upcoming/` named `{id}_bug_{slug}.md` with:
* **Symptom:** What the user observes * **Symptom:** What the user observes
* **Root Cause:** Technical explanation (if known) * **Root Cause:** Technical explanation (if known)
* **Reproduction Steps:** How to trigger the bug * **Reproduction Steps:** How to trigger the bug
@@ -146,10 +169,10 @@ Not everything needs to be a full story. Simple bugs can skip the story process:
3. **Write a Failing Test:** Before fixing the bug, write a test that reproduces it (red). This proves the bug exists and prevents regression. 3. **Write a Failing Test:** Before fixing the bug, write a test that reproduces it (red). This proves the bug exists and prevents regression.
4. **Fix the Bug:** Make minimal code changes to make the test pass (green). 4. **Fix the Bug:** Make minimal code changes to make the test pass (green).
5. **User Testing:** Let the user verify the fix in the worktree before merging. Do not proceed until they confirm. 5. **User Testing:** Let the user verify the fix in the worktree before merging. Do not proceed until they confirm.
6. **Archive & Merge:** Move the bug file to `bugs/archive/`, squash merge to master, delete the worktree and branch. 6. **Archive & Merge:** Move the bug file to `work/5_archived/`, squash merge to master, delete the worktree and branch.
6. **No Guardrail Update Needed:** Unless the bug reveals a missing constraint 7. **No Guardrail Update Needed:** Unless the bug reveals a missing constraint
### Bug vs Story ### Bug vs Story vs Spike
* **Bug:** Existing functionality is broken → Fix it * **Bug:** Existing functionality is broken → Fix it
* **Story:** New functionality is needed → Test it, then build it * **Story:** New functionality is needed → Test it, then build it
* **Spike:** Uncertainty/feasibility discovery → Run spike workflow * **Spike:** Uncertainty/feasibility discovery → Run spike workflow
@@ -166,7 +189,7 @@ Not everything needs a story or bug fix. Spikes are time-boxed investigations to
* Need to validate performance constraints * Need to validate performance constraints
### Spike Process ### Spike Process
1. **Document Spike:** Create `spikes/spike-N-short-description.md` with: 1. **Document Spike:** Create a spike file in `work/1_upcoming/` named `{id}_spike_{slug}.md` with:
* **Question:** What you need to answer * **Question:** What you need to answer
* **Hypothesis:** What you expect to be true * **Hypothesis:** What you expect to be true
* **Timebox:** Strict limit for the research * **Timebox:** Strict limit for the research
@@ -175,7 +198,7 @@ Not everything needs a story or bug fix. Spikes are time-boxed investigations to
* **Recommendation:** Next step (Story, Bug, or No Action) * **Recommendation:** Next step (Story, Bug, or No Action)
2. **Execute Research:** Stay within the timebox. No production code changes. 2. **Execute Research:** Stay within the timebox. No production code changes.
3. **Escalate if Needed:** If implementation is required, open a Story or Bug and follow that workflow. 3. **Escalate if Needed:** If implementation is required, open a Story or Bug and follow that workflow.
4. **Archive:** Move completed spikes to `spikes/archive/`. 4. **Archive:** Move the spike file to `work/5_archived/`.
### Spike Output ### Spike Output
* Decision and evidence, not production code * Decision and evidence, not production code
@@ -189,7 +212,7 @@ When the LLM context window fills up (or the chat gets slow/confused):
1. **Stop Coding.** 1. **Stop Coding.**
2. **Instruction:** Tell the user to open a new chat. 2. **Instruction:** Tell the user to open a new chat.
3. **Handoff:** The only context the new LLM needs is in the `specs/` folder and `.mcp.json`. 3. **Handoff:** The only context the new LLM needs is in the `specs/` folder and `.mcp.json`.
* *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `stories/` to see what is pending." * *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_upcoming/` and `work/2_current/` to see what is pending."
--- ---
@@ -201,7 +224,7 @@ If a user hands you this document and says "Apply this process to my project":
1. **Check for MCP Tools:** Look for `.mcp.json` in the project root. If it exists, you have programmatic access to workflow tools and agent spawning capabilities. 1. **Check for MCP Tools:** Look for `.mcp.json` in the project root. If it exists, you have programmatic access to workflow tools and agent spawning capabilities.
2. **Analyze the Request:** Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?"). 2. **Analyze the Request:** Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?").
3. **Git Check:** Check if the directory is a git repository (`git status`). If not, run `git init`. 3. **Git Check:** Check if the directory is a git repository (`git status`). If not, run `git init`.
4. **Scaffold:** Run commands to create the `specs/` and `stories/` folders. 4. **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 5-stage pipeline (`work/1_upcoming/` through `work/5_archived/`).
5. **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer. 5. **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
6. **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language. 6. **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
7. **Wait:** Ask the user for "Story #1". 7. **Wait:** Ask the user for "Story #1".
@@ -264,7 +287,7 @@ Before asking for user acceptance in Step 4:
- [ ] Run `cargo check` (Rust) - successful compilation - [ ] Run `cargo check` (Rust) - successful compilation
- [ ] Run `cargo test` (Rust) - all tests pass - [ ] Run `cargo test` (Rust) - all tests pass
- [ ] Run `npx @biomejs/biome check src/` (TypeScript) - 0 errors, 0 warnings - [ ] Run `npx @biomejs/biome check src/` (TypeScript) - 0 errors, 0 warnings
- [ ] Run `npm run build` (TypeScript) - successful build - [ ] Run `pnpm run build` (TypeScript) - successful build
- [ ] Manually test the feature works as expected - [ ] Manually test the feature works as expected
- [ ] All acceptance criteria verified - [ ] All acceptance criteria verified