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:

# 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.

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.