openagents-work-management

name	openagents-work-management
description	Manage OpenAgents issues, projects, comments, labels, assignees, and milestones through the OpenAgents CLI.
allowed-tools	["read","exec","grep"]

Use this skill when the user asks you to manage OpenAgents issues, projects, comments, labels, assignees, milestones, or Projects V2 boards from the command line. Do not use the pro-work-management skill or the Pro Linear/MCP surface. This skill targets the OpenAgents /api/v1 surface through the @openagentsinc/cli package.

The CLI has named commands for most of this work: openagents issue (list, view, create, close, reopen, comment, label, assign, unassign, deps) and openagents project (list, view, create, fields, items, item-add, item-set, item-move, item-remove). Reach for those first, and run openagents <command> --help for a flag you do not know. Read their plain output; add --json only when you need one field out of one record, because a JSON list carries every issue's whole body.

Use openagents api with a hand-built route only where no named command covers what you need. Milestones and some Projects V2 routes are still in that position, and the examples below show them.

Before you start

1. Install the CLI:

   npm install --global @openagentsinc/cli@latest
   

   Or run one command with npx --yes @openagentsinc/cli@latest.
2. Sign in:

   openagents auth login
   

3. Confirm the session:

   openagents auth status
   

4. Writes require a forge:write personal access token. Create one at /settings/api-tokens and store it with openagents auth login --token-stdin, or set OPENAGENTS_TOKEN for a single process. Do not print or commit tokens.

Route addressing

A relative path for openagents api resolves under /api/v1/. For example, repos/OWNER/REPO/issues is the same as /api/v1/repos/OWNER/REPO/issues.

• Method: -X GET|POST|PATCH|PUT|DELETE.
• String fields: repeatable -f KEY=VALUE. Every value is sent as a JSON string.
• Full JSON body: --input FILE or --input - for standard input. Use this for numbers, booleans, arrays, nested objects, or null. --field and --input are mutually exclusive.
• Custom headers: -H 'NAME: VALUE'. The CLI rejects an Authorization header override.

Issues

Implemented issue routes from docs/github-api-issues-projects-assessment.md:

Resource	Methods	Path
Issues	GET, POST	repos/OWNER/REPO/issues
Issue	GET, PUT, PATCH	repos/OWNER/REPO/issues/NUMBER
Comments	GET, POST	repos/OWNER/REPO/issues/NUMBER/comments
Comment	GET, PUT, PATCH, DELETE	repos/OWNER/REPO/issues/comments/ID
Labels	GET, POST	repos/OWNER/REPO/labels
Label	GET, PUT, PATCH, DELETE	repos/OWNER/REPO/labels/NAME
Issue labels	GET, POST	repos/OWNER/REPO/issues/NUMBER/labels
Issue label	DELETE	repos/OWNER/REPO/issues/NUMBER/labels/NAME
Assignees	GET	repos/OWNER/REPO/assignees
Issue assignees	GET, POST, DELETE	repos/OWNER/REPO/issues/NUMBER/assignees
Milestones	GET, POST	repos/OWNER/REPO/milestones
Milestone	GET, PUT, PATCH, DELETE	repos/OWNER/REPO/milestones/NUMBER

List responses are wrapped: {"issues":[...]}, {"comments":[...]}, {"labels":[...]}, {"milestones":[...]}.

Create an issue:

openagents api -X POST \
  -f title="Search returns duplicates" \
  -f body="Steps to reproduce" \
  repos/OWNER/REPO/issues

Close an issue with reason:

printf '%s' '{"state":"closed","state_reason":"completed"}' | \
  openagents api -X PATCH --input - \
  repos/OWNER/REPO/issues/41

Add a comment:

openagents api -X POST -f body="The fix is available in staging." \
  repos/OWNER/REPO/issues/41/comments

Prerequisites

An issue can wait on other issues in the same repository.

Operation	Method	Path
Read the graph	GET	repos/OWNER/REPO/issues/NUMBER/dependencies
Record prerequisites	POST	repos/OWNER/REPO/issues/NUMBER/dependencies
Remove one	DELETE	repos/OWNER/REPO/issues/NUMBER/dependencies/BLOCKER_NUMBER

Record that issue 42 waits on issues 9 and 12:

printf '%s' '{"blocked_by":[9,12]}' | \
  openagents api -X POST --input - \
  repos/OWNER/REPO/issues/42/dependencies

Pick up work that nothing blocks:

openagents api "repos/OWNER/REPO/issues?state=open&blocked=false"

Every issue response also carries openagents.blocked, openagents.blocked_by, openagents.blocks, and openagents.progress. blocked is derived from the prerequisites' state, so closing the last open prerequisite unblocks the issue with no second write. An unknown number, a self reference, and an edge that would close a cycle each return 422, and none of the batch is recorded.

progress is to_do, in_progress, or done, derived the same way: a closed issue is done, and an open issue is in_progress while a project board you can read places it in a started column. Filter on it to see what is underway:

openagents api "repos/OWNER/REPO/issues?progress=in_progress"

Ask the API what OpenAgents adds to the GitHub shape instead of reading prose:

openagents api "/api/v1"

That root document enumerates every openagents field with its type, enum values, and the endpoints that filter on it. A field that is not listed there is not part of the API.

Projects

There are no named project commands. Construct every Projects V2 route manually under repos/OWNER/REPO/projectsV2.

Operation	Method	Path
List	GET	repos/OWNER/REPO/projectsV2
Create	POST	repos/OWNER/REPO/projectsV2
Read	GET	repos/OWNER/REPO/projectsV2/PROJECT_NUMBER
List items	GET	repos/OWNER/REPO/projectsV2/PROJECT_NUMBER/items
Add item	POST	repos/OWNER/REPO/projectsV2/PROJECT_NUMBER/items
Update item	PATCH	repos/OWNER/REPO/projectsV2/PROJECT_NUMBER/items/ITEM_ID
List fields	GET	repos/OWNER/REPO/projectsV2/PROJECT_NUMBER/fields
Create field	POST	repos/OWNER/REPO/projectsV2/PROJECT_NUMBER/fields

Product promises

Projects V2 can act as a product promises registry when the project has one promise_state field with LIVE, GATED, and WITHDRAWN options. Store each promise in the item's values["promise"] map and keep one canonical issue per promise. Use readable accepted_outcome evidence that names an accepted OpenAgents.Compensation.OutcomeDecision for LIVE. Issue, changelog, and forge receipt evidence remains supporting evidence; links cannot satisfy that gate.

Use promise_state and bounty_candidate filters when listing items. Read actor-attributed append-only history from the item's /events endpoint. Evidence is redacted when the reader cannot read its repository or issue.

List projects:

openagents api repos/OWNER/REPO/projectsV2

Create a project:

openagents api -X POST -f title="Release readiness" \
  repos/OWNER/REPO/projectsV2

Add a repository-local issue to a project:

printf '%s' '{"issue_number":11,"values":{"Status":"To Do"}}' | \
  openagents api -X POST --input - \
  repos/OWNER/REPO/projectsV2/PROJECT_NUMBER/items

Add an issue from another repository:

printf '%s' '{"issue":{"owner":"SOURCE_OWNER","repo":"SOURCE_REPO","number":37},"values":{"Status":"To Do"}}' | \
  openagents api -X POST --input - \
  repos/PROJECT_OWNER/PROJECT_REPO/projectsV2/PROJECT_NUMBER/items

Update an item:

printf '%s' '{"values":{"Status":"Done"}}' | \
  openagents api -X PATCH --input - \
  repos/OWNER/REPO/projectsV2/PROJECT_NUMBER/items/ITEM_ID

Rules and constraints

• Always prefer openagents api over inventing named subcommands.
• Use --json for noninteractive or script output. openagents api always returns the response body as JSON.
• Writes require a forge:write token and repository membership. Anonymous reads are allowed only on public repositories.
• Do not print or commit tokens. Use the OS credential store or OPENAGENTS_TOKEN.
• Cross-repository project items require write access to the project repository and read access to the source issue repository.
• Issue and milestone numbers are repository-local. Project numbers are also repository-local.
• For the exact request/response envelopes and current known gaps, read docs/github-api-issues-projects-assessment.md and docs/openagents-cli/api.md.