forge-workflow 0.0.10 → 0.1.0-beta.3

package/skills/claim-safety/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "I just ran forge claim on forge-abc — how do I make sure the lease is really mine before I start editing?",
+    "should_trigger": true
+  },
+  {
+    "query": "Two of my agents may have grabbed the same issue at once — how do I tell which one actually holds it?",
+    "should_trigger": true
+  },
+  {
+    "query": "Before I close this ticket, confirm nobody reclaimed it while I was working.",
+    "should_trigger": true
+  },
+  {
+    "query": "My claim came back ok:true but I'm not convinced I won the race. Can I trust that?",
+    "should_trigger": true
+  },
+  {
+    "query": "Prove I own forge-42 before the subagent starts mutating it.",
+    "should_trigger": true
+  },
+  {
+    "query": "The lease might have expired mid-task — check I still own it before I release.",
+    "should_trigger": true
+  },
+  {
+    "query": "What's the next ready issue I should pick up?",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a feature issue titled 'Add CSV export'.",
+    "should_trigger": false
+  },
+  {
+    "query": "Close forge-19 with reason 'shipped in PR 88'.",
+    "should_trigger": false
+  },
+  {
+    "query": "Take forge-30 all the way through to a PR.",
+    "should_trigger": false
+  },
+  {
+    "query": "Implement the failing auth tests for this task.",
+    "should_trigger": false
+  }
+]

package/{.github/prompts/dev.prompt.md → skills/dev/SKILL.md}

@@ -1,14 +1,25 @@
 ---
 name: dev
-description: Subagent-driven TDD implementation per task from /plan task list
-tools: []
+description: >
+  Forge DEV stage — implement an already-planned /plan task list into committed, test-backed
+  code. Reads tasks.md + plan.md, then drives each task through a subagent TDD loop
+  (implementer → spec-compliance reviewer → code-quality reviewer) with RED-GREEN-REFACTOR,
+  HARD-GATE evidence checks, and a spec-gap decision score. Use when a plan and task list
+  already exist and it is time to implement — triggers: "/dev", "start the dev stage", "build
+  the tasks", "implement tasks.md test-first", "run the implementer/reviewer TDD loop", "write
+  the code for the planned tasks one by one", "work through the task list with subagents".
+  Per-task coding ONLY. Do NOT use for creating the design doc or task list (that is plan),
+  for the post-build type-check/lint/security/test gate (validate), for pushing the branch or
+  opening the PR (ship), for addressing PR review feedback (review), or for orchestrating
+  several stages / taking an issue end-to-end to a merged PR (smith).
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob
 ---
 
 Implement each task from the /plan task list using a subagent-driven loop: implementer → spec compliance reviewer → code quality reviewer per task.
 
 # Dev
 
-This command reads the task list created by `/plan` and implements each task using a three-stage subagent loop. TDD is enforced inside each implementer subagent.
+This skill reads the task list created by `/plan` and implements each task using a three-stage subagent loop. TDD is enforced inside each implementer subagent.
 
 ## Usage
 
@@ -24,19 +35,19 @@ This command reads the task list created by `/plan` and implements each task usi
 
 ```bash
 # Find task list and design doc
-ls docs/plans/
+ls docs/work/
 ```
 
 Read:
-- **Task list**: `docs/plans/YYYY-MM-DD-<slug>-tasks.md` — extract ALL task text upfront
-- **Design doc**: `docs/plans/YYYY-MM-DD-<slug>-design.md` — including ambiguity policy section
+- **Task list**: `docs/work/YYYY-MM-DD-<slug>/tasks.md` — extract ALL task text upfront
+- **Design doc**: `docs/work/YYYY-MM-DD-<slug>/plan.md` — including ambiguity policy section
 
 ### Step 2: Create decisions log
 
 Create an empty decisions log at the start of every /dev session:
 
 ```bash
-# docs/plans/YYYY-MM-DD-<slug>-decisions.md
+# docs/work/YYYY-MM-DD-<slug>/decisions.md
 ```
 
 Format for each entry:
@@ -74,8 +85,8 @@ Before starting the per-task loop, check for cross-developer conflicts:
 # Auto-sync to get latest team state (non-blocking)
 forge sync || true
 
-# Check for conflicts with the current beads issue
-bash scripts/conflict-detect.sh --issue <beads-id>
+# Check for conflicts with the current Forge issue
+bash scripts/conflict-detect.sh --issue <forge-id>
 ```
 
 If exit code 2 (validation error): show error message, abort — do not show conflict prompt.
@@ -84,7 +95,7 @@ If exit code 1 (conflicts found):
 - Display the conflict output to the developer
 - Ask: "Other developers are working in overlapping areas. Proceed anyway? (y/n)"
 - If `n`: exit cleanly, no side effects
-- If `y`: log override via `bd comments add <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Per-Task Loop
+- If `y`: log override via `forge comment <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Per-Task Loop
 - Audit: record conflict override per OWASP A09
 
 If exit code 0: proceed silently to Per-Task Loop.
@@ -194,7 +205,7 @@ Reviewer checks:
 - Structure: functions not too long, proper separation of concerns
 - Duplication: no copy-paste that could be extracted
 - Test coverage: tests cover happy path and at least one error path
-- No magic numbers, no commented-out code, no TODO without a Beads issue
+- No magic numbers, no commented-out code, no TODO without a Forge issue
 
 If quality issues found: implementer fixes → re-review → repeat until ✅
 
@@ -213,7 +224,7 @@ Do NOT mark task complete or move to next task until ALL confirmed in this sessi
 4. Run it fresh — show the actual output. "Last run was fine" is not evidence.
 5. Tests run fresh — actual output shows passing.
 6. Implementer has committed (git log shows the commit).
-7. `bash scripts/beads-context.sh update-progress <id> <task-num> <total> "<title>" <commit-sha> <test-count> <gate-count>` ran successfully (exit code 0). If it fails: STOP. Show error. Do not proceed to next task.
+7. Progress recorded on the Forge issue — `forge comment <id> "task <task-num>/<total> done: <title> (<commit-sha>, <test-count> tests, <gate-count> gates)"` ran successfully (exit code 0). The Forge comment is the kernel-native record. If the recording command errors: STOP, show the error, do not proceed to the next task.
 
 Forbidden phrases (these are not evidence):
 - "should pass"
@@ -274,15 +285,18 @@ Do NOT declare /dev complete until:
 </HARD-GATE>
 ```
 
-### Beads update
+### Record stage transition
 
 ```bash
-bash scripts/beads-context.sh validate <id>
-bash scripts/beads-context.sh stage-transition <id> dev validate \
-  --summary "<N tasks done, M decision gates fired>" \
-  --decisions "<key spec gaps and how they were resolved>" \
-  --artifacts "<changed source files and test files>" \
-  --next "<validation priorities — lint issues, type concerns>"
+# Confirm the issue carries design + acceptance context.
+forge issue show <id>
+
+# Record the dev→validate transition kernel-natively (Stage:/Summary:/Decisions:/Artifacts:/Next: envelope).
+forge comment <id> "Stage: dev complete → ready for validate
+Summary: <N tasks done, M decision gates fired>
+Decisions: <key spec gaps and how they were resolved>
+Artifacts: <changed source files and test files>
+Next: <validation priorities — lint issues, type concerns>"
 ```
 
 ---
@@ -299,43 +313,23 @@ Document the gate count in the final commit message.
 
 ---
 
-## Example Output (all tasks complete)
+## Dynamic Output
 
-```
-✓ Task 1: Types and interfaces — COMPLETE
-  Spec: ✅  Quality: ✅  Tests: 4/4 passing  Commit: abc1234
-  Decision gates: 0
-
-✓ Task 2: Validation logic — COMPLETE
-  Spec: ✅  Quality: ✅  Tests: 8/8 passing  Commit: def5678
-  Decision gates: 1 (PROCEED, score 2 — documented in decisions log)
-
-✓ Task 3: API endpoint — COMPLETE
-  Spec: ✅  Quality: ✅  Tests: 6/6 passing  Commit: ghi9012
-  Decision gates: 0
-
-✓ Final code review: ✅ (coherent, consistent, correctly integrated)
+The completion summary is generated from the live task list, decisions log, Forge issue state, commits, and validation output at runtime. Do not copy a static example into this skill file; run `/dev` to view the current task/status summary.
 
-✓ Decisions log: docs/plans/2026-02-26-stripe-billing-decisions.md
-  - Decision 1: RESOLVED (score 2, proceeded with conservative choice)
-  - Decision gates fired: 1 (plan quality: Good)
-
-✓ Beads updated: forge-xyz → implementation complete
+## Integration with Workflow
 
-Ready for /validate
 ```
+Utility: /status  -> Understand current context before starting
 
-## Integration with Workflow
+Default template:
+  /dev       -> Implement each task with subagent-driven TDD (you are here)
+  /validate  -> Type check, lint, tests, security
+  /ship      -> Push + create PR
+  /review    -> Address PR feedback
+  /verify    -> Post-merge health check
 
-```
-Utility: /status     → Understand current context before starting
-Stage 1: /plan       → Design intent → research → branch + worktree + task list
-Stage 2: /dev        → Implement each task with subagent-driven TDD (you are here)
-Stage 3: /validate      → Type check, lint, tests, security — all fresh output
-Stage 4: /ship       → Push + create PR
-Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
-Stage 6: /premerge   → Update docs, hand off PR to user
-Stage 7: /verify     → Post-merge CI check on main
+Pre-merge gate: doc updates + CI-green checkpoint embedded in /ship and /review (not a separate stage).
 ```
 
 ## Tips

package/skills/dev/evals/evals.json

@@ -0,0 +1,50 @@
+[
+  {
+    "query": "/dev",
+    "should_trigger": true
+  },
+  {
+    "query": "The plan and task list are done — start implementing the tasks one at a time, tests first.",
+    "should_trigger": true
+  },
+  {
+    "query": "Run the implementer then the spec and quality reviewer subagents over each task in tasks.md",
+    "should_trigger": true
+  },
+  {
+    "query": "Implement the already-planned tasks one at a time, red-green-refactor each",
+    "should_trigger": true
+  },
+  {
+    "query": "Time to write the code for the planned tasks and TDD each one in this worktree",
+    "should_trigger": true
+  },
+  {
+    "query": "Work through tasks.md subagent by subagent until every task is committed and reviewed",
+    "should_trigger": true
+  },
+  {
+    "query": "Set up the branch, worktree, and TDD task list for this new feature",
+    "should_trigger": false
+  },
+  {
+    "query": "Type-check, lint, and run the full test suite before I open the PR",
+    "should_trigger": false
+  },
+  {
+    "query": "Push the validated branch and open the pull request",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR has open review threads from the bots — fix each finding, reply, and mark them resolved.",
+    "should_trigger": false
+  },
+  {
+    "query": "Grab the next ready issue and drive it all the way to a merged PR",
+    "should_trigger": false
+  },
+  {
+    "query": "Which workflow stage am I on and what work is in flight right now?",
+    "should_trigger": false
+  }
+]

package/skills/hermes-forge/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: hermes-forge
+description: >
+  Hermes⇄Forge boundary: Hermes CONSUMES Forge state, never a second source of truth. Use
+  whenever a Hermes session runs on a Forge repo: at session start, before acting on an issue,
+  or when you need CURRENT state. Read state ONLY via `forge orient` / `forge recap
+  <issue-id>` (bounded JSON envelope), citing each source's `path`/`authority`; never
+  reconstruct it from raw stores or kernel internals. Writeback ONLY via `forge
+  comment`/`update`/`create`; NEVER leak Hermes profile or session memory into Forge state.
+  Triggers: "orient me / current project state", "where did this fact come from, cite it",
+  "orient came back truncated", "persist a decision into Forge", "safe to store in kernel
+  state?". NOT the Forge session router over stage skills (kernel), NOT the human "what stage
+  am I in" report (status), NOT everyday issue create/update/close/search CRUD (issue-basics),
+  NOT ranking the next ready issue (triage-ready), NOT live PR monitoring (shepherd—outside
+  Hermes, unseen by orient).
+compatibility: >
+  Requires the Forge CLI (`forge`) on PATH in a Forge-initialized repo. Install
+  path — like every Forge skill pack (e.g. parallel-deep-research,
+  sonarcloud-analysis) this is delivered by the unified Skills CLI; run
+  `skills sync` to install it into `.hermes/skills/hermes-forge/`. (`forge setup`
+  initializes the skills registry via `skills init` but does not sync packs to
+  agents.) Read-only orientation works anywhere; writeback requires a Forge
+  Kernel issue backend. CLI-only — no direct file or profile writes into Forge
+  state.
+metadata:
+  author: forge
+  version: "1.0.0"
+  roadmap: forge-2agy.9.7.x
+---
+
+# Hermes ⇄ Forge consumption contract
+
+Hermes is a *consumer* of Forge project state, not an owner of it. This skill
+defines how a Hermes session reads, cites, and writes back to a Forge project
+without ever becoming a second source of truth.
+
+The boundary between what Forge owns and what Hermes owns is specified in the
+Forge repo at `docs/reference/HERMES_INTEGRATION.md` (repo-relative path — this
+skill is synced to `.hermes/skills/hermes-forge/`, so relative links would not
+resolve from the installed location).
+
+## When to use
+
+- At the start of any Hermes session on a Forge repo (orientation).
+- Before acting on a specific issue (issue recap).
+- Whenever you need current project state — never reconstruct it from raw files.
+
+## Authority: orient / recap are the only state source
+
+The Forge Kernel is the single source of truth. Hermes obtains project state
+**exclusively** through two thin CLI wrappers and must not infer state by
+reading raw issue stores, design files, or kernel internals directly:
+
+```bash
+forge orient --json                # bounded project orientation (envelope)
+forge orient --budget 4000 --json
+forge recap <issue-id> --json      # bounded per-issue recap (envelope)
+```
+
+`forge orient` and `forge recap <issue-id>` emit the deterministic JSON envelope
+described below (assembly `deterministic-file-assembly-v1`). Parse the JSON; do
+not screen-scrape the human text form.
+
+> Note: `forge recap` always requires an issue id — bare `forge recap --json`
+> (no id) prints its usage and exits non-zero rather than returning a summary.
+> Use `forge orient` for project-level orientation, or `forge recap <issue-id>`
+> for a single issue; both emit the deterministic envelope.
+
+### Envelope shape
+
+| Field | Meaning |
+| --- | --- |
+| `schema_version` | Contract version (currently `1`). Reject unknown majors. |
+| `kind` | `orientation`, `issue_recap`, or `prime`. |
+| `generated_at` | Assembly timestamp. |
+| `assembly` | `deterministic-file-assembly-v1` — same inputs ⇒ same output. |
+| `token_budget` | Budget accounting (see below). |
+| `sections[]` | Ordered content blocks, each independently cited. |
+| `sources[]` | Deduplicated provenance across all sections. |
+| `next_commands[]` | Suggested follow-up `forge` commands. Prefer these for navigation. |
+
+Each `sections[]` entry: `{ id, title, content, sources, truncated, estimated_tokens }`.
+
+## Token budget
+
+`forge orient` / `forge recap <issue-id>` are bounded so they fit a context
+window deterministically.
+
+- Default budget: **2000** estimated tokens. Minimum honored: **40**.
+- Estimation is approximate: `token_budget.approximate === true`,
+  `token_budget.chars_per_token === 4`.
+- `token_budget.requested` is what you asked for; `token_budget.used` is the
+  estimate actually emitted.
+- Raise the ceiling with `--budget N` when you need more depth; do not retry
+  blindly — request a specific larger budget.
+
+## Citation & provenance model
+
+Every fact Hermes surfaces to a user MUST be attributable. Each section carries
+`sources: [{ path, source_kind, authority, role }]`:
+
+- `path` — the file the content came from.
+- `source_kind` — the kind of artifact (e.g. design, decision, claim, queue).
+- `authority` — how authoritative the source is. Prefer higher-authority
+  sources when two sources conflict; surface the conflict rather than silently
+  picking one.
+- `role` — the role the source plays in the section.
+
+When Hermes states a project fact, cite at least the `path` and `authority` of
+the backing source. The top-level `sources[]` is the deduplicated set for the
+whole payload.
+
+## Truncation policy
+
+Truncation is deterministic, never random:
+
+- Non-preserved sections are trimmed in the order given by
+  `token_budget.truncation_order`; when the budget is exhausted, sections later
+  in that order are trimmed first. Preserved sections are kept whole and trimmed
+  only as a last resort if the payload is still over budget. The authoritative
+  per-section signal is each section's `truncated` flag and `estimated_tokens` —
+  there is no per-section `priority` field; the overall trim order is
+  `token_budget.truncation_order`.
+- A trimmed section ends with the literal marker
+  `[truncated deterministically by token budget]` and has `truncated: true`.
+- `token_budget.truncated === true` means the payload as a whole was trimmed.
+
+Treat any `truncated` section as **incomplete**. Do not present a truncated
+section as exhaustive; if completeness matters, re-request with a higher
+`--budget` or recap the specific issue.
+
+## Writeback path: Hermes → Forge Kernel
+
+Evidence and decisions discovered during a Hermes session flow back into the
+Forge Kernel **only** through Forge CLI commands. Use the issue command surface
+documented in the Forge repo at
+`docs/reference/forge-kernel-issue-command-contract.md`:
+
+```bash
+forge comment <id> <body...>   # attach evidence, a decision, or a note to an issue
+forge update <id...> [flags]   # update issue state/fields
+forge create [title] [flags]   # open a new issue for follow-up work
+```
+
+> Note: `forge audit` is verify-only (`forge audit verify`) and does **not**
+> append evidence — record evidence as an issue comment via `forge comment`.
+
+These writes land in the Forge Kernel issue store, where they become part of the
+issue's durable history (view them via the issue itself, e.g. `forge show <id>`).
+Note the read/write asymmetry: the bounded `forge orient` / `forge recap`
+envelope is assembled from project docs, `docs/work` artifacts, and the issue
+summary — it surfaces issue/design/decision state but does **not** echo
+individual issue comments back. Do not assume evidence added via `forge comment`
+reappears verbatim in the next orient/recap payload; it lives in the issue
+history, reachable from the issue record.
+
+## No-profile-write guard (hard boundary)
+
+Hermes **MUST NOT write Hermes profile** state, conversation memory, or any
+Hermes-native artifact into Forge Kernel state — not into kernel storage, not
+into design/decision files, not into the issue backend. Hermes-native memory
+stays in Hermes' own store.
+
+- ✅ Read state via `forge orient` / `forge recap`.
+- ✅ Write evidence/decisions via `forge comment` / `forge update`.
+- ❌ Never persist Hermes profile/session memory into Forge Kernel state.
+- ❌ Never edit Forge state files directly to record Hermes-side context.
+
+If a piece of context only matters to Hermes, it belongs in Hermes-native
+memory. If it is a project fact, decision, or evidence item, write it through
+the Forge CLI so it becomes part of the shared, cited source of truth.
+
+## PR shepherd (external scheduler, not orientation)
+
+The PR shepherd runs **outside** Hermes. An external scheduler invokes
+`forge shepherd <pr>` as discrete bounded passes — each pass reads CI/check
+state, takes at most one idempotent action (re-run a flaky required check), or
+escalates, then exits. It **never merges** (the human merges in the GitHub UI)
+and **never resolves review threads**.
+
+Hermes does not run the shepherd and does not learn shepherd progress through
+`forge orient` (which is deterministic-source orientation with no live PR
+awareness). Shepherd progress is durable on the **PR itself** — its comments and
+labels. When a Hermes session needs PR/CI status, read the PR directly; do not
+expect `orient` to carry it.

package/skills/hermes-forge/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "I just started a Hermes session on this Forge repo — get me oriented on where the project stands before I touch anything.",
+    "should_trigger": true
+  },
+  {
+    "query": "The forge orient envelope came back with the active-work section flagged truncated. Can I treat that as the full list, or do I need to pull more?",
+    "should_trigger": true
+  },
+  {
+    "query": "Before I tell the user which approach we settled on, I need to point at the exact source file and how authoritative it is — where does that decision come from?",
+    "should_trigger": true
+  },
+  {
+    "query": "I uncovered a design decision in this session that the team needs to keep. What's the correct way to write it back into Forge without dragging my Hermes notes into kernel state?",
+    "should_trigger": true
+  },
+  {
+    "query": "Default orientation is clipping the decisions section at 2000 tokens — give me more headroom.",
+    "should_trigger": true
+  },
+  {
+    "query": "Don't rebuild the project picture by grepping the design docs yourself — go through the proper bounded orient/recap surface instead.",
+    "should_trigger": true
+  },
+  {
+    "query": "Which workflow stage am I sitting in right now, and has any of my work gone stale?",
+    "should_trigger": false
+  },
+  {
+    "query": "I'm kicking off a Forge session in Claude — which stage skill do I run to start planning a new feature?",
+    "should_trigger": false
+  },
+  {
+    "query": "Watch PR #418, rerun the flaky required check if it trips, and ping me when it's ready to merge.",
+    "should_trigger": false
+  },
+  {
+    "query": "Open a bug issue for the checkout timeout, set priority 1, and add a note about the repro steps.",
+    "should_trigger": false
+  },
+  {
+    "query": "What's the highest-priority ready issue I should pick up next?",
+    "should_trigger": false
+  }
+]

package/skills/issue-basics/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: issue-basics
+description: >
+  Everyday single-issue CRUD over the `forge issue` verbs:
+  create/update/show/list/search/close/reopen/comment, set priority/labels/assignee, claim or
+  release one issue, add/remove dependency edges, plus backlog `stats`. Use for ANY routine
+  one-off issue op: "create an issue/bug/task for X", "update/edit issue <id>", "close or
+  reopen this issue", "comment a handoff note on <id>", "list/filter open bugs by
+  status/label/priority", "bump this to P1", "reassign to alice", "mark <id> blocked by <id>".
+  Also the parity floor migrating off a Beads-style tracker (label/reopen/delete map to forge
+  equivalents). Single-operation plumbing only. Does NOT choose, rank, or explain the next
+  issue to work on or why it's blocked (use triage-ready); does NOT run
+  claim-then-prove-lease-ownership safety (use claim-safety); does NOT drive an issue through
+  the plan->dev->validate->ship pipeline or open a PR (use smith or stage skills); does NOT
+  report the current stage or what's in flight (use status).
+allowed-tools: Read, Bash(forge:*)
+---
+
+# 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
+
+| Need | Command |
+|------|---------|
+| Create an issue | `forge issue create --title "…" --type <task\|bug\|epic\|decision>` |
+| Inspect one issue | `forge issue show <id> [--json]` |
+| List / filter issues | `forge issue list [--status … --type … --priority … --label …] [--json]` |
+| Full-text search | `forge issue search "…" [--json]` |
+| Backlog counts | `forge issue stats [--json]` |
+| Claim work (DB-enforced lease) | `forge issue claim <id>` |
+| Release a claim | `forge issue release <id>` |
+| Update fields | `forge issue update <id> [flags]` |
+| Add a handoff note | `forge issue comment <id> "…"` |
+| Close (one or many) | `forge issue close <id...> --reason "…"` |
+| Dependencies | `forge issue dep add\|remove <id> <blocks-id>` |
+
+## Create — the flags that matter
+
+```bash
+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"
+```
+
+| Flag | Meaning | Default |
+|------|---------|---------|
+| `--title "…"` | Human title (a bare leading positional also works) | minted id |
+| `--type <…>` | `task` · `bug` · `epic` · `decision` | `task` |
+| `--priority <…>` | `P0`..`P4` (or bare `0`..`4`); `P0` is highest | unset |
+| `--label "a,b"` | Comma-separated set — one flag, split on `,` (repeats do NOT accumulate) | none |
+| `--body "…"` | Long description (`--description` is an accepted alias) | empty |
+| `--assignee <who>` | Persistent assignee | unset |
+| `--acceptance "…"` | Acceptance criteria (`--design`, `--notes` also persist) | unset |
+| `--parent <id>` | Parent/epic id | none |
+
+`--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:
+
+| Old verb | Forge equivalent |
+|----------|------------------|
+| `label` (add/remove) | **No subcommand** — pass the full set via `--label "a,b"` on `create`/`update` (last-value-wins). |
+| `reopen` | `forge issue update <id> --status open`. |
+| `delete` | **Unsupported by design** — the kernel is append-only/event-sourced. Use `forge issue close <id> --reason "…"` instead. |
+
+## 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.
+
+| Knob | Default | How to change |
+|------|---------|---------------|
+| **Default type** | `task` (kernel default) | Decide your create convention — e.g. always pass `--label feature` for user-facing work (feature is a label, not a canonical type), `--type bug` for regressions. |
+| **Default priority** | unset | Adopt a house scale (e.g. new work opens at `P2`, incidents at `P0`) and always pass `--priority`. |
+| **Fields required on create** | `--title` only | Require `--acceptance` (and `--label`/`--assignee`) on every create so issues are actionable from birth. |
+| **Id / reference convention** | kernel-minted ids | Standardize how you cite issues in commits/PRs (e.g. `Closes <id>`) and whether you pass an explicit `--id`. |
+| **Label taxonomy** | free-form | Pin an allowed label set your team agrees on and pass it consistently via `--label "a,b"`. |

package/skills/issue-basics/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "Open a bug ticket for the checkout 500 error and mark it P0",
+    "should_trigger": true
+  },
+  {
+    "query": "Add a note to forge-abc123 documenting why we chose JWT",
+    "should_trigger": true
+  },
+  {
+    "query": "Show me all open issues tagged backend",
+    "should_trigger": true
+  },
+  {
+    "query": "Reopen forge-77, it wasn't actually fixed",
+    "should_trigger": true
+  },
+  {
+    "query": "Add a dependency so forge-12 is blocked by forge-9",
+    "should_trigger": true
+  },
+  {
+    "query": "Claim forge-abc so I can start on it",
+    "should_trigger": true
+  },
+  {
+    "query": "What's the next ready issue I should pick up?",
+    "should_trigger": false
+  },
+  {
+    "query": "Explain why forge-55 is still blocked and what to unblock first",
+    "should_trigger": false
+  },
+  {
+    "query": "Claim this issue and confirm I hold the lease before I change anything",
+    "should_trigger": false
+  },
+  {
+    "query": "Drive forge-30 all the way through to a merged PR",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow right now and what's in flight?",
+    "should_trigger": false
+  }
+]