---
name: Status-Based Directory Layout
---

# Story 60: Status-Based Directory Layout

## User Story

As a developer, I want work items organized by pipeline status rather than by type, with a unified naming convention, so the directory structure reflects what stage everything is at.

## Current Layout (mixed)

```
.story_kit/
  current/
  stories/
    upcoming/
    archived/
  bugs/
    archive/
  spikes/
  specs/
```

## New Layout

```
.story_kit/
  work/
    1_upcoming/    ← all work items waiting to start
    2_current/     ← being coded by agents
    3_qa/          ← being reviewed by QA agent
    4_merge/       ← being merged to master
    5_archived/    ← done
  specs/           ← long-lived project info (not a workflow stage)
  worktrees/       ← agent worktrees (unchanged)
  project.toml     ← config (unchanged)
```

The numbered `work/` subdirectories define the workflow pipeline. `ls` shows them in pipeline order. `specs/`, `worktrees/`, and `project.toml` are infrastructure outside the workflow.

## Naming Convention

All work items use: `{number}_{type}_{slug}.md`

```
work/1_upcoming/57_story_foo_bar_blah.md
work/1_upcoming/58_spike_a_b_c.md
work/1_upcoming/59_bug_flappapa.md
```

Types: `story`, `bug`, `spike`. The number is the primary identifier, auto-incremented across all types. You say "story 57", "bug 59", etc.

## Acceptance Criteria

- [ ] Create `work/` directory with numbered subdirectories: `1_upcoming`, `2_current`, `3_qa`, `4_merge`, `5_archived`
- [ ] Migrate existing `stories/upcoming/` → `work/1_upcoming/`, renaming files to include `_story_` type prefix
- [ ] Migrate existing `stories/archived/` → `work/5_archived/`, renaming files to include `_story_` type prefix
- [ ] Migrate existing `current/` contents → `work/2_current/`
- [ ] Migrate existing `bugs/` → `work/5_archived/` (for closed) or `work/1_upcoming/` (for open), renaming to include `_bug_` type prefix
- [ ] Remove old `stories/`, `bugs/`, `current/` directories
- [ ] `create_story`, `create_bug` MCP tools use the new naming convention and write to `work/1_upcoming/`
- [ ] `start_agent` moves from `work/1_upcoming/` to `work/2_current/`
- [ ] `accept_story` and `close_bug` move from `work/2_current/` to `work/5_archived/`
- [ ] `find_story_file()` and all path references updated to search `work/` status dirs
- [ ] `next_story_number()` scans all `work/` status dirs for the highest number across all types
- [ ] All agent prompts in `project.toml` updated to reference `work/` paths
- [ ] All existing tests updated for new paths
- [ ] Integration test: full lifecycle through `1_upcoming` → `2_current` → `5_archived`

## Supersedes

- Story 51 (Deterministic Spike Lifecycle) — folded into this story's naming convention

## Out of Scope

- QA and merge pipeline automation (just create the empty directories)
- Frontend changes to reflect new layout
- Spike-specific MCP tools (create_spike, archive_spike) — follow-up
