Workingon

Bridge between this session and the ticketing tool. A local ledger, filled in by hooks, records what was asked, which files were touched, which commits landed and which notable commands ran.

WO = node ${CLAUDE_PLUGIN_ROOT}/src/bin/workingon.mjs. Every command accepts --json.

Rules

• Record, do not redo. The work is already done; this only documents it.
• One ticket per task, not per session. Work continuing the linked ticket becomes a comment. A different topic becomes a new ticket.
• Never invent anything that is not in the ledger or in the conversation.
• Write in the user's language.
• End the turn with one short line: ticket reference and URL. Nothing else.

The workspace may be shared

Colleagues may be looking at these boards.

• Never create projects, boards or repositories, and never touch tickets this tool did not create.
• Never delete anything. delete exists for the person to run, not for you. If asked to delete, show what would go and wait for explicit confirmation.
• Only write to the destination that ledger resolves. If it says UNDECIDED, ask first. Never pick a destination that merely looks right.
• If create or comment answer [SIMULATED], nothing was written. Say exactly that, without implying a ticket exists.

Default flow

1. Read the state.

WO ledger --session ${CLAUDE_SESSION_ID}

Returns the folder, branch, destination, linked ticket and the work not recorded yet. If the destination is UNDECIDED, go to Undecided folder.

2. Decide.

• Linked ticket and the work continues it: progress comment (step 3b).
• Linked ticket but this is a different topic: new ticket (step 3a).
• No linked ticket: search before creating.

  WO find "keywords" --session ${CLAUDE_SESSION_ID}
  

  If one is clearly the same thing, link it with WO link --issue <id> --session ${CLAUDE_SESSION_ID} --keep-unsynced and go to 3b. Otherwise create.

3a. Create.

WO create --session ${CLAUDE_SESSION_ID} --title "Title" --body-file - <<'END'
<markdown body>
END

3b. Comment.

WO comment --session ${CLAUDE_SESSION_ID} --file - <<'END'
<markdown comment>
END

Both mark the ledger as recorded. Do not run WO synced afterwards.

If the heredoc is awkward, write the text to a temporary file and pass its path.

How to write the ticket

Title: what it achieves, not what was touched. One line under 80 characters, no prefixes.

• Good: Migrate session auth to JWT
• Bad: Changes in auth.ts and login.tsx, Work on 12 March

Body: five lines at most. One sentence of context and up to four bullets.

<One sentence: what this achieves.>

- <change>
- <change>

Pending: <one line, only if something is left>

Leave out file listings, design rationale, conversation recaps, notes sections and test counts. All of that already lives in the code and in git, and in a ticket it only gets in the way.

Progress comment: two lines. What moved and what is left. Nothing already in the ticket.

Limits are 600 characters for a body and 400 for a comment, enforced by create, update and comment. If a command rejects your text, summarise it. Do not reach for --long.

Arguments

Undecided folder

Each folder is decided once. Until then nothing is written, and the hook says so.

Ask with AskUserQuestion, one question, these options:

• Record it in the default destination, naming it.
• Record it somewhere else. If chosen, show WO containers and ask which.
• Do not record anything from this folder, it is private.

Always save the answer so the question is not repeated:

WO config --map <folder>=<container id>     record there
WO config --exclude <folder>                private folder

--exclude also deletes whatever was already captured locally from that folder, and from then on the hooks store nothing about it.

Then continue the normal flow, or say in one line that nothing was recorded.

Setting up

WO setup runs three steps and can be driven with flags:

1. WO setup --step 1 --provider jira|linear|github|trello|vikunja plus that tool's credentials.
2. WO setup --step 2 --mode ask|autosave|off [--write-style nudge|silent]
3. WO setup --step 3 --container <id> [--label "Claude"]

Never ask the user to paste a token into the chat. Tell them to run WO setup themselves in the terminal, or to put it in the config file that WO doctor points at. WO providers lists the supported tools and WO doctor says what is missing.

Full API details and error tables in reference.md.