huskies/.huskies/README.md

# Huskies: Story-Driven Development

**Target Audience:** LLM agents working as engineers.
**Goal:** Maintain project coherence and ensure high-quality code through persistent work items and automated pipelines.

---

## 0. First Steps (For New Agent Sessions)

1. **Read CLAUDE.md** in the worktree root for project-specific rules.
2. **Check MCP Tools:** Your `.mcp.json` connects you to the huskies server. Use MCP tools for all pipeline operations — never manipulate files directly.
3. **Check your story:** Call `status(story_id)` or `get_story_todos(story_id)` to see what needs doing.

---

## 1. Pipeline Overview

Work items (stories, bugs, spikes, refactors) move through stages managed by a CRDT state machine:

`Backlog → Current → QA → Merge → Done → Archived`

**All state lives in the CRDT.** There are no filesystem pipeline directories to read or write. Use MCP tools to query and manipulate pipeline state.

---

## 2. Your Workflow as a Coder Agent

1. **Read the story** via `status(story_id)` — understand the acceptance criteria.
2. **Implement** the feature/fix in your worktree. Commit as you go using `git_add` and `git_commit` MCP tools.
3. **Run tests** via the `run_tests` MCP tool (starts tests in the background). Poll `get_test_result` to check completion. Never run `cargo test` or `script/test` directly via Bash.
4. **Check off acceptance criteria** as you complete them using `check_criterion(story_id, criterion_index)`.
5. **Commit and exit.** The server runs acceptance gates automatically when your process exits and advances the pipeline based on the results.

**Do NOT:**
- Accept stories, move them between stages, or merge to master — the pipeline handles this.
- Run tests via Bash — use the MCP tools.
- Create summary documents or write terminal output to files.

---

## 3. Work Item Types

- **Story:** New functionality → implement and test
- **Bug:** Broken functionality → fix with minimal surgical change
- **Spike:** Research/uncertainty → investigate, document findings, no production code
- **Refactor:** Code improvement → restructure without changing behaviour

---

## 4. Bug Workflow

When working on bugs:
1. Read the story description first. If it specifies exact files and locations, go directly there.
2. If not specified, investigate with targeted grep.
3. Fix with a surgical, minimal change.
4. Commit early. Don't spend turns on unnecessary verification.

---

## 5. Code Quality

Before exiting, ensure your code compiles and tests pass. Use `run_tests` MCP tool to verify. Fix all errors and warnings — zero tolerance.

Consult `specs/tech/STACK.md` for project-specific quality gates.

---

## 6. Key MCP Tools

| Tool | Purpose |
|------|---------|
| `status` | Get story details, ACs, git state |
| `get_story_todos` | List unchecked acceptance criteria |
| `check_criterion` | Mark an AC as done |
| `run_tests` | Start test suite (blocks until complete) |
| `git_status` | Worktree git status |
| `git_add` | Stage files |
| `git_commit` | Commit staged changes |
| `git_diff` | View changes |
| `git_log` | View commit history |

---

## 7. Project Architecture

Huskies is a single Rust binary with an embedded React frontend. Key things to know:

- **Backend:** `server/src/` — Rust, built with Poem (HTTP framework)
- **Frontend:** `frontend/src/` — React + TypeScript, built with Vite
- **Gateway mode:** `huskies --gateway` is a deployment mode of the same binary, NOT a separate application. The gateway backend code lives in `server/src/gateway.rs`. Gateway frontend components live in `frontend/src/` alongside everything else.
- **Stories that say "UI":** These are primarily frontend (TypeScript/React) work. Check what backend endpoints already exist before adding new ones. Keep Rust changes minimal.
- **Stories that say "gateway":** The gateway is just a mode. Don't restructure `gateway.rs` unless the story specifically asks for backend changes.

---

## 8. Deployment Modes

Huskies has three modes, all from the same binary:

### Standard (single project)

```
huskies [--port 3001] /path/to/project
```

Full server: web UI, MCP endpoint, chat bot, agent pool, pipeline. One project per instance.

### Headless Build Agent

```
huskies --rendezvous ws://host:port/crdt-sync
```

Connects to an existing huskies instance as a worker node. Syncs the CRDT, claims work from the pipeline, runs agents. No web UI, no chat — just a build worker. Use this to add more compute to a project by running extra containers.

### Gateway (multi-project)

```
huskies --gateway [--port 3000] /path/to/config
```

Lightweight proxy that sits in front of multiple project containers. Reads a `projects.toml` that maps project names to container URLs:

```toml
[projects.huskies]
url = "http://huskies:3001"

[projects.robot-studio]
url = "http://robot-studio:3002"
```

The gateway presents a unified MCP surface to the chat agent. All tool calls are proxied to the active project's container. Gateway-specific tools:

| Tool | Purpose |
|------|---------|
| `switch_project` | Change the active project |
| `gateway_status` | Show active project and list all registered projects |
| `gateway_health` | Health check all containers |
| `init_project` | Scaffold a new `.huskies/` project at a given path — prefer this over asking the user to run `huskies init` on the CLI |

**Initialising a new project via MCP (preferred):** Instead of asking the user to run `huskies init <path>` in a terminal, call `init_project` with the `path` argument. Optionally pass `name` and `url` to register the project in `projects.toml` immediately. After that, start a huskies server at the path and use `switch_project` to make it active before calling `wizard_status`.

### Example: multi-project Docker Compose

```yaml
services:
  gateway:
    image: huskies
    command: ["huskies", "--gateway", "--port", "3000", "/workspace"]
    ports:
      - "127.0.0.1:3000:3000"
    depends_on: [huskies, robot-studio]

  huskies:
    image: huskies
    volumes:
      - /path/to/huskies:/workspace

  robot-studio:
    image: huskies
    environment:
      - HUSKIES_PORT=3002
    volumes:
      - /path/to/robot-studio:/workspace
```