Trackers

A tracker is where a project's tasks come from and where agents report back. SI Fabrik supports three, set with tracker.kind. Each one decides which states are active, which are terminal, which columns the board shows, and which tools the agent gets.

All boards have Dispatch Now and Fetch branch into repo. Tracker credentials are resolved on the host and stripped from every agent and hook environment; agents use host-side tools instead.

Built-in board#

The SI Fabrik Board is a Kanban stored as JSON next to WORKFLOW.md. It needs no account and works offline.

tracker:
  kind: local
  provider:
    path: .symphony/board.json   # default
    prefix: HAR                  # identifiers HAR-1, HAR-2, …
  active_states: [Todo, In Progress]
  terminal_states: [Done, Canceled]
  board_states: [Backlog, Todo, In Progress, Human Review, Done, Canceled]

• Task ids are UUIDs; identifiers use the prefix.
• Blockers: set Blocked by (for example HAR-3) when you create a task. A task isn't dispatched while any blocker is not in a terminal state, and its card shows it's blocked.
• You can edit and delete tasks, and comment on them.
• The wizard adds .symphony/ to .gitignore, so the board isn't committed.
• Agent tools: board_get_issue, board_set_state, board_comment, board_create_issue.

ClickUp#

ClickUp tasks come from the current sprint of a Sprints folder, or from one or more fixed lists.

1. Create a personal API token

   In ClickUp, open your avatar → Settings → Apps → API Token. It starts with pk_.

2. Connect in Add Project

   Choose ClickUp, paste the token and press Connect. SI Fabrik saves it to the Keychain as CLICKUP_API_TOKEN (Settings → Environment); it never reaches agents.

3. Pick a sprint folder or a list

   Search Find a sprint folder or list. Choose Current sprint on a Sprints folder, or List for a fixed list. The active, hand-off and done statuses are pre-filled from that list's statuses; adjust them later in WORKFLOW.md.

4. Optionally, only your tasks

   Turn on Only dispatch tasks assigned to me to add assignee: me.

tracker:
  kind: clickup
  provider:
    api_token: $CLICKUP_API_TOKEN
    sprint_folder_id: "90120000000"   # or list_id: "901200000001", or list_ids: [...]
    # assignee: me
    # include_subtasks: true
  active_states: ["to do", "in progress"]
  terminal_states: ["complete", "closed"]

How SI Fabrik reads ClickUp:

• Current sprint: the list in the folder whose start date is at or before now and whose due date is at or after now. Between sprints it uses the most recently started one. The choice is re-resolved every 5 minutes, so sprint rollover is automatic.
• Requests include tasks added to a sprint list from their home list. Pages of 100 tasks, up to 50 pages.
• Status filters are matched against the list's own statuses, and the board's columns default to those statuses, in order.
• identifier is the custom task ID when your workspace has them, otherwise CU-<id>.
• priority is ClickUp's 1 (urgent) to 4 (low). labels are the task's tags.
• blocked_by comes from "waiting on" dependencies. A task isn't dispatched until its blockers reach a closed or done status type, or while its assignee doesn't match assignee.
• When SI Fabrik refreshes running tasks, tasks that return 404 or have left the scoped lists (after a sprint rollover, for example) are dropped.
• On the board you can drag tasks between statuses, create tasks (in the current sprint list) and comment.
• Agent tools: clickup_get_task, clickup_set_status, clickup_comment, clickup_create_task, clickup_add_tag.

GitHub Issues#

Open issues in one repository. Pull requests are skipped.

tracker:
  kind: github
  provider:
    repo: your-org/your-repo        # required
    token: $GITHUB_TOKEN            # default; falls back to `gh auth token`
    exclude_labels: [human-review, blocked]
  active_states: [open]
  terminal_states: [closed]

• States are open and closed. Identifiers are GH-<number>.
• Priority comes from p1 … p4 labels.
• Issues with any exclude_labels label aren't dispatched. Adding human-review is how the agent hands off.
• Set Required label in the wizard (tracker.required_labels) to only dispatch labelled issues.
• The board is read-only; edit issues on GitHub.
• Agent tools: github_comment, github_add_labels, github_remove_label, github_close.

Board columns and states#

tracker.board_states sets the board's columns. Columns that are active states are marked as such on the board ("agents pick these up"). The Settings form in the Workflow tab edits active states, done states, board columns, required labels and the poll interval as chips.

Tracker errors#

Tracker failures are reported with the Symphony spec's categories, in the project header and the Activity log:

See also#

• Agent MCP tools
• Environment and variables
• Example workflows