plane-work-tracking
/plane-work-tracking
Pomaga rozpoczynać, przejmować i kończyć zadania w Plane dla repozytorium, zapisywać nowe pozycje i wiązać worktree z właściwym modułem.
- Autor
- uhstray-io ↗
- Repozytorium
- huhhb ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Pomaga rozpoczynać, przejmować i kończyć zadania w Plane dla repozytorium, zapisywać nowe pozycje i wiązać worktree z właściwym modułem.
Oryginalny opis (EN)
Use when starting, picking up, finishing, or switching Plane work items in a repo that has a Plane project; when new work is discovered mid-task and must be tracked; when a session needs to know which Plane module its worktree works on; or when setting up Plane work tracking in a Claude config. Not for driving an open PR to merge — use pr-shepherd for that.
Jak działa
- Setup (once per machine)
- The worktree binding
- The per-item loop
- GitHub issues
- Rubrics
- Gotchas
- Red flags — stop
Podgląd SKILL.md
---
name: plane-work-tracking
description: Use when starting, picking up, finishing, or switching Plane work items in a repo that has a Plane project; when new work is discovered mid-task and must be tracked; when a session needs to know which Plane module its worktree works on; or when setting up Plane work tracking in a Claude config. Not for driving an open PR to merge — use pr-shepherd for that.
---
# Plane work tracking
Plane is where work is tracked; GitHub issues and PRs sync with it both ways. A session works
**one Plane work item at a time** and leaves each item complete and current before it touches the
next. Nothing is backfilled in bulk: an item is brought up to standard when a session works it.
Conventions for humans (why each rule exists) are in `README.md` beside this file. Read it only
when a teammate asks why a convention exists.
## Setup (once per machine)
Run when asked to "set up Plane work tracking". Show every change before writing it.
- [ ] `claude mcp list` shows `plane` connected. If not, stop: the Plane MCP server must be added first.
- [ ] `member me` (Plane MCP) returns your user. Never hard-code a member id; resolve it per session.
- [ ] Back up `~/.claude/CLAUDE.md`, then add the block below between its own markers. Replace an
existing copy of the block; never touch the rest of the file. Show the diff, write on approval.
- [ ] `touch ~/.claude/plane-tracking.on` — turns on the huhhb SessionStart hook that reports the
worktree's binding and any open claim.
```markdown
# >>> PLANE WORK TRACKING (BEGIN — delete this whole block to revert) >>>
In a repo with a Plane project, track work with the plane-work-tracking skill: load it before
claiming, creating or finishing a Plane work item. One item at a time; close an item out before
touching the next. Create new work as Plane work items, not GitHub issues. Every PR title carries
exactly one bracketed Plane identifier, e.g. `feat(dns): handle AAAA [AC-123]`; mention other
items without brackets. A brief to any agent that may open a PR includes that identifier.
# <<< PLANE WORK TRACKING (END) <<<
```
## The worktree binding
A worktree works one Plane **module**. The binding lives in git config on the branch (never committed):
| Key | Value |
|---|---|
| `branch.<b>.planeProject` | project UUID (`project list`, match `identifier`) |
| `branch.<b>.planeModule` | module UUID |
| `branch.<b>.planeItem` | claimed item identifier, e.g. `AC-612` |
| `branch.<b>.planeItemStart` | epoch seconds of the claim (`date +%s`) |
Unbound branch: propose a module and confirm with the user before recording it. In a repo synced
from OpenSpec, the module is the OpenSpec change (module name = change directory name). Elsewhere,
one module per feature or plan phase — create it only after the user confirms the name.
## The per-item loop
Copy this checklist for every item.
- [ ] **Pick.** Open items of the bound module (`module list_workitems`). First those with no
unresolved `blocked_by` relation (`workitem_relation list`), then OpenSpec task-number order
(`1.2` before `1.10`). Read `get_pql_reference` before writing a PQL filter. If every open
item is blocked, stop and ask the user — never start a blocked item.
- [ ] **Claim.** First `git config --get branch.<b>.planeItem`: if a claim is already recorded
(another session, or an earlier one), never overwrite it — resolve it as a resumed claim
below or ask the user. Then `workitem manage_assignee` adds `member me`; `workitem update` sets
state **In Progress**; `git config branch.<b>.planeItem <ID>` and `planeItemStart $(date +%s)`.
- [ ] **Conform this item** (this item only — never sweep the module):
- priority from the rubric below — never leave `none`;
- exactly one **type** label and one or more **area** labels (`workitem manage_label`);
- module membership (`module manage_workitems`) and milestone membership (`milestone manage_workitems`);
- dependencies: `blocked_by`/`blocking` via `relation_type`; related work via the custom
definitions *Relates to* / *Implements* / *Duplicate* (`list_definitions` for ids).
- [ ] **Work.** New work found mid-item becomes a **sub-item**: `workitem create` with `parent` = the
current item, same module and milestone, conformed like any item. If the parent's release has
already shipped, propose the next open milestone and get the owner's confirmation **before**
`workitem create`, even when that milestone already exists. This holds **even when the
new work is outside the current item's scope**: `parent` records where the work was found, not
that the parent owns it, and the parent's close-out does not wait for it. Never a GitHub issue, and
never a new line in OpenSpec `tasks.md` — the sync reads only the default branch and would
create a duplicate later. Edit `tasks.md` only when the plan's scope itself changes.
- [ ] **PR.** Title `type(scope): summary [ID]` — the brackets make Plane link the PR *and* move the
item's state by the project's PR mapping. Other items: bare `ID` (link only).
- [ ] **Close out** before claiming anything else, and before any branch or worktree cleanup
(`git branch -d` deletes the binding and the start time):
1. `work_log create`, `duration` = minutes since `planeItemStart`, one-line `description`.
2. `workitem_comment` with the outcome. A PR titled with `[ID]` is already attached by Plane's
GitHub app (a second `workitem_link create` answers 400 "URL already exists"); add a
`workitem_link` only for a PR or URL that carries no bracketed ID.
3. State: if a PR carries `[ID]`, leave it — the PR mapping owns it from then on. Set it yourself
only with no PR: Done (finished) or Cancelled (dropped).
4. Update relations the work changed (unblocked items, newly found dependencies).
5. Read back: `workitem retrieve` (assignee, priority, labels, parent), `module list_workitems`
and `milestone list_workitems` contain it, `workitem_relation list`, `work_log list`.
Fix anything missing and read back again.
6. Clear only your own claim: `git config --unset branch.<b>.planeItem '^<ID>$'` (the value
pattern leaves another session's claim alone), then `--unset branch.<b>.planeItemStart`.
**Resumed claim** (the SessionStart hook reports an OPEN CLAIM from an earlier session): log that
earlier segment first. Propose its end as the branch's last commit (`git log -1 --format=%ct`)
rather than now, which would count idle time, and confirm it with the user. If the last commit is
older than `planeItemStart`, or work went on after it, ask for the end time or an estimate.
Then reset `planeItemStart` to now and continue, or close out.
## GitHub issues
Plane is the only tracker for new work: **never add the `github` label** to a Plane item, so no
GitHub issue is created from Plane. The other direction is label-gated too: a GitHub issue reaches
Plane only when it carries the **`plane`** label. When you meet an open GitHub issue that has no
Plane item (filed by a teammate or a bot, or named in a PR), and only that one issue:
1. `gh label list` — if the repo has no `plane` label, `gh label create plane`.
2. `gh issue edit <n> --add-label plane`.
3. Find the new item (`workitem search` with the issue title). If it has not appeared after a
minute, tell the user: the repo's issue sync may not be configured.
4. Conform it like any item. Never bulk-label the backlog.
## Rubrics
| Priority | When |
|---|---|
| `urgent` | production down, security issue, data loss |
| `high` | blocks another open item, or on the milestone's critical path |
| `medium` | planned work in the current milestone (default) |
| `low` | nice to have, or belongs to a later milestone |
**Type labels** (one): `bug`, `enhancement`, `documentation`, `refactor`, `chore`, `test`, `ci`,
`security`, `dependencies`. **Area labels**: the repo's own GitHub label names, per project. A
missing label is created with exactly the GitHub name (`label create`); propose a brand-new area
label to the user first. Label and state names are permanent keys — never rename one.
**Milestone = release.** Title is the exact tag the work ships in (`v0.15.0`); `-dev.N`
prereleases are not milestones. No milestone fits → propose the next version from the latest tag
(`gh release list`) and **ask before creating it**.
## Gotchas
- `module`/`milestone manage_workitems` return `null` on success and there is no module or
milestone field on `workitem update` — membership is only provable with `list_workitems`.
- Plane Releases return HTTP 402 on our plan; milestones stand in for releases.
- `work_log create` returning HTTP 404 "Worklog is not enabled for the project" means the
project's time tracking is off. Turn it on with `project update` `is_time_tracking_enabled=true`,
then retry. If `project update` is refused (project settings need a project admin), ask an admin
to enable time tracking, keep the claim and its start time, and retry later. Never skip the time log.
- The OpenSpec sync owns which items and modules exist (keyed by `external_id`); Plane owns state,
assignees, labels and edits. Never delete or rename a synced item or renumber a task.
- Git stores `planeItem` keys lowercased; `git config --get` matches them case-insensitively.
- A relation's direction is not documented: after `workitem_relation create`, `list` it and
confirm it reads the way you meant; fix by deleting with the same `is_dependency` kind.
## Red flags — stop
| Thought | Reality |
|---|---|
| "I'll log the time at the end of the day" | The start is in git config only until the branch is cleaned up. Log at close-out. |
| "The PR is open, I'll set the item to In Review/Done" | The bracketed PR owns the state. Setting it fights the automation. |
| "Quick follow-up, I'll open a GitHub issue" | New work is a Plane sub-item with `parent` set. |
| "I'll tag it `github` so the team sees it on GitHub" | Plane is the only tracker for new work. No `github` label. |
| "It's not part of this item, so no parent" | Found while working this item → sub-item of it. Scope doesn't change that. |
| "While I'm here, let me fix every item in the module" | One item at a time. Conform only the item you claimed. |
| "No milestone fits, I'll create v0.16.0" | Propose and ask. Release scope is the owner's call. |
| "The update call succeeded, so it's set" | `manage_workitems` returns nothing. Read back. |
Pliki w paczce (2)
- README.md 14 KB
- SKILL.md 10 KB
Wersje
W bazie nie ma innych skilli o nazwie plane-work-tracking.
Migawka bazy z 13.11.2026 · wersja paczki 79b2977e370d (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100worktree-new
Tworzy worktree zadania poleceniem aidrian i uruchamia bootstrap projektu. - 100fork
Tworzy nowe drzewo robocze (worktree) repozytorium z zależnościami i środowiskiem i otwiera je w nowej sesji agenta. - 100create-pull-request
Tworzy pull request dla bieżącej gałęzi: zbiera kontekst, generuje opis według pull_request_template.md i dodaje do tytułu prefiks z ID elementu pracy Plane. - 100plane-workflow
Prowadzi zadania w Plane z czasem pracy: start i zamknięcie, timer, wpis czasu, raporty dzienne i miesięczne oraz edycję po podglądzie. - 100worktree
Tworzy worktree gita dla nowej gałęzi funkcji i przygotowuje w nim pliki oraz zależności. - 95lov-plane-cli
Czyta i zapisuje dane instancji Plane z wiersza poleceń przez REST API v1: projekty, elementy pracy, cykle, moduły, stany i etykiety oraz tworzenie i aktualizacja elementów i komentarzy.