huskies: merge 952

2026-05-13 05:38:34 +00:00
parent 0a825b9f27
commit 9ccbdff19f
3 changed files with 49 additions and 1 deletions
@@ -1,5 +1,50 @@
 # 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 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/`.