Timmy
78b1ecdc3c
The "living document" rule was soft and got ignored — coders wrote PLAN.md once at session start and then drifted away from it. Tie the update to a trigger they already do (the wip/final commit), and call out stale "Current state" as a process failure. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
## 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.
|