forge-workflow 0.0.9 → 0.1.0-beta.2

package/skills/research/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: research
+description: >
+  Forge RESEARCH — a first-class, freely-invocable investigation skill any agent can call
+  standalone OR mid-workflow (mid-/dev, mid-/validate, mid-/plan), not a plan-only stage. Use
+  it to verify/fact-check a claim against primary sources; web-search best practices, gotchas,
+  and docs; find better options/patterns and weigh trade-offs; see both sides (steelman the
+  right way AND red-team the wrong way); pull inspiration from stronger sources; and run the
+  /plan Phase 2 bundle (web research + OWASP Top 10 + DRY/blast-radius codebase exploration +
+  3+ TDD scenarios) under `## Technical Research`. Trigger on "verify/fact-check this",
+  "research X",
+  "find a better way/option", "is this true", "get inspiration", "run the research phase", or
+  mid-task "investigate before I decide". Pick over siblings: `parallel-deep-research` for a
+  heavyweight EXTERNAL market/competitive report (paid Parallel AI); `plan` for the full plan
+  stage (brainstorm + tasks); `dev` or `validate` to implement or scan rather than investigate.
+allowed-tools: Bash, Read, Write, Grep, Glob, WebSearch, WebFetch
+---
+
+Investigate anything, from anywhere: verify a claim, search the web, find better options, pull
+inspiration from stronger sources, weigh perspectives, and package technical research for a plan.
+
+# Research
+
+`/research` is a **first-class capability**, not a stage. Any agent may invoke it at any point —
+standalone, or in the middle of another skill — whenever a question needs evidence before a
+decision. It is broader than `parallel-deep-research`: that sibling is a heavyweight external
+market/industry report; this skill is your everyday "go find out and come back with evidence."
+
+## When to use it
+
+- **Verify a claim** — "is this API deprecated?", "does this library support X?", "is this the
+  current best practice?" Confirm or refute against primary sources.
+- **Find a better way / better options** — enumerate real alternatives and compare trade-offs.
+- **Web research** — best practices, gotchas, current docs, changelogs, version differences.
+- **Inspiration / prior art** — pull stronger plans, patterns, and reference implementations
+  from better sources than memory.
+- **Multi-perspective** — see it done the right way AND the wrong way; steelman and red-team.
+- **Codebase research** — DRY, blast-radius, reusable patterns already in the repo.
+- **/plan Phase 2 bundle** — the packaged deliverable `plan` delegates to (see "Plan bundle").
+
+## How to invoke
+
+Standalone (user asks directly):
+
+```bash
+/research <question or claim>
+```
+
+From inside another skill or agent — call the Skill tool mid-flow:
+
+```
+Skill("research")   # then hand it the specific question + why you're asking
+```
+
+Always give research: (1) the concrete question or claim, (2) the decision it feeds, and
+(3) any constraints (stack, versions, repo area). Research returns **evidence, not opinion**:
+cited findings, and — when a caller needs it — a recommendation with the trade-offs shown.
+
+---
+
+## Modes
+
+Pick the mode(s) that fit the question. Most investigations combine two or three.
+
+### Mode A — Verify / fact-check a claim
+
+1. State the claim in one sentence and what would confirm vs refute it.
+2. Pull **primary sources** first (official docs, source code, specs, changelogs) via WebSearch
+   → WebFetch. Secondary sources (blogs, SO) only corroborate.
+3. Adversarially check: look for the counter-evidence, not just confirmation.
+4. Return: `CONFIRMED / REFUTED / MIXED / UNKNOWN` + the cited evidence + a one-line reason.
+
+Never answer a factual claim from memory. Fetch the source, cite it (URL + the line that
+settles it). "I'm confident" is not evidence.
+
+### Mode B — Explore options / find a better way
+
+1. Frame the decision and the constraints (perf, safety, complexity, lock-in, maturity).
+2. Enumerate 2–4 concrete options — include the "boring/obvious" one and at least one you did
+   not start with.
+3. For each: what it is, when it wins, when it loses, adoption/maintenance signal.
+4. Recommend one, with the trade-off that decides it. Show the runners-up so the caller can
+   overrule.
+
+### Mode C — Web search (quick → deep)
+
+Depth ladder — escalate only as needed:
+
+| Depth | Tool | Use for |
+|-------|------|---------|
+| Quick | built-in `WebSearch` / `WebFetch` | a fact, a doc page, one gotcha |
+| Deep, cited | `Skill("deep-research")` | multi-source, adversarially verified report |
+| External report | `Skill("parallel-deep-research")` | market/competitive/industry landscape (paid) |
+
+Search terms that work: `"[stack] [feature] best practices [year]"`,
+`"[library] [feature] pitfalls"`, `"[approach] known issues"`. Prefer official docs via
+Context7/grep.app MCP when available for library/API questions.
+
+### Mode D — Inspiration / better plans from better sources
+
+Look outward before inventing: canonical implementations, well-run OSS repos, design docs,
+RFCs. Pull the *shape* of a stronger solution and adapt it — don't copy blindly. Note the
+source so the plan can cite where the idea came from.
+
+### Mode E — Multi-perspective (steelman + red-team)
+
+For anything consequential, gather both:
+
+- **Steelman (the right way)** — the strongest case for the approach and how experts do it.
+- **Red-team (the wrong way)** — failure modes, anti-patterns, "why teams regret this",
+  security and edge-case traps.
+
+Return both columns so the decision is made with eyes open, not just the happy path.
+
+### Mode F — Codebase research (DRY + blast-radius)
+
+Use actual search tools — never rely on memory:
+
+```
+Grep("<function or concept>")   # existing implementations to reuse
+Glob("**/*.<ext>")              # narrow to affected file types
+Read(<match>)                   # inspect matches in context
+```
+
+- **DRY**: if a match exists, prefer "extend existing <file>:<line>" over "create new".
+- **Blast-radius** (for remove/rename/replace): grep the entire repo (exact + case-insensitive
+  + `Glob("**/*<thing>*")`), then list every hit — including `package.json`, install/setup
+  scripts, CI workflows, agent config, and docs — so nothing is missed.
+
+For broad multi-location sweeps, spawn the `Explore` agent and keep only its summary.
+
+---
+
+## Plan bundle (what `/plan` Phase 2 delegates to)
+
+When invoked by `/plan` for a feature's design doc, run the full technical bundle and append it
+under a `## Technical Research` section in `docs/work/YYYY-MM-DD-<slug>/plan.md`:
+
+1. **Web research** (Mode C) — best practices, gotchas, patterns for the chosen approach.
+2. **OWASP Top 10 pass** — for each relevant category (A01–A10): the risk, whether it applies,
+   and the planned mitigation.
+3. **DRY check** (Mode F) — reusable existing implementations.
+4. **Blast-radius search** (Mode F) — required for any remove/rename/replace; every reference
+   captured for the task list.
+5. **Codebase exploration** — similar patterns, affected files, test infra to leverage.
+6. **TDD scenarios** — at minimum 3: happy path, error/failure path, and one Phase-1 edge case.
+
+The caller's HARD-GATE (in `/plan`) still verifies these outputs exist — research produces
+them; the gate enforces them. Do not treat delegation as a way to skip the gate.
+
+---
+
+## Invoked mid-flow (examples)
+
+- **Mid-/validate** — a security or type failure surfaces and the fix is unclear: call
+  `Skill("research")` to verify the correct API/pattern against primary sources before editing
+  (feeds the D2 root-cause trace), then return to validation.
+- **Mid-/dev** — a decision gate fires on a spec gap: research the options (Mode B) and current
+  best practice (Mode C) so the decision is evidence-backed, then log the decision and continue.
+- **Mid-/plan** — an approach looks shaky during brainstorming: research alternatives and
+  red-team the front-runner (Mode E) before committing the design.
+- **Any agent, any time** — "before I decide, let me check" is always a valid reason to invoke.
+
+## Output contract
+
+- Cite every non-obvious claim (URL or `file:line`) — findings without sources are opinions.
+- Lead with the answer/recommendation, then the evidence, then the runners-up.
+- When invoked by `/plan`, append to the design doc's `## Technical Research` section (not a
+  separate file). When invoked mid-flow, return a concise evidence-backed answer to the caller.
+- Flag what you could NOT verify as `UNKNOWN` rather than guessing.
+
+## Integration with workflow
+
+```
+Utility: /status  -> Understand current context before starting
+
+Default template:
+  /plan      -> Optional default planner; delegates its Phase 2 technical research to /research
+  /dev       -> Implement each task with subagent-driven TDD (may call /research at a spec gap)
+  /validate  -> Type check, lint, tests, security (may call /research to root-cause a failure)
+  /ship      -> Push + create PR
+  /review    -> Address PR feedback
+  /verify    -> Post-merge health check
+
+Research is callable standalone or from any of the above — it is a capability, not a gate.
+```
+
+## Tips
+
+- **Evidence beats memory** — always fetch and cite; never settle a fact from recall.
+- **Escalate depth deliberately** — quick WebSearch first; reach for `deep-research` or
+  `parallel-deep-research` only when a single search can't answer it.
+- **Both perspectives** — for consequential calls, always red-team, not just steelman.
+- **Delegation ≠ skipping gates** — when `/plan` delegates the bundle, its HARD-GATE still
+  checks OWASP + 3 TDD scenarios + blast-radius are present.

package/skills/research/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "The design doc for the rate-limiter is already written — now go do the technical research: best practices, known gotchas for this approach, and drop it under Technical Research in the doc.",
+    "should_trigger": true
+  },
+  {
+    "query": "Run an OWASP Top 10 pass over this new file-upload feature and record which categories actually apply and how we'll mitigate each.",
+    "should_trigger": true
+  },
+  {
+    "query": "Before we build the caching layer, search the codebase for anything we can reuse and make sure we're not duplicating an existing helper.",
+    "should_trigger": true
+  },
+  {
+    "query": "Just do the research phase for this feature — web plus codebase investigation and at least three TDD scenarios — skip the brainstorm and the worktree setup.",
+    "should_trigger": true
+  },
+  {
+    "query": "Pull together the security and best-practices research for the OAuth integration and append it to the feature's design doc.",
+    "should_trigger": true
+  },
+  {
+    "query": "Let's plan this feature from scratch — brainstorm the design with me one question at a time, then create the branch, worktree, and task list.",
+    "should_trigger": false
+  },
+  {
+    "query": "I need a competitive landscape report comparing Datadog, Grafana Cloud, and New Relic on pricing and features for a 500-node cluster.",
+    "should_trigger": false
+  },
+  {
+    "query": "Give me a comprehensive market analysis of the vector-database space — top players, funding, and the 3-5 year outlook.",
+    "should_trigger": false
+  },
+  {
+    "query": "Start implementing task 1 with TDD — write the failing test first, then make it pass.",
+    "should_trigger": false
+  },
+  {
+    "query": "Run the security scan, lint, and full test suite before we open the PR.",
+    "should_trigger": false
+  }
+]

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

@@ -1,14 +1,25 @@
 ---
 name: review
-description: Address ALL PR issues (GitHub Actions, Greptile, SonarCloud, CI/CD)
-tools: []
+description: >
+  Forge REVIEW stage — drives an already-open PR to all-green by resolving EVERY piece of
+  feedback: failing GitHub Actions / CI checks, Greptile and CodeRabbit inline comments and
+  summaries, and the SonarCloud quality gate. It fixes the code, replies to each thread and
+  marks it resolved until checks pass, then runs the pre-merge doc gate and hands the PR off
+  for MANUAL merge — never runs `gh pr merge`. Use whenever a PR has review feedback or red
+  checks: "address the review comments on PR #123", "the bots flagged issues / Greptile score
+  is low", "fix the failing checks and resolve the threads", "CodeRabbit and SonarCloud left
+  comments", "get my PR merge-ready". This MUTATING feedback-resolution stage is distinct from
+  shepherd (only WATCHES an open PR, changes nothing), verify (POST-merge CI health check +
+  closing issues), ship (pushes the branch + opens the PR), validate (PRE-PR local
+  type/lint/test/security), and sonarcloud / sonarcloud-analysis (only QUERY SonarCloud data).
+allowed-tools: Bash, Read, Edit, Grep, Glob
 ---
 
-Process ALL pull request issues including GitHub Actions failures, Greptile inline comments, SonarCloud analysis, and other CI/CD checks.
+Process ALL pull request issues including GitHub Actions failures, review-agent inline comments (Greptile, CodeRabbit, Qodo, or human reviewers), SonarCloud analysis, and other CI/CD checks.
 
 # Review
 
-This command handles ALL issues that arise after creating a pull request.
+This skill handles ALL issues that arise after creating a pull request.
 
 ## Usage
 
@@ -16,7 +27,7 @@ This command handles ALL issues that arise after creating a pull request.
 /review <pr-number>
 ```
 
-## What This Command Does
+## What This Skill Does
 
 ### Step 1: Fetch Complete PR Status
 ```bash
@@ -64,22 +75,22 @@ gh run view <run-id> --log-failed
 - Type failures: TypeScript type errors
 - Deployment failures: Env vars, configuration issues
 
-### Step 3: Process Greptile Review
+### Step 3: Process Review-Agent Feedback
 
-Greptile provides TWO types of feedback:
+Review agents (Greptile, CodeRabbit, Qodo, or human reviewers) provide TWO types of feedback:
 1. **Inline comments** on specific code lines
 2. **Summary** with overall recommendations
 
-**IMPORTANT**: Use the **systematic Greptile resolution process** documented in `.claude/rules/greptile-review-process.md`. This process has been standardized to ensure:
+**IMPORTANT**: Use the **systematic review-thread resolution process** documented in `.claude/rules/review-process.md`. This process is author-agnostic — it works the same whichever tool or person left the comment — and has been standardized to ensure:
 - All threads are replied to directly (not as separate PR comments)
 - All threads are marked as resolved after fixing
 - No manual tracking overhead for maintainers
 
-#### 3A. Check Greptile Inline Comments (Use Systematic Process)
+#### 3A. Check Inline Review Comments (Use Systematic Process)
 
 **Step 1: List all unresolved threads**
 ```bash
-bash .claude/scripts/greptile-resolve.sh list <pr-number> --unresolved
+bash .claude/scripts/review-resolve.sh list <pr-number> --unresolved
 ```
 
 This shows:
@@ -96,7 +107,7 @@ This shows:
 
 2. **Categorize the comment**:
    - **Valid**: Should be implemented (security issue, bug, clear improvement)
-   - **Invalid**: Greptile misunderstood context
+   - **Invalid**: the review agent misunderstood context
    - **Conflicting**: Contradicts research decisions with good reason
    - **Out of scope**: Valid but not for this PR
 
@@ -107,7 +118,7 @@ This shows:
 4. **Reply and resolve** (for ALL comments, even invalid ones)
    ```bash
    # For valid issues (fixed):
-   bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
+   bash .claude/scripts/review-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
      "✅ Fixed: [description]
 
      Changed: [what was changed]
@@ -115,27 +126,27 @@ This shows:
      Commit: [commit-sha]"
 
    # For invalid/conflicting issues:
-   bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
+   bash .claude/scripts/review-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
      "This approach is correct because:
      - Reasoning: [from design doc]
      - Evidence: [link to source]
-     - Alternative considered: [what Greptile suggested]
+     - Alternative considered: [what the review agent suggested]
      - Why rejected: [specific reason]
 
-     See: docs/plans/YYYY-MM-DD-<slug>-design.md (Decision #X)"
+     See: docs/work/YYYY-MM-DD-<slug>/plan.md (Decision #X)"
    ```
 
 **Step 3: Verify all resolved**
 ```bash
-bash .claude/scripts/greptile-resolve.sh stats <pr-number>
+bash .claude/scripts/review-resolve.sh stats <pr-number>
 ```
-Should show: "✓ All Greptile threads resolved!"
+Should show: all review threads resolved.
 
-**See complete process**: `.claude/rules/greptile-review-process.md`
+**See complete process**: `.claude/rules/review-process.md`
 
-#### 3B. Check Greptile Summary
+#### 3B. Check the Review-Agent Summary
 ```bash
-# Greptile usually posts a summary comment on the PR
+# Review agents usually post a summary comment on the PR
 # Review the overall assessment and recommendations
 ```
 
@@ -186,8 +197,8 @@ Review any other automated checks:
 
 Create a master list of all issues from:
 - GitHub Actions failures
-- Greptile inline comments
-- Greptile summary recommendations
+- Review-agent inline comments
+- Review-agent summary recommendations
 - SonarCloud issues
 - Other CI/CD tool failures
 
@@ -214,13 +225,13 @@ git push
 # Actions will auto-rerun
 ```
 
-For **Greptile inline comments** (Use Systematic Script):
+For **inline review comments** (Use Systematic Script):
 ```bash
-# Use the standardized Greptile resolution script
-# See .claude/rules/greptile-review-process.md for complete process
+# Use the standardized review-thread resolution script
+# See .claude/rules/review-process.md for complete process
 
 # For valid comments (fixed):
-bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
+bash .claude/scripts/review-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
   "✅ Fixed: [description]
 
   Changed: [what was changed]
@@ -228,28 +239,28 @@ bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-
   Commit: [commit-sha]"
 
 # For invalid/conflicting comments:
-bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
+bash .claude/scripts/review-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
   "This approach is correct because:
   - Reasoning: [from design doc]
   - Evidence: [link to source]
-  - Alternative considered: [what Greptile suggested]
+  - Alternative considered: [what the review agent suggested]
   - Why rejected: [specific reason]
 
-  See: docs/plans/YYYY-MM-DD-<slug>-design.md (Decision #X)"
+  See: docs/work/YYYY-MM-DD-<slug>/plan.md (Decision #X)"
 
 # Verify all threads resolved:
-bash .claude/scripts/greptile-resolve.sh stats <pr-number>
+bash .claude/scripts/review-resolve.sh stats <pr-number>
 ```
 
-For **Greptile summary recommendations**:
+For **review-agent summary recommendations**:
 ```bash
 # Add a PR comment addressing the summary
-gh pr comment <pr-number> --body "## Greptile Summary Response
+gh pr comment <pr-number> --body "## Review Summary Response
 
 Addressed all key recommendations:
 - [Recommendation 1]: ✓ Fixed in commit <sha>
 - [Recommendation 2]: ✓ Explained (see inline response)
-- [Recommendation 3]: ⏭️ Out of scope for this PR (created issue bd-xxx)
+- [Recommendation 3]: ⏭️ Out of scope for this PR (created issue forge-xxx)
 
 All critical and high-priority items resolved."
 ```
@@ -280,7 +291,7 @@ git commit -m "fix: address ALL PR review feedback
 GitHub Actions:
 - Fixed: [list of workflow failures resolved]
 
-Greptile:
+Review agents:
 - Fixed: [list of valid inline comments addressed]
 - Explained: [list of invalid comments with reasoning]
 - Summary: [key recommendations addressed]
@@ -308,16 +319,16 @@ gh pr checks <pr-number>
 #
 # Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
-# ✓ Greptile review (no unresolved critical comments)
+# ✓ Review agents (no unresolved critical comments)
 # ✓ SonarCloud quality gate
 # ✓ Other CI/CD checks
 ```
 
-### Step 10: Update Beads
+### Step 10: Update the Forge issue
 
 ```bash
-bd update <id> --comment "PR review complete: all issues addressed, all checks passing"
-bd sync
+forge comment <id> "PR review complete: all issues addressed, all checks passing"
+forge sync
 ```
 
 ## Example Output
@@ -328,7 +339,7 @@ bd sync
   - Tests: ✓ Passing
   - Deploy Preview: ✓ Passing
 
-✓ Greptile Review:
+✓ Review-Agent Feedback:
   Inline Comments: 8 total
   - Valid: 5 → Fixed & replied inline
   - Invalid: 2 → Explained with research evidence & replied inline
@@ -358,38 +369,63 @@ bd sync
 
 ✓ Fixes committed: 3c4d5e6
 ✓ All checks passing: ✓
-✓ Beads updated: Ready for merge
+✓ Forge issue updated: Ready for merge
 
-Next: /premerge <pr-number>
+Next: pre-merge gate — finish docs + confirm CI green, then hand off the PR for merge
 ```
 
 ```
 <HARD-GATE: /review exit>
 Do NOT declare /review complete until:
-1. bash .claude/scripts/greptile-resolve.sh stats <pr-number> shows "All Greptile threads resolved"
+1. bash .claude/scripts/review-resolve.sh stats <pr-number> shows all review threads resolved
 2. ALL human reviewer comments are either resolved or have a reply with explanation
 3. gh pr checks <pr-number> shows all checks passing
-4. Context check: Run `bash scripts/beads-context.sh validate <id>` and address any warnings
-5. Stage transition: Run the following → exit 0 confirmed:
-   bash scripts/beads-context.sh stage-transition <id> review premerge \
-     --summary "<all feedback addressed summary>" \
-     --decisions "<comment resolutions — valid fixes and justified rejections>" \
-     --artifacts "<fixed files, commit SHAs>" \
-     --next "<doc update needs for premerge>"
+4. Context check: confirm design + acceptance on the Forge issue (`forge issue show <id>`); if the beads-context helper is present, run `bash scripts/beads-context.sh validate <id>` and address any warnings
+5. Stage transition recorded (structured helper when present; kernel-native comment otherwise):
+   if [ -f scripts/beads-context.sh ]; then
+     bash scripts/beads-context.sh stage-transition <id> review verify \
+       --summary "<all feedback addressed summary>" \
+       --decisions "<comment resolutions — valid fixes and justified rejections>" \
+       --artifacts "<fixed files, commit SHAs>" \
+       --next "<pre-merge gate: finish docs + CI green, then hand off for merge>"
+   else
+     forge comment <id> "Stage: review complete → ready for verify
+Summary: <all feedback addressed summary>
+Decisions: <comment resolutions — valid fixes and justified rejections>
+Artifacts: <fixed files, commit SHAs>
+Next: <pre-merge gate: finish docs + CI green, then hand off for merge>"
+   fi
 </HARD-GATE>
 ```
 
+## Pre-merge gate (before merge)
+
+Pre-merge is a doc-update **gate/checkpoint**, not a separate stage — run it here, once feedback is addressed and 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.
+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
-Stage 1: /plan       → Design intent → research → branch + worktree + task list
-Stage 2: /dev        → Implement each task with subagent-driven TDD
-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 (you are here)
-Stage 6: /premerge   → Update docs, hand off PR to user
-Stage 7: /verify     → Post-merge CI check on main
+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).
 ```
 
 ## Understanding the Tools
@@ -441,13 +477,13 @@ Stage 7: /verify     → Post-merge CI check on main
 
 ## Tips
 
-- **Address ALL issues**: Not just Greptile and SonarCloud
+- **Address ALL issues**: Not just one review agent and SonarCloud
 - **Prioritize critical**: Fix blockers first (GitHub Actions failures, security issues)
-- **Reply inline to Greptile**: Respond to each comment directly
-- **Post summary response**: Address Greptile's overall assessment
+- **Reply inline to review agents**: Respond to each comment directly
+- **Post summary response**: Address the review agent's overall assessment
 - **Use sonarcloud skill**: Don't just check the web UI
-- **Verify all checks**: Ensure everything is green before /premerge
-- **Update Beads**: Keep issue status current
+- **Verify all checks**: Ensure everything is green before the pre-merge gate / merge
+- **Update the Forge issue**: Keep issue status current
 - **Research if needed**: Use WebSearch for unclear suggestions
 - **Document fixes**: Clear commit messages for all fixes
 - **Don't leave unresolved**: Address every comment and check

package/skills/review/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "PR #204 has three red checks and a pile of Greptile comments — work through all of it and get the PR green.",
+    "should_trigger": true
+  },
+  {
+    "query": "CodeRabbit and SonarCloud both left feedback on my pull request; fix what's valid, reply to the rest, and resolve the threads.",
+    "should_trigger": true
+  },
+  {
+    "query": "The GitHub Actions build is failing on my PR and there are unresolved review threads — sort them out before I merge.",
+    "should_trigger": true
+  },
+  {
+    "query": "My Greptile confidence score is low. Address the inline comments and keep pushing fixes until the quality gate passes.",
+    "should_trigger": true
+  },
+  {
+    "query": "Handle all the reviewer feedback on the auth PR, then update the changelog and docs before we hand it off to merge.",
+    "should_trigger": true
+  },
+  {
+    "query": "Just keep an eye on PR #150 — watch the checks and review threads and ping me when it's settled and mergeable. Don't touch the code.",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR is merged to master now — run the post-merge health check and close out the issue.",
+    "should_trigger": false
+  },
+  {
+    "query": "My branch passed validation; push it and open the pull request with the design-doc link.",
+    "should_trigger": false
+  },
+  {
+    "query": "Before I open a PR, run the type-check, lint, full test suite, and security scan on my branch.",
+    "should_trigger": false
+  },
+  {
+    "query": "Just pull up this PR's SonarCloud issues and quality-gate status so I can eyeball them.",
+    "should_trigger": false
+  }
+]