docs: add agent guidance files and templates

.agent/templates/plan.md

@@ -0,0 +1,48 @@
+# Plan
+
+## Task classification
+
+Fast / Standard / Cautious
+
+## Assumptions
+
+- ...
+
+## Files inspected
+
+- `path/to/file`
+
+## Files likely to change
+
+- `path/to/file`
+
+## Files that should not change
+
+- `path/to/file`
+
+## Implementation steps
+
+1. ...
+2. ...
+3. ...
+
+## Tests to add or update
+
+- ...
+
+## Verification commands
+
+- `...`
+
+## Risks and ambiguities
+
+- ...
+
+## Stopping conditions
+
+Stop and ask before continuing if:
+
+- scope needs to expand;
+- existing behavior contradicts the brief;
+- verification cannot be run;
+- a required dependency or secret is missing.

.agent/templates/review.md

@@ -0,0 +1,21 @@
+# Diff Review
+
+## Blockers
+
+- None / ...
+
+## Warnings
+
+- None / ...
+
+## Suggested tests
+
+- None / ...
+
+## Out-of-scope changes
+
+- None / ...
+
+## Verdict
+
+approve / request changes

.agent/templates/task-brief.md

@@ -0,0 +1,39 @@
+# Task Brief
+
+## Task ID
+
+`YYYY-MM-DD-short-name`
+
+## Goal
+
+Describe the intended change in one or two sentences.
+
+## Context
+
+Add links, errors, user stories, examples, existing behavior, or relevant files.
+
+## Non-goals
+
+- Do not ...
+- Do not ...
+
+## Acceptance criteria
+
+- [ ] ...
+- [ ] ...
+- [ ] ...
+
+## Verification
+
+Run the relevant commands for this project:
+
+- `...`
+- `...`
+
+## Risk level
+
+Choose one: Fast / Standard / Cautious
+
+## Notes for Claude
+
+Any constraints, preferred approach, migration concerns, compatibility requirements, or rollout notes.

.agent/templates/verification.md

@@ -0,0 +1,21 @@
+# Verification
+
+## Commands run
+
+- `...`
+
+## Results
+
+- Pass / Fail / Not run
+
+## Failures found
+
+- None / ...
+
+## Fixes applied
+
+- None / ...
+
+## Remaining risks
+
+- None / ...

.claude/skills/fix-review/SKILL.md

@@ -0,0 +1,25 @@
+---
+description: Fix only accepted findings from a diff review. Use after review-diff returns blockers or warnings that the user accepts.
+disable-model-invocation: true
+---
+
+Fix only the accepted review findings.
+
+Rules:
+
+- Do not rewrite the solution.
+- Do not expand scope.
+- Do not address subjective style comments unless accepted by the user.
+- Preserve the original plan unless the user explicitly approved a change.
+- Add or update tests only when needed to cover the accepted finding.
+- Run relevant verification commands again.
+
+Final report:
+
+## Fixes applied
+
+## Files changed since review
+
+## Commands run
+
+## Remaining risks

.claude/skills/implement-plan/SKILL.md

@@ -0,0 +1,30 @@
+---
+description: Implement an approved plan with minimal scope, tests, and verification. Use after the user approves a plan.
+disable-model-invocation: true
+---
+
+Implement the approved plan.
+
+Rules:
+
+- Follow the approved plan exactly.
+- Keep the diff minimal.
+- Do not refactor unrelated code.
+- Do not change behavior outside the task scope.
+- Add or update tests for changed behavior.
+- Run the verification commands from the plan or task brief.
+- Fix failures caused by your changes.
+- Stop and explain before expanding scope.
+- If a verification command is unavailable, explain why.
+
+Final report:
+
+## Summary
+
+## Files changed
+
+## Tests added or updated
+
+## Commands run
+
+## Remaining risks

.claude/skills/plan-task/SKILL.md

@@ -0,0 +1,37 @@
+---
+description: Plan a coding task before editing. Use for non-trivial implementation, bug fixing, refactoring, or unfamiliar code. Produces a concise plan and waits for approval.
+disable-model-invocation: true
+disallowed-tools: Write Edit MultiEdit
+---
+
+You are planning a coding task.
+
+Read the task brief provided by the user. If a `.agent/tasks/<task-id>/brief.md` file is mentioned, read it first.
+
+Workflow:
+
+1. Explore the relevant code in read-only mode.
+2. Do not edit files.
+3. Classify the task as Fast, Standard, or Cautious.
+4. Produce a concise implementation plan.
+5. Stop and wait for user approval before implementation.
+
+The plan must include:
+
+- task classification;
+- assumptions;
+- files inspected;
+- files likely to change;
+- files that should not change;
+- implementation steps;
+- tests to add or update;
+- verification commands;
+- risks and ambiguities;
+- stopping conditions.
+
+Constraints:
+
+- Keep the scope minimal.
+- Do not refactor unrelated code.
+- Prefer the safest minimal default for ambiguities.
+- If no code change is needed, explain with evidence.

.claude/skills/review-diff/SKILL.md

@@ -0,0 +1,56 @@
+---
+description: Review the current git diff against the task brief and approved plan in a fresh read-only context. Use before finalizing Standard or Cautious tasks.
+disable-model-invocation: true
+context: fork
+disallowed-tools: Write Edit MultiEdit
+---
+
+Review the current diff against the task brief and approved plan.
+
+Use the live git state below as the source of truth.
+
+## Current branch
+
+!`git branch --show-current || true`
+
+## Git status
+
+!`git status --short || true`
+
+## Diff stat
+
+!`git diff --stat HEAD || true`
+
+## Diff
+
+!`git diff HEAD || true`
+
+## Instructions
+
+Look for:
+
+- missing requirements;
+- bugs;
+- missing edge cases;
+- missing tests;
+- regressions;
+- security risks;
+- data consistency risks;
+- concurrency or idempotency risks;
+- unrelated changes.
+
+Do not comment on subjective style preferences unless they affect correctness or maintainability.
+
+Return exactly:
+
+## Blockers
+
+## Warnings
+
+## Suggested tests
+
+## Out-of-scope changes
+
+## Verdict
+
+Use `approve` or `request changes` for the verdict.

CLAUDE.md

@@ -0,0 +1,101 @@
+# Claude Instructions
+
+## Working style
+
+- Prefer small, focused changes.
+- Do not refactor unrelated code.
+- Do not change public behavior outside the task scope.
+- For non-trivial tasks, plan before editing.
+- If no code change is needed, stop and explain why with evidence.
+- If requirements are ambiguous, list assumptions and choose the safest minimal default.
+- Keep generated artifacts in `.agent/tasks/<task-id>/` when the task is medium or larger.
+
+## Task lanes
+
+Use the smallest lane that fits the work.
+
+### Fast lane
+Use for obvious one-file changes, typos, small logging changes, or simple renames.
+
+Workflow:
+1. Implement directly.
+2. Run the smallest relevant verification.
+3. Show the diff.
+
+### Standard lane
+Use for most product changes and bugs.
+
+Workflow:
+1. Explore relevant code.
+2. Produce a concise plan.
+3. Wait for approval before editing.
+4. Implement the approved plan.
+5. Run verification.
+6. Review the diff.
+7. Fix only accepted blockers/warnings.
+
+### Cautious lane
+Use for authentication, authorization, billing, payments, user data, migrations, concurrency, infrastructure, or broad refactors.
+
+Workflow:
+1. Create or update `.agent/tasks/<task-id>/brief.md`.
+2. Explore read-only.
+3. Produce a plan.
+4. Review the plan adversarially before editing.
+5. Implement in small steps.
+6. Run all relevant verification.
+7. Review the diff in a fresh context.
+8. Fix only accepted blockers/warnings.
+
+## Verification
+
+Before considering a task complete, run relevant project checks. Prefer commands declared by the project, such as:
+
+- test command
+- lint command
+- typecheck command
+- build command
+
+If a command is unavailable, say so explicitly. Never claim a command passed unless it was run in this session and its output was inspected.
+
+## Planning output
+
+For non-trivial tasks, produce a plan with:
+
+- task classification: Fast, Standard, or Cautious;
+- assumptions;
+- files inspected;
+- files likely to change;
+- files that should not change;
+- implementation steps;
+- tests to add or update;
+- verification commands;
+- risks and ambiguities;
+- stopping conditions.
+
+Wait for approval before editing.
+
+## Review policy
+
+Before finalizing Standard or Cautious tasks, review the diff against the task brief and approved plan.
+
+Report real issues only:
+
+- bugs;
+- missing requirements;
+- missing tests;
+- regressions;
+- security risks;
+- data consistency risks;
+- concurrency/idempotency risks;
+- out-of-scope changes.
+
+Avoid subjective style comments unless they affect correctness or maintainability.
+
+## Git
+
+- Work on a dedicated branch for non-trivial tasks.
+- Keep commits focused.
+- Show `git diff` before committing.
+- Never force push unless explicitly instructed.
+- Do not commit secrets, `.env` files, local databases, logs, or generated dependency folders.