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

/** Quickstart guide — Docker, binary, and source install instructions. */
import type { Metadata } from 'next'

/** Page metadata for the quickstart guide. */
export const metadata: Metadata = {
  title: 'Quickstart — Huskies Docs',
  description: 'Get huskies running in minutes: Docker setup, first story, first agent run.',
}

/** Renders the quickstart installation and setup guide. */
export default function QuickstartPage() {
  return (
    <>
      <h1 className="page-title">Quickstart</h1>
      <p className="page-subtitle">
        Get huskies running in your project in a few minutes. This guide covers Docker setup, running from a
        binary, your first story, and your first agent run.
      </p>

      <h2>Option A: Docker (recommended)</h2>
      <p>
        The easiest way to run huskies is with Docker Compose. This requires Docker and a Claude API key.
      </p>
      <ol className="step-list">
        <li>
          <div>
            <strong>Get the compose file.</strong> Download <code>docker-compose.yml</code> from the{' '}
            <a href="https://code.crashlabs.io/crashlabs/huskies/releases">releases page</a> or copy it from
            the repository&apos;s <code>docker/</code> directory.
          </div>
        </li>
        <li>
          <div>
            <strong>Set your API key.</strong> Create a <code>.env</code> file next to the compose file:
            <pre><code>ANTHROPIC_API_KEY=sk-ant-...</code></pre>
          </div>
        </li>
        <li>
          <div>
            <strong>Mount your project.</strong> Edit the compose file to mount your project directory:
            <pre><code>{`volumes:\n  - /path/to/your/project:/workspace`}</code></pre>
          </div>
        </li>
        <li>
          <div>
            <strong>Start the server.</strong>
            <pre><code>docker compose up</code></pre>
            Open <a href="http://localhost:3000">http://localhost:3000</a> to see the pipeline board.
          </div>
        </li>
      </ol>

      <h2>Option B: Binary</h2>
      <p>
        Download the pre-built binary for your platform from the{' '}
        <a href="https://code.crashlabs.io/crashlabs/huskies/releases">releases page</a> and place it
        somewhere on your <code>PATH</code>.
      </p>

      <h3>macOS (Apple Silicon)</h3>
      <pre><code>{`curl -L https://code.crashlabs.io/crashlabs/huskies/releases/download/latest/huskies-aarch64-apple-darwin \\
  -o /usr/local/bin/huskies
chmod +x /usr/local/bin/huskies`}</code></pre>

      <h3>Linux (x86-64)</h3>
      <pre><code>{`curl -L https://code.crashlabs.io/crashlabs/huskies/releases/download/latest/huskies-x86_64-unknown-linux-musl \\
  -o /usr/local/bin/huskies
chmod +x /usr/local/bin/huskies`}</code></pre>

      <h2>Option C: Build from source</h2>
      <p>Requires Rust (stable), Node.js, and npm.</p>
      <pre><code>{`git clone https://code.crashlabs.io/crashlabs/huskies
cd huskies
cargo build --release
# Binary is at target/release/huskies`}</code></pre>

      <h2>Initialise your project</h2>
      <p>
        From your project directory, run the init command. This creates the <code>.huskies/</code> directory
        with the pipeline structure and configuration files.
      </p>
      <pre><code>{`cd /path/to/your/project\nhuskies init --port 3000`}</code></pre>
      <p>This creates:</p>
      <ul>
        <li>
          <code>.huskies/project.toml</code> &mdash; project-wide settings
        </li>
        <li>
          <code>.huskies/agents.toml</code> &mdash; agent definitions (coder, QA, mergemaster)
        </li>
        <li>
          <code>.huskies/work/</code> &mdash; the 6-stage pipeline directory
        </li>
        <li>
          <code>.mcp.json</code> &mdash; MCP server config for Claude Code integration
        </li>
        <li>
          <code>.huskies/specs/</code> &mdash; placeholder spec files for your project context
        </li>
      </ul>

      <div className="note">
        <strong>Claude Code integration:</strong> The <code>.mcp.json</code> file automatically registers
        huskies&apos; MCP tools with Claude Code. Open a Claude Code session in your project and it will
        discover tools like <code>create_story</code>, <code>start_agent</code>, and{' '}
        <code>get_pipeline_status</code> automatically.
      </div>

      <h2>Start the server</h2>
      <pre><code>huskies --port 3000</code></pre>
      <p>
        Open <a href="http://localhost:3000">http://localhost:3000</a> to see the pipeline board, agent
        status, and chat interface.
      </p>

      <h2>Run the setup wizard</h2>
      <p>
        Open a Claude Code session in your project directory (or use the web chat UI), and tell Claude:
      </p>
      <pre><code>help me set up this project with huskies</code></pre>
      <p>
        Claude will walk you through the setup wizard &mdash; generating project context (
        <code>specs/00_CONTEXT.md</code>), tech stack docs (<code>specs/tech/STACK.md</code>), and
        test/release scripts. Review each step and confirm or ask to retry.
      </p>

      <h2>Create your first story</h2>
      <p>In the chat UI or via a chat transport, type:</p>
      <pre><code>I want to add a health check endpoint to the API</code></pre>
      <p>
        Claude will create a story file in <code>.huskies/work/1_backlog/</code> with a user story and
        acceptance criteria. Review it, then move it to current:
      </p>
      <pre><code>move &lt;story-number&gt; current</code></pre>

      <h2>Start an agent</h2>
      <p>
        Once a story is in <code>2_current/</code>, start a coding agent:
      </p>
      <pre><code>start &lt;story-number&gt;</code></pre>
      <p>
        The agent creates an isolated git worktree, implements the feature against the acceptance criteria,
        runs quality gates (clippy, tests, biome), and exits. The server automatically advances the story to
        QA if all gates pass.
      </p>

      <h2>Review and merge</h2>
      <p>Once QA passes, the story moves to <code>4_merge/</code>. To merge:</p>
      <pre><code>start &lt;story-number&gt;</code></pre>
      <p>
        The mergemaster agent resolves any conflicts and squash-merges to your main branch. The worktree is
        cleaned up automatically.
      </p>

      <div className="note">
        <strong>Tip:</strong> Use <code>status</code> in the chat at any time to see the current pipeline
        state, active agents, and their progress.
      </div>
    </>
  )
}