huskies/website/app/docs/page.tsx

/** Docs index — overview and card links to all documentation sections. */
import type { Metadata } from 'next'
import Link from 'next/link'

/** Page metadata for the docs index. */
export const metadata: Metadata = {
  title: 'Documentation — Huskies',
  description:
    'Huskies documentation: quickstart, configuration, bot commands, pipeline, and more.',
}

/** Renders the documentation overview page with section cards. */
export default function DocsIndexPage() {
  return (
    <>
      <p
        className="hero-kicker"
        style={{
          fontFamily: 'var(--display)',
          fontSize: '0.68rem',
          fontWeight: 600,
          letterSpacing: '0.18em',
          textTransform: 'uppercase',
          color: 'var(--cyan)',
          marginBottom: '1rem',
        }}
      >
        Documentation
      </p>
      <h1 className="page-title">Huskies Docs</h1>
      <p className="page-subtitle">
        Everything you need to set up and run huskies &mdash; a story-driven development pipeline that turns
        coding agents into a disciplined team.
      </p>

      <div className="doc-cards">
        <Link className="doc-card" href="/docs/quickstart">
          <div className="doc-card-title">Quickstart</div>
          <div className="doc-card-desc">
            Install huskies, run the server, create your first story, and watch an agent implement it.
          </div>
        </Link>
        <Link className="doc-card" href="/docs/configuration">
          <div className="doc-card-title">Configuration</div>
          <div className="doc-card-desc">
            Reference for <code>project.toml</code>, <code>agents.toml</code>, and <code>bot.toml</code>.
          </div>
        </Link>
        <Link className="doc-card" href="/docs/commands">
          <div className="doc-card-title">Bot commands</div>
          <div className="doc-card-desc">
            Full list of commands available in Matrix, Slack, WhatsApp, and the web UI.
          </div>
        </Link>
        <Link className="doc-card" href="/docs/pipeline">
          <div className="doc-card-title">Pipeline stages</div>
          <div className="doc-card-desc">
            How work items move from backlog through QA and merge to done.
          </div>
        </Link>
        <Link className="doc-card" href="/docs/transports">
          <div className="doc-card-title">Chat transports</div>
          <div className="doc-card-desc">
            Connect huskies to Matrix, WhatsApp, Slack, Discord, or the built-in web UI.
          </div>
        </Link>
        <Link className="doc-card" href="/docs/cli">
          <div className="doc-card-title">CLI reference</div>
          <div className="doc-card-desc">
            Command-line flags for <code>huskies</code>, <code>huskies init</code>, and{' '}
            <code>huskies agent</code>.
          </div>
        </Link>
      </div>

      <h2>What is huskies?</h2>
      <p>
        Huskies is a story-driven development server. You write stories (feature requests) with acceptance
        criteria; huskies spawns coding agents in isolated git worktrees, runs them through quality gates, and
        squash-merges the result to your main branch &mdash; all without you writing a line of code.
      </p>
      <p>
        It ships as a single Rust binary with an embedded React frontend. No separate database or build
        infrastructure required.
      </p>

      <h2>How it works</h2>
      <ol className="step-list">
        <li>
          <div>
            <strong>Write a story.</strong> Describe the change with acceptance criteria via the web UI, a chat
            room (Matrix, WhatsApp, Slack), or by dropping a Markdown file in{' '}
            <code>.huskies/work/1_backlog/</code>.
          </div>
        </li>
        <li>
          <div>
            <strong>Agent picks it up.</strong> Run <code>start &lt;number&gt;</code> (or configure
            auto-start). A coder agent creates a feature branch, implements the code, and writes tests against
            your criteria.
          </div>
        </li>
        <li>
          <div>
            <strong>Quality gates run.</strong> Linters, tests, and compilation checks run automatically when
            the agent exits. Nothing moves forward until everything passes.
          </div>
        </li>
        <li>
          <div>
            <strong>QA review.</strong> A QA agent verifies each acceptance criterion, runs your test suite,
            and either approves or rejects with detailed findings.
          </div>
        </li>
        <li>
          <div>
            <strong>Merge &amp; land.</strong> A merge agent resolves conflicts and squash-merges to your main
            branch. The worktree is cleaned up automatically.
          </div>
        </li>
      </ol>

      <h2>Key concepts</h2>
      <p>
        <strong>Stories</strong> are Markdown files with YAML front matter. They live in{' '}
        <code>.huskies/work/</code> and move through pipeline stages as work progresses.
      </p>
      <p>
        <strong>Agents</strong> are Claude Code sessions that run autonomously in git worktrees. Each story gets
        its own isolated worktree so multiple stories can be in flight simultaneously.
      </p>
      <p>
        <strong>MCP tools</strong> give Claude Code sessions programmatic access to the pipeline: creating
        stories, starting agents, checking status, recording test results.
      </p>
    </>
  )
}