forge-workflow 0.0.9 → 0.1.0-beta.2

package/skills/shepherd/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: shepherd
+description: >
+  Monitor an already-reviewed OPEN pull request toward merge: read the CI/check rollup and the
+  branch-protection required-check set, take at most one idempotent action (re-run a flaky
+  required check, or post a status reply to a thread), then declare MERGE_READY, PENDING, or
+  escalate. Use when the user says "is PR #123 ready to merge yet?", "poll/watch the checks on
+  my PR", "the required CI job is flaky — kick off a re-run", "keep an eye on this PR until
+  it's green", "babysit the checks after /review", "shepherd PR 45", or "monitor the PR toward
+  merge (rebase if behind, --auto-rebase)". NEVER merges (the human merges in the GitHub UI),
+  edits code, or resolves review threads. Do NOT use to fix or reply-and-resolve PR feedback
+  from Greptile/CodeRabbit/SonarCloud — that is `review`; nor to open/push the PR — that is
+  `ship`; nor for the post-merge "CI green on master + close issues" check — that is `verify`;
+  nor for a general "where am I / what's in flight" report — that is `status`.
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+Run one bounded monitor pass over a pull request: read CI and check state, take at most one idempotent action, then hand off. Never merges and never resolves review threads.
+
+# Shepherd
+
+`shepherd` is a **utility command, not a workflow stage.** It automates the polling / rerun / escalation loop that today is done by hand after `/review`. It does **not** replace `/review` (which still owns semantic review and its stage transition) and does **not** perform the pre-merge doc gate (embedded in `/ship` and `/review`).
+
+## Usage
+
+```bash
+forge shepherd <pr-number>
+forge shepherd <pr-number> --auto-rebase   # opt-in, default OFF
+```
+
+## Bounded-pass model (one pass = one invocation)
+
+Each `forge shepherd <pr>` invocation is **ONE discrete bounded pass**: it reads PR state, takes at most the allowed Tier-A action, then **exits**. It never sits in-process polling "until merge-ready."
+
+This mirrors the project's documented ergonomic from `/review`, the pre-merge gate, and the Greptile process: **poll briefly, then stop and hand off.** Any pass that finds checks still pending exits as `PENDING`, and the next scheduled pass picks up where it left off.
+
+A `--watch` affordance, if you want one, lives in an **external scheduler** (e.g. cron or a `/loop`) that re-invokes the bounded pass on an interval with debounce (>= 60s between passes, cancel-in-progress). There is no in-process infinite loop.
+
+## What it never does
+
+- **Never merges.** There is no merge action and no server-side auto-merge latch. The shepherd terminates at `MERGE_READY` and hands off to the human, who merges in the GitHub UI (mirroring the pre-merge gate's merge handoff).
+- **Never resolves review threads.** It may post a status **reply** to a thread (via the existing `.claude/scripts/review-resolve.sh reply` helper), but thread **resolution** is semantic and stays with `/review`.
+
+## Action ladder
+
+- **Tier-A (autonomous, idempotent, reversible):** re-run a flaky **required** check via `gh run rerun --failed` (capped by a rerun budget). Post status replies to threads (reply only).
+- **Tier-B (opt-in per-flag, default OFF):** `--auto-rebase` rebases onto the base and force-pushes with lease. Preconditions: clean working tree, HEAD unchanged during the pass. A lease rejection is a **hard-stop + escalate** — the shepherd never re-arms the lease, because doing so would clobber the concurrent human push the lease exists to protect.
+- **Tier-C (human escalation):** merge conflicts, required-check failures a rerun did not fix, an unreadable required-check set, unknown mergeability, auth/scope failures, oscillation, and budget exhaustion all stop and escalate with context posted to the PR.
+
+## Merge-readiness gate
+
+Merge-ready is declared **only** when the branch-protection required-check set is **known** AND all of it is green AND the branch is not behind base. The required set is read from `gh api repos/{owner}/{repo}/branches/{base}/protection/required_status_checks`. If branch protection is unreadable (insufficient token scope, or the branch is not protected), the shepherd does **not** guess — it escalates with the readable rollup attached.
+
+## Concurrency & safety
+
+- The advisory `shepherd:active` marker is **not** mutual exclusion. The real guard is a per-action HEAD-SHA re-read: before any mutating action the shepherd re-reads the head SHA, and if HEAD moved since the pass started it **aborts** the action.
+- Auth taxonomy: token expiry (401) pauses and surfaces; insufficient scope (403) is a permanent **hard-stop**; a secondary rate limit (403 + `Retry-After`) honors the delay and resumes on the next pass.
+
+## Per-harness behavior
+
+- **Claude Code / Codex:** invoke `forge shepherd <pr>` directly; an external scheduler may drive repeated bounded passes.
+- **Cursor:** manually-invoked only. Run `forge shepherd <pr>` from a terminal — there is no polling-loop affordance and no hook reliance on this surface.
+
+## State
+
+Progress is durable in GitHub: PR **comments** and **labels** plus `git`. There is no separate local state store.

package/skills/shepherd/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Is PR #212 ready to merge yet?",
+    "should_trigger": true
+  },
+  {
+    "query": "The lint check on my PR keeps failing intermittently — kick off a re-run of the failed jobs.",
+    "should_trigger": true
+  },
+  {
+    "query": "Keep an eye on pull request 88 and tell me when all the required checks pass.",
+    "should_trigger": true
+  },
+  {
+    "query": "I just wrapped up /review on this PR — babysit the checks and escalate if it isn't mergeable.",
+    "should_trigger": true
+  },
+  {
+    "query": "Shepherd PR 300 and rebase it onto master if it's behind.",
+    "should_trigger": true
+  },
+  {
+    "query": "Fix all the CodeRabbit and Greptile comments on my PR and resolve each review thread.",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR just merged to master — confirm CI is green there and close the linked issue.",
+    "should_trigger": false
+  },
+  {
+    "query": "Push my validated feature branch and open a pull request from the template.",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow and what work is still in flight right now?",
+    "should_trigger": false
+  },
+  {
+    "query": "Show me the SonarCloud issues flagged on this PR.",
+    "should_trigger": false
+  }
+]

package/skills/ship/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: ship
+description: >
+  Forge SHIP stage: push the validated feature branch and open a PR populated from the
+  project's OWN PR template (design-doc link, Forge issue IDs, real test/commit data), then
+  hand off for MANUAL merge; never merges or auto-merges. Use once /validate passes and you
+  want a PR on the board. Triggers: "ship it", "ship this branch", "open the PR", "push and
+  open a PR", "gh pr create", "checks passed, now cut the PR". Runs branch-freshness +
+  parallel-PR merge-sim checks, force-with-lease push, records the ship->review handoff, then
+  stops. One stage only; not for: the whole plan->dev->validate->ship->review pipeline or
+  drive-to-done (smith); type-check/lint/tests/security first (validate); addressing PR
+  comments or resolving Greptile/SonarCloud/CodeRabbit threads on an existing PR (review);
+  babysitting an open PR toward merge (shepherd); post-merge CI health check + closing issues
+  (verify); reverting an already-shipped change (rollback). If the PR already exists, this is
+  not the skill.
+allowed-tools: Bash, Read, Edit, Grep, Glob
+---
+
+Push code and create a pull request with full context and documentation links.
+
+# Ship
+
+This skill creates a PR after validation passes.
+
+## Usage
+
+```bash
+/ship
+```
+
+```
+<HARD-GATE: /ship entry>
+Do NOT create PR until:
+1. /validate was run in this session with all four outputs shown (type, lint, tests, security)
+2. All checks confirmed passing — not assumed, not "was passing earlier"
+3. Forge issue is in_progress (`forge issue show <id>` confirms status)
+4. git branch --show-current output is NOT main or master
+</HARD-GATE>
+```
+
+## What This Skill Does
+
+### Step 1: Verify /validate Passed
+Ensure all four validation checks completed successfully with fresh output in this session.
+
+### Step 2: Freshness Check — Is Branch Still Current?
+
+Even though /validate rebased onto the base branch, time may have passed since then (user reviewed design doc, took a break, etc.). This lightweight check catches staleness before pushing.
+
+```bash
+BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
+if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
+git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify freshness"; exit 1; }
+BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
+```
+
+- If `BEHIND > 0`: **STOP**. Print: "$BASE has advanced since /validate ($BEHIND new commits). Run /validate again to rebase and re-check."
+- If `BEHIND = 0`: Continue to push.
+- If fetch fails: the `|| { ...; exit 1; }` guard catches this — **STOP**. Do NOT push without confirming freshness.
+
+This is NOT a full rebase — just a check. The rebase happens in /validate where the full test suite runs afterward.
+
+### Parallel PR coordination (soft block)
+
+Before creating the PR, check merge readiness:
+
+```bash
+# Run merge simulation against base branch
+bash scripts/pr-coordinator.sh merge-sim "$(git branch --show-current)" 2>&1
+
+# Show recommended merge order
+bash scripts/pr-coordinator.sh merge-order 2>&1 || true
+
+# Auto-label the PR after creation (called after gh pr create below)
+# bash scripts/pr-coordinator.sh auto-label <issue-id>
+```
+
+If merge simulation finds conflicts:
+- Display conflicted files
+- Ask: "Merge conflicts detected with base branch. These PRs should merge first: [list]. Proceed with PR creation anyway? (y/n)"
+- If `n`: exit cleanly
+- If `y`: log override via `forge comment <id> "Ship override: creating PR despite merge conflicts"`, then continue
+
+After PR creation completes:
+```bash
+# Auto-label the newly created PR
+bash scripts/pr-coordinator.sh auto-label <issue-id>
+
+# Check for stale worktrees (informational)
+bash scripts/pr-coordinator.sh stale-worktrees 2>&1 || true
+```
+
+### Step 3: Record PR Handoff
+```bash
+forge comment <id> "PR created: <pr-url>. Awaiting review and merge verification."
+forge sync
+```
+
+Do not mark the Forge issue done during `/ship`. Completion happens only after merge and post-merge verification.
+
+### Step 4: Push Branch
+
+Use `--force-with-lease` because `/validate` may have rebased the branch, rewriting history. This is safe: it only forces the push if the remote branch hasn't been updated by someone else since the last fetch.
+
+```bash
+git push --force-with-lease -u origin <branch-name>
+```
+
+### Step 5: Create PR Using Project's PR Template
+
+**CRITICAL**: Always use the project's own PR template. Never use a hardcoded body.
+
+**Step 5a: Locate the PR template**
+
+Check for a PR template in the project (in order of precedence):
+```bash
+# Check standard locations
+PR_TEMPLATE=""
+for path in .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md docs/pull_request_template.md pull_request_template.md; do
+  if [ -f "$path" ]; then
+    PR_TEMPLATE="$path"
+    break
+  fi
+done
+```
+
+**Step 5b: Read and populate the template**
+
+If a PR template exists:
+1. **Read the template file** using the Read tool
+2. **Fill in every section** with actual data from the current PR context:
+   - Replace HTML comments (`<!-- ... -->`) with real content
+   - Check applicable checkboxes (`- [x]`)
+   - Fill in Forge issue IDs (replace `forge-xxx` with actual ID)
+   - Fill in test results, validation status, and other concrete data
+   - Reference the design doc: `docs/work/YYYY-MM-DD-<slug>/plan.md`
+3. **Do NOT remove any sections** — fill them all, even if "N/A"
+4. **Do NOT restructure the template** — keep the project's chosen format
+
+If no PR template exists, use this minimal fallback:
+```
+## Summary
+[1-3 sentences: what this PR does and why]
+
+## Changes
+[Bulleted list of key changes]
+
+## Testing
+[How it was tested, test results]
+
+## Issue
+Closes forge-xxx
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+**Step 5c: Create the PR**
+
+```bash
+gh pr create --title "<type>: <concise description>" --body "<populated-template-content>"
+```
+
+Rules for the PR body:
+- **Use the project's template structure** — never substitute your own format
+- **Fill in concrete data** — commit counts, test results, actual file paths, real Forge IDs
+- **Check applicable checkboxes** — `[x]` for items that apply, `[ ]` for items that don't
+- **Include "Closes forge-xxx"** in the Issue section (required for auto-close in /verify)
+
+### Step 6: Confirm Context and Record Stage Transition
+```bash
+# Confirm the issue carries design + acceptance context (helper when present; otherwise inspect the issue).
+# Only falls back to `forge issue show` when the helper is absent — a real validate failure stays visible.
+if [ -f scripts/beads-context.sh ]; then
+  bash scripts/beads-context.sh validate <id>
+else
+  forge issue show <id>
+fi
+
+# Record the ship→review transition (structured helper when present; kernel-native comment otherwise).
+# The fallback comment mirrors the same envelope the helper emits (Stage:/Summary:/Decisions:/Artifacts:/Next:).
+if [ -f scripts/beads-context.sh ]; then
+  bash scripts/beads-context.sh stage-transition <id> ship review \
+    --summary "<PR created, checks pending>" \
+    --decisions "<template sections filled, issue linked>" \
+    --artifacts "<PR URL, branch name>" \
+    --next "<review focus areas>"
+else
+  forge comment <id> "Stage: ship complete → ready for review
+Summary: <PR created, checks pending>
+Decisions: <template sections filled, issue linked>
+Artifacts: <PR URL, branch name>
+Next: <review focus areas>"
+fi
+```
+
+### Team sync after PR
+
+After PR is created, sync issue state to GitHub and verify 1:1 mapping:
+
+```bash
+# Sync issue state to GitHub
+forge team sync 2>&1 || true
+
+# Verify 1:1 mapping
+forge team verify 2>&1 || true
+```
+
+## Output
+
+`/ship` reports live validation status, branch freshness, Forge issue PR handoff state, push status, PR URL, template sections, linked issue IDs, and CI polling state. Values come from the current branch, issue tracker, and GitHub response; do not copy static IDs, URLs, or branch names into this skill file.
+
+When checks are still pending after the polling window, stop after reporting the PR number and direct the next session to `/review <pr-number>` once automated checks complete or new feedback appears.
+
+## Pre-merge gate (before merge)
+
+Pre-merge is a doc-update **gate/checkpoint**, not a separate stage — run it here, before the PR is handed off for merge, whenever the change touches anything documented:
+
+1. **Finish the docs on the feature branch** (update only what genuinely changed):
+   - `CHANGELOG.md` (always) — entry under `## [Unreleased]` using Keep a Changelog categories, with PR number + issue ID.
+   - `README.md` (user-facing), `docs/reference/API_REFERENCE.md` (API), architecture docs (structural).
+   - `CLAUDE.md` — **USER section only** (between the USER markers); never touch other managed blocks.
+   - `AGENTS.md` (agent config, skills, or cross-agent workflow changes).
+   Commit the doc updates to the feature branch and push.
+2. **Confirm CI is green** — doc commits re-trigger CI; poll briefly (~60s), then hand off if still pending. New review feedback → run `/review` again.
+3. **Sync the issue store** — `forge sync`.
+4. **Hand off for MANUAL merge** — present the PR and stop. **Never run `gh pr merge`; never auto-merge.** The user merges in the GitHub UI, then runs `/verify`.
+
+## Integration with Workflow
+
+```
+Utility: /status  -> Understand current context before starting
+
+Default template:
+  /plan      -> Optional default planner; external planners may satisfy /dev entry
+  /dev       -> Implement each task with subagent-driven TDD
+  /validate  -> Type check, lint, tests, security
+  /ship      -> Push + create PR
+  /review    -> Address PR feedback
+  /verify    -> Post-merge health check
+
+Pre-merge gate: doc updates + CI-green checkpoint embedded in /ship and /review (not a separate stage).
+```
+
+## Tips
+
+- **Use the project's PR template**: Always read `.github/pull_request_template.md` (or equivalent) and populate it — never substitute your own format
+- **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
+- **Include "Closes forge-xxx"**: Required for auto-close in /verify
+- **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
+- **NO auto-merge**: Always wait for /review phase

package/skills/ship/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Validation came back clean — go ahead and open the pull request for this branch.",
+    "should_trigger": true
+  },
+  {
+    "query": "Push my feature branch and raise a PR, and fill in our PR template with the issue and design-doc links.",
+    "should_trigger": true
+  },
+  {
+    "query": "Dev's done and all the checks passed, cut me a PR.",
+    "should_trigger": true
+  },
+  {
+    "query": "Do a gh pr create for feat/rate-limit using the repo's template, not a hand-written body.",
+    "should_trigger": true
+  },
+  {
+    "query": "Everything's green after validate — ship it, but hand it off for me to merge, don't merge it yourself.",
+    "should_trigger": true
+  },
+  {
+    "query": "Take forge-42 from planning all the way to a merge-ready PR — plan it, build it TDD, validate, then ship, checking with me at the gates.",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR's picked up Greptile and CodeRabbit comments — fix them and resolve the threads.",
+    "should_trigger": false
+  },
+  {
+    "query": "Run the type-check, lint, tests and security scan before I push anything.",
+    "should_trigger": false
+  },
+  {
+    "query": "Keep watching PR #128 and ping me the moment its checks go green so I can merge.",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR merged to master — confirm CI is green there and close the linked issue.",
+    "should_trigger": false
+  }
+]

package/skills/smith/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: smith
+description: >
+  The flagship Forge orchestrator: given a goal or a ready issue, it composes the
+  stage skills (triage-ready · claim-safety · plan · dev · validate · ship · review
+  · verify) into the right path for the work, running autonomously between human
+  gates and pausing at them. Use this whenever the user wants to work the next ready
+  issue, drive a feature or fix end-to-end, "take this through to a PR", orchestrate
+  the whole workflow with human checkpoints, or asks some form of "what should I
+  work on and get it done" — even if they never say "smith" or "orchestrate". Reach
+  for it especially when the request spans multiple stages (plan → build → ship) or
+  asks to keep a human in the loop at intent, plan, or merge. Prefer a single stage
+  skill only when the user explicitly wants just that one step (e.g. "just open the
+  PR").
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Smith — the orchestrator super-skill
+
+Smith is a thin orchestrator. It adds no stage behaviour of its own; every step
+below is an existing skill or `forge` verb. What smith contributes is *judgement*:
+which path to take for this piece of work, and how densely to involve the human.
+It is maximally driving between gates and deliberately stops at them — the goal is
+conversational autonomy, not unattended autonomy.
+
+Keep the word "kernel" internal — it is the event store under the hood, not a
+term users should see.
+
+Deeper lookup tables live in
+[references/autonomy-and-gates.md](references/autonomy-and-gates.md): read that
+when you calibrate a specific issue or need the exact gate IDs and commands.
+
+## The orchestration procedure
+
+1. **Pick the work with `triage-ready`.** Rank the ready queue
+   (`forge issue ready --json`) and explain why the top pick is genuinely
+   workable. Readiness is a *derived* model, so recompute it each time rather than
+   trusting a remembered "ready" — you want the item that is actually unblocked
+   now, not a stale guess. Hand off one issue.
+
+2. **Claim it, then prove you own it, with `claim-safety`.**
+   `FORGE_ACTOR=<actor> forge claim <id>`, then `forge issue owns <id>` (exit 0 =
+   owned). A claim returning `ok:true` is not proof — a duplicate replay returns
+   `ok:true` too, and a live lease can be reclaimed once it expires. Proving
+   ownership is what stops two agents from quietly working the same issue. If you
+   are not the owner, don't work it; reselect via `triage-ready`.
+
+3. **Calibrate autonomy during planning.** Read the issue's size × importance ×
+   complexity, map it to a tier (lean / standard / high), and *propose that tier
+   directly to the human* — a short "here's how much oversight I think this needs."
+   This proposal is a plain conversational checkpoint at the start of planning; it
+   is deliberately **not** itself one of the enforcement gates, so it stays reachable
+   even for the Lean tier (which may require no intent gate at all). The human
+   confirms or overrides, and the chosen tier decides **which enforcement gates you
+   require approval for on this issue** (step 5). Keep the two mechanisms distinct:
+   `forge gate enable|disable <gate>` is the **repo-wide default** (a gate the user
+   turned off is always skipped), whereas the per-issue tier is *your* runtime
+   decision about which of the still-enabled gates to actually require for this one
+   issue. Matching checkpoint density to stakes is the whole point: a docs typo
+   should not drag through a full brainstorm, and a risky refactor should not run
+   unattended. When your read is uncertain, lean toward *more* gates — an extra
+   approval costs seconds, a missing one can cost a lot of rework. See the
+   reference for the tier → gate mapping.
+
+4. **Drive the stages along the path that fits.** Sequence
+   `plan → dev → validate → ship → review → verify`, invoking each stage skill as
+   its step arrives. The stage skills already encode the TDD, validation, and
+   review discipline, so smith's job is only to pick the path by change
+   classification (critical / standard / simple / hotfix / docs / refactor): a docs
+   typo skips brainstorming and most of the ladder; a critical feature runs the
+   full ladder.
+
+5. **Stop at every enabled human gate.** Before advancing past a gate, run:
+
+   ```bash
+   forge gate check <issue> <gate>     # exit 0 iff the gate is disabled or approved
+   ```
+
+   On exit 0, proceed. On non-zero, stop and ask the human to
+   `forge gate approve <issue> <gate> [--reason "…"]` (or
+   `forge gate reject <issue> <gate> --reason "…"` to send it back); inspect
+   history any time with `forge gate status <issue>`. Approvals are recorded as
+   durable events, which is what lets smith re-check and continue after a crash or
+   compaction instead of re-asking. The three human gates are `gate.intent`,
+   `gate.plan-approval`, and `gate.merge` (details in the reference).
+
+6. **Re-prove ownership and check readiness before closing.** A lease can expire
+   and be reclaimed while you work, so run `forge issue owns <id>` again before you
+   close — you don't want to close someone else's issue. Then confirm the tree is
+   actually shippable:
+
+   ```bash
+   forge release check --target <version> --json   # success:true ⇒ healthy
+   ```
+
+   Close only when ownership holds and readiness is healthy
+   (`forge close <id> --reason "…"`), then `forge sync`.
+
+## Autonomy tiers at a glance
+
+Full table and the reasoning are in the reference; the short version:
+
+- **Lean** — small · simple · low-importance work: enforce just `gate.merge`, or
+  run under CI with the human gates disabled.
+- **Standard** (default) — an ordinary feature/bug: enforce `gate.intent`,
+  `gate.plan-approval`, and `gate.merge`.
+- **High** — large · important · or complex work: enforce all three, plus
+  per-milestone check-ins and a pre-ship pass.
+
+The tier is a **per-issue** decision: smith requires `check`/approval only for the
+gates its tier calls for on *this* issue and simply skips the rest — it does not
+toggle repo config per issue. Separately, `forge gate disable <gate-id>` is the
+**repo-wide** off switch (a disabled gate makes `check` fall through for *every*
+issue) — use it when the user never wants that checkpoint at all. So a lean run
+skips a checkpoint by not requiring it for this issue; disabling a gate removes it
+everywhere.
+
+## Reliability
+
+- **The human always wins, and uncertainty adds oversight.** Smith proposes a
+  tier; it never lowers the human-loop density on its own, and a rejected gate
+  sends the work back rather than proceeding.
+- **Re-check gates on resume.** After any interruption, trust the recorded events
+  (`check` / `status`), not your memory of what was approved.
+- **Prove ownership twice** — after claiming and again before close/release.
+- **Never bypass a gate or a hook.** A failed gate or failing hook is a stop to
+  resolve, not an obstacle to route around (no `LEFTHOOK=0`, no `--no-verify`).
+
+## Fork points
+
+Smith is a default assembly, not a fixed ladder — re-carve it:
+
+| Knob | Default | How to change |
+|------|---------|---------------|
+| **Stakes heuristic** | size × importance × complexity → tier | Re-weight it (e.g. weight blast-radius or reversibility higher), or map your own change-classes to tiers. |
+| **Tier → gate set** | lean / standard / high (see reference) | Change which human gates each tier enforces; enact per repo with `forge gate enable\|disable <gate-id>`. |
+| **Gate density** | intent · plan-approval · merge | Add a checkpoint (enable a gate or add a per-milestone pause) or drop one (disable it); the human overrides smith's proposal at `gate.intent`. |
+| **Composed flow** | triage → claim → plan → dev → validate → ship → review → verify | Skip stages by change class (docs typo → doc-only path), reorder, or swap in your own `plan`/`dev`/`review` adapter. |
+| **Release target** | `forge release check` default | Pass `--target <version>` for the release you are certifying. |
+
+Smith is the assembled hammer; the sub-skills are the head and handle; the gates
+are the grip adjustments. Ship a good default, then let users re-carve it.

package/skills/smith/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "Grab the next ready issue off the board and take it all the way through to a PR for me — plan it, build it TDD, validate, and open the PR, but stop and check with me before it actually merges.",
+    "should_trigger": true
+  },
+  {
+    "query": "I want you to orchestrate the whole workflow for the payments-webhook feature end to end: design the plan, do the dev, run validation, ship it, handle the review comments — just keep me in the loop at the plan-approval and merge points.",
+    "should_trigger": true
+  },
+  {
+    "query": "What should I pick up next? Whatever's highest-priority and ready, claim it and drive it to done with the usual human checkpoints — I don't want to babysit every step but I do want to approve the design and the merge.",
+    "should_trigger": true
+  },
+  {
+    "query": "Take issue forge-9k2 from planning through a merged PR. It's a big risky refactor so keep me involved — I want to sign off at intent, at the plan, and per milestone before you push.",
+    "should_trigger": true
+  },
+  {
+    "query": "Run the full plan through ship flow on the login-rate-limit bug, but it's a tiny fix so don't over-gate it — just let me approve the merge and go.",
+    "should_trigger": true
+  },
+  {
+    "query": "Autonomously work through the ready queue and get each task to a PR, pausing for my approval before any merge.",
+    "should_trigger": true
+  },
+  {
+    "query": "Just open the PR for my current branch, it's already validated and I've written the description.",
+    "should_trigger": false
+  },
+  {
+    "query": "What stage am I in and what's my active work right now? Anything gone stale?",
+    "should_trigger": false
+  },
+  {
+    "query": "Go through the CodeRabbit and SonarCloud comments on PR #288 and address them, then re-request review.",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a feature issue for adding dark mode to the settings page, priority 2, and link it under the theming epic.",
+    "should_trigger": false
+  },
+  {
+    "query": "Just claim forge-abc for me so nobody else picks it up while I look at it.",
+    "should_trigger": false
+  }
+]