Rules: the house rules read in every conversation

# Project rules (starter-kit template, edit it for your project)

> Put this file in the project root. Claude Code reads it at the start of every session. Keep it short: only what must be known every time.

## Communication
- Always answer in [your language].
- Write long answers into `reply.md`; in the terminal, say one line of confirmation (e.g. "reply updated, line 120").
- I write requests in `req.md`; when I say "req updated", go and read it. Details: `.claude/rules/req-reply-protocol.md`.

## Way of working
- Give ONE recommended plan and just do it; only discuss options when I say "give me some options".
- Anything you could not finish or could not do properly must be said out loud. See `.claude/rules/honest-reporting.md`.
- Code marked `[hand-edited]` must not be changed. See `.claude/rules/protect-hand-edits.md`.

## Project info (fill in)
- What this project does:
- Tech stack:
- How to start / how to test:
- Where it is deployed:

## Common commands (see `.claude/commands/`)
- `/status`: show current progress and open items
- `/estimate`: estimate before starting
- `/session-end`: save notes before finishing, so the next session can resume

# Rule: report completion status honestly

When part of a task is "technically impossible / cannot be done completely", never hide it behind something that looks complete but does not work or has holes.

1. Do the doable parts for real, no shortcuts.
2. Mark what cannot be done: in code comments, in a warning banner in the UI, in a ⚠️ section of the docs. Say clearly "this is a placeholder / mock / demo".
3. Say what is missing to make it real (e.g. "needs backend verification of the payment callback", "needs a real API key"). Do not just write "not supported yet".
4. Say it proactively in the completion report; do not wait to be asked.
5. Split the report into three kinds: verified (and how), not tested (and why), not done (and why).

Typical triggers: payments, multi-user accounts, permission checks, anything depending on resources the user does not have yet (real keys, real servers), "only tested on local mock data".

# Rule: protect the parts I wrote by hand

- Code with a `[hand-edited]` comment must not be modified, and must not be "tidied up while you are there".
- When I tell you "I edited this by hand": add one row to the "hand-edit log" table in the project `CLAUDE.md` (date / file / note) and leave it alone from then on.
- If you really must touch that part to finish the task: stop, explain why, and wait for my approval.

Hand-edit log (append as needed):

| Date | File | Note |
|------|------|------|

# Rule: req / reply communication protocol

Purpose: keep "what the human says" and "what the AI answers" in two files, with line numbers, so they can be looked up later and do not vanish when a session is cleared.

## Files
- `req.md`: I write requests here (casual is fine, one per line).
- `reply.md`: you write answers here. Only APPEND new blocks at the end of the file; never rewrite, merge or delete old blocks.

## Trigger
When I say "req updated" or "after req line N": first read `req.md` and check it has enough lines (if not, say "the file may not be saved"), then answer.

## reply block format
```
══════════════════════════════
❓ [date time]
Original:
1. (paste the req text verbatim)
2. (paste the req text verbatim)

Reorganised questions (mapped to the original)
1. (original [1][2]) the reorganised question
───────────────────────────────
Answers
1. (original [1][2]) title
   Answer (plain text, no tables or Markdown marks, because I read the raw text with line numbers)
Status: [1] ✅  [2] ⏳ waiting for confirmation
📌 req lines X-X → reply line XX ✅
```
- The original must be verbatim; "the gist" is not allowed.
- The reorganised-questions mapping must always be there. If one number has several sub-points, map and answer each one; never merge them and drop one.
- `reply line XX` is the line number of this block's `══` line; check it with a search after writing, never write "here".
- In the terminal output only: one line of confirmation + `✅ req lines X-X → reply line XX`.