npm package: @kitsy/coop
Description: COOP command-line interface.
Latest version: 2.3.0

# @kitsy/coop

CLI package for COOP.

Install globally:

```bash
npm i -g @kitsy/coop
coop --help
coop help-ai --format json
```

Install locally in a repo:

```bash
pnpm add -D @kitsy/coop
pnpm exec coop --help
```

For AI-oriented command discovery:

```bash
coop help-ai
coop help-ai --format json
coop help-ai --format markdown
coop help-ai --selection --format markdown
coop help-ai --state-transitions --format json
coop help-ai --artifacts --format markdown
coop help-ai --post-execution --format markdown
coop help-ai --initial-prompt --strict --repo C:/path/to/repo --delivery MVP --command coop.cmd
coop help-ai --initial-prompt --rigour balanced --repo C:/path/to/repo --delivery MVP --command coop.cmd
coop config artifacts.dir docs/agent-artifacts
```

Agent contract notes:
- `coop complete <id>` / `coop complete task <id>` requires the task to already be in `in_review`.
- `coop start <id>` / `coop start task <id>` can resume a blocked task directly into `in_progress` when the effective transition map allows `blocked -> in_progress`.
- `coop unblock <id>` / `coop unblock task <id>` always lands on `todo`; it does not restore the prior state.
- `coop workflow transitions show|set|add|remove|reset` is the primary CLI surface for workspace transition policy.
- multi-step recovery auto-hops write a transition audit artifact; direct transitions do not.
- balanced initial prompts are the recommended default for normal implementation sessions.
- if an agent is unsure about selection, transitions, artifacts, or whether it should continue, it should call the matching focused `help-ai` topic command instead of guessing.
- strict initial prompts tell agents to stop after completing the selected task instead of auto-picking another one.

On Windows PowerShell, the global npm install may resolve `coop` to `coop.ps1` first. If an agent or CI shell hits execution-policy issues, use `coop.cmd` explicitly.

Both entrypoints operate on the nearest parent `.coop/` workspace. If no workspace log target exists, CLI errors fall back to `~/.coop/logs/cli.log` or `COOP_HOME/logs/cli.log`.

COOP v2 stores project data under `.coop/projects/<project.id>/...` and keeps workspace selection in `.coop/config.yml`.

Command shape rule:
- When a command accepts an entity reference, the entity noun is optional. For example, `coop show PM-100` and `coop show task PM-100` are equivalent.
- Commands without an entity reference, such as `coop next`, remain task-first workflow surfaces.

Current implemented command families:
- `coop`
- `coop init [--name <name>] [--id <id>] [--aliases <csv>] [--naming <template>] [--yes]`
- `coop project list|create|use|show`
- `coop naming`
- `coop naming preview <title> [--template <template>]`
- `coop naming token default show|set|clear <token> [value]`
- `coop create task ...`
- `coop create task --acceptance <csv> --tests-required <csv> --authority-ref <ref> --derived-ref <ref>`
- `coop create task --from-file <path> | --stdin`
- `coop create task --from <idea> --ai`
- `coop create idea --from-file <path> | --stdin`
- `coop refine idea <id> [--apply] [--input-file <path>] [--stdin]`
- `coop refine task <id> [--apply] [--input-file <path>] [--stdin]`
- `coop apply draft --from-file <path> | --stdin`
- `coop create idea ...`
- `coop create track ...`
- `coop create delivery ... [--commit] [--user <user>] [--force]`
- `coop next [--track <track>] [--delivery <delivery>]`
- `coop pick [id] [--track <track>] [--delivery <delivery>] [--claim] [--to <assignee>]`
- `coop start [id] [--claim] [--to <assignee>]`
- `coop review|complete|block|unblock|cancel|reopen <id>`
- `coop rename <id> <alias>`
- `coop workflow transitions show|set|add|remove|reset`
- `coop assign task <id> --to <assignee> [--actor <actor>]`
- `coop list tasks|ideas|alias ...`
- `coop list tasks --completed|--todo|--blocked|--all`
- `coop show task|idea ...`
- `coop transition task ... [--user <user>] [--force]`
- `coop graph validate|next|show|critical-path ...`
- `coop index status|rebuild`
- `coop plan delivery <name>`
- `coop plan delivery <name> --monte-carlo [--iterations <n>]`
- `coop plan capacity <track>`
- `coop status [--today <date>]`
- `coop view kanban`
- `coop view timeline --delivery <name>`
- `coop view velocity [--today <date>]`
- `coop view burndown --delivery <name> [--today <date>]`
- `coop view capacity [--today <date>]`
- `coop ui [--host <host>] [--port <port>] [--no-open]`
- `coop serve [--host <host>] [--port <port>] [--repo <path>]`
- `coop webhook github [--host <host>] [--port <port>] [--repo <path>]`
- `coop migrate --dry-run --to 2`
- `coop migrate workspace-layout --to v2 [--name <name>] [--id <id>] [--aliases <csv>] [--yes]`
- `coop alias ...`
- `coop list alias [pattern]`
- `coop config index.data yaml|json`
- `coop config id.naming "<TYPE>-<TITLE16>-<SEQ>"`
- `coop config id.naming "<TYPE>-<TITLE24>"`
- `coop config project.name <name>`
- `coop config project.id <id>`
- `coop config project.aliases <csv>`
- `coop config artifacts.dir <path>`
- `coop config ai.provider mock|openai|anthropic|gemini|ollama|codex_cli|claude_cli|gemini_cli`
- `coop config ai.model <model-name>`
- `coop run task <id> [--step <step>] [--dry-run]`

Known limitations:
- `ext` is still a placeholder for future phases.
- Provider-backed AI is supported for `openai`, `anthropic`, `gemini`, and `ollama` via `.coop/projects/<project.id>/config.yml` + env vars.
- CLI-backed AI is supported for `codex_cli`, `claude_cli`, and `gemini_cli` via installed/authenticated local CLIs.
- Authorization is advisory and config-driven (`.coop/projects/<project.id>/config.yml -> authorization`).
- Plugin runtime supports manifest triggers under `.coop/projects/<project.id>/plugins/*.yml` (webhook + console + `github_pr` actions).
- `coop ui` is read-only and depends on the active project's `.index` data. The command rebuilds stale indexes before launch.
- `coop init` creates `.coop/.ignore` and `.coop/.gitignore` so logs, tmp files, and index artifacts are not committed by default.
- Semantic title-based IDs are the default. Use `coop naming` to inspect token behavior and preview IDs before changing `id.naming`.

GitHub integration quick example:
```yaml
github:
  owner: kitsy
  repo: coop
  base_branch: main
  token_env: GITHUB_TOKEN
  webhook_secret_env: GITHUB_WEBHOOK_SECRET
  merge_method: squash
```

With `.coop/projects/<project.id>/plugins/github-pr.yml` enabled:
- `coop transition task PM-101 in_review` creates or updates a PR
- `coop transition task PM-101 done` merges the linked PR
- `coop webhook github --port 8787` receives GitHub review/merge webhooks and syncs task status

API server and cross-repo dependency quick example:
```yaml
api:
  host: 127.0.0.1
  port: 3847
  remotes:
    platform-repo:
      base_url: http://127.0.0.1:3848
```

With cross-repo task references such as `external:platform-repo/PM-200`:
- `coop serve --port 3847` exposes the local read-only API
- remote dependencies resolve through the configured API base URL when reachable
- unreachable remotes are reported as external dependency risks

Workspace identity:
```yaml
# .coop/projects/<project.id>/config.yml
project:
  name: Payments Platform
  id: payments-platform
  aliases:
    - pay
    - ledger.master
```

This identity is exposed through:
- `GET /api/meta`
- MCP `coop_workspace_info`
- MCP `coop://workspace`

Provider config quick example:
```yaml
ai:
  provider: openai
  model: gpt-5-mini
  openai:
    api_key_env: OPENAI_API_KEY
```