huskies: merge 485_story_documentation_site_for_huskies_dev
This commit is contained in:
dave
@@ -0,0 +1,231 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Pipeline Stages — Huskies Docs</title>
|
||||
<meta name="description" content="How work items move through the huskies pipeline: backlog, current, QA, merge, done.">
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@400;500;600;700;800&family=Karla:ital,wght@0,300;0,400;0,500;1,300;1,400&display=swap" rel="stylesheet">
|
||||
<link rel="stylesheet" href="docs.css">
|
||||
<style>
|
||||
.pipeline-stages {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 1px;
|
||||
background: var(--border);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 6px;
|
||||
overflow: hidden;
|
||||
margin: 1.5rem 0;
|
||||
}
|
||||
.stage-row {
|
||||
display: grid;
|
||||
grid-template-columns: 48px 140px 1fr;
|
||||
gap: 0;
|
||||
background: var(--surface);
|
||||
transition: background 0.2s;
|
||||
align-items: stretch;
|
||||
}
|
||||
.stage-row:hover { background: var(--surface-hover); }
|
||||
.stage-num {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
font-family: var(--display);
|
||||
font-size: 0.7rem;
|
||||
font-weight: 700;
|
||||
color: var(--text-dim);
|
||||
border-right: 1px solid var(--border);
|
||||
}
|
||||
.stage-name {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
padding: 1rem 1.1rem;
|
||||
font-family: var(--display);
|
||||
font-size: 0.88rem;
|
||||
font-weight: 600;
|
||||
color: var(--text);
|
||||
border-right: 1px solid var(--border);
|
||||
}
|
||||
.stage-desc {
|
||||
padding: 1rem 1.2rem;
|
||||
font-size: 0.85rem;
|
||||
color: var(--text-secondary);
|
||||
line-height: 1.6;
|
||||
}
|
||||
.stage-row.active .stage-name { color: var(--cyan); }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<div class="shell">
|
||||
<header class="reveal r1">
|
||||
<a href="/" class="logo">huskies</a>
|
||||
<nav>
|
||||
<a href="/#how">How it works</a>
|
||||
<a href="/#features">Features</a>
|
||||
<a href="/docs/" class="active">Docs</a>
|
||||
<a href="https://code.crashlabs.io/crashlabs/huskies">Source</a>
|
||||
<a href="https://code.crashlabs.io/crashlabs/huskies/releases">Releases</a>
|
||||
<a href="mailto:hello@huskies.dev" class="nav-cta">Get in touch</a>
|
||||
</nav>
|
||||
</header>
|
||||
</div>
|
||||
|
||||
<div class="shell">
|
||||
<div class="docs-layout">
|
||||
<aside class="sidebar reveal r2">
|
||||
<div class="sidebar-section">
|
||||
<div class="sidebar-heading">Getting started</div>
|
||||
<nav>
|
||||
<a href="/docs/">Overview</a>
|
||||
<a href="quickstart.html">Quickstart</a>
|
||||
</nav>
|
||||
</div>
|
||||
<div class="sidebar-section">
|
||||
<div class="sidebar-heading">Reference</div>
|
||||
<nav>
|
||||
<a href="configuration.html">Configuration</a>
|
||||
<a href="commands.html">Bot commands</a>
|
||||
<a href="cli.html">CLI</a>
|
||||
</nav>
|
||||
</div>
|
||||
<div class="sidebar-section">
|
||||
<div class="sidebar-heading">Guides</div>
|
||||
<nav>
|
||||
<a href="pipeline.html" class="active">Pipeline stages</a>
|
||||
<a href="transports.html">Chat transports</a>
|
||||
</nav>
|
||||
</div>
|
||||
</aside>
|
||||
|
||||
<main class="docs-main reveal r3">
|
||||
<h1 class="page-title">Pipeline Stages</h1>
|
||||
<p class="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 class="pipeline-stages">
|
||||
<div class="stage-row">
|
||||
<div class="stage-num">1</div>
|
||||
<div class="stage-name">Backlog</div>
|
||||
<div class="stage-desc"><code>1_backlog/</code> — New work items awaiting prioritisation. Stories sit here until you decide to start them.</div>
|
||||
</div>
|
||||
<div class="stage-row active">
|
||||
<div class="stage-num">2</div>
|
||||
<div class="stage-name">Current</div>
|
||||
<div class="stage-desc"><code>2_current/</code> — Work in progress. Run <code>start <number></code> to assign a coder agent. Multiple stories can be in current simultaneously (up to <code>max_coders</code>).</div>
|
||||
</div>
|
||||
<div class="stage-row">
|
||||
<div class="stage-num">3</div>
|
||||
<div class="stage-name">QA</div>
|
||||
<div class="stage-desc"><code>3_qa/</code> — 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 class="stage-row">
|
||||
<div class="stage-num">4</div>
|
||||
<div class="stage-name">Merge</div>
|
||||
<div class="stage-desc"><code>4_merge/</code> — Ready to merge. Stories reach here after QA approval. Run <code>start <number></code> to trigger the mergemaster agent, which squash-merges to your base branch.</div>
|
||||
</div>
|
||||
<div class="stage-row">
|
||||
<div class="stage-num">5</div>
|
||||
<div class="stage-name">Done</div>
|
||||
<div class="stage-desc"><code>5_done/</code> — Merged and complete. The mergemaster moves stories here after a successful merge. Auto-swept to archive after 4 hours.</div>
|
||||
</div>
|
||||
<div class="stage-row">
|
||||
<div class="stage-num">6</div>
|
||||
<div class="stage-name">Archived</div>
|
||||
<div class="stage-desc"><code>6_archived/</code> — Long-term storage. Stories land here automatically from done. Use <code>overview <number></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 class="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 — 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 <number></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 <number></code> to reset the retry counter.</li>
|
||||
<li>Run <code>start <number></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
|
||||
depends 45 # clear all dependencies</code></pre>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<footer class="reveal r3">
|
||||
<span>© 2026 Libby Labs Ltd.</span>
|
||||
<a href="/privacy.html">Privacy Policy</a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user