huskies/.huskies/AGENT.md

# Huskies project-local agent guidance

## Session Start & Resume Protocol

### PLAN.md — required for every coder session

At the very start of each coder session, before doing any code exploration, check for `PLAN.md` in the worktree root:

**If `PLAN.md` exists (resuming after a watchdog respawn):**
1. Read `PLAN.md` first — it is your primary orientation document.
2. Only after reading it, call `git_log` / `git_diff` to see commits made since the plan was last updated.
3. Reconcile any divergence between the plan and the current git state, then update the plan.

**If `PLAN.md` is absent (first session on this story):**
1. Write `PLAN.md` before any grep, file read, or exploration tool call.
2. Populate it with what you know from the story ACs alone; add specifics as you discover them.

### What PLAN.md must contain

`PLAN.md` is a living document. Update it after each completed AC or natural unit of work — not only at the start.

**Required trigger:** Before every `wip(...)` commit AND the final commit, update PLAN.md's "Current state" section to reflect what's now done, and tick off completed items in "What's left". This is required, not optional — stale "Current state: No code changes yet" while files are being edited is a process failure. Stage the PLAN.md update in the same commit as the code change it describes.

Required sections:

```markdown
# Plan: Story <id>

## ACs → implementation locations
- AC 1: <exact file path>:<line range> — <one-line description of what changes>
- AC 2: <exact file path>:<line range> — …
…

## Decisions
- <Decision made>: <rationale> — rejected alternative: <what was considered and why it lost>
…

## Current state
<What has been done so far. Reference commit hashes or specific functions completed.>

## What's left
- [ ] <specific remaining task with file path and function name>
…
```

### Non-conforming outputs

A PLAN.md that contains only generic steps like "read the code", "write the code", "run the tests", or leaves file paths as `<TBD>` or unspecified is **non-conforming**. Every AC entry must name a real file path and describe the actual change. Every decision entry must name both the chosen approach and at least one rejected alternative with a reason. A stub plan is worse than no plan — rewrite it with specifics.

## Doc comments — your merge will fail if you skip even one

Every time you introduce a NEW public item — `pub mod X`, `pub fn`, `pub struct`, `pub enum`, `pub trait`, `pub const`, `pub static`, `pub type`, or a `mod X;` declaration that introduces a new module file — the line directly above it **MUST** be a doc comment starting with `///` (or `//!` at the top of a new module file).

There are no exceptions. The merge gate runs `source-map-check` and rejects the merge for any single missing doc comment. Two stories today (961, 962) passed every test, every clippy check, and every other gate, then got bounced at the final step because of one missed `///` on a `pub mod` line. **Treat the `///` as part of writing the declaration, not as an afterthought.**

Before committing, run `cargo run -p source-map-gen --bin source-map-check -- --worktree . --base master` and address every missing-docs direction it prints. If you added a new module file (e.g. `foo.rs` or `foo/mod.rs`), the FIRST line of that file MUST be a `//! What this module is for` doc comment.

## Documentation
Docs live in `website/docs/*.html` (static HTML), **not** Markdown files. When a story asks you to document something, edit the relevant `.html` file in `website/docs/`.

## Configuration files
- Agent config: `.huskies/agents.toml` (preferred) or `[[agent]]` blocks in `.huskies/project.toml`
- Project settings: `.huskies/project.toml`
- Bot credentials: `.huskies/bot.toml` (gitignored — never commit)

## Frontend build
The frontend is embedded into the Rust binary via `rust-embed`. Run `npm run build` in `frontend/` before testing frontend changes, or the embedded assets will be stale.

## Quality gates (all enforced by `script/test`)
1. `npm run build` (frontend)
2. `cargo fmt --all --check`
3. `cargo clippy -- -D warnings`
4. `cargo test`
5. `npm test` (frontend Vitest)

Clippy is zero-tolerance: no warnings allowed. Fix every warning before committing.

## Pre-commit hook

Every agent worktree has a pre-commit hook installed at `.git-hooks/pre-commit` that runs `script/check` (fmt-check, clippy, cargo check, source-map-check) before every `git commit`. If the hook fails, fix the issues shown and re-run `script/check` to validate.

`git commit --no-verify` bypasses the hook. Do **not** use it. The hook exists to prevent broken commits from reaching the merge gate; bypassing it defeats the purpose and wastes CI cycles.

## File size
Target a maximum of 800 lines per source file as a soft guide. If a file grows beyond 800 lines, decompose it by concern into smaller modules. Split at natural seams: group related types, functions, or handlers together and move each cohesive group to its own file. This keeps files readable and diffs focused.

## Runtime validation
The `validate_agents` function in `server/src/config.rs` rejects unknown runtimes. Supported values: `"claude-code"` and `"gemini"`. Adding a new runtime requires updating that function.