diff --git a/.story_kit/README.md b/.story_kit/README.md index fc7f47b..9afc1f9 100644 --- a/.story_kit/README.md +++ b/.story_kit/README.md @@ -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. 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. -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. @@ -40,25 +40,48 @@ Agents have programmatic access to the workflow via MCP tools served at `POST /m ## 2. Directory Structure -When initializing a new project under this workflow, create the following structure immediately: - ```text project_root/ .mcp.json # MCP server configuration (if MCP tools are available) .story_kit/ - |-- README.md # This document - ├── stories/ # Story workflow (upcoming/current/archived). - ├── specs/ # Minimal guardrails (context + stack). - │ ├── 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 + ├── README.md # This document + ├── project.toml # Agent configuration (roles, models, prompts) + ├── work/ # Unified work item pipeline (stories, bugs, spikes) + │ ├── 1_upcoming/ # New work items awaiting implementation + │ ├── 2_current/ # Work in progress + │ ├── 3_qa/ # QA review + │ ├── 4_merge/ # Ready to merge to master + │ └── 5_archived/ # Completed work + ├── 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") @@ -67,8 +90,8 @@ 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 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`). -* **Front Matter (Required):** Every story file MUST begin with YAML front matter containing `name` and `test_plan` fields: +* **Action:** Create a story via MCP tool `create_story` (guarantees correct front matter and auto-assigns the story number). +* **Front Matter (Required):** Every work item file MUST begin with YAML front matter containing `name` and `test_plan` fields: ```yaml --- 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). -* **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. * **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. +* **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) * **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) * **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:** 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:** 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 `work/2_current/` (or `work/4_merge/`) to `work/5_archived/`. * **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 3. Perform the squash merge: `git merge --squash feature/story-name` 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: * Updated code in `src/` * 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 ### 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 * **Root Cause:** Technical explanation (if known) * **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. 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. -6. **Archive & Merge:** Move the bug file to `bugs/archive/`, squash merge to master, delete the worktree and branch. -6. **No Guardrail Update Needed:** Unless the bug reveals a missing constraint +6. **Archive & Merge:** Move the bug file to `work/5_archived/`, squash merge to master, delete the worktree and branch. +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 * **Story:** New functionality is needed → Test it, then build it * **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 ### 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 * **Hypothesis:** What you expect to be true * **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) 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. -4. **Archive:** Move completed spikes to `spikes/archive/`. +4. **Archive:** Move the spike file to `work/5_archived/`. ### Spike Output * 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.** 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`. - * *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. 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`. -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. 6. **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language. 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 test` (Rust) - all tests pass - [ ] 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 - [ ] All acceptance criteria verified