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

package/skills/kernel/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "kernel",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 993,
+      "body_lines": 187,
+      "score": 33
+    },
+    "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": 80
+}

package/skills/memory/SKILL.md

@@ -13,6 +13,7 @@ description: >
   The local backend is always the offline floor. Not for: issue create/list/close ops
   (issue-basics), workflow status (status), or transient scratch notes.
 allowed-tools: Bash, Read, Grep, Glob
+terminal: true
 ---
 
 # Memory
@@ -20,6 +21,16 @@ allowed-tools: Bash, Read, Grep, Glob
 Durable project memory for agents. This skill teaches you where a fact belongs,
 which backend is active, and how to use graph memory when it is enabled.
 
+## Applies to: Forge-managed memory
+
+This skill describes memory managed by **Forge's own store** — `forge remember` /
+`forge recall`, whose backend the Backends section (below) explains. If the repo you are working in ships
+its **own** memory system (a database, an API, a "log a decision" surface, an
+in-app memory service), **that** system is authoritative here and this skill does
+not apply — follow the repo's own memory instructions instead. When unsure, prefer
+the host repo's memory over `forge remember`; a note written to the wrong store is
+a note nobody finds.
+
 ## The one rule
 
 Persistent, project-level knowledge goes to **`forge remember`** — never to a
@@ -33,7 +44,11 @@ is a local file store, so they always work offline with zero setup.
   convention, a decision and its rationale, a non-obvious gotcha, an environment
   quirk, a "we tried X, it failed because Y". Add `--tag <label>` for retrieval.
 - **`forge recall "<query>"`** — before assuming, check what is already known.
-  Search first; do not re-derive knowledge the project already recorded.
+  Search first; do not re-derive knowledge the project already recorded. Note that
+  memory relevant to your current prompt **may already be injected automatically**
+  (a per-turn hook surfaces the best-matching notes; silent when nothing clears the
+  relevance bar). Treat auto-surfaced memory as a head start, and still `recall`
+  explicitly when you need to search for something specific it did not surface.
 - **`forge issue comment <id> "<note>"`** — progress or context that belongs to
   ONE issue's lifecycle (status, a blocker, a hand-off). Issue-scoped, not global.
 - **Rule of thumb:** would a future session on a *different* issue want this? →

package/skills/memory/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "memory",
+  "fixtures": "no-fixtures",
+  "static": {
+    "token_cost": {
+      "desc_chars": 938,
+      "body_lines": 101,
+      "score": 44
+    },
+    "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": "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": 83
+}

package/skills/parallel-deep-research/SKILL.md

@@ -17,6 +17,7 @@ compatibility: Requires PARALLEL_API_KEY in .env.local. Uses curl. Takes 3-25 mi
 metadata:
   author: harshanandak
   version: "1.0.0"
+terminal: true
 ---
 
 # Parallel Deep Research

package/skills/parallel-deep-research/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "parallel-deep-research",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 996,
+      "body_lines": 92,
+      "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/plan/SKILL.md

@@ -13,12 +13,18 @@ description: >
   where work stands or what is stale (status), and NOT for everyday issue create/list/close or
   picking the next ready issue (issue-basics / triage-ready).
 allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+next: dev
+terminal: false
+subskills:
+  - research
 ---
 
 Plan a feature from scratch: brainstorm design intent, research technical approach, then set up branch, worktree, and a complete task list ready for /dev.
 
 # Plan
 
+> **Chain (HARD-GATE):** the next skill after `plan` is `dev`. `plan` composes the `research` sub-skill for its Phase 2 technical bundle. Do not skip ahead past `dev`.
+
 `/plan` is the default planning super-skill. A full invocation runs the three legacy sections below (intent, research, setup/task list), but v3 treats the internal planning work as callable sub-skills:
 
 - `plan.intent_capture`

package/skills/plan/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "plan",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 958,
+      "body_lines": 530,
+      "score": 3
+    },
+    "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": 4,
+    "reachable": true,
+    "keyword_alignment": 0.8
+  },
+  "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": 51
+}

package/skills/portability/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: portability
+description: >
+  Forge kernel data portability — getting issue data in and out of the local kernel. `forge
+  export [--dir] [--dry-run]` writes the kernel backlog to deterministic git-tracked JSONL
+  (D16 portability projection); `forge export --import` reads that committed snapshot back
+  into the kernel (hydrate). `forge migrate --from beads [--dry-run] [--source <dir>]` imports
+  a Beads issue store into the kernel — the onboarding path for users coming from Beads. Use
+  when the user says "export the kernel backlog to JSONL", "back up / snapshot the backlog",
+  "re-import / hydrate the backlog", "migrate from beads", or "import a beads store". Honesty:
+  bare `forge migrate --dry-run` (no `--from`) is v2→v3 preview only; a re-import that applies
+  nothing reports "already hydrated". NOT the cloud/backend sync of the kernel (that is `forge
+  sync`, cloud-native), NOT a database/schema migration (plan/dev), NOT memory notes (memory),
+  NOT syncing a git branch with main (ship).
+allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+---
+
+Moving Forge kernel issue data across a boundary: project the backlog to a git-committable snapshot (and hydrate it back), or import an existing issue store into the kernel. This is data portability — distinct from schema/database migrations and from the cloud backend sync (`forge sync`).
+
+# Export / re-import the backlog
+
+```bash
+forge export                     # write the kernel backlog to git-tracked JSONL (deterministic)
+forge export --dir <path>        # choose the projection directory
+forge export --dry-run           # show what would be written, change nothing
+forge export --import            # read the committed JSONL snapshot back INTO the kernel (hydrate)
+```
+
+`forge export` is the **D16 portability projection**: a deterministic, git-committable snapshot of the backlog you can review in a diff and carry between machines or checkouts. `forge export --import` is the reverse — it hydrates the kernel from that on-disk snapshot; a re-import that finds everything already present reports "already hydrated" rather than claiming it imported anything.
+
+# Migrate in from Beads (or preview v2→v3)
+
+```bash
+forge migrate --from beads [--dry-run]     # import a Beads issue store into the kernel
+forge migrate --from beads --source <dir>  # point at exported beads *.jsonl (defaults to auto-detecting .beads/)
+forge migrate --dry-run                    # preview the v2→v3 migration (the ONLY supported mode without --from)
+```
+
+`forge migrate --from beads` is the **onboarding path for users coming from Beads** — it imports a Beads issue store into the Forge Kernel (`--dry-run` reads + maps only, writing nothing). Without `--from`, migrate is **v2→v3 preview only**: `--dry-run` is required and applying the migration is not yet available.
+
+## Boundaries
+
+- The **cloud/backend sync** of the kernel is `forge sync` (cloud-native) — a different operation; this skill is the local, git-based portability projection.
+- A **database/schema** migration (adding a column, altering a table) is application work — that's **plan**/**dev**, not `forge migrate`.
+- Persisting a decision or note is **memory** (`forge remember`), not export.
+- Syncing a git **branch** with main before a PR is **ship**/**worktree**.

package/skills/portability/evals/evals.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Back up the kernel backlog to a git-tracked JSONL snapshot.",
+    "should_trigger": true
+  },
+  {
+    "query": "Export the kernel backlog to git-tracked JSONL.",
+    "should_trigger": true
+  },
+  {
+    "query": "Migrate our Beads issue store into the Forge kernel.",
+    "should_trigger": true
+  },
+  {
+    "query": "Dry-run the beads migration and show what would be imported.",
+    "should_trigger": true
+  },
+  {
+    "query": "Re-import the exported backlog JSONL into the kernel.",
+    "should_trigger": true
+  },
+  {
+    "query": "Migrate the database schema to add the new billing column.",
+    "should_trigger": false
+  },
+  {
+    "query": "Sync my feature branch with main before opening the PR.",
+    "should_trigger": false
+  },
+  {
+    "query": "Remember this decision for later.",
+    "should_trigger": false
+  }
+]

package/skills/portability/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "portability",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 957,
+      "body_lines": 31,
+      "score": 50
+    },
+    "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": 5,
+    "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": 85
+}

package/skills/research/SKILL.md

@@ -14,6 +14,7 @@ description: >
   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
+terminal: true
 ---
 
 Investigate anything, from anywhere: verify a claim, search the web, find better options, pull

package/skills/research/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "research",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 1014,
+      "body_lines": 179,
+      "score": 33
+    },
+    "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": 2,
+    "reachable": true,
+    "keyword_alignment": 0.4
+  },
+  "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": 60
+}

package/skills/review/SKILL.md

@@ -13,12 +13,18 @@ description: >
   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
+next: verify
+terminal: false
+handoffs:
+  - shepherd
 ---
 
 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
 
+> **Chain (HARD-GATE):** the successor depends on the change classification (source of truth: lib/workflow/stages.js) — Critical → `verify` (post-merge health check); Standard ENDS at `review`. `verify` is the default/critical-path next. While the PR is still open you may hand off to `shepherd` to watch checks toward merge. `review` never merges.
+
 This skill handles ALL issues that arise after creating a pull request.
 
 ## Usage

package/skills/review/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "review",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 988,
+      "body_lines": 476,
+      "score": 4
+    },
+    "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": 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": 71
+}

package/skills/rollback/SKILL.md

@@ -13,6 +13,7 @@ description: >
   (shepherd), the post-merge CI health check on master (verify), pushing a branch or opening a
   PR (ship), or ordinary issue status/field edits (issue-basics).
 allowed-tools: Bash, Read, Edit, Grep, Glob
+terminal: true
 ---
 
 Comprehensive rollback system with multiple methods and automatic USER content preservation.

package/skills/rollback/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "rollback",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 965,
+      "body_lines": 95,
+      "score": 43
+    },
+    "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": 1,
+    "reachable": true,
+    "keyword_alignment": 0.17
+  },
+  "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/setup/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: setup
+description: >
+  Forge install & setup lifecycle. `forge setup` interactively configures Forge for your
+  coding agents; `forge init [--profile minimal|standard|full]` writes the
+  adoption config in a fresh repo; `forge doctor` reports whether the kernel DB is on a
+  cloud/network path; `forge upgrade [--dry-run]` previews + self-heals upgrade readiness;
+  `forge hooks install --global` installs native hooks; `forge reset --soft|--hard --force`
+  and `forge reinstall --force` undo/redo the install; `forge recommend` lists suggested
+  tools. Use when the user says "install/set up forge", "init forge", "adoption profile",
+  "forge doctor", "upgrade forge", "install the hooks globally", or "reset/reinstall forge".
+  Footguns: setup is interactive — pass `--yes` in automation; `doctor` only checks the
+  kernel-DB filesystem class, NOT general health; `upgrade` self-heals Forge state, NOT the
+  npm package; reset/reinstall need `--force`. NOT toggling a gate/rail (gates), NOT
+  orienting in a set-up repo (status), NOT installing project deps (dev).
+allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+---
+
+Getting Forge installed, configured, upgraded, and diagnosed in a repo. These are the bootstrap and maintenance commands — distinct from the everyday workflow stages.
+
+# Install & configure
+
+```bash
+forge setup                      # interactive agent configuration (Claude/Cursor/Codex …)
+forge setup --yes                # non-interactive: accept defaults (use this in automation)
+forge setup --agents claude,cursor --skip-external   # target specific harnesses, skip service prompts
+forge setup --path <dir> --dry-run                   # preview against another dir, write nothing
+```
+
+`forge setup` is **interactive by default**. In any automated/agent context pass `--yes` (or `--non-interactive`) so it never blocks on a prompt.
+
+# Initialize a fresh repo
+
+```bash
+forge init --minimal             # shortcut for --profile minimal --yes
+forge init --profile standard --harness claude,cursor
+forge init --classification standard --dry-run       # preview the adoption config
+```
+
+`forge init` writes the Forge adoption config (`.forge/config.yaml`). The profile picks how much enforcement ships on: `minimal` (rails off) → `standard` → `full`. This configures the workflow; toggling an individual gate afterward is the **gates** skill.
+
+# Diagnose
+
+```bash
+forge doctor            # is the kernel DB on a cloud-synced / network path? (reliability signal)
+forge doctor --json     # machine-readable
+```
+
+`forge doctor` is **narrow**: it reports the filesystem class of the Forge kernel database path (local / cloud-synced / network) so you can catch the reliability footgun of running the DB on OneDrive/Dropbox/a network share. It is **not** a general health check.
+
+# Upgrade readiness
+
+```bash
+forge upgrade --dry-run    # preview the planned self-heal, change nothing
+forge upgrade              # apply safe self-heal steps to make the repo upgrade-ready
+```
+
+`forge upgrade` previews and applies **safe self-heal** steps for Forge's own state. It does **not** update the installed npm package — use your package manager for that.
+
+# Global hooks
+
+```bash
+forge hooks install --global                       # install native hooks for all harnesses
+forge hooks install --global --harness codex       # scope to one harness (codex|hermes|all)
+forge hooks install --global --dry-run             # preview
+```
+
+`--global` is the required consent flag — it opts you into installing hooks at the user level. (The other `forge hooks` subcommands — `session-start`, `inbox-pickup`, `shepherd-events`, `memory-recall`, `capture` — are machine-facing hook emitters the harness calls, not things you run by hand.)
+
+# Undo / redo the install
+
+```bash
+forge reset --soft --force     # remove .forge/ config only (keeps commands, rules, agents)
+forge reset --hard --force     # remove ALL forge-managed files (keeps user-created files)
+forge reinstall --force        # remove + re-run default setup in one step
+```
+
+`reset` and `reinstall` are destructive, so `--force` is required. `reset` with no `--soft`/`--hard` just prints usage.
+
+# Recommend tooling
+
+```bash
+forge recommend         # suggest tools/integrations for the current project
+```
+
+## Boundaries
+
+- Toggling a single gate/rail (e.g. TDD, kernel-tracking) is **gates** — `init` *writes* the initial config; `gates` *flips* one afterward.
+- "Where am I / how is forge set up" in an already-configured repo is **status** / **kernel**, not setup.
+- Installing project dependencies (`bun install`) is **dev**, not `forge setup`.

package/skills/setup/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Install Forge into this repo and configure it for Claude and Cursor.",
+    "should_trigger": true
+  },
+  {
+    "query": "Initialize forge in this fresh repository with the minimal adoption profile.",
+    "should_trigger": true
+  },
+  {
+    "query": "Run forge doctor — is the kernel database on a cloud-synced path?",
+    "should_trigger": true
+  },
+  {
+    "query": "Upgrade forge and self-heal anything unsafe first.",
+    "should_trigger": true
+  },
+  {
+    "query": "Install the Forge native hooks globally for Codex.",
+    "should_trigger": true
+  },
+  {
+    "query": "Undo the forge install — reset this repo's forge files.",
+    "should_trigger": true
+  },
+  {
+    "query": "Disable the TDD gate, it's blocking my commit.",
+    "should_trigger": false
+  },
+  {
+    "query": "Set up the database schema for the new billing feature.",
+    "should_trigger": false
+  },
+  {
+    "query": "Upgrade the eslint dependency to the latest version.",
+    "should_trigger": false
+  },
+  {
+    "query": "Install the project dependencies with bun install.",
+    "should_trigger": false
+  }
+]