@sjawhar/pi-legion-envoy 0.1.0

package/dist/skills/AGENTS.md

@@ -0,0 +1,37 @@
+# Skills Layer
+
+Legion skills guide the architect and its sequential phase workers in a shared issue workspace.
+They are Markdown instructions loaded by Oh My Pi sessions; the daemon and OMP extension own
+event intake, process lifecycle, credentials, and role delivery.
+
+## Structure
+
+```
+skills/
+├── github/              # GitHub issue and pull-request operations
+├── linear/              # Linear adapter instructions
+├── legion-architect/    # Tree ownership, decomposition, gates, and scheduling
+├── legion-controller/   # Derived-verdict control-plane operation
+├── legion-oracle/       # Repository-grounded research
+├── legion-retro/        # Post-review retrospective
+└── legion-worker/       # Sequential architect, plan, implement, test, and review phases
+```
+
+## Phase workers
+
+The extension supplies a phase worker with its issue, workspace, role token, and structured
+output schema. The worker claims its supplied role, works only on its phase artifact, and
+returns that schema to the architect. It writes the same phase-specific payload to
+`.legion/<phase>.json`, verifies it exists, and commits the handoff before reporting completion.
+The committed predecessor handoff wins after revival or re-creation.
+
+Workers do not run a controller loop, mutate lifecycle labels, or create human dispatch threads.
+When an issue needs a product, scope, cross-phase, or human decision, they send the owning
+architect the verified observation and decision needed through hub.
+
+## Durable artifacts
+
+Phase handoffs are committed in lifecycle order: architect, plan, implement, test, and review.
+The reviewer removes `.legion/` as its final commit; retro records its learning in
+`docs/solutions/` and writes no handoff. GitHub comments and reviews carry the required Legion
+footer so the daemon can attribute artifacts to their worker session.

package/dist/skills/envoy/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: envoy
+description: Use when subscribing sessions to Envoy topics, sending agent-to-agent messages, or reasoning about topic formats for Slack/GitHub/agent routing.
+---
+
+# Envoy
+
+Envoy is Legion's event-routing subsystem. It delivers Slack, GitHub, and agent-to-agent events to OpenCode sessions.
+
+## What the tools do
+
+- `envoy_subscribe(topics)` — make the current session RECEIVE future events on those topics
+- `envoy_unsubscribe(topics?)` — stop receiving some or all topics
+- `envoy_list()` — show the union of live local and persisted registry subscriptions, with each topic marked `live`, `registry`, or `both`
+- `envoy_send(session_id, message)` — SEND a message directly to another session
+
+## Topic formats
+
+### Agent-to-agent
+
+- Direct session route:
+  - `notifications.agent.<session_id>`
+
+Example:
+
+- `notifications.agent.ses_2e6ca3034ffejVikSZ8mDwk0mR`
+
+### Legion role claims
+
+- Role topic:
+  - `notifications.role.<role>`
+
+Legion agents receive through a daemon-minted role token. Claim the role for the current
+session with `envoy_role_set(role="<role>")`; claiming transfers its holder with
+last-claim-wins semantics. A claimant does not manually subscribe to its role topic.
+
+Legion role tokens must satisfy `^[a-z0-9][a-z0-9_-]*$` and are unique across repositories:
+
+```text
+legion-<project>-controller
+legion-<project>-<enc(owner)>__<enc(repo)>-<number>-<role>
+```
+
+`<project>` matches `[a-z0-9]+`. In owner and repository components, the injective escape
+encoding is `_` → `_u`, `.` → `_d`, and `-` → `_h`; `__` separates owner from repository.
+The daemon owns the authoritative token-to-issue map and hands the token to each process.
+Do not construct a token from a partial issue reference.
+
+Claims last through the issue's post-close linger. They survive parking and worker
+re-creation; a re-claim re-points the role to the backing session. The daemon publishes to an
+issue role only while the issue is active. Inactive issue events become daemon state and later
+surface as derived catch-up, never as raw event replay.
+
+### Legion exception lane
+
+`no_holder` and `delivery_failed` on a Legion role are daemon liveness signals, not a prompt
+for a second subscriber or a manual retry. The daemon probes the process that owns the tree:
+
+1. If it is alive, the daemon sends a control-topic directive. The extension revives or
+   re-creates the backing worker in code, then the daemon re-delivers the message.
+2. If it is dead, the daemon resurrects the root process behind a generation lock and supplies
+   derived catch-up plus the shared workspace handoffs.
+
+This keeps raw delivery failures out of architect context. Controller exception wakes are
+handled by the controller's wake routing table; every other role follows the liveness path.
+
+### GitHub
+
+GitHub topics are **resource-scoped** — every event includes the resource type and number (or, for push/workflow events, the ref or workflow filename).
+
+**Topic structure:** `notifications.github.<owner>.<repo>.<resource_type>.<number>.<event_kind>`
+
+- PR opened/closed/merged/ready:
+  - `notifications.github.<owner>.<repo>.pr.<number>`
+- Issue opened/closed/labeled:
+  - `notifications.github.<owner>.<repo>.issue.<number>`
+- Comment on a PR:
+  - `notifications.github.<owner>.<repo>.pr.<number>.comment`
+- Comment on an issue:
+  - `notifications.github.<owner>.<repo>.issue.<number>.comment`
+- PR review submitted:
+  - `notifications.github.<owner>.<repo>.pr.<number>.review`
+- Raw CI check observation (per-PR, immediate):
+  - `notifications.github.<owner>.<repo>.pr.<number>.check`
+  - Every PR-associated `check_run` publishes one raw observation per associated PR. `Payload` is JSON with `sha`, `name`, `status`, and `conclusion`; `PayloadSummary` names the check and its state.
+- CI/check summary (per-PR, per-commit, debounced):
+  - `notifications.github.<owner>.<repo>.pr.<number>.ci`
+  - The same `check_run` updates ingest-side per-commit state in JetStream KV bucket `envoy_ci_state`. Once the check set has been quiet for `ENVOY_CI_DEBOUNCE` (default `5s`), Envoy publishes one JSON summary. A new summary is emitted only when the check set changes; a new push starts a fresh tally, and a re-run that returns to running changes the tally.
+  - `PayloadSummary` is a compact JSON object (`Payload` unused): `{"kind":"ci_summary","repo":"<o>/<r>","number":"<n>","sha":"<sha>","failed":{"count":N,"checks":[...]},"running":{...},"passed":{...},"queued":{...},"skipped":{...}}`. Each status is `{count, checks}` with the full sorted name list; every status is present (`{"count":0,"checks":[]}` when empty).
+  - `check_suite` is ignored (it is a per-app rollup without a per-check name). Checks not tied to a PR are dropped, so there is no repo-wide CI topic. For non-PR visibility, use `workflow.<filename>.<action>`; individual GitHub Actions `workflow_job` events are not routed.
+- Mention events (per-resource):
+  - `notifications.github.<owner>.<repo>.pr.<number>.mention`
+  - `notifications.github.<owner>.<repo>.issue.<number>.mention`
+- Mention events (repo-wide — catches all mentions):
+  - `notifications.github.<owner>.<repo>.mention`
+- Push events (per branch/tag):
+  - `notifications.github.<owner>.<repo>.push.branch.<branch>`
+  - `notifications.github.<owner>.<repo>.push.tag.<tag>`
+  Branch and tag names with dots are sanitized to underscores (`v1.0.0` → `v1_0_0`).
+  Push events for refs other than `refs/heads/...` and `refs/tags/...` are not routed.
+- Workflow run events (per workflow file):
+  - `notifications.github.<owner>.<repo>.workflow.<filename>.<action>`
+  Filename is the basename of `workflow_run.path` with dots sanitized (`ci.yml` → `ci_yml`).
+  `action` is one of `requested`, `in_progress`, `completed`.
+
+**Using wildcards to subscribe broadly:**
+- All events in a repo: `notifications.github.<owner>.<repo>.>`
+- All PR events in a repo: `notifications.github.<owner>.<repo>.pr.>`
+- All events for a specific PR: `notifications.github.<owner>.<repo>.pr.<number>.>`
+- All issue events in a repo: `notifications.github.<owner>.<repo>.issue.>`
+- All events for a specific issue: `notifications.github.<owner>.<repo>.issue.<number>.>`
+- All push events in a repo: `notifications.github.<owner>.<repo>.push.>`
+- Pushes to main only: `notifications.github.<owner>.<repo>.push.branch.main`
+- All branch pushes: `notifications.github.<owner>.<repo>.push.branch.>`
+- All tag pushes: `notifications.github.<owner>.<repo>.push.tag.>`
+- All workflow events: `notifications.github.<owner>.<repo>.workflow.>`
+- All events for a specific workflow: `notifications.github.<owner>.<repo>.workflow.ci_yml.>`
+- Every workflow completion: `notifications.github.<owner>.<repo>.workflow.*.completed`
+
+Examples:
+
+- `notifications.github.trajectory-labs-pbc.agent-c.pr.9880` (PR #9880 state changes)
+- `notifications.github.trajectory-labs-pbc.agent-c.pr.9880.comment` (comments on PR #9880)
+- `notifications.github.trajectory-labs-pbc.agent-c.issue.9909.>` (all events on issue #9909)
+- `notifications.github.sjawhar.legion.pr.>` (all PR events across all PRs)
+- `notifications.github.sjawhar.legion.mention` (all @mentions repo-wide)
+- `notifications.github.sjawhar.legion.push.branch.main` (pushes to main)
+- `notifications.github.sjawhar.legion.workflow.ci_yml.in_progress` (CI workflow starts)
+
+### Slack
+
+- Channel message events:
+  - `notifications.slack.<team_id>.<channel_id>.message`
+- App mention events:
+  - `notifications.slack.<team_id>.<channel_id>.mention`
+- Thread message events:
+  - `notifications.slack.<team_id>.<channel_id>.thread.<normalized_ts>.message`
+- Thread mention events:
+  - `notifications.slack.<team_id>.<channel_id>.thread.<normalized_ts>.mention`
+
+Thread timestamps are normalized: `1234567890.123456` → `1234567890_123456`
+(dots replaced with underscores to make the thread ID a single NATS segment).
+
+Examples:
+
+- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.message`
+- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention`
+- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.message`
+- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.mention`
+
+### Ghost Wispr
+
+- Session started events:
+  - `notifications.ghostwispr.<session_id>.session.started`
+- Session ended events:
+  - `notifications.ghostwispr.<session_id>.session.ended`
+- Summary ready events:
+  - `notifications.ghostwispr.<session_id>.summary.ready`
+
+**Parameters:**
+- `<session_id>`: Ghost Wispr session timestamp string (e.g., `20260326041405`). Alphanumeric only, safe for NATS topic segments.
+- Supported kinds: `session.started`, `session.ended`, `summary.ready`
+
+Examples:
+
+- `notifications.ghostwispr.20260326041405.session.ended` (session ended)
+- `notifications.ghostwispr.20260326041629.summary.ready` (summary ready)
+
+### WhatsApp
+
+- Chat message events:
+  - `notifications.whatsapp.<phone>.<jid>.message`
+- Status/receipt events:
+  - `notifications.whatsapp.<phone>.<jid>.status`
+
+**Parameters:**
+- `<phone>`: Connected WhatsApp account phone number in E.164 digits-only format (no `+` prefix). Example: `15551234567`. This identifies **which WhatsApp account** the events belong to — not the remote contact.
+- `<jid>`: Remote chat's WhatsApp JID. Individual: `PHONE@s.whatsapp.net`. Group: `ID@g.us`.
+- Supported kinds: `message`, `status`
+
+> **⚠️ JID dot expansion:** JID dots (`.`) become additional NATS subject tokens. For example, `5551234567@s.whatsapp.net` splits into tokens `5551234567@s`, `whatsapp`, `net`. This means individual chat topics produce 7 tokens and group chat topics produce 6 tokens. **Always use `>` (multi-level wildcard), never `*` (single-token wildcard)**, when subscribing to a chat or phone number.
+
+Examples:
+
+- `notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.message` (individual chat messages — note this expands to 7 NATS tokens)
+- `notifications.whatsapp.15551234567.120363XXX@g.us.message` (group chat messages — 6 NATS tokens)
+
+## When to use what
+
+### To receive future Slack/GitHub/WhatsApp events
+
+1. Decide the exact topic(s)
+2. Call `envoy_subscribe([...])`
+3. Optionally call `envoy_list()` to confirm
+
+### To talk directly to another agent/session
+
+1. Get the target session ID
+2. Call `envoy_send(session_id, message)`
+
+You do NOT need to subscribe in order to send or publish.
+
+### To wait for CI, PR checks, or other async work
+
+**Don't `sleep`-poll. Don't "check back in N minutes."** Subscribe to the event and continue with productive work — the system will wake the session when the event arrives.
+
+1. Identify the relevant topic (e.g., `notifications.github.<owner>.<repo>.pr.<num>.>` for all PR events; `.pr.<num>.check` for immediate per-check state; `.pr.<num>.ci` for the debounced PR summary; `.workflow.<filename>.completed` for a workflow run finishing)
+2. Call `envoy_subscribe([...])`
+3. Move on to other work, or end the response and let the watcher wake you
+4. The next response is triggered by the event, with the payload available in your context
+
+If you have nothing else to do, end the response. The user is not your alarm clock; do not loop with `sleep`.
+
+### Tools
+
+- `envoy_subscribe(topics)` — receive future events on those topics
+- `envoy_unsubscribe(topics?)` — stop receiving some or all topics
+- `envoy_list()` — show live and persisted subscriptions, marked by source
+- `envoy_send(session_id, message)` — send directly to a specific session (point-to-point)
+- `envoy_publish(topic, message)` — publish a normal topic to matching subscribers or route a role topic to its current holder
+- `envoy_role_set(role)` — claim a named role for the current session (exactly-one-holder)
+
+## Patterns
+
+### Subscribe controller to a specific Slack channel mentions
+
+```text
+envoy_subscribe([
+  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention"
+])
+```
+
+### Subscribe to all events in a specific Slack thread
+
+```text
+envoy_subscribe([
+  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.>"
+])
+```
+
+### Subscribe to only messages in a Slack thread (not mentions)
+
+```text
+envoy_subscribe([
+  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.1234567890_123456.message"
+])
+```
+
+### Subscribe to all threads in a Slack channel
+
+```text
+envoy_subscribe([
+  "notifications.slack.T09FRELLTS8.C0A0DHVU8HE.thread.>"
+])
+```
+
+### Subscribe to all PR events for agent-c
+
+```text
+envoy_subscribe([
+  "notifications.github.trajectory-labs-pbc.agent-c.pr.>"
+])
+```
+
+### Subscribe controller to GitHub @mentions for agent-c
+
+```text
+envoy_subscribe([
+  "notifications.github.trajectory-labs-pbc.agent-c.mention"
+])
+```
+
+### Message another session directly
+
+```text
+envoy_send(
+  session_id="ses_2e6ca3034ffejVikSZ8mDwk0mR",
+  message="Please continue the smoke test"
+)
+```
+
+### Subscribe to a specific WhatsApp contact (1:1 chat)
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.>"
+])
+```
+
+Use `>` (not `*`) to catch all event kinds despite JID dot expansion into multiple NATS tokens.
+
+### Subscribe to a WhatsApp group
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.120363XXX@g.us.>"
+])
+```
+
+### Subscribe to all WhatsApp events for an account
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.>"
+])
+```
+
+Catches all conversations and event kinds for the specified phone number.
+
+**When to use which:**
+- **1:1 chat** — when monitoring a specific contact conversation (e.g., a bot handling customer queries)
+- **Group chat** — when monitoring a specific group for commands or events
+- **All chats for a phone** — when building a general WhatsApp event handler or dashboard for an account
+
+## Important notes
+
+- Sessions choose their own Slack/GitHub subscriptions
+- Different sessions can subscribe to different channels/repos
+- Agent-to-agent delivery uses exact session IDs
+- `envoy_list()` distinguishes `live`, `registry`, and `both`; a `live` topic is receiving now even when the listener registry has not caught up.
+- For Slack, use the real `team_id` in topics (for example `T09FRELLTS8`), not a workspace slug like `trajectorylabs`
+- GitHub mention routing is body-based because GitHub has no dedicated app mention webhook event
+
+## Synthetic Smoke Test (WhatsApp — NATS Routing Only)
+
+> **Important:** This procedure validates Envoy's NATS → listener → session delivery path using `envoy_publish`. It does **not** test real WhatsApp message ingestion. The generic MCP bridge (`packages/envoy/cmd/mcp/`) can bridge real WhatsApp events, but requires production configuration. See "Current Limitations" below.
+>
+> **Two sessions required:** `envoy_publish` sets `source_session` to the publishing session's ID. The listener skips delivering broadcasts back to the sender (`packages/envoy/cmd/listener/main.go`). You must subscribe in one session and publish from a different session.
+
+### Step 1: Subscribe to a WhatsApp topic (Session A)
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.>"
+])
+```
+
+### Step 2: Verify subscription is active (Session A)
+
+```text
+envoy_list()
+```
+
+Confirm `notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.>` appears as `live` or `both`.
+
+### Step 3: Publish a synthetic test envelope (Session B — a different session)
+
+```text
+envoy_publish(
+  topic="notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.message",
+  message="Synthetic WhatsApp smoke test: hello from envoy_publish"
+)
+```
+
+### Step 4: Verify delivery (Session A)
+
+Session A should receive a notification containing the text "Synthetic WhatsApp smoke test: hello from envoy_publish". This confirms:
+- The topic pattern matches the subscription
+- NATS routes the message to the listener
+- The listener delivers to the subscribed session (Session A ≠ the publishing session)
+
+**If the notification does not arrive:** Check `envoy_list()` in Session A. The topic should be `live` or `both`; `registry` alone does not confirm the local subscription is receiving. Verify the topic in `envoy_publish` matches the subscription pattern. Ensure you are publishing from a **different** session than the one subscribed.
+
+### Reference: Real WhatsApp Envelope Shape
+
+When the MCP bridge (`packages/envoy/internal/mcpbridge/envelope.go`) publishes a real WhatsApp event, the Envoy envelope has this structure:
+
+```json
+{
+  "event_id": "<generated unique ID>",
+  "source": "whatsapp",
+  "source_event_id": "whatsapp://messages/15551234567/5551234567@s.whatsapp.net",
+  "topic": "notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.message",
+  "dedupe_key": "whatsapp.<event_id value>",
+  "issued_at": 1712345678000,
+  "payload_summary": "Hello from WhatsApp",
+  "payload_ref": "whatsapp://messages/15551234567/5551234567@s.whatsapp.net",
+  "trace_id": "<generated unique ID>"
+}
+```
+
+**Field notes:**
+- `source` is `"whatsapp"` — in contrast, `envoy_publish` sets `source: "agent"` for synthetic messages
+- `issued_at` is in **milliseconds** (Unix epoch ms), not seconds
+- `dedupe_key` is `source + "." + event_id` (e.g., `"whatsapp.cuid_abc123"`)
+- `payload_summary` is the actual message text from the MCP resource read (truncated to 200 chars), or fallback `"whatsapp event from <uri>"` if no text content
+- `payload_ref` and `source_event_id` are both the MCP resource notification URI
+- `source_session` is **omitted** (empty) — the MCP bridge is not an OpenCode session, so no echo-skip occurs
+- `expires_at` is **omitted** — the bridge does not set message expiry
+
+## Current Limitations (WhatsApp)
+
+- **No production WhatsApp event ingestion configured.** The repo contains a generic MCP→NATS bridge (`packages/envoy/cmd/mcp/` + `packages/envoy/internal/mcpbridge/`) that already supports WhatsApp topic patterns (tested in `packages/envoy/internal/integration/delivery_test.go`). However, it is not yet configured/deployed to connect to the `@sjawhar/whatsapp-mcp` server in production.
+- **Synthetic testing only.** The smoke test above uses `envoy_publish` to inject test messages into NATS. It validates Envoy delivery mechanics (NATS → listener → session), not true WhatsApp end-to-end delivery.
+- **Production wiring needed.** To receive real WhatsApp events, the MCP bridge needs to be configured with the `@sjawhar/whatsapp-mcp` server connection details (similar to how `packages/envoy/cmd/github/` and `packages/envoy/cmd/slack/` are configured for their respective platforms). The bridge would then subscribe to WhatsApp MCP resource notifications and publish Envoy envelopes to NATS automatically.
+- **Subscription + routing + delivery path is ready.** The contracts layer (`whatsappSubject` helper), NATS topic format, generic listener routing, and MCP bridge infrastructure all work. Only the production configuration connecting the bridge to the WhatsApp MCP server is missing.

package/dist/skills/github/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: github
+description: Manage GitHub issues via Projects V2. Use when LEGION_ISSUE_BACKEND=github.
+---
+
+# GitHub (gh CLI)
+
+Direct CLI operations via `gh`. No embedded MCP — all commands are shell invocations.
+
+## Setup
+
+Requires `gh` CLI installed and authenticated:
+```bash
+gh auth login
+```
+
+## Operations
+
+### Search/List Issues (via project)
+
+List all items in a GitHub Project V2:
+
+```bash
+gh project item-list $PROJECT_NUM --owner $OWNER --format json
+```
+
+**Parameters:**
+- `$PROJECT_NUM`: Project number (from `LEGION_ID` format: `owner/project-number`)
+- `$OWNER`: Repository owner
+- `--format json`: Returns structured data for parsing
+
+**Example:**
+```bash
+gh project item-list 42 --owner acme --format json | jq '.items[] | {id, title, status}'
+```
+
+### Get Issue Details
+
+Fetch full issue metadata:
+
+```bash
+gh issue view $ISSUE_NUMBER --json title,body,labels,comments,state -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `$ISSUE_NUMBER`: Issue number (e.g., `123`)
+- `-R $OWNER/$REPO`: Repository (required for multi-repo support)
+- `--json`: Fields to return (title, body, labels, comments, state, etc.)
+
+**Example:**
+```bash
+gh issue view 123 --json title,body,labels,state -R acme/backend
+```
+
+### Update Status (Projects V2 — GraphQL)
+
+Update issue status in a GitHub Project V2. Requires field and option IDs from project schema:
+
+```bash
+gh api graphql -f query='mutation {
+  updateProjectV2ItemFieldValue(input: {
+    projectId: "$PROJECT_ID"
+    itemId: "$ITEM_ID"
+    fieldId: "$STATUS_FIELD_ID"
+    value: { singleSelectOptionId: "$OPTION_ID" }
+  }) { projectV2Item { id } }
+}'
+```
+
+**Parameters:**
+- `$PROJECT_ID`: GraphQL ID of the project (not the number)
+- `$ITEM_ID`: GraphQL ID of the issue in the project
+- `$STATUS_FIELD_ID`: GraphQL ID of the Status field
+- `$OPTION_ID`: GraphQL ID of the status option (e.g., "In Progress", "Done")
+
+**Note:** Field and option IDs must be resolved from the project schema. The controller caches these after first query.
+
+**Resolve IDs (one-time):**
+```bash
+gh api graphql -f query='query {
+  repository(owner: "$OWNER", name: "$REPO") {
+    projectV2(number: $PROJECT_NUM) {
+      fields(first: 20) {
+        nodes {
+          ... on ProjectV2SingleSelectField {
+            id
+            name
+            options { id name }
+          }
+        }
+      }
+    }
+  }
+}'
+```
+
+### Add Label
+
+Add a label to an issue (additive — does not remove existing labels):
+
+```bash
+gh issue edit $ISSUE_NUMBER --add-label "needs-approval" -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `$ISSUE_NUMBER`: Issue number
+- `--add-label`: Label to add (can be used multiple times)
+- `-R $OWNER/$REPO`: Repository
+
+**Example:**
+```bash
+gh issue edit 123 --add-label "needs-approval" -R acme/backend
+```
+
+### Remove Label
+
+Remove a label from an issue:
+
+```bash
+gh issue edit $ISSUE_NUMBER --remove-label "needs-approval" -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `$ISSUE_NUMBER`: Issue number
+- `--remove-label`: Label to remove (can be used multiple times)
+- `-R $OWNER/$REPO`: Repository
+
+**Example:**
+```bash
+gh issue edit 123 --remove-label "legion-backlog" -R acme/backend
+```
+
+### Comment on Issue
+
+Add a comment to an issue:
+
+```bash
+gh issue comment $ISSUE_NUMBER --body "Fixed in commit abc123" -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `$ISSUE_NUMBER`: Issue number
+- `--body`: Comment text (supports Markdown)
+- `-R $OWNER/$REPO`: Repository
+
+**Example:**
+```bash
+gh issue comment 123 --body "Implemented in PR #456" -R acme/backend
+```
+
+### Create Issue
+
+Create a new issue:
+
+```bash
+gh issue create --title "Bug: Login fails" --body "Details" -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `--title`: Issue title (required)
+- `--body`: Issue description (optional, supports Markdown)
+- `-R $OWNER/$REPO`: Repository
+
+**Example:**
+```bash
+gh issue create --title "Feature: Add dark mode" --body "User request from #789" -R acme/backend
+```
+
+## Key Differences from Linear
+
+| Aspect | Linear | GitHub |
+|--------|--------|--------|
+| **Labels** | Replace all (read-modify-write) | Additive (`--add-label`, `--remove-label`) |
+| **Status** | Direct field update | Projects V2 GraphQL mutation |
+| **PR Association** | Attachment field | Native (issue ↔ PR link) |
+| **API** | MCP tool dispatch | Direct `gh` CLI |
+| **Multi-repo** | Single team | `-R owner/repo` per command |
+
+## Important Notes
+
+- **Always specify `-R $OWNER/$REPO`** for multi-repo project support
+- **Labels are additive**: Use `--add-label` and `--remove-label` separately (unlike Linear which replaces all)
+- **Status updates require Projects V2 GraphQL** — not just issue labels
+- **PR association is automatic** — GitHub links issues and PRs natively
+- **`$OWNER` and `$REPO` come from `LEGION_ID`** (format: `owner/project-number`)
+- **Field/option IDs must be cached** by the controller after first resolution
+
+## Error Handling
+
+Common errors and solutions:
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Could not resolve to a Repository` | Wrong `-R` format | Use `-R owner/repo` (not `owner-repo`) |
+| `Could not resolve to an Issue` | Issue doesn't exist | Verify issue number is correct |
+| `GraphQL error: Field not found` | Wrong field ID | Re-resolve field IDs from project schema |
+| `Not authenticated` | `gh` not logged in | Run `gh auth login` |
+
+## Reference
+
+- **Project number**: Visible in GitHub UI (e.g., `https://github.com/orgs/acme/projects/42` → `42`)
+- **Issue number**: Visible in URL (e.g., `https://github.com/acme/backend/issues/123` → `123`)
+- **GraphQL IDs**: Base64-encoded, returned by GraphQL queries (not human-readable)