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:

[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

Example: multi-project Docker Compose

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