forge-workflow 0.0.9 → 0.1.0-beta.2

package/skills/smith/references/autonomy-and-gates.md

@@ -0,0 +1,94 @@
+# Autonomy calibration & human gates — reference
+
+Read this when you are calibrating how much to involve the human on a specific
+issue, or when you need the exact gate commands and IDs. `SKILL.md` carries the
+procedure; this file carries the lookup tables and the reasoning behind them.
+
+## The three human gates
+
+Forge registers three human gates in the runtime graph as **approval-satisfied
+events** (`requires: []`), additive to the evidence exit-gates. They are the
+points where smith pauses and hands control to the human.
+
+| Gate | Fires | What the human is deciding |
+|------|-------|----------------------------|
+| `gate.intent` | before planning / brainstorm | Do we agree on the goal, and on the autonomy tier smith proposed, before any design work? |
+| `gate.plan-approval` | after the design doc + task DAG exist, before `dev` | Is this plan the right one (approve), or should it be redirected? |
+| `gate.merge` | after `review`, before merge | Is the PR good to merge? |
+
+The evidence exit-gates — `gate.plan-exit`, `gate.dev-exit`,
+`gate.validate-exit`, `gate.ship-entry` — are a different kind: they are
+satisfied by artifacts *inside* the stage skills (a design doc, TDD tests,
+validation output), not by a human. Smith relies on each stage skill's own exit
+checks for those and does not gate on them itself.
+
+### Why gates are events, not prose
+
+Each approval is written to the issue's event stream as a durable
+`gate.approved` / `gate.rejected` record. That is what makes a gated run
+**resume-safe**: if smith is interrupted by a crash or a context compaction, it
+re-reads the event with `check` / `status` on resume and knows whether it may
+proceed — instead of re-asking the human or guessing from memory. Prose in a
+transcript cannot survive a compaction; an event can.
+
+### Gate commands
+
+```bash
+forge gate check <issue> <gate>              # exit 0 iff the gate is DISABLED or APPROVED
+forge gate approve <issue> <gate> [--reason] # human records approval (durable event)
+forge gate reject  <issue> <gate> --reason   # human sends the work back
+forge gate status  <issue> [--json]          # list this issue's gate events (who/when)
+forge gate enable|disable <gate-id>          # repo default toggle: workflow.gates.<id>.enabled
+```
+
+`check` is the enforcement primitive smith calls before advancing past a gate. It
+exits 0 when the gate is disabled for the repo *or* an approval event exists, so a
+disabled gate simply falls through — that is how a lean tier skips a checkpoint.
+
+## Autonomy calibration — stakes → gate density
+
+Match checkpoint density to what is at stake. A one-line docs fix and a risky
+refactor need very different amounts of oversight: forcing the docs fix through a
+full brainstorm wastes everyone's time, while letting the refactor run unattended
+risks a large wrong turn. Smith reads the issue's **size × importance ×
+complexity**, proposes a tier at `gate.intent`, and the human confirms or
+overrides.
+
+| Tier | Stakes read | Enforced human gates | Extra checkpoints |
+|------|-------------|----------------------|-------------------|
+| **Lean** | small · simple · low-importance (docs typo, one-line fix) | just `gate.merge`, or none under CI | skip the intent brainstorm; lean on CI + the evidence exit-gates |
+| **Standard** (default) | an ordinary feature or bug | `gate.intent` · `gate.plan-approval` · `gate.merge` | the evidence exit-gates as configured |
+| **High** | large · important · or complex (critical feature, risky refactor) | all three human gates, enabled | per-milestone / per-task human check-ins (pause + `forge comment`), an explicit pre-ship review pass |
+
+### How a tier is enacted
+
+The tier maps to *which gate events are required* for this issue. The human enacts
+add/drop with `forge gate enable|disable <gate-id>` (the repo default), and smith
+enforces every *enabled* gate via `check`. Because approvals are per-issue events,
+the human can add or drop a checkpoint mid-flight and smith re-reads it on the next
+step — the calibration is not frozen at planning time.
+
+### Why uncertainty adds gates rather than removing them
+
+Smith only *proposes* a tier; it never lowers oversight on its own. When its read
+of size/importance/complexity is low-confidence, it defaults to **more**
+checkpoints, because an unwanted extra approval is a few seconds of the human's
+time, while a missed one can mean a large amount of wasted or wrong work. The
+human always wins the final say.
+
+## Composition map — smith invents nothing
+
+Every step is an existing skill or `forge` verb; smith only sequences them.
+
+| Step | Composed skill / verb |
+|------|-----------------------|
+| Pick work | `triage-ready` (`forge issue ready` / `blocked` / `stats`) |
+| Claim + prove ownership | `claim-safety` (`forge claim` → `forge issue owns`) |
+| Human gates | `forge gate check` / `approve` / `reject` / `status` |
+| Plan | `plan` (intent brainstorm → design doc → task DAG) |
+| Build | `dev` (per-task implementer → spec → quality TDD) |
+| Validate | `validate` (types · lint · security · tests) |
+| Ship | `ship` (push + PR) |
+| Review | `review` (address CI / bot feedback) |
+| Verify | `verify` (post-merge health) |
+| Release readiness | `forge release check --target <version> --json` |

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

@@ -1,7 +1,18 @@
 ---
 name: sonarcloud
-description: Pull issues, metrics, quality gates, and analysis data from SonarCloud
-tools: []
+description: >
+  Query SonarCloud code-quality data via the `/sonarcloud` slash command — the fast in-context
+  lookup for a project, branch, or PR. Handles `issues`, `metrics`, `gate` (pass/fail + failed
+  conditions), `health`, `pr <number>`, `hotspots`, `history`, plus `--branch`, `--severity`,
+  `--type`, `--new-code` filters. Use the moment the user types `/sonarcloud ...` or asks in
+  plain language: "what does SonarCloud say about this PR", "check the SonarCloud quality gate
+  before I ship", "SonarCloud blocker/critical bugs on develop", "new-code SonarCloud issues
+  on PR 214". Only READS/reports — does NOT fix findings or reply-to/resolve PR threads (that
+  is `review`); it is the lightweight command surface, NOT the deep-analysis session
+  correlating findings with local source or history trends (that is `sonarcloud-analysis`).
+  Not for local SAST scans of your own code, nor the Forge issue tracker (`forge issue ...`,
+  "open/ready issues") — here those bare words always mean SonarCloud.
+allowed-tools: Bash, Read, Grep, Glob, WebFetch
 ---
 
 # SonarCloud Query Command
@@ -41,7 +52,7 @@ Pull code quality data from SonarCloud. Requires `SONARCLOUD_TOKEN` environment
    - Optional filters (branch, severity, type, new-code, etc.)
 2. Check for `SONARCLOUD_TOKEN` environment variable. If not set, inform user.
 3. Check for `SONARCLOUD_ORG` environment variable or ask user for organization key.
-4. Execute the appropriate API call using curl or the TypeScript client at `next-app/src/lib/integrations/sonarcloud.ts`
+4. Execute the appropriate API call against the SonarCloud REST API (see the API Reference section below for endpoints)
 5. Format and present results clearly:
    - For issues: Group by severity/type, show file, line, message
    - For metrics: Show as table with metric name and value

package/skills/sonarcloud/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "/sonarcloud gate my-project",
+    "should_trigger": true
+  },
+  {
+    "query": "/sonarcloud pr befach-web 214 --new-code",
+    "should_trigger": true
+  },
+  {
+    "query": "What does SonarCloud say about this pull request? Just the quality gate and the blocker issues, quick.",
+    "should_trigger": true
+  },
+  {
+    "query": "Show SonarCloud bugs and vulnerabilities on the develop branch for the api project",
+    "should_trigger": true
+  },
+  {
+    "query": "Any new-code SonarCloud issues on PR 88 before I ship?",
+    "should_trigger": true
+  },
+  {
+    "query": "Pull the SonarCloud coverage and code-smell numbers for my-project so I can eyeball them",
+    "should_trigger": true
+  },
+  {
+    "query": "Open an isolated SonarCloud deep-dive: correlate every flagged vulnerability with the actual source files, walk the analysis history for coverage trends, and hand back a synthesized technical-debt report",
+    "should_trigger": false
+  },
+  {
+    "query": "SonarCloud flagged issues on PR 214 — fix them, reply to each review thread, and mark them resolved",
+    "should_trigger": false
+  },
+  {
+    "query": "Run a SAST security scan over my code and list the vulnerabilities you find",
+    "should_trigger": false
+  },
+  {
+    "query": "Show me the open issues that are ready to work on next",
+    "should_trigger": false
+  },
+  {
+    "query": "Run lint and type-check and the test suite before I ship this branch",
+    "should_trigger": false
+  }
+]

package/skills/sonarcloud-analysis/SKILL.md

@@ -1,13 +1,18 @@
 ---
 name: sonarcloud-analysis
 description: >
-  Pull issues, metrics, quality gates, and analysis data from SonarCloud. ALWAYS
-  use this skill when the user mentions SonarCloud, asks about code quality metrics,
-  wants to check PR quality gates, or needs to review security vulnerabilities and
-  technical debt from static analysis. Also trigger during /review workflow when
-  SonarCloud issues need addressing. Trigger on phrases like "SonarCloud",
-  "quality gate", "code quality metrics", "technical debt", "coverage report",
-  "static analysis issues", "security vulnerabilities from scan".
+  SonarCloud deep-dive via its REST API: pull open issues (bugs, vulnerabilities, code
+  smells), coverage/duplication metrics, quality-gate pass/fail with failed thresholds,
+  security hotspots, and measure/analysis history for a whole project, branch, or PR, then
+  return a ranked summary. Use whenever the user names SonarCloud or asks about code-quality
+  metrics, technical debt, a red/failing quality gate, or static-analysis
+  vulnerabilities/hotspots — e.g. 'why is the SonarCloud gate failing on this PR' or 'pull
+  every BLOCKER vulnerability with file and line'. NOT for: the thin `/sonarcloud <query>
+  <project>` slash command for a quick lookup (sibling 'sonarcloud'); replying to/resolving PR
+  review threads across Greptile, CodeRabbit, or GitHub Actions ('review'); running local
+  lint/type-check/test/security scans pre-ship ('validate'); implementing or patching a
+  flagged issue ('dev'); or an external market/competitor report on SonarSource or DevSecOps
+  vendors ('parallel-deep-research').
 category: Code Quality
 tags: [sonarcloud, code-quality, issues, metrics, security]
 context: fork
@@ -77,12 +82,12 @@ export SONARCLOUD_ORG="your-org"
 export SONARCLOUD_PROJECT="your-project"
 
 # Common queries
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/issues/search?organization=$ORG&componentKeys=$PROJECT&resolved=false"
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/measures/component?component=$PROJECT&metricKeys=bugs,coverage"
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$PROJECT"
+curl -H "Authorization: Bearer $SONARCLOUD_TOKEN" \
+  "https://sonarcloud.io/api/issues/search?organization=$SONARCLOUD_ORG&componentKeys=$SONARCLOUD_PROJECT&resolved=false"
+curl -H "Authorization: Bearer $SONARCLOUD_TOKEN" \
+  "https://sonarcloud.io/api/measures/component?component=$SONARCLOUD_PROJECT&metricKeys=bugs,coverage"
+curl -H "Authorization: Bearer $SONARCLOUD_TOKEN" \
+  "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$SONARCLOUD_PROJECT"
 ```
 
 ## Endpoints

package/skills/sonarcloud-analysis/evals/evals.json

@@ -1,50 +1,46 @@
 [
   {
-    "query": "Check the SonarCloud quality gate status for our latest PR — I want to see if there are any blockers before we can merge, especially around security vulnerabilities and code coverage",
+    "query": "Why is our quality gate red on this pull request? Break down exactly which conditions failed and by how much.",
     "should_trigger": true
   },
   {
-    "query": "Pull the SonarCloud analysis results for our project — show me all the critical and major security vulnerabilities found in the last scan, with file locations and remediation guidance",
+    "query": "How much technical debt has piled up in the codebase, and which files carry the worst maintainability rating?",
     "should_trigger": true
   },
   {
-    "query": "We're in /review and SonarCloud flagged some issues — get the full list of code smells, bugs, and vulnerabilities from the latest analysis so I can address them before the quality gate passes",
+    "query": "Give me the coverage and duplication numbers for the develop branch and flag the modules that regressed.",
     "should_trigger": true
   },
   {
-    "query": "What's our current technical debt ratio in SonarCloud? Show me the metrics dashboard — maintainability rating, reliability rating, security rating, and coverage percentage",
+    "query": "List every unresolved BLOCKER and CRITICAL vulnerability SonarCloud found, with file and line, so I know what to fix first.",
     "should_trigger": true
   },
   {
-    "query": "The SonarCloud quality gate is failing on our PR — pull the specific issues that are blocking it and show me what needs to be fixed, sorted by severity",
+    "query": "Pull the security hotspots that still need review and summarize the risk for each.",
     "should_trigger": true
   },
   {
-    "query": "Get the SonarCloud code coverage report for our project — I want to see which modules have low coverage and identify the files that need more tests before our next release",
+    "query": "Show me how our reliability and security ratings have trended over the last month of analyses.",
     "should_trigger": true
   },
   {
-    "query": "Implement a new REST API endpoint for user profile management with CRUD operations, input validation, and proper error handling",
+    "query": "/sonarcloud issues checkout-service --severity BLOCKER",
     "should_trigger": false
   },
   {
-    "query": "Search for best practices around implementing OAuth2 PKCE flow in a Node.js application",
+    "query": "Go through all the open PR review threads from Greptile and CodeRabbit, reply to each explaining the fix, and mark them resolved.",
     "should_trigger": false
   },
   {
-    "query": "Write a comprehensive market analysis of the DevSecOps tools landscape covering SAST, DAST, and SCA vendors",
+    "query": "Run lint, type-check, the test suite, and the security scanner and give me fresh output before I ship this branch.",
     "should_trigger": false
   },
   {
-    "query": "Scrape https://docs.sonarcloud.io and extract the full list of supported languages and analysis rules",
+    "query": "Fix the SQL-injection vulnerability SonarCloud flagged in login.ts and add a regression test.",
     "should_trigger": false
   },
   {
-    "query": "Build a structured company profile for SonarSource — return JSON with founding year, funding, products, and competitive positioning",
-    "should_trigger": false
-  },
-  {
-    "query": "Add proper citations to docs/research/security-audit-findings.md following our project's citation standards",
+    "query": "Produce a competitive market report comparing SonarCloud, Snyk, and Codacy for our tooling decision.",
     "should_trigger": false
   }
 ]

package/skills/status/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: status
+description: >
+  Report where the project stands and what work is in flight -- the Forge status snapshot.
+  Reach for this at session start or whenever the user says "/status", "where am I", "what's
+  in progress", "catch me up", "resume work", or "what changed recently". It surfaces the workflow stage, your active/claimed issues, all issues ranked by
+  composite score with conflict-risk flags, stale already-merged issues (which it closes), and
+  recent commits. Use it to ORIENT and decide the next move -- it reports state; it does not
+  plan, develop, or claim issues. Not for: routing to a stage skill or documenting the full
+  issue-verb surface (kernel); ranking and EXPLAINING a single next-ready or blocked issue to
+  hand off (triage-ready); everyday create/update/list/close/comment/search issue ops
+  (issue-basics); the Hermes harness's token-bounded orient/recap contract (hermes-forge); or
+  the post-merge CI health check that closes issues after a merge lands (verify).
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+Check where you are in the project and what work is in progress.
+
+# Status Check
+
+This skill helps you understand the current state of the project before starting new work.
+
+## Usage
+
+```bash
+/status
+```
+
+## What This Skill Does
+
+## Step 0: Sync team state
+
+```bash
+# Sync team state before showing status
+forge sync || true
+```
+
+### Step 1: Smart Status (ranked issues with conflict detection)
+
+```bash
+bash scripts/smart-status.sh
+```
+This command dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed.
+
+For full context on any issue: `forge show <id>`
+
+### Step 1b: Reconcile stale in-progress issues
+
+Check if any in-progress issues were already merged but not closed (can happen if `/verify` was skipped or backup was restored from stale snapshot):
+
+```bash
+# Detect default branch dynamically (prefer main over master)
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+if [ -z "$DEFAULT_BRANCH" ]; then
+  if git rev-parse --verify main >/dev/null 2>&1; then DEFAULT_BRANCH="main"
+  elif git rev-parse --verify master >/dev/null 2>&1; then DEFAULT_BRANCH="master"
+  else echo "ERROR: No main or master branch found -- skipping stale reconciliation" >&2; DEFAULT_BRANCH=""; fi
+fi
+
+# For each in_progress issue, check if its PR was already merged
+if [ -n "$DEFAULT_BRANCH" ]; then
+  forge list --status=in_progress --json 2>/dev/null | jq -r '.[].id' | while read id; do
+    # Search git log for the issue ID in commit messages (fixed-strings for literal match)
+    if git log --oneline --first-parent "$DEFAULT_BRANCH" --fixed-strings --grep="$id" | grep -q .; then
+      echo "STALE: $id -- found in git history, likely already merged"
+    fi
+  done
+fi
+```
+
+If stale issues are found, close them:
+```bash
+forge close <id> --force --reason="Already merged -- detected during status reconciliation"
+```
+
+### Step 2: Review Recent Commits
+```bash
+git log --oneline -10
+```
+
+### Step 3: Determine Context
+- **New feature**: No active work, ready to start fresh
+- **Continuing work**: In-progress issues found, resume where left off
+- **Review needed**: Work marked complete, needs review/merge
+
+### Team context
+
+Show current developer's active work and team overview:
+
+```bash
+# Show my active issues
+forge team workload --me 2>&1 || true
+
+# One-line team summary
+forge team dashboard 2>&1 | head -5 || true
+```
+
+## Next Steps
+
+- **If starting new work**: Run `/plan <feature-name>`
+- **If continuing work**: Resume with appropriate phase command
+- **If reviewing**: Run `/review <pr-number>` (the pre-merge doc gate is embedded in `/ship` and `/review`)

package/skills/status/evals/evals.json

@@ -0,0 +1,50 @@
+[
+  {
+    "query": "/status",
+    "should_trigger": true
+  },
+  {
+    "query": "where am I on this project right now?",
+    "should_trigger": true
+  },
+  {
+    "query": "catch me up -- what's in progress and what got merged recently?",
+    "should_trigger": true
+  },
+  {
+    "query": "I stepped away for a few days, give me the current state of the work before I dive back in",
+    "should_trigger": true
+  },
+  {
+    "query": "show me my active issues and which stage we're at",
+    "should_trigger": true
+  },
+  {
+    "query": "are there any in-progress issues that were already merged and should be closed?",
+    "should_trigger": true
+  },
+  {
+    "query": "what's the single best next issue to start, and explain why that one?",
+    "should_trigger": false
+  },
+  {
+    "query": "why is issue forge-456 blocked -- what's it waiting on?",
+    "should_trigger": false
+  },
+  {
+    "query": "route me to the correct Forge stage skill for opening a PR",
+    "should_trigger": false
+  },
+  {
+    "query": "create an issue titled 'fix flaky login test' and tag it a bug",
+    "should_trigger": false
+  },
+  {
+    "query": "the PR just merged to master -- confirm CI is green and close the linked issues",
+    "should_trigger": false
+  },
+  {
+    "query": "keep an eye on PR #88 until its checks and review threads settle",
+    "should_trigger": false
+  }
+]

package/skills/triage-ready/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: triage-ready
+description: >
+  Surfaces, ranks, and EXPLAINS the single best next issue in a Forge project — strictly
+  read-only. Recomputes the live ready queue and explains what is blocked via `forge issue
+  ready`/`blocked`/`stats`/`show`, always against the live kernel, never `forge board`.
+  Recommends ONE issue with a one-line reason, then hands off; never claims, comments, closes,
+  or mutates. Use when the user asks "what should I work on", "what's next", "what's ready",
+  "pick/triage my next task", "top of the ready queue", "which issue should I start", "why is
+  this issue blocked", or "what's blocking the most work". NOT for claiming or taking
+  ownership of the pick (use claim-safety), not for everyday issue
+  create/update/list/search/close/comment/dep CRUD (use issue-basics), not for reporting the
+  current workflow stage or "where am I / what's in flight" (use status), not for orienting a
+  whole session or routing to stage skills (use kernel), not for driving an issue to a merged
+  PR (use smith).
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Triage: what should I work on next
+
+A read-only orientation skill. It answers "what is the single best thing to work
+on right now, and *why*?" and hands the pick off to `claim-safety` / `dev` — it
+never mutates the store itself.
+
+Readiness in the Forge kernel is a **derived read model**: an issue is ready only
+when every dependency is satisfied, it is unclaimed (no live lease), it is a
+claimable type (epics and decisions never enter the queue), and no defer window
+holds it back. Because it is derived, **always recompute it** — never trust a
+cached "status == ready". Recompute means: run the query fresh each time.
+
+## Do NOT use `board`
+
+`forge board` reads a legacy snapshot store, not the live kernel, so its readiness
+can be stale or wrong. This skill uses `forge issue ready`, `forge issue blocked`,
+and `forge issue stats` exclusively.
+
+## Procedure
+
+### 1. Take the pulse
+
+```bash
+forge issue stats --json
+```
+
+Returns `data.counts` (`open`/`done`/`cancelled` — keys are present only when
+non-zero, and there is no `in_progress` bucket: claimed work stays in status
+`open` and is surfaced via `active_claims`), `ready_count`, `blocked_count`, and
+`active_claims`. A high `blocked_count` relative to
+`ready_count` is your signal that dependency repair (not new work) is the real
+bottleneck — hand off to `dependency-planning` / `backlog-hygiene`.
+
+### 2. Rank the ready queue
+
+```bash
+forge issue ready --json
+```
+
+`data.issues[]` comes back ordered by `rank` (priority ascending, then id), each
+carrying `id`, `title`, `type`, `priority` (`P0`..`P4`), `rank`, `blocked`,
+`claimed_by`, `parent_id`, `labels[]`, and `dependencies[]`. The top item is your
+default pick. Surface the top few (see Fork points for how many), not the whole
+list.
+
+### 3. Explain WHY the top item is ready
+
+Do not just name it — justify it. Pull its full record:
+
+```bash
+forge issue show <id> --json
+```
+
+State the reason in one sentence, drawn from the record:
+
+- **Priority / rank** — `P0` at `rank` 0 outranks everything below it.
+- **Dependencies satisfied** — every id in `dependencies[]` is closed/done, so
+  nothing gates it (`blocked: false`).
+- **Unclaimed** — `claimed_by` is `null`, so no other agent holds the lease.
+- **Claimable type** — it is a `task`/`feature`/`bug`, not an `epic`/`decision`.
+
+### 4. Explain why the runners-up are NOT ready
+
+```bash
+forge issue blocked --json
+```
+
+For a blocked item, name the specific unmet dependency (from its `dependencies[]`
+cross-referenced against `forge issue show`) — e.g. "blocked by `forge-x` which is
+still `open`". This turns triage into an actionable map: the fastest way to unlock
+the most work is usually to finish the shared blocker.
+
+### 5. Hand off
+
+Recommend ONE issue with its one-line justification, then stop. The caller claims
+it (via `claim-safety`) and executes (via `dev`). Triage does not claim, comment,
+or close — it is strictly read-only.
+
+## Reliability
+
+- **Recompute, never cache.** Readiness is derived; re-run `forge issue ready`
+  every session rather than remembering a prior "ready" verdict.
+- **Respect non-claimable types.** Epics and decisions never appear in `ready`
+  (the queue surfaces only claimable types — `task`/`bug`), so do not hand them
+  off as work. There is no `claimable` field in the CLI JSON; this is behavioral,
+  not a flag you can read.
+- **Check the envelope.** Every `--json` reply carries `ok`; on `ok:false` read
+  `error.message` and retry the query rather than guessing at state.
+- **Read-only.** This skill runs only `stats`/`ready`/`blocked`/`show`. If a fix is
+  needed, hand off — never mutate here.
+
+## Fork points
+
+Editable knobs — change these to carve your own triage policy. This skill is a
+canonical source you fork, not a fixed ladder.
+
+| Knob | Default | How to change |
+|------|---------|---------------|
+| **Readiness query / filters** | `forge issue ready` (whole queue) | Narrow to a slice, e.g. `forge issue list --status open --priority P0 --json` or post-filter `ready` output by `labels[]`/`type` to focus one workstream. |
+| **How many items to surface** | Top 3 by `rank` | Raise for a broad standup view, lower to 1 for a strict "next task only" hand-off. |
+| **Stale threshold** | `forge issue stale --days 14` | Change `--days` to flag idle in-progress work sooner/later; surface stale claims as a caveat before recommending fresh work. |
+| **Priority ordering** | Kernel `rank` (priority, then id) | Re-rank the `ready` list by your own weights — epic proximity (`parent_id`), label, or age — before picking. |
+| **Blocked-explain depth** | One hop (direct unmet deps) | Trace transitively via repeated `forge issue show` when you need the full blocking chain; hand to `graph-forensics` for deep `explain`. |

package/skills/triage-ready/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "I just sat down at this repo — what's the highest-priority thing I can actually start right now?",
+    "should_trigger": true
+  },
+  {
+    "query": "Give me the top few off the ready queue and tell me why the first one is unblocked.",
+    "should_trigger": true
+  },
+  {
+    "query": "Why can't I start forge-2agy.2.2 yet? What's holding it up?",
+    "should_trigger": true
+  },
+  {
+    "query": "The backlog feels stuck — is it mostly blocked, and which one dependency would unlock the most work?",
+    "should_trigger": true
+  },
+  {
+    "query": "Pick my next task and justify the choice, don't grab it yet.",
+    "should_trigger": true
+  },
+  {
+    "query": "Claim forge-abc123 for me and confirm I actually hold the lease before I start editing.",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a P1 bug titled 'login returns 500' and add a comment linking the repro.",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow right now and what work is in flight?",
+    "should_trigger": false
+  },
+  {
+    "query": "Search every issue mentioning 'oauth' and list the open ones.",
+    "should_trigger": false
+  },
+  {
+    "query": "Take forge-xyz all the way through to a merged PR.",
+    "should_trigger": false
+  }
+]