FronyBoard

Use it when a quarter's work is over and the user wants it closed with a retrospective. Close a period (YYYYQn) and record its retrospective — call when its work is over. Refuses while any task is still todo or in_progress. Stores `result_markdown` as the period's `result` and marks its milestone, if it has one, done. The retrospective is written in the user's language, stays under ~30 lines and holds judgment and reasons only — summary vs goal, what landed and what did not, carried-over tasks (old id -> new id), lessons. Calling it again on a closed period rewrites the retrospective and changes nothing else.

Use it when the user wants a codebase tracked here (register a project, set up a board). Register a new project — once per codebase, before any planning happens. `key` is the task-id prefix (2-5 uppercase letters, e.g. DLY); `description` is one line saying what the project is, in the user's language (shown on the dashboard cards); `repo` is where its code lives (owner/name or a URL). Status starts as active. A fresh project takes tasks at once: create_task opens the current quarter. The plan (set_overview, upsert_milestone) is optional and written with the user.

Use it when you start a piece of work or the user asks to add one (add a task, new to-do). Create a task — one issue/branch-sized unit of work — with status todo. The id is assigned from the project-global sequence and never reused. `period` is YYYYQn: the current quarter (in the server's time zone) opens by itself if it is not open yet, and the answer then carries `opened`; any other quarter must already be open (open_period). Nothing else — no overview, no milestone — has to exist first. `title` is a short English imperative ("Add multi-select status filter") — it is what every reader sees, so it has to say the whole thing. `content` is optional: one line, at most 300 characters, English. It answers **why this task exists** — the pressure that made it necessary, or the scope you deliberately left out. It is written now, before the work, so it cannot describe the approach or the result: the approach you choose, and why, goes in the commit; what proves the work done is `check`, which transition_task takes when you finish. Do not restate the title here: a note that only rephrases it tells the next agent nothing. Line breaks are folded into spaces; a longer text is rejected, not cut. `tags` are free-form labels ("frontend", "bug", "infra"): up to 8 per task, 24 characters each, no commas. Reuse the wording already in use on the project (list_tasks shows it) instead of coining a new spelling for the same thing. `depends_on` lists the task ids this one builds on — the *earlier* work whose result it needs, or the task that handed it this scope. Full ids, other projects allowed. It points backwards only: there is no forward list, so a task never has to be updated because a later one appeared. It is a pointer, not a lock — nothing is blocked, and `list_tasks` / `get_status` merely flag the entries not yet done as `waiting_on`.

Use it when the user asks how a past quarter went (last quarter's retrospective). Read a closed period's (YYYYQn) retrospective — the `result` markdown close_period wrote. Errors while the period is still open; get_status says which ones are closed.

Use it when the user asks for the plan (roadmap, this year's goals, quarter goals). Read a project's plan as written: yearly overviews (goal, now, target, checklist), quarterly milestones, and the names of its periods. Goals only, no counts — get_status for progress and the current period, list_tasks for the tasks themselves. Timestamps (`meta`) are left out unless `include_meta` is set.

Use it first when you start on a project, and when the user asks where it stands (progress, what's left, what's in progress). The resume: everything an agent needs to pick a project up cold, in one call. The latest year's overview (goal / now / target / checklist); per period its milestone goal and status (a period without a milestone has no goal and reports active while open, done once closed), task counts by status, whether it is closed, and `open_tasks` — every todo / blocked / in_progress task with its title, tags, branch, one-line content and `waiting_on`; and `recent_done` — the ten most recently finished tasks across every period, newest first, each with its content, its `check` and when it completed. Closed periods are included. `recent_done` is what the project already has, in the words of whoever built it, and `check` is what they said proves it. Both are claims: confirm against the code before building on one. Older finished work and cancelled tasks are list_tasks; the plan as written is get_roadmap. Call it once at the start of a session; there is nothing to poll for afterwards.

Use it when you know a task id and need the whole record (task details). Read one task in full by id (DLY-042) — the project comes from the prefix, so no key is needed. Returns the record with its period. Use this instead of list_tasks whenever you already know the id; search_tasks when you only know a word from it. The record also carries `waiting_on` when it applies.

Use it for questions about FronyBoard itself — what it is for, which tool to call when, and how a session works with it — and read it once before your first other call in a conversation. Returns the whole guide as Markdown text. To read or change what is recorded, call the working tools directly: get_status, create_task, transition_task, list_tasks, search_tasks.

Use it when the user asks which projects are tracked (project list, which boards exist). List every project (key, name, description, repo, status, meta) — how to find out which keys exist. Archived ones are left out unless `include_archived` is set. Each entry carries a `summary`: its open periods, task counts by status and `last_activity` (the newest task update). No milestones or task detail: get_roadmap for the plan, get_status for per-period progress, list_tasks for the tasks.

Use it when the user asks for finished, cancelled or tagged work, or a past quarter's (done work, tasks by tag). List one project's tasks, optionally narrowed by period, status, tags or recency. get_status already lists the open ones; use this for done or cancelled tasks, a closed period, or a tag cut. get_task when you know the id, search_tasks for text across projects. `period` is YYYYQn (all periods, closed ones included, when omitted), `status` is one of todo | in_progress | done | blocked | cancelled. `tags` narrows to the tasks carrying *all* of the given labels; pass one tag to match on it alone, and call again per tag when you want the union. `updated_since` keeps tasks touched after a duration ("24h", "7d") or ISO timestamp. A row carries `waiting_on` (the ids from its `depends_on` not yet done) only when there are any. Cancelled tasks are excluded unless `include_cancelled` is set or `status` is 'cancelled'.

Use it only to file work under a quarter other than the current one (open next quarter). Open a quarter's period (YYYYQn, e.g. 2026Q3) other than the current one — create_task opens the current quarter by itself, so this is only for filing work under another quarter. No milestone is needed; if the quarter has a planned one, it flips to active.

Use it when the user asks what changed recently or who did it. What changed recently and who did it: the tool calls recorded in tools.jsonl, newest first — `ts`, `tool`, `caller` (key:<name> / session:<user> / oauth:… / stdio / local), `project`, `task` and `args` (argument names; prose fields appear as `<name>_len`); `ok: false` marks a rejected call. This is the mutation history; task records themselves keep only timestamps. `since` is a duration ("24h" default, "7d", "90m") or an ISO timestamp; `key` narrows to one project; `limit` caps the rows (default 50) while `count` reports the total. Read-only calls are dropped unless `writes_only=False`.

Use it when the user remembers a word from a task but not its id or project (find a task). Find tasks by text across all projects, with the dashboard's rules: case-insensitive substring over project key, task id, title and content (not branch or tags); a matching project key returns all of its tasks. Closed periods are included; cancelled tasks only with `include_cancelled` (or `status='cancelled'`). Hits are compact, ordered by project, then in_progress -> blocked -> todo -> done -> cancelled, then id; `match` says which field hit; a task's one-line `content` is included when it has one. `key` narrows to one project, `limit` (default 20) caps the hits while `count` still reports the total. Follow up with get_task for the full record.

Use it when one item of the year's checklist is done or undone (tick off a checklist item). Tick or untick one item of a year's overview checklist: `index` is its 0-based position in get_roadmap's `checklist`, `done` the new state. Returns the updated overview. To add, remove or reword items use set_overview.

Use it when the user sets or rewrites a year's plan (this year's goals, yearly plan). Create or replace a year's overview: the one-line yearly `goal`, plus the three blocks the dashboard shows for the current year — `now` (what is being worked on), `target` (what that work is meant to reach) and `checklist` (the concrete steps to get there, ticked off as they land). A year needs an overview before upsert_milestone will add a quarter to it. `year` is YYYY. All prose here is in the user's language. `now` and `target` are one short line each. `checklist` items are strings (not done yet) or {text, done} maps, in display order. Calling it again replaces the whole overview — resend the checklist to keep it; use set_check to tick a single item. Quarterly goals belong in upsert_milestone, not here.

Use it when work starts, finishes, stalls or is dropped (start, finish, block or cancel a task). Move a task to a new status: todo | in_progress | done | blocked | cancelled. The only tool that changes status — title, content and tags are update_task. `task_id` is the full id, e.g. DLY-042; the project is derived from that prefix, so `key` may be omitted (if given it must match). Call when work starts (in_progress, ideally with the branch name) and when it finishes (done); the server stamps started_at and completed_at itself. `done` requires `check`: one line, at most 300 characters, saying **what proves the work done** — the command you ran and what it printed ("uv run pytest -q: 96 passed"), or the observable a reader can go and see ("GET /healthz returns 200 on the deployed host"). You are the only one who can write it; by the next session the run is gone and all that is left is your word. A restatement of the title proves nothing, so do not write one. get_status shows it beside the finished task, and reopening a task drops it. `cancelled` is the soft delete — there is no hard one: the record is kept but hidden from queries by default, and `reason` is required. Use blocked for work that may resume, cancelled for work that will not happen. Transitioning a cancelled task to any other status restores it.

Use it when the user renames, re-describes, pauses or archives a project. Update a project's own fields — pass at least one of name, description, repo, status. The key (and with it the task id prefix) never changes, and nothing here touches the roadmap, periods or tasks. `name` and `description` follow create_project's language rule. `status`: active | paused | archived. paused only changes the badge; archived hides the project from list_projects and refuses every other mutation until it is set back to active. Archived is as far as removal goes — there is no hard delete.

Use it when a task's title, note, branch, tags or links change (edit a task). Update a task's fields — everything except status, which is transition_task. `branch` records the working branch name; `content` replaces the one-line note (same rule as create_task: one line, at most 300 characters). `check` corrects the proof recorded at completion and is only accepted on a task that is already done. `tags` replaces the whole label list — pass the tags the task should end up with, not just the new ones. `depends_on` likewise replaces the whole predecessor list. Omitted fields are left as they are. To remove an optional field pass an empty value: `content=""`, `branch=""`, `tags=[]`, `depends_on=[]`, `check=""` (title cannot be removed). `task_id` is the full id including the project prefix, e.g. DLY-042 — the project is derived from that prefix, so `key` may be omitted (if given it must match).

Use it when the user sets or changes a quarter's goal (quarter goal, milestone). Create or update a quarterly milestone — a year's goal for one quarter. `year` is YYYY (its overview must exist), `quarter` is Q1-Q4, `goal` is one line in the user's language (a new milestone needs one), `status` is planned | active | done (opening the period flips planned to active, close_period sets done; a milestone added to a quarter already open starts active). Omitted fields keep their current value. A milestone is optional — tasks never need one.

Use it only after the store was edited outside these tools (check the data). Check a project's stored data against the FronyBoard schema and rules, returning errors and warnings. Rarely needed on its own — every mutation runs this same gate and refuses to write when it fails. Use it after the store was edited outside these tools.