tcw-cli 2.3.0__tar.gz → 2.5.1__tar.gz

{tcw_cli-2.3.0 → tcw_cli-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.3.0
+Version: 2.5.1
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -292,8 +292,10 @@ by installing `tcw-cli` from PyPI with `pipx`, so one installed mid-session
 cannot run until the next one begins. That first session needs network access. It
 installs over an existing `pipx install tcw-cli` rather than beside it, and
 leaves a development checkout (`pip install -e .`) alone. If `tcw` goes missing
-anyway, `pipx install tcw-cli` is the whole fix — the **`tcw-setup`** skill
-carries the cases where it is not.
+anyway, `pipx install tcw-cli` is the whole fix — the **`setup`** skill
+carries the cases where it is not. When the `tcw` CLI and the plugin's skills
+come from different releases, the session tells you which versions they are and
+what to run to line them up; it never stops your work.
 
 In **Codex**:
 
@@ -302,8 +304,10 @@ codex plugin marketplace add brocef/TCW --ref main
 codex plugin add tcw@tcw
 ```
 
-Codex has no session-start hook, so ask the agent to run the **`tcw-setup`**
-skill — it runs the same install script Claude runs automatically.
+Codex has no session-start hook, so ask the agent to run the **`setup`**
+skill — it runs the same install script Claude runs automatically. Every tcw
+skill also asks the agent to run the plugin's version check once per session,
+which warns when the CLI and the skills come from different releases.
 
 The plugin ships the skills and read-only review agents described in
 [Skills and Agents](#skills-and-agents).
@@ -497,11 +501,11 @@ becomes your own `permission`.
 
 #### Skills
 
-| Skill                                          | What it does                                                                                              |
-| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| [`tcw-taxonomy`](skills/tcw-taxonomy/SKILL.md) | Guides an agent through declaring vocabulary and features, linking them, and resolving inherited entries. |
+| Skill                                  | What it does                                                                                              |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| [`taxonomy`](skills/taxonomy/SKILL.md) | Guides an agent through declaring vocabulary and features, linking them, and resolving inherited entries. |
 
-To draft a first taxonomy from an existing codebase, use the `tcw-setup` skill
+To draft a first taxonomy from an existing codebase, use the `setup` skill
 described in [Skills and Agents](#skills-and-agents).
 
 #### CLI
@@ -513,7 +517,7 @@ described in [Skills and Agents](#skills-and-agents).
 | `tcw taxonomy add`     | creates a vocabulary entry or a feature                               |
 | `tcw taxonomy show`    | prints one entry                                                      |
 | `tcw taxonomy path`    | prints the folder the taxonomy is stored in                           |
-| `tcw taxonomy rm`      | removes a local entry                                                 |
+| `tcw taxonomy rm`      | removes a local entry nothing is nested under or refers to            |
 | `tcw taxonomy search`  | searches entry names and descriptions                                 |
 | `tcw taxonomy check`   | checks that every reference and inherited project resolves            |
 | `tcw taxonomy extends` | adds or removes a project whose taxonomy this one inherits            |
@@ -558,9 +562,9 @@ registered in the taxonomy before a capability names it.
 
 #### Skills
 
-| Skill                                                  | What it does                                                                                                                                                          |
-| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`tcw-capabilities`](skills/tcw-capabilities/SKILL.md) | Guides an agent through checking a planned change against the existing capabilities, catching contradictions, and updating a capability's status when work completes. |
+| Skill                                          | What it does                                                                                                                                                          |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`capabilities`](skills/capabilities/SKILL.md) | Guides an agent through checking a planned change against the existing capabilities, catching contradictions, and updating a capability's status when work completes. |
 
 #### CLI
 
@@ -609,8 +613,8 @@ behavior, changes to its internals, or changes to how the project itself runs.
 - **Blockers** are recorded on an item (`tcw work edit --blocked-by`). An item
   with an unresolved blocker cannot start, or be completed as done, without
   `--force`; there is no separate "blocked" status.
-- **Large items split.** A child item lives inside its parent's folder and moves
-  with it. An **epic** groups related items, including items in other
+- **Large items split.** A child item has its own status and keeps a link to its
+  parent, which cannot be closed while the child is open. An **epic** groups related items, including items in other
   repositories, and reports their combined status.
 - **Completing is checked.** `tcw work complete` prints the project's Definition
   of Done (a list you set in `docs/work/dod.yaml`) and refuses until you confirm
@@ -695,7 +699,7 @@ The transitions, and what each one checks before it moves an item:
 | `start`      | `tcw work start <slug>`                                                          | backlog → active                      | a blocker is unresolved; the item belongs to an epic that is not active                                                                   |
 | `submit`     | `tcw work submit <slug>`                                                         | active → review                       | never                                                                                                                                     |
 | `rework`     | `tcw work rework <slug>`                                                         | review → active                       | `refined-outcome.md` is present (it says the work was accepted)                                                                           |
-| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; no `--confirm` |
+| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; the item's folder in its worktree has uncommitted changes; no `--confirm` |
 | discard      | `tcw work complete <slug> --resolution wontfix\|duplicate\|superseded --confirm` | backlog, active or review → discarded | no `--confirm`                                                                                                                            |
 | `drop`       | `tcw work drop <slug> --confirm`                                                 | backlog → removed                     | the item is not in backlog; no `--confirm`                                                                                                |
 | not retained | happens during `complete` or discard                                             | completed or discarded → removed      | only happens when `work.retain` says that status is not kept; `tcw work delete` finishes one that was interrupted                         |
@@ -709,6 +713,11 @@ such as a design rule read at `spec` or `tcw validate` run before `complete`. Se
 [Configuration](docs/guide/configuration.md). `tcw work lifecycle` prints the
 whole contract, with whatever the project has attached.
 
+Some of TCW's other instructions can be replaced the same way: how to work items
+unattended, triage issues, keep documentation in sync, and seven more.
+`tcw work procedure prompt <id>` prints one of them, and a project replaces or
+adds to its text under `work.procedures` in `tcw-config.yaml`.
+
 #### Jira integration
 
 A project can name the Jira Cloud site its team works from. Tickets can then
@@ -718,18 +727,22 @@ to the transitions.
 
 | Lifecycle step                          | Without Jira                   | With Jira configured                                                                                                                           |
 | --------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket |
+| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
 | `request`, `spec`, `plan` stages        | unchanged                      | unchanged                                                                                                                                      |
 | at any time                             | —                              | `tcw work tracker link` / `unlink` records or removes the link between an existing item and a ticket; Jira itself is not touched               |
+| an item has no ticket                   | —                              | `tcw work tracker create <slug>` makes one for it and binds it; `--all` sweeps every open item without one. Needs `work.tracker.create` and `statuses.backlog`. With `create.on-new`, filing an item makes its ticket |
 | `start`                                 | moves the item                 | also claims a linked ticket, and posts a comment if `comments: true`                                                                           |
 | `submit`, `rework`, `complete`, discard | moves the item                 | also moves a linked ticket to the Jira status mapped under `statuses`, and posts a comment if `comments: true`                                 |
 | the ticket could not follow             | —                              | the item still moves; the command exits 1 and records the ticket as pending or conflicting; `tcw work tracker sync` retries                    |
+| the ticket is behind its item           | —                              | with `tcw work tracker link --sync-status`, a ticket linked to work already under way is claimed and moved forward to where the item is      |
+| the ticket does not match its item      | —                              | `tcw work tracker sync <slug>` puts it where the item's status says, whether the ticket is ahead of the item or behind it; a backwards move says so |
 
 Setting `strict: true` changes several steps, so that no work happens without a
 claimed ticket:
 
-- `tcw work new` (except `--epic`) and `inbox accept` are refused, and point you at
-  `tcw work tracker import`.
+- `tcw work new` (except `--epic`) and `inbox accept` of an inbox entry are refused,
+  and point you at `tcw work tracker import`. Where `inbox-query` is set, `inbox accept`
+  of a ticket is allowed, because it claims the ticket.
 - `start` refuses an item with no ticket. For a linked item it claims the ticket
   first, and moves the item only if the claim worked.
 - `submit`, `rework` and `complete --resolution done` read the ticket first, and
@@ -750,10 +763,24 @@ work:
         credentials:
             email-env: TCW_JIRA_EMAIL
             token-env: TCW_JIRA_API_TOKEN
-        transitions: { claim: Start Progress }
+        transitions: { start: Start Progress }
         statuses: { active: In Progress, review: In Review, completed: Done }
+        inbox-query: project = ENG AND status = Triage # optional
 ```
 
+`candidate-query` selects the tickets ready for you to take, and `tcw work tracker
+list` shows them. The optional `inbox-query` selects the tickets still waiting to be
+triaged. When it is set, `tcw work inbox list` prints two sections, `raw intake:` and
+`tracker tickets:`, so triage works from one list. `tcw work inbox show` and
+`inbox accept` then take a ticket key as well as an inbox entry: an inbox entry with
+the same name wins, and `--ticket` reads the name as a ticket anyway. Accepting a
+ticket claims it, exactly as `tcw work tracker import` does. Write the query so it
+leaves out tickets that already have a work item; TCW does not filter them. A
+triage status does not offer the transition that starts work, so to take tickets
+straight from it, name the status and its way out under `pre-backlog` (for example
+`pre-backlog: { Triage: Accept }`, with `statuses.backlog` set): every claim then
+moves the ticket out of Triage to the backlog first, and says so.
+
 The credentials entries hold the **names** of environment variables, never the
 e-mail address or token themselves.
 
@@ -777,7 +804,34 @@ tcw work tracker link <slug> ENG-517       # TCW: records the link.
 tcw work start <slug>                      # TCW: backlog → active.               Jira: if unassigned or yours, ENG-517 → In Progress, assigned to you
 ```
 
-**Example 3: the same project with `strict: true`.**
+**Example 2a: making a ticket for an item that has none.**
+
+```sh
+tcw work new "Speed up the checkout page"  # TCW: creates a backlog item.         Jira: unchanged
+tcw work tracker create <slug> --dry-run   # TCW: says what it would do.          Jira: unchanged
+tcw work tracker create <slug>             # TCW: binds the new ticket.           Jira: creates it, then moves it to statuses.backlog
+tcw work tracker create --all              # TCW: the same for every open item.   Jira: one new ticket per item without one
+```
+
+The move out of whatever status Jira starts issues in is part of creating the
+ticket, not a courtesy: in a project with a triage column, that starting status
+is usually the one `inbox-query` selects, so a ticket left there would come back
+through `tcw work inbox` as new inbound work. Run `--all` with `--dry-run`
+first — nothing here can delete a ticket.
+
+**Example 3: taking a ticket without starting it, and handing it back.**
+
+```sh
+tcw work tracker claim <slug>           # TCW: records you as the owner.          Jira: ENG-517 assigned to you; status unchanged
+#   …you decide it is not yours after all…
+tcw work tracker release <slug>         # TCW: clears the owner.                  Jira: ENG-517 unassigned; status unchanged
+```
+
+Neither command moves anything. Claiming an item already under way is how you
+take work over; releasing one is how you hand it on, and it stays where it is
+until somebody else claims it.
+
+**Example 4: the same project with `strict: true`.**
 
 ```sh
 tcw work new "Speed up the checkout page"
@@ -795,11 +849,11 @@ reports, comments, and the known limits are in
 
 #### Skills
 
-| Skill                                                | What it does                                                                                                                                                                                  |
-| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`tcw-work`](skills/tcw-work/SKILL.md)               | Guides an agent through the whole work lifecycle: triaging the inbox, writing the request, spec and plan, implementing, verifying, completing, splitting large items, and coordinating epics. |
-| [`tcw-post-mortem`](skills/tcw-post-mortem/SKILL.md) | Once a problem has surfaced (rejected work, a false claim in a spec, something shipped that should not have), finds which lifecycle stage could first have caught it.                         |
-| [`tcw-work-create`](skills/tcw-work-create/SKILL.md) | Turns an idea for a piece of work into a work item, or adds it to the item or inbox entry that already covers it, after checking what is already tracked.                                     |
+| Skill                                        | What it does                                                                                                                                                                                  |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`work`](skills/work/SKILL.md)               | Guides an agent through the whole work lifecycle: triaging the inbox, writing the request, spec and plan, implementing, verifying, completing, splitting large items, and coordinating epics. |
+| [`post-mortem`](skills/post-mortem/SKILL.md) | Once a problem has surfaced (rejected work, a false claim in a spec, something shipped that should not have), finds which lifecycle stage could first have caught it.                         |
+| [`work-create`](skills/work-create/SKILL.md) | Turns an idea for a piece of work into a work item, or adds it to the item or inbox entry that already covers it, after checking what is already tracked.                                     |
 
 Most day-to-day work starts from one of the command skills (planning an item,
 driving it to completion, verifying it, processing the inbox) described in
@@ -815,7 +869,7 @@ driving it to completion, verifying it, processing the inbox) described in
 | `tcw work list` | shows the board; completed and discarded items only when asked |
 | `tcw work show` | prints an item's status, fields and documents                  |
 | `tcw work path` | prints the work store's folder, or an item's folder            |
-| `tcw work edit` | changes an item's title, estimates, tags or blockers           |
+| `tcw work edit` | changes an item's title, estimates, tags, blockers or type     |
 | `tcw work tags` | lists, adds or removes the project's registered tags           |
 
 **Transitions**
@@ -831,18 +885,19 @@ driving it to completion, verifying it, processing the inbox) described in
 
 **Lifecycle stages**
 
-| Command              | What it does                                                                              |
-| -------------------- | ----------------------------------------------------------------------------------------- |
-| `tcw work lifecycle` | prints every stage and transition, with what this project attaches to each                |
-| `tcw work stage`     | `stage gate` checks a stage may run; `stage prompt` prints its instructions               |
-| `tcw work scaffold`  | writes a draft of a stage's document from its template                                    |
-| `tcw work docs`      | prints the project's documentation entries: which documents a change must keep up to date |
+| Command              | What it does                                                                                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tcw work lifecycle` | prints every stage and transition, with what this project attaches to each                                                                             |
+| `tcw work stage`     | `stage gate` checks a stage may run; `stage prompt` prints its instructions; `stage validate` checks the arguments given to the `work-stage` skill |
+| `tcw work procedure` | `procedure prompt` prints one of TCW's procedures, such as `unattended-work` or `search`, with this project's own text for it                           |
+| `tcw work scaffold`  | writes a draft of a stage's document from its template                                                                                                 |
+| `tcw work docs`      | prints the project's documentation entries: which documents a change must keep up to date                                                              |
 
 **Inbox, and work across projects**
 
 | Command              | What it does                                                      |
 | -------------------- | ----------------------------------------------------------------- |
-| `tcw work inbox`     | `inbox list`, `inbox show` and `inbox accept` raw requests        |
+| `tcw work inbox`     | `inbox list`, `inbox show` and `inbox accept` raw requests, and Jira tickets awaiting triage |
 | `tcw work nodes`     | lists this project's parent and child projects                    |
 | `tcw work delegate`  | writes a request into a child project's inbox                     |
 | `tcw work escalate`  | writes a request into the parent project's inbox                  |
@@ -852,7 +907,7 @@ driving it to completion, verifying it, processing the inbox) described in
 
 | Command              | What it does                                                                                                  |
 | -------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `tcw work tracker`   | `list`, `show`, `import`, `link`, `unlink` and `sync` against Jira; see [Jira integration](#jira-integration) |
+| `tcw work tracker`   | `list`, `show`, `import`, `claim`, `release`, `link`, `unlink` and `sync` against Jira; see [Jira integration](#jira-integration) |
 | `tcw work init`      | creates the work store's folders (the same as `tcw init work`)                                                |
 | `tcw work tombstone` | records items resolved before the store kept a record of them, so their slugs are never reused                |
 
@@ -882,36 +937,37 @@ across the axes.
 
 | Skill                                                      | What it does                                                                                                                                                                                |
 | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`tcw-setup`](skills/tcw-setup/SKILL.md)                   | Gets TCW working: installs or repairs the CLI, starts using TCW in a repository, sets up a project on a new machine, and drafts a first taxonomy or capabilities list from existing code.   |
-| [`tcw-configure`](skills/tcw-configure/SKILL.md)           | Changes a working project's configuration: what runs at each stage or transition, the Definition of Done, documentation entries, Jira, where stores live, connected and inherited projects. |
-| [`documentation-sync`](skills/documentation-sync/SKILL.md) | Decides which documents a finished change must update (README, changelogs, release notes, guides, skills), and offers a version bump when work is done.                                     |
-| [`tcw-work-stage`](skills/tcw-work-stage/SKILL.md)         | Reads one lifecycle stage in a single step: the stage's own instructions together with whatever this project adds to them.                                                                  |
+| [`setup`](skills/setup/SKILL.md)                           | Gets TCW working: installs or repairs the CLI, starts using TCW in a repository, sets up a project on a new machine, and drafts a first taxonomy or capabilities list from existing code.   |
+| [`configure`](skills/configure/SKILL.md)                   | Changes a working project's configuration: what runs at each stage or transition, the Definition of Done, documentation entries, Jira, where stores live, connected and inherited projects. |
+| [`documentation-sync`](skills/documentation-sync/SKILL.md) | Decides which documents a finished change must update (README, changelogs, release notes, guides, skills), and runs the version cut when you ask for one.                                     |
+| [`work-stage`](skills/work-stage/SKILL.md)                 | Reads one lifecycle stage in a single step: the stage's own instructions together with whatever this project adds to them.                                                                  |
 
 **Command skills: the everyday workflows**
 
-| Skill                                                                                            | What it does                                                                                                    |
-| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| [`tcw-commands-process-inbox`](skills/tcw-commands-process-inbox/SKILL.md)                       | Turns raw inbox entries into work items and writes each one's request.                                          |
-| [`tcw-commands-plan-work`](skills/tcw-commands-plan-work/SKILL.md)                               | Takes an item, or a request made in chat, through the request, spec and plan stages, and stops before any code. |
-| [`tcw-commands-drive-work-to-completion`](skills/tcw-commands-drive-work-to-completion/SKILL.md) | Takes an item from wherever it is through implementation, and stops for your verification before completing it. |
-| [`tcw-commands-verify-work`](skills/tcw-commands-verify-work/SKILL.md)                           | Checks finished work against its spec with you, and records whether it was accepted or needs rework.            |
+| Skill                                                                                    | What it does                                                                                                    |
+| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| [`commands-process-inbox`](skills/commands-process-inbox/SKILL.md)                       | Turns raw inbox entries into work items and writes each one's request.                                          |
+| [`commands-plan-work`](skills/commands-plan-work/SKILL.md)                               | Takes an item, or a request made in chat, through the request, spec and plan stages, and stops before any code. |
+| [`commands-drive-work-to-completion`](skills/commands-drive-work-to-completion/SKILL.md) | Takes an item from wherever it is through implementation, and stops for your verification before completing it. |
+| [`commands-verify-work`](skills/commands-verify-work/SKILL.md)                           | Checks finished work against its spec with you, and records whether it was accepted or needs rework.            |
+| [`commands-pause-work`](skills/commands-pause-work/SKILL.md)                              | Stops the work in hand, writes down what resuming needs in the item, and waits for you to say carry on.        |
 
 **Extras: optional, built for one way of working**
 
 | Skill                                                                      | What it does                                                                                                        |
 | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| [`tcw-extras-autonomous-work`](skills/tcw-extras-autonomous-work/SKILL.md) | Drives work items to completion unattended, asking two read-only advisors wherever the lifecycle would ask you.     |
-| [`tcw-extras-triage-issues`](skills/tcw-extras-triage-issues/SKILL.md)     | Works through **your** project's GitHub issues and turns the ones worth doing into work items.                      |
-| [`tcw-extras-report`](skills/tcw-extras-report/SKILL.md)                   | Files a bug report or suggestion about TCW itself on [this project's issues](https://github.com/brocef/TCW/issues). |
+| [`extras-autonomous-work`](skills/extras-autonomous-work/SKILL.md) | Drives work items to completion unattended, asking read-only advisors wherever the lifecycle would ask you — by default Codex and an Opus subagent, replaceable by your project. |
+| [`extras-triage-issues`](skills/extras-triage-issues/SKILL.md)     | Works through **your** project's GitHub issues and turns the ones worth doing into work items.                      |
+| [`extras-report`](skills/extras-report/SKILL.md)                   | Files a bug report or suggestion about TCW itself on [this project's issues](https://github.com/brocef/TCW/issues). |
 
 **Agents.** Three read-only agents ship with the plugin. None of them edits a
 file or moves an item; each reports back to the session that started it.
 
 | Agent                 | What it does                                                                                                                                     |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `tcw-verifier`        | For the `verify` stage: reads the change against the item's spec, runs checks, and reports whether each acceptance criterion is met.             |
-| `tcw-backlog-auditor` | Checks one backlog item for problems: already done, out of date, in the wrong project, not actionable, or blocked by something already resolved. |
-| `tcw-post-mortem`     | Reads an item's documents and commit history backwards to find which stage could first have caught a problem.                                    |
+| `verifier`        | For the `verify` stage: reads the change against the item's spec, runs checks, and reports whether each acceptance criterion is met.             |
+| `backlog-auditor` | Checks one backlog item against your project's backlog-audit procedure. By default: already done, out of date, in the wrong project, not actionable, or blocked by something already resolved. |
+| `post-mortem`     | Reads an item's documents and commit history backwards to find which stage could first have caught a problem.                                    |
 
 ## TCW Local Web App
 
@@ -1046,7 +1102,7 @@ PyPI. Details, including the one-time PyPI setup, are in
 
 File bugs and suggestions on
 [GitHub issues](https://github.com/brocef/TCW/issues). With the plugin installed,
-the `tcw-extras-report` skill gives you a ready-to-fill template.
+the `extras-report` skill gives you a ready-to-fill template.
 
 ### License