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:

TypeFilename patternWhen 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