# Бирит

## Connect Claude Code (recommended: MCP)

In your project folder, run:

  claude mcp add --transport http birit https://do.birit.ru/api/mcp \
    -H "Authorization: Bearer <YOUR_TOKEN>"

Then tell Claude: "track this project's tasks in Бирит". It will call
whoami and follow the workflow below.

Get a token at https://do.birit.ru/tokens (create one bound to a project for
zero-config, or a workspace token to let Claude create projects).


# Бирит — how to manage this project

You are collaborating with a human on a software project. Task tracking lives in
Бирит. Keep the board in sync with your actual work so the human always sees
current status without asking.

## Workflow
1. Call `whoami` first to load the project, its columns, and open tasks.
2. When you START working on a task, call `start_session(task_id)` — it
   returns a briefing with full context (project, task, prior session results).
   Read it before doing anything. Then move the task to the "in progress"
   column (e.g. "В работе") with `move_task`.
3. When you FINISH working, call `finish_session(session_id, summary, ...)`
   with what you did and what remains — the next session starts from this
   report. Move the task to the REVIEW column ("Ревью") and add a short
   `add_comment` describing what you did (link the branch/PR via
   `update_task external_ref` when relevant). **Do NOT move tasks to the
   "done" column ("Готово") yourself** — the human reviews the work and moves it
   to Done. Review is the human's step.
4. When you DISCOVER new work, create a task with `create_task` so nothing is
   lost. Set a sensible column and priority.
5. Prefer referring to columns by their human name (e.g. "Ревью"); the API
   resolves names case-insensitively.
6. Do NOT delete tasks unless the human explicitly asks you to.

## Principles
- The board is the shared truth. Update it as you go, not at the end.
- Implemented work goes to **Ревью**, never straight to Готово — the human has
  the final say and moves reviewed tasks to Done.
- One task = one unit of work the human would want to see tracked.
- Comments are the async communication channel with the human. Use them to
  report progress, blockers, and decisions.


# Бирит REST API (v1)

Base URL: `/api/v1`  ·  Auth: `Authorization: Bearer <token>`
All responses: `{ "ok": true, "data": ... }` or `{ "ok": false, "error": "..." }`.

- `GET  /api/v1/me` — current project with its board snapshot
- `POST /api/v1/tasks` — body: { title, column?, description?, type?, priority? }
- `GET  /api/v1/tasks/:id` — task detail with comments
- `PATCH /api/v1/tasks/:id` — body: { title?, description?, type?, priority?, points?, state?, externalRef? }
- `DELETE /api/v1/tasks/:id` — delete a task
- `POST /api/v1/tasks/:id/move` — body: { column, toIndex? }
- `POST /api/v1/tasks/:id/comments` — body: { body }
- `POST /api/v1/tasks/:id/sessions` — start a Work Session; body: { agent?, repository?, branch? }; returns { sessionId, briefing }
- `GET  /api/v1/tasks/:id/sessions` — Work Session history for a task
- `GET  /api/v1/sessions/:id` — session detail (report + events)
- `POST /api/v1/sessions/:id/finish` — body: { summary, nextSteps?, remaining?, filesChanged?, decisions?, branch? }

type ∈ epic | story | task | bug  (Jira-style issue type; set it when creating work)
priority ∈ low | medium | high | urgent