Issue basics — the CRUD floor

Everyday issue operations over the Forge kernel. Every command here is a real forge issue verb (confirm with forge issue --help). The kernel is the single source of truth — never hand-edit the issue store.

Every --json reply is the same envelope: { ok, schema_version, command, data, next_commands } on success, or { ok:false, error:{ message, exit_code } } on failure. Gate on ok — do not parse data until you confirm ok:true.

The core loop

Create — the flags that matter

forge issue create --title "Add rate limiting" --type task \
  --priority P1 --label "feature,api,security" --assignee alice \
  --acceptance "429 returned after N req/min; covered by a test"

--status defaults to open. Status vocabulary: open · in_progress · review · done · cancelled. Unlike --priority and --status (which reject unknown values), --type is stored verbatim — a non-canonical value like feature is accepted without error but carries no kernel behaviour, so stick to the four canonical types. Epics and decisions are excluded from the ready queue (non-claimability is a queue convention, not enforcement — forge issue claim currently returns ok:true on them too).

Update — same field flags, plus close

forge issue update <id> takes --status, --title, --body/--description, --priority, --label (reparents the whole set), --parent, --assignee, --acceptance, --design, --notes. forge issue close <id> --reason "…" records the reason on the close event and accepts multiple ids in one call.

Migrating from a Beads-style tracker — verb disposition

Nothing you relied on silently disappears; a few verbs map onto a forge flag or are intentionally unsupported:

Reliability

• Check ok before trusting output. On ok:false, read error.message and fix the input rather than retrying blindly.
• Claim before you mutate shared work. forge issue claim <id> takes a DB-enforced lease; hand off to the claim-safety procedure before acting on a claimed issue you intend to change. forge issue release <id> if you abandon it.
• Record decisions as comments, not memory. forge issue comment <id> "…" survives the session; scratch notes do not.

Fork points

Editable conventions — set these once for your team and this skill enforces them. It is a canonical source you fork, not a fixed policy.