From caf738008828c425ba99aab3394960067b42c614 Mon Sep 17 00:00:00 2001 From: Allan Souza Date: Sun, 7 Jun 2026 17:20:56 -0300 Subject: [PATCH] docs: add agent guidance files and templates --- .agent/templates/plan.md | 48 ++++++++++++ .agent/templates/review.md | 21 +++++ .agent/templates/task-brief.md | 39 ++++++++++ .agent/templates/verification.md | 21 +++++ .claude/skills/fix-review/SKILL.md | 25 ++++++ .claude/skills/implement-plan/SKILL.md | 30 ++++++++ .claude/skills/plan-task/SKILL.md | 37 +++++++++ .claude/skills/review-diff/SKILL.md | 56 ++++++++++++++ CLAUDE.md | 101 +++++++++++++++++++++++++ 9 files changed, 378 insertions(+) create mode 100644 .agent/templates/plan.md create mode 100644 .agent/templates/review.md create mode 100644 .agent/templates/task-brief.md create mode 100644 .agent/templates/verification.md create mode 100644 .claude/skills/fix-review/SKILL.md create mode 100644 .claude/skills/implement-plan/SKILL.md create mode 100644 .claude/skills/plan-task/SKILL.md create mode 100644 .claude/skills/review-diff/SKILL.md create mode 100644 CLAUDE.md diff --git a/.agent/templates/plan.md b/.agent/templates/plan.md new file mode 100644 index 0000000..9b7cb2a --- /dev/null +++ b/.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. diff --git a/.agent/templates/review.md b/.agent/templates/review.md new file mode 100644 index 0000000..f1704e3 --- /dev/null +++ b/.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 diff --git a/.agent/templates/task-brief.md b/.agent/templates/task-brief.md new file mode 100644 index 0000000..5e3cf2a --- /dev/null +++ b/.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. diff --git a/.agent/templates/verification.md b/.agent/templates/verification.md new file mode 100644 index 0000000..7fb3e69 --- /dev/null +++ b/.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 / ... diff --git a/.claude/skills/fix-review/SKILL.md b/.claude/skills/fix-review/SKILL.md new file mode 100644 index 0000000..7118509 --- /dev/null +++ b/.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 diff --git a/.claude/skills/implement-plan/SKILL.md b/.claude/skills/implement-plan/SKILL.md new file mode 100644 index 0000000..387305a --- /dev/null +++ b/.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 diff --git a/.claude/skills/plan-task/SKILL.md b/.claude/skills/plan-task/SKILL.md new file mode 100644 index 0000000..d358807 --- /dev/null +++ b/.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//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. diff --git a/.claude/skills/review-diff/SKILL.md b/.claude/skills/review-diff/SKILL.md new file mode 100644 index 0000000..99d8ec8 --- /dev/null +++ b/.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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c74d861 --- /dev/null +++ b/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//` 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//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.