# Pipeline Stages

Work items move through six stages from idea to archive. Each stage is a directory under `.huskies/work/`. Moving a file between directories advances the story.

1
Backlog
`1_backlog/` — New work items awaiting prioritisation. Stories sit here until you decide to start them.
2
Current
`2_current/` — Work in progress. Run `start <number>` to assign a coder agent. Multiple stories can be in current simultaneously (up to `max_coders`).
3
QA
`3_qa/` — Quality review. The server automatically moves stories here when the coder agent passes all quality gates. A QA agent (or a human) verifies each acceptance criterion.
4
Merge
`4_merge/` — Ready to merge. Stories reach here after QA approval. Run `start <number>` to trigger the mergemaster agent, which squash-merges to your base branch.
5
Done
`5_done/` — Merged and complete. The mergemaster moves stories here after a successful merge. Auto-swept to archive after 4 hours.
6
Archived
`6_archived/` — Long-term storage. Stories land here automatically from done. Use `overview <number>` to see the implementation summary for any archived story.

## Work item types

All work item types move through the same pipeline. They differ in naming convention and workflow:

Type | Filename pattern | When to use
--- | --- | ---
story | `42_story_add_login.md` | New functionality. Requires acceptance criteria and tests.
bug | `43_bug_login_crashes.md` | Defect in existing functionality. Write a failing test first.
spike | `44_spike_auth_options.md` | Time-boxed research to reduce uncertainty. No production code.
refactor | `45_refactor_extract_auth.md` | Code quality improvement. Behaviour must not change.

## Story file format

Every work item is a Markdown file with YAML front matter:

    ---
    name: "Short human-readable name"
    qa: agent          # optional: override default_qa
    agent: opus        # optional: request specific agent model
    ---

    # Story 42: Add login endpoint

    ## User Story
    As a user, I want to log in with email and password so that I can access my account.

    ## Acceptance Criteria
    - [ ] POST /auth/login accepts email and password
    - [ ] Returns a JWT token on success
    - [ ] Returns 401 on invalid credentials
    - [ ] Rate-limited to 5 attempts per minute per IP

    ## Out of Scope
    - OAuth / social login
    - Password reset flow

## Acceptance criteria tracking

Acceptance criteria use Markdown checkboxes (`- [ ]`). The QA agent reviews each criterion against the code diff and marks passing criteria as `- [x]` in the story file. Criteria that fail are noted in the QA report.

Golden rule: No code is written until acceptance criteria are captured in the story. The agent reads the story file to understand what to build and what to test.

## Filesystem watcher

The server watches `.huskies/work/` for changes. When a file is created, moved, or modified, the watcher auto-commits with a deterministic message and broadcasts a WebSocket update to the frontend. This means:

- You can drag a story between stage folders in your IDE and it advances automatically.
- MCP tools only need to write or move files — the watcher handles git commits.
- The pipeline board updates in real time without a manual refresh.

## Blocked stories

A story is marked blocked when it fails the same pipeline stage more than `max_retries` times (default: 3). Blocked stories require manual intervention:

1. Run `status <number>` to see the failure log.
2. Fix the underlying issue (update the story, fix a build problem, etc.).
3. Run `unblock <number>` to reset the retry counter.
4. Run `start <number>` to try again.

## Dependencies

Stories can declare dependencies using the `depends` command. A story with unresolved dependencies waits in `2_current/` until all its dependencies have reached `5_done/`.

    depends 45 42 43   # story 45 waits for 42 and 43 to finish
    depends 45          # clear all dependencies