# Claude Instructions

## Project Documentation

The product requirements are defined in `PRD.md`.

When planning or implementing features:
- Treat `PRD.md` as the source of truth for product behavior.
- If a task conflicts with `PRD.md`, stop and report the conflict.
- If a task introduces behavior not covered by `PRD.md`, explicitly identify the gap.

Documentation priority:

1. Task Brief
2. PRD.md
3. Existing code

If there is a conflict:
Task Brief > PRD.md > Existing code

Always report conflicts before implementing.

## 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.
- If any decision is not clearly instructed, stop and ask the user before proceeding.
- When resolving Ruby, Rails, or Tailwind CSS questions, use the Context7 MCP tool — do not rely on training data.
- Always use `bin/rails generate` to create artifacts (models, controllers, migrations, etc.) instead of crafting files manually.
- 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.