forge-workflow 0.1.0-beta.3 → 0.1.0-beta.5

package/skills/smith/SKILL.md

@@ -13,6 +13,14 @@ description: >
   skill only when the user explicitly wants just that one step (e.g. "just open the
   PR").
 allowed-tools: Read, Bash(forge:*)
+terminal: true
+subskills:
+  - plan
+  - dev
+  - validate
+  - ship
+  - review
+  - verify
 ---
 
 # Smith — the orchestrator super-skill

package/skills/smith/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "smith",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 819,
+      "body_lines": 127,
+      "score": 47
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 0,
+    "reachable": false,
+    "keyword_alignment": 0
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 84
+}

package/skills/sonarcloud/SKILL.md

@@ -13,6 +13,7 @@ description: >
   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
+terminal: true
 ---
 
 # SonarCloud Query Command

package/skills/sonarcloud/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "sonarcloud",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 977,
+      "body_lines": 147,
+      "score": 38
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 6,
+    "reachable": true,
+    "keyword_alignment": 1
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 61
+}

package/skills/sonarcloud-analysis/SKILL.md

@@ -18,6 +18,7 @@ tags: [sonarcloud, code-quality, issues, metrics, security]
 context: fork
 tools: [Bash, WebFetch, Read, Grep, Glob]
 model: sonnet
+terminal: true
 ---
 
 <role>

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

@@ -0,0 +1,41 @@
+{
+  "skill": "sonarcloud-analysis",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 993,
+      "body_lines": 156,
+      "score": 36
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 0,
+    "reachable": false,
+    "keyword_alignment": 0
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 81
+}

package/skills/status/SKILL.md

@@ -12,6 +12,7 @@ description: >
   (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
+terminal: true
 ---
 
 Check where you are in the project and what work is in progress.
@@ -44,6 +45,8 @@ This command dynamically computes and displays all issues ranked by composite sc
 
 For full context on any issue: `forge show <id>`
 
+For the full workflow contract and command reference at session start, run `forge prime`.
+
 ### 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):

package/skills/status/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "status",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 954,
+      "body_lines": 90,
+      "score": 44
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.33
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 63
+}

package/skills/triage-ready/SKILL.md

@@ -14,6 +14,8 @@ description: >
   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:*)
+next: claim-safety
+terminal: false
 ---
 
 # Triage: what should I work on next

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

@@ -0,0 +1,41 @@
+{
+  "skill": "triage-ready",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 977,
+      "body_lines": 105,
+      "score": 42
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 1,
+    "reachable": true,
+    "keyword_alignment": 0.2
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 83
+}

package/skills/using-forge/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: using-forge
+description: >
+  Forge dispatch skill: the session bootstrap that makes Forge's skills auto-trigger as a
+  reasoning-driven SYSTEM. Reach for this FIRST, before ANY response (including clarifying
+  questions, codebase exploration, or file reads), whenever there is even a 1% chance a Forge
+  skill applies. Carries the 1%-rule, the announce-before-acting rule, an anti-rationalization
+  red-flags table, a subagent escape hatch, and an intent-to-skill routing table: add/build/scope
+  a feature to plan; implement an existing task to dev; fix a failing test or bug to dev (debug
+  first); type-check/lint/tests to validate; push and open a PR to ship; address PR/review
+  feedback to review; post-merge health to verify; what to work on to triage-ready; where am I /
+  current stage to status; create/close/search an issue to issue-basics; drive one issue
+  end-to-end to smith; monitor a PR to shepherd. Run `forge skill for "<situation>"` for a
+  deterministic fallback. NOT itself a stage; the kernel skill is the fuller umbrella index
+  once oriented.
+allowed-tools: Read, Bash(forge:*)
+terminal: true
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute one specific task, ignore this skill and do
+the task you were given. This dispatch rule is for the top-level session, not for a scoped
+subagent — otherwise every subagent would re-enter routing instead of working.
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a Forge skill applies to what you are doing, you MUST
+invoke that skill BEFORE any response or action.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. You cannot rationalize your way out of it.
+</EXTREMELY-IMPORTANT>
+
+## The rule
+
+**Invoke the relevant or requested Forge skill BEFORE any response or action** — including
+clarifying questions, exploring the codebase, or checking files. If it turns out wrong for the
+situation, you don't have to follow it — but you check first.
+
+Then **announce** `Using [skill] to [purpose]` and follow the skill exactly. If it has a
+checklist or HARD-GATE, create one todo per item.
+
+When unsure WHICH skill fits, either consult the routing table below or run
+`forge skill for "<what you are about to do>"` for a deterministic best-fit answer.
+
+## Intent → skill routing table
+
+Process skills set the approach first; then the stage/implementation skill carries it out.
+
+| When the situation is… | Start with |
+|------------------------|-----------|
+| "Add / build / scope a new feature", "let's build X" | `plan` |
+| Implement a task that a plan already defined | `dev` |
+| "Fix this bug" / a failing test / unexpected behavior | `dev` (if `superpowers:systematic-debugging` is installed, apply its technique first, then implement via `dev`) |
+| Run type-check, lint, security, or tests | `validate` |
+| Push the branch and open a PR | `ship` |
+| Address PR / review-agent feedback (CodeRabbit, Greptile, CI) | `review` |
+| Post-merge health check, close issues | `verify` |
+| "What should I work on?" — rank the ready queue | `triage-ready` |
+| "Where am I?" / current stage / stale or active work | `status` |
+| Create / update / close / search / comment on ONE issue | `issue-basics` |
+| Claim an issue and PROVE the lease before mutating | `claim-safety` |
+| Drive one issue plan→merged-PR under human gates | `smith` |
+| Monitor / shepherd a PR's CI + checks (never merges) | `shepherd` |
+| Deep, multi-source web research | `research` / `parallel-deep-research` |
+| "How does Forge fit together?" / which verb for X | `kernel` |
+| Safe revert / undo a merged change | `rollback` |
+
+If two skills seem to apply, run the process skill first (`plan`, `systematic-debugging`), then
+the doing skill. `kernel` is the umbrella index — use it to orient, not to do the work.
+
+## Red flags — these thoughts mean STOP, you are rationalizing
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for a skill. |
+| "I need more context first" | The skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for a skill. |
+| "This doesn't need a formal stage" | If a skill exists, use it. |
+| "I remember what that skill says" | Skills evolve. Read the current version. |
+| "The skill is overkill here" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "It's obviously a plan/dev/ship" | Then invoking it costs nothing. Invoke it. |
+
+## Subagent escape hatch
+
+You do NOT have to hold every skill in your own context. When a task is independent and
+bounded, dispatch a subagent with the specific skill and a self-contained brief, and keep only
+its conclusion. Parallelize independent tasks (see `superpowers:dispatching-parallel-agents`).
+Reviewers/verifiers that find nothing must say so and name what they inspected.
+
+## Agent-agnostic
+
+This skill syncs to every harness mirror (`.agents/`, `.claude/`, `.codex/`, `.cursor/`,
+`.hermes/`), and the same routing guidance is reachable via `forge skill for "<situation>"` on
+any harness — never branch on harness identity. On Claude the SessionStart hook injects this
+text automatically; elsewhere, AGENTS.md points here and the CLI router is the fallback.
+
+## User instructions win
+
+CLAUDE.md / AGENTS.md and direct user requests take precedence over skills, which in turn
+override default behavior. Skip a skill only when your human partner explicitly tells you to.

package/skills/using-forge/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "using-forge",
+  "fixtures": "no-fixtures",
+  "static": {
+    "token_cost": {
+      "desc_chars": 1016,
+      "body_lines": 87,
+      "score": 42
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": false,
+    "router_exempt": false,
+    "fixtures": "no-fixtures",
+    "fixtures_total": 0,
+    "fixtures_best_hit": 0,
+    "reachable": null,
+    "keyword_alignment": null
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 63
+}

package/skills/validate/SKILL.md

@@ -13,6 +13,8 @@ description: >
   is `/ship`), it does not answer PR review feedback from Greptile / SonarCloud / CodeRabbit
   (that is `/review`), and it is not the post-merge CI health check (that is `/verify`).
 allowed-tools: Bash, Read, Grep, Glob
+next: ship
+terminal: false
 ---
 
 > **Note:** Three things share the "validate" name in Forge:
@@ -24,6 +26,8 @@ Run comprehensive validation including type checking, linting, code review, secu
 
 # Validate
 
+> **Chain (HARD-GATE):** the ONLY skill you invoke after `validate` is `ship`. Do not open the PR until validation shows fresh passing output in THIS session.
+
 This skill validates all code before creating a pull request.
 
 ## Usage

package/skills/validate/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "validate",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 995,
+      "body_lines": 300,
+      "score": 21
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 3,
+    "reachable": true,
+    "keyword_alignment": 0.6
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 56
+}

package/skills/verify/SKILL.md

@@ -12,12 +12,16 @@ description: >
   rollback to undo an already-shipped change, status to merely report the current stage
   without acting, and issue-basics to close an issue unrelated to a just-merged PR.
 allowed-tools: Bash, Read, Grep, Glob
+next: ship
+terminal: false
 ---
 
 Verify that the merge landed correctly and everything is running properly after merge.
 
 # Verify
 
+> **Chain (HARD-GATE):** the successor depends on the change classification (source of truth: lib/workflow/stages.js) — in the post-merge flow (Critical/Standard/Refactor/Simple/Hotfix) NOTHING follows `verify`; the `docs` flow alone reuses `verify` → `ship` as a pre-ship content check. `verify` is therefore not universally terminal — a chain-aware harness MUST gate on classification, not blindly follow `next`.
+
 This skill runs AFTER the user has merged the PR. It checks system health — not documentation (that was handled by the pre-merge gate embedded in `/ship` and `/review`).
 
 ## Usage

package/skills/verify/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "verify",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 890,
+      "body_lines": 287,
+      "score": 28
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.33
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 78
+}

package/skills/worktree/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: worktree
+description: >
+  Forge's worktree lifecycle. `forge worktree create <slug>` makes an isolated checkout
+  under `.worktrees/`, creates its branch (feat/<slug>), links a kernel issue (`--issue`),
+  and installs dependencies — all in one step; `forge worktree list`/`remove <slug>` manage
+  them; `forge clean` removes worktrees whose branches already merged (squash-aware) and
+  fast-forwards the default branch. Use when the user says "work on this in an isolated
+  branch/worktree", "spin up a worktree", "parallel work on another PR or issue", "clean up
+  merged worktrees", or "why did my worktree miss its dependencies". Footgun it prevents:
+  raw `git worktree add` only creates a branch — it skips the issue link and dep install —
+  so always use `forge worktree create`; and `forge clean` is cwd-scoped, run it from the
+  primary repo root, never inside a worktree. NOT for opening/pushing a PR or the branch
+  (ship), NOT for planning a feature (plan), NOT the stages that create a worktree as one
+  step — this is the worktree lifecycle itself.
+allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+---
+
+Forge worktrees give a task its own isolated checkout so concurrent work never collides on `HEAD` or a shared branch. Use `forge worktree`, not raw `git worktree add` — the Forge command does the extra setup that a bare branch add skips.
+
+# Worktree lifecycle
+
+## When to use
+
+- "Work on this in an isolated branch / worktree", "spin up a worktree for this".
+- Parallel work: a second PR or issue you want to develop without disturbing the current checkout.
+- "Clean up the merged worktrees" — reclaim worktrees whose branches already landed.
+- Diagnosing "why did my new worktree miss its dependencies / node_modules".
+
+This skill is the **worktree lifecycle itself**. The `plan`/`ship` stages may create a worktree as one internal step, but managing worktrees directly — create, list, remove, clean — is this skill.
+
+## Create
+
+```bash
+forge worktree create <slug>
+```
+
+Creates the worktree at `.worktrees/<slug>` and, in one step:
+
+- creates its branch (default `feat/<slug>`),
+- links a kernel issue to the worktree when `--issue <id>` is given (records issue → worktree),
+- installs dependencies with the repo's detected package manager (bun/pnpm/yarn/npm).
+
+Flags:
+
+| Flag | Purpose |
+| --- | --- |
+| `--branch <name>` | Custom branch name (default `feat/<slug>`). |
+| `--base <ref>` | Base ref the new branch forks from (default the repo default branch, e.g. `origin/main`). |
+| `--issue <id>` | Kernel issue id to link this worktree to. |
+| `--work-folder <path>` | Repo-relative work-folder this issue owns (drops a `.forge-issue` marker). |
+
+The kernel issue store lives in the git common dir that every worktree shares, so a new worktree already sees the same kernel — no per-worktree issue-store bootstrap is needed.
+
+## The footgun this skill prevents
+
+**Never use raw `git worktree add`** for Forge work. It only creates a branch + checkout — it does **not** link the kernel issue and does **not** install dependencies. A worktree made that way is why deps end up missing. Always use `forge worktree create`.
+
+## List / remove
+
+```bash
+forge worktree list              # read the worktree registry from the kernel
+forge worktree remove <slug>     # git worktree remove for that slug
+```
+
+## Clean merged worktrees
+
+```bash
+forge clean                      # remove worktrees whose branches merged; FF the default branch
+forge clean --dry-run            # show what would be removed, change nothing
+```
+
+`forge clean` is **squash-aware** — it detects branches that merged via squash, not just fast-forward merges. Removing a merged worktree also closes the kernel issue the branch was linked to, citing the merge as evidence.
+
+Two things it will never touch, because closing an issue is irreversible (`done` is terminal):
+
+- **A branch with no commits of its own.** A freshly created worktree points at a default-branch commit, which git alone reads as "merged". That is unstarted work — it is kept, and its issue stays open.
+- **A worktree it skipped.** Uncommitted changes hold a worktree back, and a held-back worktree never has its issue closed.
+
+### `forge clean` footguns
+
+- **cwd-scoped.** Run it from the **primary repo root**, never from inside a `.worktrees/<slug>` checkout. There is no default-branch guard, so a bare run from the wrong place can remove a clean checkout.
+- **Fast-forward the local default branch first** so squash-merge detection sees the merged state.
+- **Windows long paths.** `node_modules` inside a worktree can exceed the Windows path limit; if `git worktree remove --force` de-registers the worktree but the directory lingers, delete it with a PowerShell extended-path (`\\?\`) remove.
+
+## Adjacent skills
+
+- Opening or pushing a PR / the branch → `ship`.
+- Planning a feature (which may create a worktree as a step) → `plan`.
+- Watching an open PR toward merge → `shepherd`.
+- Everyday issue create/update/close → `issue-basics`.

package/skills/worktree/evals/evals.json

@@ -0,0 +1,38 @@
+[
+  {
+    "query": "Spin up an isolated worktree so I can work on this branch separately.",
+    "should_trigger": true
+  },
+  {
+    "query": "Create a worktree for this issue with its branch and dependencies installed.",
+    "should_trigger": true
+  },
+  {
+    "query": "I want to work on another PR in parallel without disturbing my current checkout.",
+    "should_trigger": true
+  },
+  {
+    "query": "Clean up all the merged worktrees and fast-forward main.",
+    "should_trigger": true
+  },
+  {
+    "query": "Why did my new worktree miss its node_modules dependencies?",
+    "should_trigger": true
+  },
+  {
+    "query": "Set up an isolated branch checkout under .worktrees for this task.",
+    "should_trigger": true
+  },
+  {
+    "query": "Open a pull request and push my feature branch.",
+    "should_trigger": false
+  },
+  {
+    "query": "Plan this new feature and break it into a task list.",
+    "should_trigger": false
+  },
+  {
+    "query": "Watch my PR and tell me why it isn't merging.",
+    "should_trigger": false
+  }
+]