Metadata-Version: 2.4
Name: tcw-cli
Version: 3.0.0
Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
           1. Definitions.
        
              "License" shall mean the terms and conditions for use, reproduction,
              and distribution as defined by Sections 1 through 9 of this document.
        
              "Licensor" shall mean the copyright owner or entity authorized by
              the copyright owner that is granting the License.
        
              "Legal Entity" shall mean the union of the acting entity and all
              other entities that control, are controlled by, or are under common
              control with that entity. For the purposes of this definition,
              "control" means (i) the power, direct or indirect, to cause the
              direction or management of such entity, whether by contract or
              otherwise, or (ii) ownership of fifty percent (50%) or more of the
              outstanding shares, or (iii) beneficial ownership of such entity.
        
              "You" (or "Your") shall mean an individual or Legal Entity
              exercising permissions granted by this License.
        
              "Source" form shall mean the preferred form for making modifications,
              including but not limited to software source code, documentation
              source, and configuration files.
        
              "Object" form shall mean any form resulting from mechanical
              transformation or translation of a Source form, including but
              not limited to compiled object code, generated documentation,
              and conversions to other media types.
        
              "Work" shall mean the work of authorship, whether in Source or
              Object form, made available under the License, as indicated by a
              copyright notice that is included in or attached to the work
              (an example is provided in the Appendix below).
        
              "Derivative Works" shall mean any work, whether in Source or Object
              form, that is based on (or derived from) the Work and for which the
              editorial revisions, annotations, elaborations, or other modifications
              represent, as a whole, an original work of authorship. For the purposes
              of this License, Derivative Works shall not include works that remain
              separable from, or merely link (or bind by name) to the interfaces of,
              the Work and Derivative Works thereof.
        
              "Contribution" shall mean any work of authorship, including
              the original version of the Work and any modifications or additions
              to that Work or Derivative Works thereof, that is intentionally
              submitted to Licensor for inclusion in the Work by the copyright owner
              or by an individual or Legal Entity authorized to submit on behalf of
              the copyright owner. For the purposes of this definition, "submitted"
              means any form of electronic, verbal, or written communication sent
              to the Licensor or its representatives, including but not limited to
              communication on electronic mailing lists, source code control systems,
              and issue tracking systems that are managed by, or on behalf of, the
              Licensor for the purpose of discussing and improving the Work, but
              excluding communication that is conspicuously marked or otherwise
              designated in writing by the copyright owner as "Not a Contribution."
        
              "Contributor" shall mean Licensor and any individual or Legal Entity
              on behalf of whom a Contribution has been received by Licensor and
              subsequently incorporated within the Work.
        
           2. Grant of Copyright License. Subject to the terms and conditions of
              this License, each Contributor hereby grants to You a perpetual,
              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
              copyright license to reproduce, prepare Derivative Works of,
              publicly display, publicly perform, sublicense, and distribute the
              Work and such Derivative Works in Source or Object form.
        
           3. Grant of Patent License. Subject to the terms and conditions of
              this License, each Contributor hereby grants to You a perpetual,
              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
              (except as stated in this section) patent license to make, have made,
              use, offer to sell, sell, import, and otherwise transfer the Work,
              where such license applies only to those patent claims licensable
              by such Contributor that are necessarily infringed by their
              Contribution(s) alone or by combination of their Contribution(s)
              with the Work to which such Contribution(s) was submitted. If You
              institute patent litigation against any entity (including a
              cross-claim or counterclaim in a lawsuit) alleging that the Work
              or a Contribution incorporated within the Work constitutes direct
              or contributory patent infringement, then any patent licenses
              granted to You under this License for that Work shall terminate
              as of the date such litigation is filed.
        
           4. Redistribution. You may reproduce and distribute copies of the
              Work or Derivative Works thereof in any medium, with or without
              modifications, and in Source or Object form, provided that You
              meet the following conditions:
        
              (a) You must give any other recipients of the Work or
                  Derivative Works a copy of this License; and
        
              (b) You must cause any modified files to carry prominent notices
                  stating that You changed the files; and
        
              (c) You must retain, in the Source form of any Derivative Works
                  that You distribute, all copyright, patent, trademark, and
                  attribution notices from the Source form of the Work,
                  excluding those notices that do not pertain to any part of
                  the Derivative Works; and
        
              (d) If the Work includes a "NOTICE" text file as part of its
                  distribution, then any Derivative Works that You distribute must
                  include a readable copy of the attribution notices contained
                  within such NOTICE file, excluding those notices that do not
                  pertain to any part of the Derivative Works, in at least one
                  of the following places: within a NOTICE text file distributed
                  as part of the Derivative Works; within the Source form or
                  documentation, if provided along with the Derivative Works; or,
                  within a display generated by the Derivative Works, if and
                  wherever such third-party notices normally appear. The contents
                  of the NOTICE file are for informational purposes only and
                  do not modify the License. You may add Your own attribution
                  notices within Derivative Works that You distribute, alongside
                  or as an addendum to the NOTICE text from the Work, provided
                  that such additional attribution notices cannot be construed
                  as modifying the License.
        
              You may add Your own copyright statement to Your modifications and
              may provide additional or different license terms and conditions
              for use, reproduction, or distribution of Your modifications, or
              for any such Derivative Works as a whole, provided Your use,
              reproduction, and distribution of the Work otherwise complies with
              the conditions stated in this License.
        
           5. Submission of Contributions. Unless You explicitly state otherwise,
              any Contribution intentionally submitted for inclusion in the Work
              by You to the Licensor shall be under the terms and conditions of
              this License, without any additional terms or conditions.
              Notwithstanding the above, nothing herein shall supersede or modify
              the terms of any separate license agreement you may have executed
              with Licensor regarding such Contributions.
        
           6. Trademarks. This License does not grant permission to use the trade
              names, trademarks, service marks, or product names of the Licensor,
              except as required for reasonable and customary use in describing the
              origin of the Work and reproducing the content of the NOTICE file.
        
           7. Disclaimer of Warranty. Unless required by applicable law or
              agreed to in writing, Licensor provides the Work (and each
              Contributor provides its Contributions) on an "AS IS" BASIS,
              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
              implied, including, without limitation, any warranties or conditions
              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
              PARTICULAR PURPOSE. You are solely responsible for determining the
              appropriateness of using or redistributing the Work and assume any
              risks associated with Your exercise of permissions under this License.
        
           8. Limitation of Liability. In no event and under no legal theory,
              whether in tort (including negligence), contract, or otherwise,
              unless required by applicable law (such as deliberate and grossly
              negligent acts) or agreed to in writing, shall any Contributor be
              liable to You for damages, including any direct, indirect, special,
              incidental, or consequential damages of any character arising as a
              result of this License or out of the use or inability to use the
              Work (including but not limited to damages for loss of goodwill,
              work stoppage, computer failure or malfunction, or any and all
              other commercial damages or losses), even if such Contributor
              has been advised of the possibility of such damages.
        
           9. Accepting Warranty or Additional Liability. While redistributing
              the Work or Derivative Works thereof, You may choose to offer,
              and charge a fee for, acceptance of support, warranty, indemnity,
              or other liability obligations and/or rights consistent with this
              License. However, in accepting such obligations, You may act only
              on Your own behalf and on Your sole responsibility, not on behalf
              of any other Contributor, and only if You agree to indemnify,
              defend, and hold each Contributor harmless for any liability
              incurred by, or claims asserted against, such Contributor by reason
              of your accepting any such warranty or additional liability.
        
           END OF TERMS AND CONDITIONS
        
           APPENDIX: How to apply the Apache License to your work.
        
              To apply the Apache License to your work, attach the following
              boilerplate notice, with the fields enclosed by brackets "[]"
              replaced with your own identifying information. (Don't include
              the brackets!)  The text should be enclosed in the appropriate
              comment syntax for the file format. We also recommend that a
              file or class name and description of purpose be included on the
              same "printed page" as the copyright notice for easier
              identification within third-party archives.
        
           Copyright [yyyy] [name of copyright owner]
        
           Licensed under the Apache License, Version 2.0 (the "License");
           you may not use this file except in compliance with the License.
           You may obtain a copy of the License at
        
               http://www.apache.org/licenses/LICENSE-2.0
        
           Unless required by applicable law or agreed to in writing, software
           distributed under the License is distributed on an "AS IS" BASIS,
           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
           See the License for the specific language governing permissions and
           limitations under the License.
        
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: jsonschema; extra == "dev"
Requires-Dist: setuptools>=61; extra == "dev"
Dynamic: license-file

# TCW — Taxonomy · Capabilities · Work

TCW keeps three things about a software project inside the repository, next to
the code: what the project deals with, what a user can do with it, and what is
being changed. One command-line tool, `tcw`, and an agent plugin for Claude Code,
Codex, and Pi keep all three in step with the code.

| Component        | Answers                                                 |
| ---------------- | ------------------------------------------------------- |
| **Taxonomy**     | What things does this project deal with?                |
| **Capabilities** | What can a user do with those things?                   |
| **Work**         | What are we changing, and where does each change stand? |

## Contents

- [Problem Statement](#problem-statement)
- [Installation](#installation)
    - [Plugin](#plugin)
    - [CLI](#cli)
    - [Cloud Environment Instructions](#cloud-environment-instructions)
- [Overview](#overview)
- [Why taxonomy and capabilities live in the repository](#why-taxonomy-and-capabilities-live-in-the-repository)
- [Taxonomy](#taxonomy)
    - [Overview](#overview-1)
    - [Usage](#usage)
- [Capabilities](#capabilities)
    - [Overview](#overview-2)
    - [Usage](#usage-1)
- [Work](#work)
    - [Overview](#overview-3)
    - [Two backends, one model](#two-backends-one-model)
    - [Relationship to Capabilities and Taxonomy](#relationship-to-capabilities-and-taxonomy)
    - [Stages](#stages)
    - [Moving an item](#moving-an-item)
    - [Usage](#usage-2)
- [Skills and Agents](#skills-and-agents)
- [TCW Local Web App](#tcw-local-web-app)
- [Documentation](#documentation)
- [Development](#development)
    - [Setting up](#setting-up)
    - [Running the tests](#running-the-tests)
    - [How work is tracked here](#how-work-is-tracked-here)
    - [Measuring the skill layer](#measuring-the-skill-layer)
    - [Releasing](#releasing)
    - [Reporting problems](#reporting-problems)
    - [License](#license)
- [Further Reading](#further-reading)

## Problem Statement

Ask three people at a company with twenty repositories what one of those
repositories does, what a user can do with it, and what is being changed in it
right now. You get three different answers, assembled from four different places:
a ticket tracker that knows about work but not about the product, a wiki whose
glossary was last edited two years ago, a `FOLLOWUPS.md` that only grows, and
design documents that stopped matching the code some time back.

None of those places is wrong on purpose. They drift because none of them sits
next to the code, and nothing makes them move when the code moves.

TCW puts all three in the repository. One commit carries a code change and the
description of what it changed, and a reviewer sees both in the same diff.

## Installation

### Plugin

In **Claude Code**:

```
/plugin marketplace add brocef/TCW
/plugin install tcw
```

Or, in the Claude **web app** or **desktop app**, open the plugin directory, add
`brocef/TCW` as a marketplace, and install `tcw` from it — no terminal needed.

**Then start a new session.** The plugin installs the `tcw` CLI at session start
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 **`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**:

```bash
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 **`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.

In **Pi**:

```bash
pi install git:github.com/brocef/TCW
```

Add `-l` to install for the current project instead of your personal settings.
For a development checkout, use `pi install /absolute/path/to/TCW`.
Start a new Pi session, then run `/skill:setup` to install or check the `tcw`
CLI. You can also install it yourself with `pipx install tcw-cli`.
Invoke skills with `/skill:work`, `/skill:capabilities`, or `/skill:taxonomy`.

Pi loads the same skills through the official `pi` declaration in `package.json`.
It does not run TCW's Claude session-start hook or shell injections; the skills
provide explicit commands for setup, version checks, and lifecycle instructions.
Claude's custom review agents are not installed as Pi agents. When delegation
is unavailable, run ordinary lifecycle stages in the main session; autonomous
work still requires the advisors named by that workflow.
Git installation also installs the repository's Node.js package dependencies,
which support the TCW web app; local-path installation uses the checkout directly.

The plugin ships the skills and Claude Code read-only review agents described in
[Skills and Agents](#skills-and-agents).

### CLI

```sh
pipx install tcw-cli
```

Use this when you want the CLI without an agent harness at all. The PyPI package
is named **`tcw-cli`** because `tcw` was taken by an unrelated project; the
command it installs is still `tcw`.

Requires **Python ≥ 3.11** (its only runtime dependency is PyYAML); every
command, `tcw serve` included, runs on Python alone. Released wheels carry the
prebuilt web assets, so there is no frontend build step and no network needed
after install.

### Cloud Environment Instructions

A cloud agent session — Claude Code on the web, a Codex cloud task, a CI job —
starts from a clean image and is thrown away when it ends, so a `tcw` you install
by hand is gone by the next one. Install it as part of the environment's own
setup, and every session gets it without anyone remembering to.

**Claude Code on the web.** Add a script to your repository:

```sh
#!/usr/bin/env bash
# Make `tcw` available in a disposable agent container.
# Exit 0 on every path — a session must start even when this cannot finish.
set -u

command -v tcw >/dev/null 2>&1 && exit 0

# pipx where it exists; otherwise install into the container's own interpreter.
# That is the right answer *here* and nowhere else: the container is disposable
# and single-purpose, so there is no user environment to damage.
if command -v pipx >/dev/null 2>&1; then
    pipx install tcw-cli >/dev/null 2>&1 || echo "tcw: pipx install tcw-cli failed"
elif ! python3 -m pip install tcw-cli >/dev/null 2>&1 &&
    ! python3 -m pip install tcw-cli --break-system-packages >/dev/null 2>&1; then
    echo "tcw: pip install tcw-cli failed — the tcw CLI is not available."
fi

# An install that landed outside PATH is installed and unusable. $CLAUDE_ENV_FILE
# is the harness's own channel for repairing that.
if ! command -v tcw >/dev/null 2>&1 && [ -n "${CLAUDE_ENV_FILE:-}" ]; then
    userbin="$(python3 -m site --user-base 2>/dev/null)/bin"
    [ -x "$userbin/tcw" ] && echo "export PATH=\"$userbin:\$PATH\"" >>"$CLAUDE_ENV_FILE"
fi

exit 0
```

Then wire it to `SessionStart` in your repository's `.claude/settings.json`:

```json
{
    "hooks": {
        "SessionStart": [
            {
                "hooks": [
                    {
                        "type": "command",
                        "command": "\"${CLAUDE_PROJECT_DIR}\"/scripts/tcw_session_setup.sh"
                    }
                ]
            }
        ]
    }
}
```

Three things make the difference between a hook that helps and one that wastes a
session:

- **Exit 0 on every path, and print only on failure.** A hook that fails the
  session start over a missing CLI has cost more than the CLI was worth.
- **Print to stdout.** Claude Code adds a `SessionStart` hook's stdout to the
  agent's context, where it will be read; stderr becomes a transcript notice
  nobody sees.
- **Check for `tcw` first.** The hook runs every session, including the ones
  where a previous install is still there.

**Codex cloud.** A Codex cloud environment does not read a hook from your
repository. Its install steps go in the environment's **setup script**, which you
set in the environment's settings. Two things differ from Claude Code:

- **The setup script has internet access; the agent does not, by default.**
  Install `tcw` in the setup script, not by asking the agent to do it later.
- **The setup script runs in its own shell**, so an `export` there never reaches
  the agent. Repair `PATH` by writing to `~/.bashrc` instead.

```sh
if ! command -v tcw >/dev/null 2>&1; then
    if command -v pipx >/dev/null 2>&1; then
        pipx install tcw-cli
    else
        python3 -m pip install tcw-cli || python3 -m pip install tcw-cli --break-system-packages
    fi
fi

# An install that landed outside PATH: make the agent's shell find it.
userbin="$(python3 -m site --user-base 2>/dev/null)/bin"
if ! command -v tcw >/dev/null 2>&1 && [ -x "$userbin/tcw" ]; then
    echo "export PATH=\"$userbin:\$PATH\"" >>~/.bashrc
fi
```

**If your work store lives in another repository**, the container holds only the
repository it cloned, so its work items are declared but absent. Run `tcw provision`
after the install — it obtains what the checkout does not have, and does nothing
on a machine that already holds it. See
[Working across repositories](docs/guide/multi-repo.md).

Installing the **plugin** in a Claude Code session is a separate step from
installing the CLI, and only needed where the harness does not carry your plugins
in: append `claude plugin marketplace add brocef/TCW` and
`claude plugin install tcw@tcw` to the same script, guarded on `command -v claude`.

## Overview

TCW describes a project along three axes. **Taxonomy** is the project's
vocabulary and its features. **Capabilities** are the things a user can do,
each with a status. **Work** is the set of changes being made, each moving through
a series of stages. The three link by one-directional pointers: a capability
names the taxonomy entries it involves, and a work item names the capabilities
it changes. None of them copies another's content.

Taxonomy and capabilities are plain files in the repository, so a code change
and the description of what it changed travel in the same commit and the same
pull request. A work item is a **folder that never moves**: its stage is a
property recorded about it (a value, not a location), and its documents stay in
the same folder from the first stage to the last. Each item is addressed by its
**slug**, `project/folder`, such as `my-app/2026-09-15-export-invoices-as-pdf`.

**One command-line tool, `tcw`**, does everything:

| Command                   | What it does                                                                  |
| ------------------------- | ----------------------------------------------------------------------------- |
| `tcw init`                | marks a folder as a TCW project and creates the folders for each axis         |
| `tcw provision`           | obtains the stores and projects this project declares but this machine lacks |
| `tcw validate [--remote]` | checks every file, reference and link in the project; in a Jira-mode project the item references, stages and declared record changes are checked only with `--remote`, which also checks the Jira workflow |
| `tcw projects list`       | lists this project and every project connected to it                          |
| `tcw config show`         | prints the configuration commands run with; `--origin` says where each value came from |
| `tcw serve`               | starts a local web app for reading and editing all three axes                 |
| `tcw taxonomy`            | the vocabulary and features                                                   |
| `tcw capabilities`        | what a user can do                                                            |
| `tcw work`                | the changes, and the stages each one moves through                            |

A repository adopts TCW with one command:

```sh
tcw init --id my-project                # all three axes
tcw init --id my-project taxonomy work  # …or only some of them
```

That writes a `tcw-config.yaml` holding the project's ID and creates the folders
under `docs/`. A project can adopt the work axis alone and add the others later.
`tcw validate` exits non-zero on any error, so it works as a check in CI. What
every command prints, and its exit codes, are in
[the command-line guide](docs/guide/cli.md).

**The CLI enforces the rules; the agent plugin supplies the judgment.** Which
stage moves are allowed, references that must resolve, and the checks before an
item can be completed are enforced by `tcw` itself. Deciding what a request
means, writing a spec, or judging whether work is finished is what the plugin's
skills guide an agent through. See [Skills and Agents](#skills-and-agents).

**Many repositories, one model.** Projects are identified by ID, never by path.
A project lists the projects it is connected to under `projects` in its
`tcw-config.yaml`, as its `parent`, its `children`, or an `upstream` it reads.
It can inherit their taxonomy and capabilities, and address their work items as
`<project-id>/<folder>`. A parent and child each declare the other; an
`upstream` connection is declared only by the reader and is read-only from its
side, so a private project can read a public one that never names it. A
checkout holding only some of the connected repositories still works: a command
that needs an absent project says so and names `tcw provision`. See
[Working across repositories](docs/guide/multi-repo.md).

## Why taxonomy and capabilities live in the repository

The product's description, its vocabulary, its features and what its users can
do, changes in the same commit as the code that changes it. A reviewer sees both
in one diff, and the `implement` stage is where the description is changed, by
whoever writes the code.

Because the description is files in the repository, any commit shows the
product as it was at that moment. Anyone can read it, with nothing more than a
file viewer, at any point in the project's history.

That also means documentation could be generated from the records: for example,
a knowledge base that updates with every change and lets a reader pick any
point in time to see the product as it was then. TCW does not do this today; the
records are kept in a form that would allow it.

Tickets describe changes, and are short-lived; the records describe the product,
and last. So the records are never stored in Jira, whichever backend a project
uses for its work items.

## Taxonomy

### Overview

A taxonomy entry has one of two kinds. **Vocabulary** entries are the project's
basic language: `Invoice`, `Customer`, `Permission`. **Feature** entries are the
user- or application-facing parts that operate on that vocabulary, and each names
the vocabulary entries it involves. A feature can only name vocabulary that
already exists, so vocabulary is registered first.

Entries form a tree, and an entry's path is its address: `admin/permission` and
`billing/permission` are two different entries.

A project can **inherit** another project's taxonomy. Inherited entries keep the
other project's ID as a prefix, so an inherited `acme/permission` never quietly
becomes your own `permission`.

### Usage

#### Skills

| 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 `setup` skill
described in [Skills and Agents](#skills-and-agents).

#### CLI

| Command                    | What it does                                                          |
| -------------------------- | --------------------------------------------------------------------- |
| `tcw taxonomy list`        | prints every entry's path                                             |
| `tcw taxonomy add`         | creates a vocabulary entry or a feature; its description from standard input |
| `tcw taxonomy show`        | prints one entry                                                      |
| `tcw taxonomy path`        | prints the folder the taxonomy is stored in                           |
| `tcw taxonomy rm`          | removes a local entry nothing is nested under or refers to            |
| `tcw taxonomy search`      | searches entry names and descriptions                                 |
| `tcw taxonomy extends add` | inherits a connected project's taxonomy (`extends rm` stops)          |

Creating the taxonomy's folder is `tcw init taxonomy`, and checking it is
`tcw validate`.

```sh
echo "A bill issued to a customer." | tcw taxonomy add Invoice   # vocabulary by default
echo "Running the shop." | tcw taxonomy add Admin
tcw taxonomy add Permission --parent admin                       # → admin/permission
tcw taxonomy add "PDF Export" --kind feature --vocab invoice
tcw taxonomy list
tcw taxonomy extends add acme-shared                             # inherit another project
```

More in [Taxonomy and Capabilities](docs/guide/taxonomy-and-capabilities.md).

## Capabilities

### Overview

A capability is one thing a user can do, such as "Download an invoice as PDF".
Each is addressed by a path (`billing/invoices`), gets a stable ID when created,
and carries a **status**: `Supported`, `Partial`, `Missing`, `Blocked` or
`Omitted`. The status is what makes the list useful: it says what the product
actually does today. The `implement` stage changes the record in the same change
as the code, and `Missing` means a gap the team has acknowledged, never a plan.

Capabilities can be **inherited** from another project. A web frontend and a
mobile app that drive the same server declare their shared capabilities once, and
each **overrides** only what differs, for example marking one `Omitted` or adding
to its description. An override can be undone to go back to the inherited
version.

#### Relationship to Taxonomy

A capability points at taxonomy, never the other way. Its `Subject` field names
the vocabulary entries it involves (any number of them), and its `Feature` field
names the taxonomy feature that delivers it. TCW checks that both resolve, and
refuses to save a capability whose references do not, so a feature is
registered in the taxonomy before a capability names it.

### Usage

#### Skills

| Skill                                          | What it does                                                                                                                                                  |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`capabilities`](skills/capabilities/SKILL.md) | Guides an agent through a work item that changes what users can do: declaring the change at spec, checking it against the existing capabilities, and changing the records during implement. |

#### CLI

| Command                        | What it does                                                                     |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `tcw capabilities list`        | prints every capability's path; `--status` and `--local` narrow it               |
| `tcw capabilities show`        | prints one capability                                                            |
| `tcw capabilities path`        | prints the folder capabilities are stored in                                     |
| `tcw capabilities add`         | creates a capability; its body from standard input                               |
| `tcw capabilities set`         | changes a capability's status or fields; on an inherited one, writes an override |
| `tcw capabilities reset`       | removes a local override, going back to the inherited version                    |
| `tcw capabilities rm`          | removes a local capability                                                       |
| `tcw capabilities search`      | searches names and descriptions                                                  |
| `tcw capabilities extends add` | inherits a connected project's capabilities (`extends rm` stops)                 |
| `tcw capabilities drift`       | reports inherited capabilities nobody here has ruled on, and changes finished work declared that today's records do not show |

Creating the ledger's folder is `tcw init capabilities`, and checking it is
`tcw validate`.

```sh
tcw capabilities add billing/invoices "Download an invoice as PDF" < invoices.md
tcw capabilities set billing/invoices --field "Subject=invoice" --field "Feature=pdf-export"
tcw capabilities list --status Missing
tcw capabilities set billing/invoices --status Supported
tcw capabilities extends add web-frontend                 # inherit another project
```

More in [Taxonomy and Capabilities](docs/guide/taxonomy-and-capabilities.md).

## Work

### Overview

The work axis tracks every change being made to the project: new product
behavior, changes to its internals, or changes to how the project itself runs.

- **A work item is a folder that never moves.** It is created in the work store
  (`docs/work/` unless the project says otherwise) and stays there. Inside it is
  one folder for each stage that produces something: `spec/spec.md`,
  `implement/round-1.md`, and so on.
- **Every item has the same properties**: title, stage, priority, effort,
  complexity, tags, assignee, parent and blocked-by. Tags come from a list the
  project registers (`tcw work tags`), so a typo never quietly creates a new tag.
- **An item with children is an epic.** A child names its parent; `tcw work show`
  lists an item's children, and what blocks it and what it blocks.
- **TCW never changes git state.** It writes an item's files and leaves
  committing, pulling and pushing to you; a project that wants each move
  committed adds that itself, as
  [the configuration guide's example](docs/guide/configuration.md#example-keeping-git-in-step-with-each-stage-change-something-your-project-adds)
  shows.

The full reference is [The Work component](docs/guide/work.md).

### Two backends, one model

A project keeps its work items with one of two **backends**, chosen by
`work.backend` in `tcw-config.yaml`. The model is the same in both: the same
stages, the same properties, the same item folders and the same commands. What
differs is where each fact is kept.

| Fact                                         | Filesystem                     | Jira                            |
| -------------------------------------------- | ------------------------------ | ------------------------------- |
| the request                                  | `request/request.md`           | the ticket's description        |
| the stage                                    | `item.yaml`                    | the ticket's status             |
| assignee, priority, effort, complexity, tags | `item.yaml`                    | the ticket's fields and labels  |
| parent and blocked-by                        | `item.yaml`                    | the ticket's parent and links   |
| comments                                     | `comments/` in the item folder | the ticket's comments           |
| spec, plan, rounds, handoffs                 | the item folder                | the item folder                 |
| the records it changes, `capabilities.yaml`  | the item folder                | the item folder                 |
| taxonomy and capabilities                    | the repository                 | the repository                  |

#### Filesystem: everything in the repository

With the **filesystem** backend, the default, everything about an item is a file
in your repository: its properties in `item.yaml`, its request in
`request/request.md`, each comment in `comments/`, and its documents in its
stage folders. No other service is involved, and anything you can do to a file
(review it, diff it, grep it) you can do to your work items. See
[The Work component](docs/guide/work.md).

#### Jira: what people read in Jira, the technical record in the repository

With the **Jira** backend, Jira owns everything a person outside engineering
reads or changes: the request, the status, the assignee, the estimates, the
labels and the links. The repository owns the technical record: specs, plans,
rounds and handoffs, kept in a folder per item named after the ticket's key.
Nothing is copied between the two. See [Using TCW with Jira](docs/guide/jira.md).

### Relationship to Capabilities and Taxonomy

A change to the product is followed from the first request to the records:

1. The **request** states the product changes in plain prose.
2. The item's **`capabilities.yaml`**, written at `spec`, declares them formally:
   the capability and taxonomy paths it adds, changes and removes.
3. **`implement`** changes the records, in the same change as the code.
4. The **records gate**, on any move into the stage after `implement`, checks
   that the records match the declaration.
5. **`qa`** checks the product's behavior against the request.

In filesystem mode, the agent working `qa` may record the verdict itself, unless
the project's own instructions for `qa` ask for a person to decide. When they
do, the agent still writes the round, recording the person's decision. In Jira
mode, a person accepts or rejects on the ticket.

Work reaches taxonomy through those capabilities: a new capability names the
vocabulary and feature it involves, and those entries must exist first.

### Stages

```mermaid
%%{init: {"themeVariables": {"edgeLabelBackground": "#b45309", "textColor": "#ffffff"}}}%%
flowchart LR
    inbox("inbox"):::stage
    request("request"):::stage
    spec("spec"):::optional
    plan("plan"):::optional
    implement("implement"):::stage
    review("review"):::optional
    qa("qa"):::optional
    completed("completed"):::terminal
    discarded("discarded"):::terminal
    postmortem(["postmortem<br/><i>worked alongside, never moved into</i>"]):::side

    inbox --> request --> spec --> plan --> implement --> review --> qa --> completed
    review -.->|rejected| implement
    qa -.->|rejected| implement
    completed -.- postmortem

    classDef stage fill:#1d4ed8,stroke:#93c5fd,stroke-width:2px,color:#ffffff
    classDef optional fill:#1d4ed8,stroke:#93c5fd,stroke-width:2px,stroke-dasharray:5 4,color:#ffffff
    classDef terminal fill:#1d4ed8,stroke:#93c5fd,stroke-width:4px,color:#ffffff
    classDef side fill:#6b7280,stroke:#d1d5db,stroke-width:2px,stroke-dasharray:5 4,color:#ffffff
    linkStyle default stroke:#d97706,stroke-width:2px
```

Dashed boxes are stages a project can turn off; an item then moves straight
past them. Any item can be moved to `discarded`, with a reason.

| Stage        | Purpose                                                    | Writes                                    | Can be turned off |
| ------------ | ---------------------------------------------------------- | ----------------------------------------- | ----------------- |
| `inbox`      | a raw request waits to be taken on                         | nothing                                   | no                |
| `request`    | what is asked for, and why                                 | `request/request.md` (Jira: the ticket)    | no                |
| `spec`       | what to build, with acceptance criteria                    | `spec/spec.md`, and `capabilities.yaml`   | yes               |
| `plan`       | how to build it, as ordered tasks                          | `plan/plan.md`                            | yes               |
| `implement`  | build it, and change the records                           | `implement/round-N.md`, one per attempt   | no                |
| `review`     | check the change against the spec and plan                 | `review/round-N.md`, each with a verdict  | yes               |
| `qa`         | check the product's behavior against the request           | `qa/round-N.md` (Jira: the ticket)        | yes               |
| `completed`  | finished work                                              | nothing                                   | no                |
| `discarded`  | abandoned work, with the reason                            | nothing                                   | no                |
| `postmortem` | for a finished item: which stage could first have caught a problem | `postmortem/postmortem.md`        | yes               |

A project attaches its own text to a stage's instructions, its own checks before
an item moves into a stage, and its own commands after; see
[Configuration](docs/guide/configuration.md). `tcw work lifecycle` prints the
stages with whatever the project has attached.

### Moving an item

One command moves an item: **`tcw work advance <slug>`**, to the next stage that
is turned on. From `review` or `qa`, the next stage follows the verdict: accepted
goes forward, rejected goes back to `implement`.

- `--to <stage>` names the target. Going back needs no `--force`; going
  forward past a stage that is turned on is a skip, and needs `--force`.
  Reopening a `completed` or `discarded` item needs a `--reason`, and so does
  leaving `qa` in a Jira-mode project.
- `--force --reason "<why>"` moves the item even when a check refuses, and
  records the reason, and what it was forced past, as a comment on the item.
- `--dry-run` says where the item would go, and moves nothing.
- `tcw work discard <slug> --reason "<why>"` abandons an item, from any stage.
- **Gates** are checks that must pass first: TCW's own records gate (into the
  stage after `implement`) and completion gate (into `completed`), and a
  project's own `pre` hooks. A failing gate refuses the move and changes
  nothing.
- After the move, the target stage's **`post` hooks** run. If one fails, the move
  stands and `advance` exits with code 6.

The details are in [The Work component](docs/guide/work.md#moving-an-item).

### Usage

#### Skills

| Skill                                        | What it does                                                                                                                                                                       |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`work`](skills/work/SKILL.md)               | Guides an agent through every stage of an item: deciding on an inbox arrival, writing the request, spec and plan, implementing, reviewing and testing, splitting large items, and filing work into another project. |
| [`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 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, processing the inbox) described in
[Skills and Agents](#skills-and-agents).

#### CLI

**Items**

| Command            | What it does                                                    |
| ------------------ | --------------------------------------------------------------- |
| `tcw work new`     | creates an item and prints its slug; its request from standard input; `--project` creates it in another project |
| `tcw work list`    | prints the slugs of unfinished items; `--all` adds finished ones |
| `tcw work show`    | prints an item's properties, its request and its comments       |
| `tcw work path`    | prints the work store's folder, an item's folder, or where a stage's file goes |
| `tcw work edit`    | changes an item's properties                                    |
| `tcw work comment` | adds a comment, from standard input                             |
| `tcw work rename`  | renames an item's folder                                        |
| `tcw work tags`    | lists, adds or removes the project's registered tags            |

**Moving items**

| Command            | What it does                                            |
| ------------------ | ------------------------------------------------------- |
| `tcw work advance` | moves an item to its next stage, or to the one `--to` names |
| `tcw work discard` | abandons an item, with a reason                         |

**Stage instructions**

| Command                  | What it does                                                                                               |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `tcw work stage prompt`  | prints a stage's instructions, with this project's own text, for one item                                  |
| `tcw work lifecycle`     | prints every stage, whether it is turned on, and what this project attaches to it                          |
| `tcw work procedure`     | prints one of TCW's procedures, such as `unattended-work` or `search`, with this project's own text for it |
| `tcw work docs`          | prints the project's documentation entries: which documents a change must keep up to date                  |

**Jira**

| Command                 | What it does                                  |
| ----------------------- | --------------------------------------------- |
| `tcw work tickets list` | prints the Jira tickets waiting to become items |
| `tcw work tickets adopt` | makes a Jira ticket an item                  |

A session with the **filesystem** backend:

```sh
tcw work new "Export invoices as PDF" < request.md     # → my-app/2026-09-15-export-invoices-as-pdf
tcw work stage prompt spec 2026-09-15-export-invoices-as-pdf
tcw work advance 2026-09-15-export-invoices-as-pdf     # request → spec
tcw work list --stage implement
tcw work advance 2026-09-15-export-invoices-as-pdf --dry-run   # says where it would go
```

A session with the **Jira** backend:

```sh
tcw work tickets list                                   # SHOP-42
tcw work tickets adopt SHOP-42                          # → shop/SHOP-42-export-invoices-as-pdf
tcw work advance SHOP-42                                # request → spec; the ticket moves to the status set for spec
tcw work show SHOP-42
```

Every command has `--help`, and the full reference is
[The Work component](docs/guide/work.md).

## Skills and Agents

The CLI enforces the rules: which moves are allowed, which references must
resolve, what has to be true before an item completes. What a command cannot
decide (what a request really asks for, whether a spec is good enough, whether
the work is finished) is judgment, and the plugin's skills guide an agent through
it. Skills name `tcw` commands and never reimplement them, and the instructions
for each stage come from `tcw work stage prompt`, so they work the same way under
Claude Code, Codex, and Pi.

The skills for a single axis are listed in that axis's section above. These cut
across the axes.

**Setting up and configuring**

| Skill                                                      | What it does                                                                                                                                                                                  |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`setup`](skills/setup/SKILL.md)                           | Gets TCW working: installs or repairs the CLI, starts using TCW in a repository, connects a project to Jira, 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: which stages it uses, the text and commands bound to each, the Jira backend, documentation entries, where stores live, connected and inherited projects, and personal configuration. |
| [`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.                                       |

**Command skills: the everyday workflows**

| Skill                                                                                    | What it does                                                                                                                     |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [`commands-process-inbox`](skills/commands-process-inbox/SKILL.md)                       | Decides on every arrival in the work inbox, then writes the request for each one taken on.                                       |
| [`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 implement, review and qa, to completed where the agent may record the qa verdict, or to qa for a person where it may not. |
| [`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                                                                                                                                                                       |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`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 a read-only 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.** Two read-only agents ship with the plugin. Neither edits a file or
moves an item; each reports back to the session that started it.

| Agent             | What it does                                                                                                                                                         |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reviewer`        | For the `review` stage: reads an item's change against its spec, plan and `capabilities.yaml`, runs the project's checks, and recommends a verdict criterion by criterion; the session that started it writes the round. |
| `backlog-auditor` | Checks one unfinished item against your project's audit-backlog procedure, `tcw work procedure audit-backlog`, checking the item's claims against the code.          |

## TCW Local Web App

`tcw serve` starts a local web app for reading and editing the project it is run
in, as an alternative to the command line.

```sh
tcw serve              # http://127.0.0.1:8765/, and opens a browser
tcw serve --no-open    # start without opening a browser
tcw serve --port 9000  # use a different port
```

- **One Python process.** The browser client is built ahead of time and shipped
  inside the Python package, so nothing else needs to be installed, and it works
  offline.
- **What you can read.** Tabs for the work board, the taxonomy and the
  capabilities, with filters and a text search. The address bar follows the view,
  so any page can be bookmarked or shared, and any `tcw://` reference in a
  document is a link to its target.
- **What you can change.** An item's documents, rounds and handoffs, its
  `capabilities.yaml`, its properties and comments; new work items, in this
  project or in a connected one; and taxonomy entries and capabilities, created
  and edited.
- **No stage moves.** The app shows each item's stage but never changes it, and
  names the `tcw work advance` command to run instead.
- **In Jira mode**, what Jira owns (the request, comments, stage and properties)
  is shown read-only, with **Open in Jira** to change it there, and a **Tickets**
  view lists inbox tickets and adopts them.
- **One project.** The app serves the project it was started in; an item in
  another project is shown as a labelled name.
- **Local only.** The server listens only on `127.0.0.1`, and refuses requests
  that do not name a local address, which blocks other websites from making
  changes through your browser. Two people editing the same file cannot silently
  overwrite each other.

Everything else about the app is in
[The local web viewer](docs/guide/web-viewer.md).

## Documentation

| Document                                                                          | Covers                                                                                                                                       |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [The Work component](docs/guide/work.md)                                          | Work items, their stages and folders, moving items, and every `tcw work` command, for both backends                                          |
| [Using TCW with Jira](docs/guide/jira.md)                                         | The Jira backend: who owns what, writing and following tickets, setting up, statuses, adopting tickets, QA on the ticket                     |
| [Configuration](docs/guide/configuration.md)                                      | `tcw-config.yaml`: personal configuration, stage bindings, how hooks run, documentation entries, and the opt-in git example                  |
| [The command line](docs/guide/cli.md)                                             | What every command prints on standard output and standard error, how to name an item, and the exit codes                                     |
| [Taxonomy and Capabilities](docs/guide/taxonomy-and-capabilities.md)              | Declaring vocabulary, features and capabilities, from a request to the records, drift, and inheriting both from other projects                |
| [Working across repositories](docs/guide/multi-repo.md)                           | Connecting projects, creating items in another project, keeping a store in another repository, and obtaining what a checkout does not have   |
| [Linking and validation](docs/guide/linking-and-validation.md)                    | `tcw://` references between objects, and `tcw validate` as a CI check                                                                        |
| [The local web viewer](docs/guide/web-viewer.md)                                  | Everything about `tcw serve`                                                                                                                 |
| [Configuration reference](skills/configure/SKILL.md)                              | Every configuration key, and which ones a person may override                                                                                |
| [The abstraction rules](docs/lifecycle/abstraction.md)                            | Why every operation must work for a backend that is not a filesystem, in full                                                                |
| [Release notes](docs/release-notes/)                                              | What changed for users in each version                                                                                                       |
| Migration guides                                                                  | Upgrading across a breaking release: [0.10 → 0.11](docs/migration-guide-0.10.X-to-0.11.0.md), [0.12 → 0.13](docs/migration-guide-0.12.X-to-0.13.0.md), [0.14 → 0.15](docs/migration-guide-0.14.X-to-0.15.0.md), [0.15 → 0.16](docs/migration-guide-0.15.X-to-0.16.0.md), [0.21 → 1.0](docs/migration-guide-0.21.X-to-1.0.0.md), [1.x → 2.0](docs/migration-guide-1.X-to-2.0.0.md), [2.4 → 2.5](docs/migration-guide-2.4.X-to-2.5.0.md), [2.8 → 3.0](docs/migration-guide-2.8-to-3.0.0.md) |

Every command also has `--help`.

## Development

This section is for working on TCW itself.

### Setting up

```sh
git clone https://github.com/brocef/TCW.git
cd TCW
pip install -e '.[dev]'     # or: scripts/remote_session_setup.sh --force
```

`scripts/remote_session_setup.sh` installs this checkout with its development
dependencies and installs the `tcw` plugin from the checkout. In a Claude Code
remote session it runs by itself: `.claude/settings.json` wires it to
`SessionStart`, and also enables the `tcw` plugin for this repository. It is safe
to run repeatedly and prints only when something failed. It is contributor
tooling, not the install path for users (that is `scripts/session_bootstrap.sh`,
which installs the released `tcw-cli`).

TCW does not create git worktrees. If you make one with `git worktree add`, the
editable install still runs the primary checkout's code, not the worktree's. How
to give the worktree its own environment is in
[`AGENTS.md`](AGENTS.md#working-in-a-git-worktree).

### Running the tests

```sh
pytest                  # the Python suite; what CI runs (.github/workflows/test.yml)
pnpm typecheck          # formatting check, then TypeScript
pnpm lint               # ESLint over the web app
pnpm test               # web app unit tests
pnpm test:e2e           # Playwright end-to-end tests of the web app
pnpm build              # rebuild the committed web assets
pnpm prettify           # format source and documentation
pnpm prettify:check     # check formatting without changing files
```

The `pnpm` commands need Node.js 22.12 or newer and `pnpm install` first. Python
tests build their own throwaway git repositories and never read this
repository's board.

### How work is tracked here

TCW tracks its own development with `tcw work`: every change is a work item under
`docs/work/`, and `tcw work list` shows what is in progress. The working rules for
contributors, human or agent, are in [`AGENTS.md`](AGENTS.md). This repository
adds its own instructions to three stages:
[`docs/lifecycle/abstraction.md`](docs/lifecycle/abstraction.md) at `spec` and
`plan`, [`docs/lifecycle/harness.md`](docs/lifecycle/harness.md) at `spec` and
`implement`, and [`docs/lifecycle/implementation.md`](docs/lifecycle/implementation.md)
at `implement`.

Older design history lives in [`docs/plan/`](docs/plan/) (the original designs
for each component) and [`docs/superpowers/`](docs/superpowers/); the developer
changelog for each version is in [`docs/changelogs/`](docs/changelogs/).

### Measuring the skill layer

[`evals/`](evals/) holds a harness that measures whether this project's lifecycle
instructions actually reach an agent, and what the plugin's skills add. The test
suite cannot answer that: it can prove a skill file says the right words, but not
that an agent read them. Running it starts real agent sessions and costs money;
`python -m evals.run_evals --axis a --dry-run` shows what it would run.

### Releasing

`python scripts/cut_version.py <patch|minor|major|X.Y.Z>` bumps the version in all
five files that carry it, combines the waiting changelog and release-note entries
into that version's files, commits and tags. Each change adds its entries as its
own file in `docs/changelogs/upcoming/` and `docs/release-notes/upcoming/`, named
after its work item's folder name (`<folder>.md`), so changes finished on
separate branches never edit the same file. Pushing the tag publishes the release to
PyPI. Details, including the one-time PyPI setup, are in
[`docs/releasing.md`](docs/releasing.md).

### Reporting problems

File bugs and suggestions on
[GitHub issues](https://github.com/brocef/TCW/issues). With the plugin installed,
the `extras-report` skill gives you a ready-to-fill template.

### License

Apache License 2.0; see [`LICENSE`](LICENSE).

## Further Reading

- [`AGENTS.md`](AGENTS.md): the working rules for contributing. Read it first.
- [`docs/lifecycle/abstraction.md`](docs/lifecycle/abstraction.md): the rule that
  keeps TCW's model independent of the filesystem, in full.
- [`docs/plan/`](docs/plan/): the original design documents for each component.
- `tcw work list`: what is being changed in this repository right now.
