work-items · diff

git:20260915.594c83e to git:20260916.2afadb2

21 added, 5 removed. Audit A to A.

---

name: work-items

description: >-

This skill should be used when you are planning or discovering the SHAPE of a

work item — that it breaks into sub-tasks (a parent and its parts), or that

one piece must land before another (a blocks / blocked-by dependency) — and

you want that structure recorded so it shows up in Kurrent Capacitor's Home

- "Blockers & dependencies" view and progress figures. Use the `kcap mcp

- workitems` MCP tools to DECLARE the breakdown and relations. Do NOT use this

- skill for ordinary "attach this session to issue X" correlation alone (a

- single `declare_work_item` call, no structure) or when the work is a single

- indivisible task with no parts and no dependencies.

+ "Blockers & dependencies" view and progress figures. Also use it at the end of

+ a session or a plan step that leaves work unfinished, to record each

+ unfinished piece as a loose end in the user's next-work ledger. Use the `kcap

+ mcp workitems` MCP tools to DECLARE the breakdown, the relations and the loose

+ ends. Do NOT declare STRUCTURE for ordinary "attach this session to issue X"

+ correlation alone (a single `declare_work_item` call, no structure), or for a

+ single indivisible task with no parts and no dependencies — a loose end is

+ worth declaring in either case.

---

# Work items — declaring breakdown and dependencies

A work item's **breakdown** (a parent broken into parts) and its **dependencies**

(one item blocks / is blocked by another) are things you **declare** through the

`kcap mcp workitems` tools. The server never infers them — if you don't declare

the structure, the work item has an empty topology and Home renders no blockers,

no dependency graph, and no `n/m parts` progress figure for it.

Only declare structure that is **real and you are confident of**. Fabricated or

speculative parts/relations are worse than none. A single indivisible task needs

no breakdown.

## When to use these tools

- You've planned a work item as several sub-tasks → create the part items and

declare the parent→parts breakdown.

- You know one item must be finished before another can start → declare the

dependency.

- The structure changed (a part was dropped, a dependency no longer holds) →

retract it.

- You want to see the current structure → read the topology.

- Two items describe the same work (a title-only item you created and the

issue/PR-keyed item the server minted) → merge yours into the keyed one.

- The session was attached to the wrong item → detach it.

+ - You are ending a session, or a plan step, with work you did not finish → declare

+ it as a loose end so it lands in the user's next-work ledger instead of evaporating.

## The flow

1. **Attach the session to its work item** (if it isn't already). `declare_work_item`

with exactly one of `issue_key`, `pr_number`, `work_item_id`, or `new_title`.

Check `get_session_work_items` first if unsure what the session is attached to.

2. **Create the part items.** Each part is itself a work item — create one per

sub-task with `declare_work_item` (`new_title`), keeping the id each returns.

3. **Declare the breakdown.** `declare_work_breakdown` with `parent_id` and the

`part_ids`. It is idempotent — re-declaring an existing part is accepted, not

an error.

4. **Declare dependencies** where they exist. `declare_work_relation` with

`from_id`, `to_id`, and `relation_kind` `"blocks"` (from_id blocks to_id) or

`"blocked_by"` (from_id is blocked by to_id).

5. **Verify** with `get_work_item_topology` (pass the parent's `work_item_id`) —

it returns the parent, parts, and dependencies you can see.

## Duplicates and wrong attaches

A `new_title` declare made before a PR or issue existed becomes a duplicate once the

server mints the keyed item for that work. Do not declare a breakdown to connect the

two — that records structure that isn't there. Merge instead:

- `merge_work_item` with `work_item_id` = the title-only item and `into_work_item_id` =

the keyed item. The keyed item survives; the title item's sessions and links move to

it. Repeating a landed merge is a no-op.

- The server refuses (409) when a user marked either item standalone, rejected the

pairing, or the items belong to different tracker hierarchies. Stop and tell the

user — they can merge from the dashboard. Do not retry.

- `detach_work_item` removes this session from an item it was wrongly attached to. The

removal is durable for automated correlation; an attachment a user pinned cannot be

removed by an agent.

+ ## Loose ends

+ A loose end is one concrete piece of unfinished work — a missing test, a TODO you left in

+ the code, a follow-up the user asked for. Declare each with `declare_loose_end` (`text`,

+ one plain sentence). The server keys it on the session, the owner and the normalized text,

+ so declaring the same end twice is a no-op (`created: false`). It refuses text shorter than

+ 12 or longer than 500 characters and "none"-style phrases — do not declare that there is

+ nothing left. Loose ends are the user's; they are never converted into work items by this

+ tool.

## Rules the server enforces

- **Visibility, not repository.** Every item you name must be visible to you.

Repository is display only: a part may live in a different repository than its

parent, and a relation may cross repositories.

- **One parent per part.** A part can belong to at most one parent breakdown.

- **No self-relation.** An item cannot block or be blocked by itself.

- **Idempotent declares.** Re-declaring an existing part or relation is fine.

- **Server-assigned attribution.** These tools take no `source`/`declared_by` —

the server resolves the caller. Don't look for such arguments.

- **Retract, don't delete.** Use `retract_work_breakdown` / `retract_work_relation`

when the structure changes.

- **Merges defer to user facts.** A standalone confirmation or a rejected pairing a

user recorded blocks an agent merge; only a user can lift it.

## Tool reference

| Tool | Required args | Purpose |

|---|---|---|

| `get_session_work_items` | — | List what the current session is attached to. |

+ | `declare_loose_end` | `text` | Record one unfinished item in the user's next-work ledger. `session_id` defaults to the current session. |

| `declare_work_breakdown` | `parent_id`, `part_ids` | Declare parent → parts. |

| `retract_work_breakdown` | `parent_id`, `part_ids` | Detach parts from the parent. |

| `retract_work_relation` | `from_id`, `to_id`, `relation_kind` | Retract a dependency. |

| `get_work_item_topology` | `work_item_id` | Read parent, parts, and dependencies (visibility-scoped). |

| `merge_work_item` | `work_item_id`, `into_work_item_id` | Merge a duplicate into the survivor (prefer the keyed item as survivor). |

| `detach_work_item` | `work_item_id` | Detach the session from a wrongly attached item. `session_id` defaults to the current session. |

## Requirements

Requires `kcap login`. The `kcap-workitems` MCP server is auto-registered for

every supported harness by `kcap setup` and by `kcap plugin install`.