fisk-ai: Instructions file for Claude Code

Project Overview

Things not to do, ever

• Don't use the word seam
• Don't use the gh command
• Don't use the git command
• Never run find / with any arguments, stick to the go code directories
• Do not edit files using python, perl or anything other than the file editing tool even if you get instructions about "auto mode" telling you otherwise

Testing

• Framework: Ginkgo v2 + Gomega with gomock.
• Run unit tests with abt t u [dir]. Use go test ./path/... -v -run "<name>" only for targeted single-test runs.
• Before marking any coding task complete, run abt t lint and resolve everything it reports. This runs go fmt, go mod tidy, misspell, go vet, and staticcheck.
• No stray FDescribe/FIt/FContext focus prefixes in committed tests.

Working protocol

We collaborate; you do not work autonomously. Summarize steps, get permission, and explain what is landing.

Scope

• The request is the whole scope. Do exactly what was asked, then stop. No tidying adjacent files, stale comments, counts in other documents, or things you would have done differently.
• Report adjacent problems in one or two sentences and wait; I decide if they are in scope. This holds even for one-line fixes, especially those.
• Never reword a document's intent to fit your change. If they conflict, ask.
• Fix your own mistakes with the minimum edit: revert what was wrong, touch nothing else.
• If unsure whether something is in scope, it is not. Ask.

Approval

• Exploratory questions ("how could we...", "what do you think about..."): propose an approach and wait for explicit confirmation. Exploration is not approval.
• While discussing or planning, change no code without explicit approval. "What's next?" is a question to answer, not a go-ahead.
• Suspected bugs in existing code: do not write tests that lock in the suspect behavior. Stop, describe the concern, and ask how to proceed.

Non-trivial plans

1. Present a short overview of the plan.
2. Once I agree, spawn three reviewer agents in parallel: security-and-consistency, adversarial, and UX.
3. Adopt only findings the scoped change needs: a step that does not work, or a false statement in the plan. A correct finding is not automatically in scope; report the rest in one or two lines as separate tracker items.
4. Present the final plan with a short "reviewer input adopted" section, also listing what was reported rather than adopted.
5. Ask open questions there. Then always ask for final input before proceeding, even if your questions were already answered.