| helpA | 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.
|
| create_projectA | 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.
|
| update_projectA | 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.
|
| list_projectsA | 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.
|
| get_roadmapA | 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.
|
| set_overviewA | 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.
|
| set_checkA | 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.
|
| upsert_milestoneA | 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.
|
| open_periodA | 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.
|
| close_periodA | 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.
|
| get_retrospectiveA | 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.
|
| create_taskA | 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`.
|
| update_taskA | 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).
|
| transition_taskA | 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.
|
| list_tasksA | 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'.
|
| get_statusA | 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.
|
| get_taskA | 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.
|
| search_tasksA | 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.
|
| recent_activityA | 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`.
|
| validateA | 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. |
