huskies/website/app/docs/pipeline/page.tsx

/** Pipeline stages reference — describes the six-stage story workflow. */
import type { Metadata } from 'next'

/** Page metadata for the pipeline stages guide. */
export const metadata: Metadata = {
  title: 'Pipeline Stages — Huskies Docs',
  description:
    'How work items move through the huskies pipeline: backlog, current, QA, merge, done.',
}

/** Renders the pipeline stages reference page. */
export default function PipelinePage() {
  return (
    <>
      <h1 className="page-title">Pipeline Stages</h1>
      <p className="page-subtitle">
        Work items move through six stages from idea to archive. Each stage is a directory under{' '}
        <code>.huskies/work/</code>. Moving a file between directories advances the story.
      </p>

      <div className="pipeline-stages">
        <div className="stage-row">
          <div className="stage-num">1</div>
          <div className="stage-name">Backlog</div>
          <div className="stage-desc">
            <code>1_backlog/</code> &mdash; New work items awaiting prioritisation. Stories sit here until
            you decide to start them.
          </div>
        </div>
        <div className="stage-row active">
          <div className="stage-num">2</div>
          <div className="stage-name">Current</div>
          <div className="stage-desc">
            <code>2_current/</code> &mdash; Work in progress. Run <code>start &lt;number&gt;</code> to
            assign a coder agent. Multiple stories can be in current simultaneously (up to{' '}
            <code>max_coders</code>).
          </div>
        </div>
        <div className="stage-row">
          <div className="stage-num">3</div>
          <div className="stage-name">QA</div>
          <div className="stage-desc">
            <code>3_qa/</code> &mdash; 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.
          </div>
        </div>
        <div className="stage-row">
          <div className="stage-num">4</div>
          <div className="stage-name">Merge</div>
          <div className="stage-desc">
            <code>4_merge/</code> &mdash; Ready to merge. Stories reach here after QA approval. Run{' '}
            <code>start &lt;number&gt;</code> to trigger the mergemaster agent, which squash-merges to your
            base branch.
          </div>
        </div>
        <div className="stage-row">
          <div className="stage-num">5</div>
          <div className="stage-name">Done</div>
          <div className="stage-desc">
            <code>5_done/</code> &mdash; Merged and complete. The mergemaster moves stories here after a
            successful merge. Auto-swept to archive after 4 hours.
          </div>
        </div>
        <div className="stage-row">
          <div className="stage-num">6</div>
          <div className="stage-name">Archived</div>
          <div className="stage-desc">
            <code>6_archived/</code> &mdash; Long-term storage. Stories land here automatically from done.
            Use <code>overview &lt;number&gt;</code> to see the implementation summary for any archived
            story.
          </div>
        </div>
      </div>

      <h2>Work item types</h2>
      <p>
        All work item types move through the same pipeline. They differ in naming convention and workflow:
      </p>

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

      <h2>Story file format</h2>
      <p>Every work item is a Markdown file with YAML front matter:</p>
      <pre>
        <code>{`---
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`}</code>
      </pre>

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

      <div className="note">
        <strong>Golden rule:</strong> 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.
      </div>

      <h2>Filesystem watcher</h2>
      <p>
        The server watches <code>.huskies/work/</code> 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:
      </p>
      <ul>
        <li>
          You can drag a story between stage folders in your IDE and it advances automatically.
        </li>
        <li>MCP tools only need to write or move files &mdash; the watcher handles git commits.</li>
        <li>The pipeline board updates in real time without a manual refresh.</li>
      </ul>

      <h2>Blocked stories</h2>
      <p>
        A story is marked <strong>blocked</strong> when it fails the same pipeline stage more than{' '}
        <code>max_retries</code> times (default: 3). Blocked stories require manual intervention:
      </p>
      <ol>
        <li>
          Run <code>status &lt;number&gt;</code> to see the failure log.
        </li>
        <li>Fix the underlying issue (update the story, fix a build problem, etc.).</li>
        <li>
          Run <code>unblock &lt;number&gt;</code> to reset the retry counter.
        </li>
        <li>
          Run <code>start &lt;number&gt;</code> to try again.
        </li>
      </ol>

      <h2>Dependencies</h2>
      <p>
        Stories can declare dependencies using the <code>depends</code> command. A story with unresolved
        dependencies waits in <code>2_current/</code> until all its dependencies have reached{' '}
        <code>5_done/</code>.
      </p>
      <pre>
        <code>{`depends 45 42 43   # story 45 waits for 42 and 43 to finish\ndepends 45          # clear all dependencies`}</code>
      </pre>
    </>
  )
}