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