Skip to content

t1k:plane

FieldValue
Modulet1k-plane
Version2.13.24
Effortmedium
Tools—

Keywords: bind repo to plane, create tasks, estimated time, plane, plane cycle, plane issue, plane mcp, plane module, plane project, plane state, tạo task, tạo work item, task tuần, todo in progress done, weekly tasks, work item, work item status, workitem, workload estimate

/t1k:plane
[bind|status|match|estimate|advance|comment|unbind] [PROJ-N]

Bind work to Plane (The1Studio/plane-mcp-server) and keep the board honest without anyone hand-updating it. Two bindings, two lifetimes: a repo binds to one project AND (for a game repo) one module, persistently; a session binds to one or more work items, freshly each session.

This skill is also the SSOT behind the enforced work-item workflow that t1k:plan, t1k:cook, t1k:fix, t1k:test, t1k:review, t1k:git, and t1k:ship invoke. Those skills cite references/workflow-enforcement.md; they do not re-implement any of it.

  • Any /t1k:plan, /t1k:cook, /t1k:fix, /t1k:test, /t1k:review, /t1k:git, /t1k:ship run — the lifecycle gate fires automatically.
  • “Bind this repo to Plane”, “which Plane project is this repo?”, “rebind to a different project”.
  • “What am I working on?”, “show my open work items”, “find the work item for X”.
  • “Move CODEBASE-42 to In Progress”, “set 6 hours on CODEBASE-42”, “comment the PR on the work item”.
  • Creating a work item / module / project when nothing matches the task at hand.
  • A single read you already know the tool for — call mcp__plane__retrieve_work_item_by_identifier directly.
  • Conceptual questions about Plane the product — answer from training data, no tool calls.
  • ClickUp, Linear, Jira, or GitHub Issues work — wrong tracker. GitHub issue claiming is skills/t1k-git/references/issue-claim-discipline.md; the two systems are independent and both can be active.
  • Bulk import of >100 work items — rate-limited; script it against the API instead.
  • A bulk update of up to ~100 caller-listed items (state, start/target dates): spawn t1k-plane-updater with the explicit identifier list.
TriggerStageWhat happens
/t1k:planTodoMatch or create the work item · above 4 hours, decompose into a nested sub-task tree (every leaf <= 4h; see references/workflow-enforcement.md § “Decomposition”) · assign to the current user · write per-leaf estimates · state → unstarted group
/t1k:cook, /t1k:fixIn ProgressResolve the session binding · state → started group · write start_date + target_date · comment the plan path · move each phase sub-task as that phase starts, and to its completed state as it finishes
/t1k:test, /t1k:review(no transition)Comment the result — pass/fail counts, review verdict. Uses an In Review/Testing state only if the project defines one
/t1k:git push, /t1k:ship, PR mergedDoneComment the commit SHA / PR URL · state → completed group

Done fires once, at whichever of these comes last: a push with no PR opened → Done at push; a PR opened → Done at merge, not at push. Config: planeWorkflow.doneTrigger (pr-merge-else-push).

Stages resolve to state UUIDs by state group, never by name — see Gotchas.

Every work item T1K creates carries a scope prefix and the matching labels:

[Discipline][Kind] Title

Kind is required, exactly one. Discipline is optional, zero or one, and comes first.

Tokens
kind (required)feature bug doc chore refactor test polish balance
discipline (optional)2d 3d ui ux vfx anim audio design level liveops build qa
[Feature] Add piggy bank shop tier labels: feature
[2D][Feature] New rarity frame icon set labels: 2d, feature
[Audio][Polish] Rebalance SFX bus levels labels: audio, polish
[Balance] Retune wave 12 HP curve labels: balance

Compose and parse with the script — never hand-assemble a prefix, because the token→prefix casing is data (2d → [2D], liveops → [LiveOps]), not a derivable rule:

Terminal window
bun .claude/scripts/t1k-plane-taxonomy.cjs compose --kind feature --discipline 2d --title "…"
bun .claude/scripts/t1k-plane-taxonomy.cjs parse --title "[2D][Feature] …"

Tokens are inferred, not asked for — from the invoking skill, the title’s verbs, the branch name, then changed paths. The composed title appears inside the existing create-item confirmation and is editable there; only low confidence or a genuine tie triggers a question.

T1K never retrofits. An item it merely binds to keeps its owner’s title and labels untouched. Vocabulary meanings, inference precedence, label auto-create policy, and the full non-goals list: references/taxonomy.md.

This is a company-wide self-hosted Plane (https://plane.the1studio.org, not plane.so cloud) with multiple workspaces. One plane MCP server registration now addresses all of them; the workspace is not fixed at install time.

Get the workspace list from the server, not from this file. list_workspaces() returns every workspace the account belongs to, with each one’s project_count. Call it once per session and cache the result; this skill deliberately hardcodes no slug list, because a copy here is a second source of truth that goes stale the moment someone adds a workspace in Plane.

mcp__plane__list_workspaces() # → { discovery, workspaces: [{slug, name, id, reachable}], … }
mcp__plane__set_workspace(slug) # → session default

Read discovery before trusting the list — "api" means it is complete, "probe" means it is not (see Gotchas).

Resolution order, highest wins: explicit workspace_slug arg on the call → set_workspace(slug) session default → OAuth claim → PLANE_WORKSPACE_SLUG env default.

Picking one is the judgment the API cannot make for you. Match the work, not the repo: marketing and TOFUNNY work goes to the marketing workspace, Cocos-engine work to the Cocos one, Unity-engine work to the Unity one. Engine-agnostic kit or core work has no obvious home — ask rather than defaulting, and bind the answer per t1k-plane-binding.cjs bind --workspace-slug so it is asked once per repo.

Before the first bind in a repo, run this sequence — it is not optional:

  1. list_workspaces() — enumerate. Never assume the set; never reuse a slug from this file.
  2. Search the project across every workspace returned, not just the default. A project name that exists in one workspace may exist in another, and search_work_items / list_projects are workspace-scoped, so a single-workspace search cannot tell “not here” from “not anywhere”.
  3. If more than one workspace could plausibly own the work — or none obviously does — AskUserQuestion. Engine-agnostic core/kit work is exactly this case and has no right answer the API can supply.
  4. Only then bind --workspace-slug <chosen>.

bind now refuses without --workspace-slug (--default-workspace is the deliberate single-workspace opt-out), and unknown flags are a hard error rather than a silent no-op — a misspelled --workspace used to be dropped, leaving the bind silently on the server default while the caller believed it had named one. Neither guard replaces step 3: the script can force you to name a workspace, but only the user knows which one is right.

Terminal window
bun .claude/scripts/t1k-plane-binding.cjs status
bun .claude/scripts/t1k-plane-binding.cjs bind \
--workspace-slug unity \
--project-id <team-project-uuid> --project-identifier WORLDGRAIN \
--project-name "World Grain Team" --module-id <game-module-uuid> --module-name "<Game Name>"
bun .claude/scripts/t1k-plane-binding.cjs unbind

The script owns local state only; it never calls Plane. Resolution algorithm (workspace → team project → game module → confirm → auto-learn) is in references/binding.md.

Always pass --workspace-slug — a project UUID is only unique within its workspace, so a binding without it silently resolves against whatever the server default is. Then pass workspace_slug=<binding.workspaceSlug> on every Plane call rather than relying on that default. A binding written before this field existed has no workspaceSlug and means “use the server default” — still valid on a single-workspace instance.

Studio convention: a Plane PROJECT is a team, a MODULE is a game/deliverable. In workspace unity, projects are teams (AAA Team, Moochi Team, World Grain Team, Dream Bit Team, DOTS AI Library, …) and each game or deliverable repo is a module inside its team’s project. Bind a game repo at module level by default: pass both --project-id and --module-id. Fall back to a project-only bind only when list_modules shows no matching module AND the user confirms via AskUserQuestion (offer to create the module first). A project-only binding is still valid (the gate blocks only on no-target), but it files this repo’s work onto the whole team’s board. planeWorkflow.moduleBinding ("optional" default, "required" opt-in, #1271) is the org-level floor. Detection and algorithm: references/binding.md § “What each hierarchy level means”.

Terminal window
bun .claude/scripts/t1k-plane-binding.cjs session list
bun .claude/scripts/t1k-plane-binding.cjs session add \
--work-item-id <uuid> --identifier CODEBASE-42 --name "Add plane skill" --stage todo
bun .claude/scripts/t1k-plane-binding.cjs session stage --identifier CODEBASE-42 --stage in_progress
bun .claude/scripts/t1k-plane-binding.cjs session clear

session stage returns changed:false when the item is already at that stage — skip the Plane write on false. That guard is what stops a re-run of /t1k:cook from spamming duplicate transitions.

Priority order — stop at the first hit:

  1. Explicit identifier in the user’s prompt (CODEBASE-42) → retrieve_work_item_by_identifier.
  2. Session binding already holds a matching item → reuse, no search.
  3. Repo-bound project → list_work_items(project_id, pql='stateGroup IN openStates() AND assignee = currentUser()'), plus search_work_items(query=<task keywords>) for a workspace-wide sweep.
  4. Score candidates on title/description overlap with the task, then propose — never auto-adopt.

No confident match → AskUserQuestion: bind to a candidate · bind to an identifier you type · create a new work item · proceed unbound (session-level only — does not satisfy the repo-level gate: the repo must still be bound, or recorded tracked:false). Full scoring rules: references/binding.md.

mcp__plane__set_issue_workload_estimate(project_id, work_item_id, hours)

Hours, not points. Derived from the plan’s phase breakdown and surfaced for confirmation before writing (planeWorkflow.estimate.confirmBeforeWrite). A work item that has sub-items rejects the write with PARENT_HAS_CHILDREN — put the estimate on the leaves; the parent rolls up via get_workload_rollups.

Every leaf estimate must be <= 4 hours. A larger number means the item is not decomposed yet, not that it is a big task — split it and re-estimate. Plans above 4 hours are tracked as a nested tree, never as one item (a plan of 4 hours or less MAY be one leaf). Full contract: references/workflow-enforcement.md § “Decomposition”.

states = mcp__plane__list_states(project_id) # cache per project per session
target = first state whose `group` == stageMapping[stage].group
(tie-break by `preferredNames`, then lowest `sequence`)
mcp__plane__update_work_item(project_id, work_item_id, state=target.id)

mcp__plane__create_work_item_comment(project_id, work_item_id, comment_html=...) — HTML, not markdown. Used for plan links, test results, review verdicts, commit SHAs, PR URLs.

Full tool map, PQL notes, and the rest of the surface: references/operations.md.

A user pastes N lines and says “create these as tasks” (one line = one work item), often with “estimate for a full week” or “spread Mon-Fri”. This is not a hooked-skill stage, so nothing fires it: load this skill yourself before the first Plane call (the skill-suggest hook only nudges, and only on a keyword in the prompt). Recipe, with the tool-argument traps, in references/operations.md § “Batch-create and schedule from a pasted list”. Two rules to hold up front:

  • Real estimate, no title copy. Set hours with set_issue_workload_estimate even when the project has no estimate system (retrieve_project → estimate: null); never write [4h] into the title or description as a substitute (a second source of truth that drifts).
  • A pasted line above 4h still hits the leaf cap (§ 4). Surface it in the confirmation AskUserQuestion (split into <= 4h sub-tasks, or keep one item because the user said so) instead of silently creating a 5-6h leaf.

Every time you name a work item, module, or project to the user, give them its URL. A bare identifier (WORLDGRAIN-289) or a UUID is not something a human can click, and neither the MCP tools nor the binding file carries a link — you have to build it. The script does it for you:

Terminal window
bun .claude/scripts/t1k-plane-binding.cjs url # narrowest bound scope
bun .claude/scripts/t1k-plane-binding.cjs url --scope project # project board
bun .claude/scripts/t1k-plane-binding.cjs url --work-item <uuid> # one item
bun .claude/scripts/t1k-plane-binding.cjs url --open # launch the browser

status also returns a urls block, so a caller that already ran it needs no second command. Prefer both over hand-assembling a path.

Route shapes ({base} = PLANE_BASE_URL, {ws} = binding.workspaceSlug):

ScopeRoute
Project board{base}/{ws}/projects/{projectId}/issues
Module{base}/{ws}/projects/{projectId}/modules/{moduleId}
Work item{base}/{ws}/projects/{projectId}/issues/{workItemId}
Cycles{base}/{ws}/projects/{projectId}/cycles

The work-item route keys on the UUID, not the identifier. WORLDGRAIN-289 is not addressable — resolve it through retrieve_work_item_by_identifier (or the id you already hold from a list_*) and pass that UUID.

PLANE_BASE_URL is not in your environment. The plane MCP server is stdio-launched with it set inline in its own config block, so it never reaches the agent process. The script resolves it in override order — PLANE_BASE_URL env → binding.baseUrl → project .mcp.json → ~/.claude.json — and reports which one answered as baseUrlSource. When none does, it returns state: "skip" rather than a guessed hostname: say you cannot build the link instead of emitting a plausible wrong one.

  • Confirm before creating or estimating. create_project, create_module, create_work_item, set_issue_workload_estimate, and any delete require explicit user confirmation via AskUserQuestion. Configured in planeWorkflow.guardedWrites.confirmRequired.
  • State transitions and comments are pre-authorized — they are the workflow the user opted into. Do not prompt for each one.
  • Never delete or archive a work item, module, or project as part of a workflow hook. Deletion is only ever an explicit user request.
  • Never invent a UUID. Every id comes from a list_* / retrieve_* call in the same session.
  • Never silently proceed unbound. If matching fails and the user does not choose an option, stop and say so — do not quietly skip the board update.
  • Never write to a project the repo is not bound to without re-confirming the binding.
  • The binding file is never kit-shipped. .claude/plane-binding.json is consumer data. Do not move it into t1k-config-plane.json — t1k modules update replaces kit config files wholesale and would destroy every binding.

T1K_PLANE_MODE=advisory (warn, never block) · T1K_PLANE_MODE=off (skip entirely) · --no-plane on any hooked skill · planeWorkflow.enabled: false in t1k-config-plane.json · a recorded tracked:false (optout). An unbound repo or an absent plane server blocks the hooked skills until one of these applies — the escape hatches, not a silent warning, are the way through. A registered-but-unreachable server blocks in the skill body.

  • references/workflow-enforcement.md — the enforced lifecycle contract cited by the seven hooked skills
  • references/binding.md — repo→project/module and session→work-item resolution algorithms
  • references/operations.md — full tool map, PQL, estimates, cycles, modules
  • modules/t1k-plane/rules/plane-workitem-workflow.md — the always-loaded rule that makes the workflow enforced
  • t1k-config-plane.json — enforcement mode, stage mapping, guarded-write lists