PyPI - tcw-cli - Versions diffs - 2.3.0__tar.gz → 2.4.0__tar.gz - Mend

tcw-cli 2.3.0tar.gz → 2.4.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (177) hide show

{tcw_cli-2.3.0 → tcw_cli-2.4.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.3.0
+Version: 2.4.0
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -292,7 +292,7 @@ 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
+anyway, `pipx install tcw-cli` is the whole fix — the **`setup`** skill
 carries the cases where it is not.
 In **Codex**:
@@ -302,7 +302,7 @@ 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`**
+Codex has no session-start hook, so ask the agent to run the **`setup`**
 skill — it runs the same install script Claude runs automatically.
 The plugin ships the skills and read-only review agents described in
@@ -497,11 +497,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 +513,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 +558,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
@@ -695,7 +695,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 +709,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 +723,21 @@ 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               |
 | `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 +758,20 @@ 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.
 The credentials entries hold the **names** of environment variables, never the
 e-mail address or token themselves.
@@ -777,7 +795,19 @@ 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 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 +825,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 +845,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 +861,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 +883,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 +913,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 +1078,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

{tcw_cli-2.3.0 → tcw_cli-2.4.0}/README.md RENAMED Viewed

@@ -76,7 +76,7 @@ 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
+anyway, `pipx install tcw-cli` is the whole fix — the **`setup`** skill
 carries the cases where it is not.
 In **Codex**:
@@ -86,7 +86,7 @@ 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`**
+Codex has no session-start hook, so ask the agent to run the **`setup`**
 skill — it runs the same install script Claude runs automatically.
 The plugin ships the skills and read-only review agents described in
@@ -281,11 +281,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
@@ -297,7 +297,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            |
@@ -342,9 +342,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
@@ -479,7 +479,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                         |
@@ -493,6 +493,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
@@ -502,18 +507,21 @@ 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               |
 | `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
@@ -534,10 +542,20 @@ 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.
 The credentials entries hold the **names** of environment variables, never the
 e-mail address or token themselves.
@@ -561,7 +579,19 @@ 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 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"
@@ -579,11 +609,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
@@ -599,7 +629,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**
@@ -615,18 +645,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                  |
@@ -636,7 +667,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                |
@@ -666,36 +697,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
@@ -830,7 +862,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

{tcw_cli-2.3.0 → tcw_cli-2.4.0}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "tcw-cli"
-version = "2.3.0"
+version = "2.4.0"
 description = "Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,7 +31,7 @@ include = ["tcw*"]
 [tool.setuptools.package-data]
 "tcw.serve" = ["dist/*", "dist/**/*"]
-"tcw.work" = ["prompts/*.md"]
+"tcw.work" = ["prompts/*.md", "procedures/*.md"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]

tcw_cli-2.4.0/tcw/__init__.py ADDED Viewed

	@@ -0,0 +1 @@
1	+ __version__ = "2.4.0"

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

tcw-cli 2.3.0tar.gz → 2.4.0tar.gz