# Agent Instructions

This documentation workspace uses Taskmaster as the source of truth for agent work.

## Repository Rules

- Repository-wide operating rules live in `RTK.md` at this vault root; follow them in addition to this file.
- For product or code changes that affect frontend or backend, keep `frontend` and `backend` package versions/build numbers bumped together and synchronized unless the user explicitly asks otherwise.
- Preserve Telegram Mini App auth retry behavior: `/api/auth/telegram` must accept repeated valid `initData` for the same launch session; replay rejection belongs only on one-time routes such as webhook/session creation.
- In the final response, mention version/build bumps and verification commands when they were part of the work.

## Sync-From-Code Rule (MANDATORY)

Whenever an agent finishes a commit-push in `../backend` or `../frontend`, this
vault MUST be updated **in the same working session**:

1. Add a new entry to `09 - Audits/Activity Log.md` — newest at the top.
   Use this template:

   ```markdown
   ### YYYY-MM-DD — <repo>@<short-sha> — <one-line summary>

   **Commits:** `<sha1>` `<sha2>` …
   **Touched:** path/one.ts, path/two.tsx
   **Why:** <motivation — bug, feature, PRD link, incident #>
   **Verification:** <build status, smoke result, manual check>
   **Linked docs updated:** [[03 - API Reference/Foo]], [[04 - Flows/Bar]]
   ```

2. If the change affects API surface, data models, flows, architecture, ops,
   env vars, or design, update the matching numbered section in this vault
   in addition to the Activity Log entry (do not just log it).

3. Commit with message: `docs: sync from <repo> <short-sha> — <summary>` and
   push to `origin/main`.

The companion `AGENTS.md` files at `../backend/AGENTS.md` and
`../frontend/AGENTS.md` carry the same rule from the code-side.

## Taskmaster Workflow

- Before choosing implementation or documentation work, run `task-master next` from the repository root.
- Inspect the selected task before editing with `task-master show <id>`.
- When starting a task or subtask, mark it active:
  - `task-master set-status --id=<id> --status=in-progress`
- Keep Taskmaster updated as work progresses:
  - `task-master update-subtask --id=<id> --prompt="<what changed, what was learned, blockers, and verification>"`
- When work is complete and verified, mark it done:
  - `task-master set-status --id=<id> --status=done`
- If work is paused or incomplete, leave the task in `in-progress` and add a progress note with the remaining work.

## Local Task Files

- Canonical Taskmaster data: `.taskmaster/tasks/tasks.json`
- Per-task markdown files: `.taskmaster/tasks/task-*.md`
- Source PRDs and audits: `.taskmaster/docs/*.md`
- Public share copy: `taskmaster-share/tasks.json`

Do not hand-edit `.taskmaster/tasks/tasks.json` or generated task markdown files unless the user explicitly asks for direct file maintenance. Prefer Taskmaster CLI commands so task state stays consistent.

## Expected Agent Behavior

- Treat pending Taskmaster tasks as the prioritized backlog.
- Respect task dependencies shown by `task-master next` and `task-master show`.
- Update the relevant task whenever edits, findings, verification results, or blockers materially change the state of the work.
- Before the final response, confirm that Taskmaster reflects the current task status AND that the Activity Log has the latest push entry (if a push happened in this session).
- If `task-master` is unavailable, mention that in the final response and summarize the Taskmaster update that should be applied manually.
