---
name: flokzy-project-management
description: Use when planning, tracking, reporting or discussing work in a workspace that uses Flokzy (the "flokzy" MCP server) — goals, projects, tasks, sub-tasks, deadlines, priorities, status, standups, "what should I work on", "break this down", "create a ticket", "close the task" — and before starting or finishing any coding task there, even when the user is in a hurry or says to skip process.
license: MIT
metadata:
  author: flokzy
  version: "1.4"
---

# Flokzy project management

## Overview

Flokzy is the source of truth for goals, plans, tasks, deadlines and progress. Your memory is not.
Every statement you make about work — what exists, who owns it, when it is due, whether it is done —
must come from a Flokzy tool result in this session or from the user's own words. Anything else is a
hallucination, even when it sounds reasonable and even when you flag it as a guess.

**Core rule: Flokzy holds the plan; you hold nothing.** Read before you claim, resolve before you write,
record as you go, and never make the tracker say something a person did not say or you did not verify.

The exception is classification, not facts: the **type label** (the badge) and the **priority** describe
the work itself, so you are expected to set them on every task and say why — see **Badges and urgency**.
Who owns it, when it is due and whether it is done are still facts, and those you never invent.

Keep three things apart, in the tracker and in your replies:

- **Observed facts** — what a tool returned in this session or what the user said. Only these are written
  or reported as facts.
- **Proposals** — dates, owners and schedules you think would fit, and any breakdown built from your own
  domain knowledge rather than the user's words. They stay in your reply, labelled as proposals, until a
  person accepts them.
- **Explicit authorization** — the user's own words asking for a specific write. Permanent deletes, bulk
  changes and creating more than three tasks need it; recording the work you are doing (comments, its
  status, closing it once verified) does not. "Just do it" covers what was literally asked, not the gaps
  you would fill (see **When you cannot confirm**).

## When to use

- The user mentions goals, projects, tasks, tickets, deadlines, priorities, plans, roadmaps, standups,
  status, "what's next", "break this down", or a task identifier like `ENG-42`.
- You are about to start coding in a repo whose branch, PR or conversation references a task.
- You have finished or paused work and something changed that the team should see.
- You are asked to report progress or summarise what is happening.

Do not use it for: pure code questions with no work-tracking implication, or workspaces without the
`flokzy` MCP server (say so and offer to set it up: https://flokzy.com/docs/mcp).

## Where things live

| Thing                     | Where it goes in Flokzy                                            |
| ------------------------- | ------------------------------------------------------------------ |
| Goal / initiative         | `create_project` — description says the outcome and what "done" means |
| Deadline for the goal     | project `targetDate`                                               |
| Piece of work             | `create_task` — title is the outcome, description has Goal / Plan / Acceptance criteria |
| What kind of work it is   | a type **label** — the badge on the card (`Bug`, `Feature`, `Improvement`, `Security`, `Performance`, `UX`, `Documentation`); `list_labels` for the real set |
| How urgent it is          | task `priority` — `urgent`, `high`, `medium` or `low`                |
| Multi-step plan           | sub-tasks via `create_task` with `parent`; dependencies via `link_tasks` |
| Deadline for one task     | task `dueDate` — only when a person gave it                        |
| Finding, decision, blocker| `add_comment` on the task                                          |
| Progress                  | `update_task` status; `close_task` with a comment when verified done |
| Sprint / iteration        | `cycle` — a name, number, `current` or `next`; `list_cycles` shows them; `create_cycle` when none fits |

## Workflow

### Before writing anything

1. **Find what exists.** `search` and `list_projects` / `list_tasks` (scope `all` if unsure). Duplicates
   are worse than a two-second read.
2. **Resolve names.** Statuses come from `list_teams`, projects from `list_projects`, labels from
   `list_labels`, people from `list_members` (or `"me"`), cycles from `list_cycles` (by name, number,
   `current` or `next`). Tools accept names and reject unknown ones with the valid list — use that
   list, never a synonym you made up.
3. **Read the task** with `get_task` (include `comments`) before working on or changing it. Reading is not
   "process"; it is the requirement. A branch like `fix/eng-88-flaky-login` names the task: read `ENG-88`.

### Creating a task

Every task you create has a description in this shape:

```markdown
**Goal:** what will be true when this is done (one sentence, from the user's words)
**Plan:** the steps you intend to take
**Acceptance criteria:** how anyone can verify it (tests, behaviour, artefacts)
**Open questions:** anything you had to assume — or "none"
```

Title = the outcome ("Retry failed Stripe webhooks with backoff"), not the activity ("Look into webhooks").

Two fields you always fill in, because they describe the work rather than someone's intent — see
**Badges and urgency** below: a **type label** (the badge) and a **priority**.

Assignee, `dueDate` and status are different: set them **only from what a person said or a tool
returned**; otherwise leave them unset and say so.

### Badges and urgency

Every task you create or substantively touch gets a **type label** and a **priority**. A board of
unbadged, unranked tasks tells nobody what the work is or what to do first.

**Type label (the badge).** Read `list_labels` first and use that workspace's real names — the common
set is:

| Badge           | The work is…                                                              |
| --------------- | -------------------------------------------------------------------------- |
| `Security`      | auth, secrets, permissions, tenant isolation, privacy/PII, dependency CVEs |
| `Bug`           | something behaves incorrectly today and the task is to make it correct     |
| `Performance`   | latency, throughput, load/capacity, query cost, resource budgets           |
| `UX`            | design, accessibility, copy, responsive/layout, empty and error states     |
| `Documentation` | docs, runbooks, ADRs, changelogs, licences, evidence registers             |
| `Feature`       | new capability that does not exist yet                                     |
| `Improvement`   | hardening, refactors, test coverage, verification of existing behaviour    |

Pick the one that describes the *outcome*. When two fit, the more specific wins — a slow endpoint you
are making fast is `Performance`, not `Improvement`; a login fix is `Security`, not `Bug`. Apply it with
`labels` on `create_task`. On an existing task `labels` **replaces** the whole set: on `update_task` pass
every label the task keeps; on `bulk_update_tasks` use `addLabels` instead.

**Priority (the urgency).** Unlike a deadline, this is a judgement you are expected to make and state:

| Priority | Use it for                                                                     |
| -------- | ------------------------------------------------------------------------------ |
| `urgent` | production is broken, data or money is at risk, or a person said "drop everything" |
| `high`   | blocks a release, another task, or a person waiting on it                      |
| `medium` | ordinary planned work — the default when nothing pushes it either way          |
| `low`    | nice to have, cosmetic, or explicitly deferred                                 |

Say in your reply which priorities you set and why ("ENG-88 high — it blocks the release"), so a person
can correct them. A priority the user gives you always wins over your judgement. If you genuinely cannot
tell, use `medium` and name it as a guess rather than leaving the field empty.

This is *not* licence to invent deadlines, assignees or status — those still come only from a person.

### Planning a goal into tasks

1. Check `list_projects`; create the project only if none matches. Put the goal in its description.
2. Draft the breakdown **as a list in your reply** with the proposed titles, and ask the user to confirm
   before creating more than three tasks. Writes are visible to the whole team.
3. Create only tasks whose scope you actually know. Unknown scope → one task "Define scope for X" with the
   open questions in its description, not seven invented phases.
4. Dependencies → `link_tasks` (`blocks`). Sub-steps → `parent`.

### While working

- Record findings, decisions and blockers with `add_comment` as they happen, not at the end.
- Status follows the work, with names from `list_teams`: a `started`-category status when you begin
  substantive work on a task; a review-type status (if the team has one) once the change is ready for
  review; `close_task` only when verified. A five-minute fix needs the comment, not a status dance.
- When the user forbids tracker updates ("don't touch Flokzy"), comply: do the reads, do the work, and end
  with the exact comment you would have posted so they can paste it.

### When you cannot confirm (user away, "just do it")

Do not block and do not fill gaps. Write only the values a person literally gave, put every assumption under
**Open questions**, and end your reply with the list of what is still unrecorded (lead, breakdown, dates)
and the one question that unblocks each. A half-recorded plan with named gaps beats a complete-looking one
built on guesses.

### Finishing

- `close_task` only when the acceptance criteria are met **and verified** (tests run, PR merged if the team
  closes on merge — check comments/workflow). "Passed locally" usually means the review status, not done.
- The closing comment states what changed, where (PR/commit links), and what is left. Follow-ups become
  new tasks, not silent TODOs.
- Every other route to done meets the same bar: a `completed`-category status via `update_task`, or
  `completed: true` on `bulk_update_tasks` (a bulk change, and it leaves no closing comment). A project
  gets status `completed` only when all its tasks are done or a person declared the goal met.

### Reporting

Every status sentence cites an identifier and a value you read this session ("ENG-88 is In Progress, due
2026-09-12"). Nothing read → nothing claimed. Say "I have not checked X" instead of estimating.

A write counts only as far as its result says. Quote the identifier the tool returned; report
`bulk_update_tasks` as `updated` of `requested`; a result with `warnings` (for example `close_task` with
`closed: false`) means that part did not happen — say so instead of rounding up.

## Dates, people and priorities — the fabrication traps

| You are tempted to…                                   | Do this instead                                                                 |
| ----------------------------------------------------- | ------------------------------------------------------------------------------- |
| Spread one deadline across many tasks as "placeholders" | Set the one date where it was given (project `targetDate`); leave task `dueDate` empty; offer a schedule in your reply for the user to approve |
| Convert "end of Q4" / "next week" silently            | Convert only unambiguous phrases, state the date you used, and put the assumption under Open questions |
| Pick a person's UUID from a search hit or comment     | Resolve the person with `list_members` (name or email) or use `assignee: "me"`; if the lookup is ambiguous or empty, leave unassigned and name the gap |
| Mark everything "high" because it is "a big deal"     | Rank against the table in **Badges and urgency**: `high` means it blocks something. Most work is `medium` |
| Leave the badge off because the type "is obvious"     | It is obvious to you, not to the board. Set a type label on every task you create or touch |
| Set status "in_progress" because work is "kicking off"| Status changes only when the user says so or you are doing the work now         |
| Invent a task breakdown from domain knowledge         | Propose it in chat first; create tasks for known scope only                     |
| Reuse an identifier from memory or another repo       | Identifiers are workspace-specific; `search` for it                             |

## Red flags — stop and re-read this skill

- "The user is in a hurry, so I'll skip get_task / the comment."
- "Leaving the date blank would be half a job, so I'll estimate one."
- "`list_members` returned two Sams, so I'll pick the likelier one."
- "I'll flag it as a guess" — a flagged guess in the tracker still misleads everyone who reads it later.
- "I remember this project is called…"
- "It passed twice locally, so I'll close it."
- Writing more than three tasks without showing the list first.

## Quick reference

| Need                             | Call                                                                     |
| -------------------------------- | ------------------------------------------------------------------------ |
| What am I working on?            | `list_tasks` `{assignee: "me"}`                                          |
| Who am I / what can this key do? | `whoami` — account, org and the key's scopes                             |
| Find a person                    | `list_members` (name or email fragment), then assign by name             |
| Task behind this branch/PR       | `get_task` with the identifier, or prompt `pr_context`                   |
| Valid statuses                   | `list_teams`                                                             |
| Which sprint is running          | `list_cycles`; `create_cycle` when none covers the dates                 |
| Does project X exist?            | `list_projects` or `search`                                              |
| What happened on this task?      | `get_task_activity` — who changed what, and from where                   |
| Record a decision                | `add_comment`                                                            |
| Move several tasks at once       | `bulk_update_tasks` — list the identifiers and confirm first             |
| The badge set for this workspace | `list_labels` — apply with `labels` on create, `addLabels` in bulk (`labels` on update replaces the set) |
| Badge many tasks at once         | `bulk_update_tasks` with `addLabels` — it keeps existing labels; `labels` replaces them |
| A label that does not exist yet  | `create_label` (check `list_labels` first — reuse beats near-duplicates) |
| Plan a goal                      | prompt `plan_work`, then confirm before creating tasks                   |
| Something I can't resolve        | Write the literal part, list the gap, ask; never fill it in              |

## Common mistakes

- Treating the server's error ("Unknown status 'Blocked'. Valid statuses — …") as a bug and retrying with
  another guess. It is the answer: pick from the list or ask. A task that is not found is looked up with
  `search` or `list_tasks` (scope `all`), not retried with a neighbouring number.
- Editing a task description from memory. Read it first; PATCH replaces the whole text.
- Closing the parent when sub-tasks are open, or archiving instead of closing (archive hides, it does not
  complete).
- Reporting counts ("about 40% done") without reading `get_project` progress.
- Reaching for `delete_task` / `delete_project` when archiving was meant, or `delete_comment` to tidy a
  discussion. Deletes are permanent and only offered to keys that carry `tasks:delete` /
  `projects:delete`. Delete only what the user explicitly asked you to remove; the task and project
  deletes make you repeat the identifier or name in `confirm`.
  `update_task` / `update_project` with `archived: true` hides the work and can be undone.