@kitsy/coop

CLI package for COOP.

Install globally:

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

Install locally in a repo:

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

For AI-oriented command discovery:

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:

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:

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:

# .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:

ai:
  provider: openai
  model: gpt-5-mini
  openai:
    api_key_env: OPENAI_API_KEY