| name | update-work-item |
| description | Update fields (status, priority, tags, parent, etc.) of an existing work item. Use to transition status, change priority, manage tags, or edit any frontmatter field. No transition enforcement — arbitrary changes are allowed. |
| argument-hint | [work-item-ref] [field-op...] |
| allowed-tools | ["Bash(${CLAUDE_PLUGIN_ROOT}/bin/accelerator config *)","Bash(${CLAUDE_PLUGIN_ROOT}/skills/work/scripts/*)"] |
Update Work Item
!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config context --skill update-work-item --fail-safe
!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config agents --fail-safe
If no "Agent Names" section appears above, use these defaults:
accelerator:reviewer, accelerator:codebase-locator,
accelerator:codebase-analyser, accelerator:codebase-pattern-finder,
accelerator:documents-locator, accelerator:documents-analyser,
accelerator:web-search-researcher.
Work items directory: !${CLAUDE_PLUGIN_ROOT}/bin/accelerator config path work --fail-safe
Work Item Template
The following template defines the work item schema and field defaults.
Hint values are extracted at runtime via work-item-template-field-hints.sh.
!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config template work-item --fail-safe
You are tasked with updating frontmatter fields on an existing work item.
This skill supports status transitions, priority changes, tag management,
parent assignment, title changes, and any other frontmatter field edit.
No status transition logic is enforced — the user decides what's valid.
A future feature may add user-configurable transition graphs; this skill
predates that feature.
Step 1: Identify Target Work Item
Parse the first argument and resolve via the configured pattern's
resolver:
${CLAUDE_PLUGIN_ROOT}/skills/work/scripts/work-item-resolve-id.sh <argument>
The resolver respects work.id_pattern and accepts paths, full IDs
(PROJ-0042), and bare numbers (legacy or pattern-shape).
- Exit 0: stdout is the absolute path; use it.
- Exit 1: input was unrecognised. Print
"Unrecognised input '<argument>' — pass a path, a full ID, or a bare number." and exit.
- Exit 2: ambiguous match. The resolver lists every candidate with
a source-category tag. Show the list and ask the user to
disambiguate by re-running with a full ID or path.
- Exit 3: no match. Print
"No work item matching <argument>." and
exit.
- No argument: ask the user which work item to update. Accept the
response and run the resolver against it.
Step 2: Read Current Frontmatter
Read the target file. Extract frontmatter between --- delimiters.
- If the first line is not
---: print "Error: <filename> has no YAML frontmatter. Add a '---' line as the first line of the file, then re-run." and exit. Use the resolved filename, not a glob pattern.
- If
--- opens but never closes: print "Error: <filename> has unclosed YAML frontmatter. Add a '---' line after the last frontmatter key, then re-run." and exit.
Parse field/value pairs from the frontmatter. Preserve the original key
order for diff rendering in Step 4.
Step 3: Interpret Operation
Parse the remaining arguments (after the work item reference) as one or
more field operations. If no operation arguments were provided, show the
current frontmatter and ask which field(s) to change.
Arguments are parsed left-to-right using these rules:
3.1 Tag operations
add tag <value> / remove tag <value> — delegate to
work-item-update-tags.sh:
${CLAUDE_PLUGIN_ROOT}/skills/work/scripts/work-item-update-tags.sh <path> add|remove <value>
The script handles parsing, mutation, canonical re-serialisation, and
no-op detection. If it exits 1 (e.g. block-style tags), print the
stderr message and exit without writing. If it prints no-change,
report "No change needed" and exit cleanly.
3.2 Structured field operations
<field> <value> where <field> is a known frontmatter field name
from the template (e.g. status ready, priority high, parent 0001,
title "New title"). The next token after the field name is consumed
as the value. Quoted strings are treated as a single value.
3.3 Field-only hint elicitation
A known field name as the last token with no following value
triggers hint elicitation. Call work-item-template-field-hints.sh:
${CLAUDE_PLUGIN_ROOT}/skills/work/scripts/work-item-template-field-hints.sh <field>
Present the returned values as examples: "Common statuses: draft,
ready, in-progress, review, done, blocked, abandoned. What would you
like to set?" Accept any value the user provides, including values not
in the hint list. If the script returns no hints, skip the hint list
and simply ask for a value.
3.4 Natural language
Anything that does not match rules 3.1–3.3 (e.g. "mark as done",
"set priority to high", "add backend tag") — interpret into one of the
structured shapes above and echo the interpretation explicitly:
"Interpreted as: status → done" so the user can correct before
confirming.
Disambiguation
If the token sequence is ambiguous, ask the user for clarification
rather than guessing. Present the possible interpretations and let the
user choose.
Special field rules
id (own-identity) — hard-blocked: print "Error: own-identity (id) cannot be changed — the filename prefix is the authoritative work item ID. To renumber a work item, rename the file (e.g. jj mv) and update the id field to match. The id field is always a quoted string." No diff, no write, no confirmation prompt. The same hard
block applies if the user names the field as work_item_id (the
legacy alias accepted on read for files predating the unified
schema).
date — warned: inform the user that date records the work item's
creation time and is typically not edited, then use the AskUserQuestion tool
with two options:
- Yes, proceed anyway — proceed through the normal diff-and-confirm flow
- No, cancel — print "No changes applied." and exit
parent — canonicalised: normalise the value via
work-item-common.sh:wip_canonicalise_id before writing. The
canonicaliser produces the full ID under the configured pattern,
quoted as a string. Examples:
- Default
{number:04d}: 1 → "0001", 42 → "0042".
{project}-{number:04d} with default_project_code: PROJ:
1 → "PROJ-0001", PROJ-0042 → "PROJ-0042",
0042 (legacy) → "PROJ-0042" (canonical form).
No-op detection
If the computed new value equals the current value:
- Single-op: print
"No change needed: <field> is already '<value>'." and exit. No diff, no write.
- Multi-op: note the no-op field informally (
"status is already 'ready' — skipping"), exclude it from the diff, and continue with
the remaining changes. If ALL operations are no-ops, print the
combined "no change needed" message and exit.
Non-template values
If a value is not one of the template's default hints, add a
single-line informational note above the diff: "Note: '<value>' is not one of the template's default statuses; proceeding anyway." No
enforcement — the user confirms, the skill writes.
Step 4: Preview and Confirm
Produce a diff showing only the lines that change, before and after:
-status: draft
+status: ready
-priority: medium
+priority: high
Body label sync
When a field that has a corresponding body label changes, scan the body
for the first line outside any code fence (between ``` delimiters)
whose text starts with the matching label. If found, include the body
line change in the diff preview. If no such line exists, do not inject
one.
Field-to-label mapping:
status ↔ **Status**: kind ↔ **Kind**: priority ↔ **Priority**: author ↔ **Author**:
Convert the frontmatter value to display text using this deterministic
rule: replace hyphens with spaces and apply title case (capitalise each
word, keeping small words lowercase unless they open the phrase). Small
words: a, an, and, as, at, but, by, for, in, nor, of, on, or, so, the, to, up, vs, yet. Single words are simply capitalised
(draft → Draft). Multi-word hyphenated values become spaced title
case (waiting-on-legal → Waiting on Legal,
in-progress → In Progress).
Title sync
If the title is changing, include the body H1 change in the diff too.
The H1 is the first # line in the body after the frontmatter.
Preserve any prefix before the first : in the existing H1 (e.g.
# 0042: Old title or # ADR Work item: Old title) and substitute
the new title after the prefix:
-# 0042: Old title
+# 0042: New title
If the existing H1 has no : separator, replace the full heading text
after # with the new title. Only the first H1 is touched.
Confirmation prompt
Print the diff, then use the AskUserQuestion tool with two options:
- Yes, apply changes — write the changes to disk
- No, cancel — print "No changes applied." and exit without writing
Field insertion preview
When a field does not exist in the target work item's frontmatter (e.g.
adding priority: to a legacy work item), the diff preview shows a pure
addition: +priority: high.
Step 5: Write
Apply edits using the Edit tool:
- Frontmatter changes first — each field change is a separate Edit
call. For field insertion (field absent from frontmatter), insert
the new field as the last line before the closing
--- delimiter.
- Body label syncs second — update the matching body lines.
- Title H1 sync — if the title changed, update the body H1.
If a body sync Edit fails after frontmatter was already written, print:
"Warning: frontmatter updated but body sync failed for **<Label>**: — check the file manually. To revert, run: jj restore <filename>". Do
not attempt to revert the frontmatter change.
After writing, print a confirmation:
Updated <filename>:
status: draft → ready
Quality Guidelines
- Confirmation required: never write without explicit user
confirmation via the y/n prompt.
- No transition enforcement: any status value the user supplies is
acceptable. Arbitrary transitions (draft → done, skipping
intermediate states) are allowed without warning.
- Hint values are suggestions, not constraints: when surfacing
field hints via
work-item-template-field-hints.sh, present them as
examples. Accept any value the user provides.
- Own-identity is immutable: hard-block edits to
id (or to
work_item_id on legacy files) with an error pointing to file
rename (jj mv) as the correct approach.
date is guarded: warn before editing the creation timestamp;
allow if the user confirms.- Tags via script: delegate all tag operations to
work-item-update-tags.sh. The script owns parsing, mutation, and
canonical re-serialisation. If the script exits 1 (block-style),
print stderr and exit. If it prints no-change, report "No change
needed" and exit.
- Body label sync scope: only update the first non-code-fence
occurrence of
**Status**:, **Kind**:, **Priority**:, or
**Author**:. Do not inject labels into work items that lack them.
Do not update occurrences inside code fences.
- Resilient to malformed frontmatter: abort cleanly on missing or
unclosed frontmatter. Error messages use the resolved filename and
match
work-item-read-field.sh phrasing.
- Legacy work items supported: work items with unusual kind or status
values (e.g.
kind: adr-creation-task, status: todo) are fully
updatable. No migration is offered or required.
- Ambiguous globs: if multiple work items match a number glob, list
them and ask the user to choose. Never silently pick one.
- No file renaming: own-identity edits (
id, or work_item_id on
legacy files) are hard-blocked. Point the user to jj mv + manual
frontmatter edit for renumbering.
!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config instructions update-work-item --fail-safe
