Work CLI

Operate the local-first .work/ tracker as an agent-facing work ledger.

When To Use

Use this skill when the task is to:

• Inspect or operate a repo's .work/ state.
• Migrate older .work records with work migrate.
• Capture an untriaged request with work inbox add.
• Promote accepted work with work triage accept.
• Claim or renew a time-bounded work item lease with work claim.
• Mark verified work complete with work done.
• Create a direct work item with work new.
• Show work records or scan views with work show and work view.
• Use a typed work item with --type, including scaffolded item spaces and optional type policy via work show --policy.

Do not use this skill for:

• Changing cmd/work, internal/work, or internal/workcli. Those live in the external gh-xj/work-cli repo; edit them there.
• Redesigning the .work/ filesystem contract.
• Adding verification gates or repo convention docs.

Use convention-engineering for convention design and go-scripting for CLI implementation work.

Maintenance Rule

When the gh-xj/work-cli implementation changes, update this skill in the same work session if the changed command, output, storage layout, or operator workflow affects agents. Keep SKILL.md, references/operator-workflow.md, and generated adapter copies in sync before calling the work complete.

Install

work is an external dependency. Install once per machine:

go install github.com/gh-xj/work-cli/cmd/work@latest

Check the installed binary when a command is missing or behavior looks stale:

work version
work version --check

If work version --check reports an older release, rerun go install github.com/gh-xj/work-cli/cmd/work@latest. There is intentionally no work update command; future Homebrew or package-manager installs should be updated through that package manager.

Or grab a tarball release from https://github.com/gh-xj/work-cli/releases. The repo's .conventions.yaml may declare a min_work_version that scripts/verify.sh enforces.

First Actions

1. Find the repo root and check whether the work store config exists.
2. Prefer the repo wrapper when present:

task work -- view ready

3. Otherwise call the binary directly:

work --store .work view ready

4. Use --json whenever another tool or agent will parse the result.
5. If multiple agents or sessions may see the same ready work, claim it before starting. Set WORK_ACTOR to a stable, unique ID for this agent, for example export WORK_ACTOR="agent:run42:review-1". Each sibling needs a different value; reuse your own for renewals. A shared default actor can renew another session's lease: session provenance is not the ownership boundary.

task work -- claim W-0001 --actor "$WORK_ACTOR" --ttl 1h

6. If a store may predate record schema versions, inspect migration first:

task work -- migrate --dry-run

Operating Loop

Read references/operator-workflow.md before making changes to .work/.

Default flow:

1. Capture uncertain requests in the inbox.
2. Triage only when the repo should track the work.
3. Work from canonical records under .work/items/*.yaml.
4. Put item-owned notes and small supporting artifacts under .work/spaces/<W-ID>/ when a work item needs a directory.
5. Use views as derived read models, not as storage.
6. Run the repo's verification gate before marking completion.
7. Use work done with a short summary and evidence after verification passes.
8. Before work done, write the closeout packet (state, evidence, failure accounting, dirty tree, privacy, risks, next prompt); see references/operator-workflow.md Closeout Packet.

Storage Model

• Inbox entry: unaccepted demand signal under .work/inbox/IN-NNNN.yaml, currently schema_version: 1.
• Work item: accepted canonical record under .work/items/W-NNNN.yaml, currently schema_version: 1.
• Work space: optional item-owned directory under .work/spaces/W-NNNN/ for notes, research captures, plans, completion summaries, and other supporting files.
• Work lease: optional time-bounded claim under .work/leases/W-NNNN.yaml.
• Work type: optional scaffold/template under .work/types/<type>/ that can create an initial work space for typed items and expose type policy from .work/types/<type>/policy.md.

Core Commands

work init
work inbox
work inbox add "Title" --body "Context" --source "user"
work triage accept IN-0001 --area cli --priority P1
work new "Title" --area docs --priority P2
work claim W-0001 --actor "$WORK_ACTOR" --ttl 1h
work done W-0001 --summary "Completed" --evidence "task verify passed"
work migrate --dry-run
work migrate
work view ready
work show W-0001
work show W-0001 --policy

Boundaries

• Say "work item" in user-facing text; avoid bare "item" when clarity matters.
• Inbox entries are demand signals, not accepted work.
• Work items are the durable source of truth.
• Claims are coordination leases, not lifecycle status. Claiming a work item does not change status.
• work done sets status: done, records completed_at, releases an active lease when present, and writes optional completion notes under the work space.
• Work spaces support a work item, but do not replace the canonical item YAML.
• Type policies are agent-facing instructions for a work type; they complement the work item and workspace but do not replace either.
• Large logs, browser captures, and bulky evidence payloads belong outside .work/; store only pointers in the work item or its space.
• Do not create legacy compatibility paths unless the user explicitly asks for migration documentation.