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 (async, returns immediately) |
| `get_test_result` | Poll for test completion |
| `git_status` | Worktree git status |
| `git_add` | Stage files |
| `git_commit` | Commit staged changes |
| `git_diff` | View changes |
| `git_log` | View commit history |