nick-doc/AGENTS.md

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:

   ### 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.