forge-workflow 0.0.10 → 0.1.0-beta.2

package/skills/hermes-forge/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: hermes-forge
+description: >
+  Hermes⇄Forge boundary: Hermes CONSUMES Forge state, never a second source of truth. Use
+  whenever a Hermes session runs on a Forge repo: at session start, before acting on an issue,
+  or when you need CURRENT state. Read state ONLY via `forge orient` / `forge recap
+  <issue-id>` (bounded JSON envelope), citing each source's `path`/`authority`; never
+  reconstruct it from raw stores or kernel internals. Writeback ONLY via `forge
+  comment`/`update`/`create`; NEVER leak Hermes profile or session memory into Forge state.
+  Triggers: "orient me / current project state", "where did this fact come from, cite it",
+  "orient came back truncated", "persist a decision into Forge", "safe to store in kernel
+  state?". NOT the Forge session router over stage skills (kernel), NOT the human "what stage
+  am I in" report (status), NOT everyday issue create/update/close/search CRUD (issue-basics),
+  NOT ranking the next ready issue (triage-ready), NOT live PR monitoring (shepherd—outside
+  Hermes, unseen by orient).
+compatibility: >
+  Requires the Forge CLI (`forge`) on PATH in a Forge-initialized repo. Install
+  path — like every Forge skill pack (e.g. parallel-deep-research,
+  sonarcloud-analysis) this is delivered by the unified Skills CLI; run
+  `skills sync` to install it into `.hermes/skills/hermes-forge/`. (`forge setup`
+  initializes the skills registry via `skills init` but does not sync packs to
+  agents.) Read-only orientation works anywhere; writeback requires a Forge
+  Kernel issue backend. CLI-only — no direct file or profile writes into Forge
+  state.
+metadata:
+  author: forge
+  version: "1.0.0"
+  roadmap: forge-2agy.9.7.x
+---
+
+# Hermes ⇄ Forge consumption contract
+
+Hermes is a *consumer* of Forge project state, not an owner of it. This skill
+defines how a Hermes session reads, cites, and writes back to a Forge project
+without ever becoming a second source of truth.
+
+The boundary between what Forge owns and what Hermes owns is specified in the
+Forge repo at `docs/reference/HERMES_INTEGRATION.md` (repo-relative path — this
+skill is synced to `.hermes/skills/hermes-forge/`, so relative links would not
+resolve from the installed location).
+
+## When to use
+
+- At the start of any Hermes session on a Forge repo (orientation).
+- Before acting on a specific issue (issue recap).
+- Whenever you need current project state — never reconstruct it from raw files.
+
+## Authority: orient / recap are the only state source
+
+The Forge Kernel is the single source of truth. Hermes obtains project state
+**exclusively** through two thin CLI wrappers and must not infer state by
+reading raw issue stores, design files, or kernel internals directly:
+
+```bash
+forge orient --json                # bounded project orientation (envelope)
+forge orient --budget 4000 --json
+forge recap <issue-id> --json      # bounded per-issue recap (envelope)
+```
+
+`forge orient` and `forge recap <issue-id>` emit the deterministic JSON envelope
+described below (assembly `deterministic-file-assembly-v1`). Parse the JSON; do
+not screen-scrape the human text form.
+
+> Note: `forge recap` always requires an issue id — bare `forge recap --json`
+> (no id) prints its usage and exits non-zero rather than returning a summary.
+> Use `forge orient` for project-level orientation, or `forge recap <issue-id>`
+> for a single issue; both emit the deterministic envelope.
+
+### Envelope shape
+
+| Field | Meaning |
+| --- | --- |
+| `schema_version` | Contract version (currently `1`). Reject unknown majors. |
+| `kind` | `orientation`, `issue_recap`, or `prime`. |
+| `generated_at` | Assembly timestamp. |
+| `assembly` | `deterministic-file-assembly-v1` — same inputs ⇒ same output. |
+| `token_budget` | Budget accounting (see below). |
+| `sections[]` | Ordered content blocks, each independently cited. |
+| `sources[]` | Deduplicated provenance across all sections. |
+| `next_commands[]` | Suggested follow-up `forge` commands. Prefer these for navigation. |
+
+Each `sections[]` entry: `{ id, title, content, sources, truncated, estimated_tokens }`.
+
+## Token budget
+
+`forge orient` / `forge recap <issue-id>` are bounded so they fit a context
+window deterministically.
+
+- Default budget: **2000** estimated tokens. Minimum honored: **40**.
+- Estimation is approximate: `token_budget.approximate === true`,
+  `token_budget.chars_per_token === 4`.
+- `token_budget.requested` is what you asked for; `token_budget.used` is the
+  estimate actually emitted.
+- Raise the ceiling with `--budget N` when you need more depth; do not retry
+  blindly — request a specific larger budget.
+
+## Citation & provenance model
+
+Every fact Hermes surfaces to a user MUST be attributable. Each section carries
+`sources: [{ path, source_kind, authority, role }]`:
+
+- `path` — the file the content came from.
+- `source_kind` — the kind of artifact (e.g. design, decision, claim, queue).
+- `authority` — how authoritative the source is. Prefer higher-authority
+  sources when two sources conflict; surface the conflict rather than silently
+  picking one.
+- `role` — the role the source plays in the section.
+
+When Hermes states a project fact, cite at least the `path` and `authority` of
+the backing source. The top-level `sources[]` is the deduplicated set for the
+whole payload.
+
+## Truncation policy
+
+Truncation is deterministic, never random:
+
+- Non-preserved sections are trimmed in the order given by
+  `token_budget.truncation_order`; when the budget is exhausted, sections later
+  in that order are trimmed first. Preserved sections are kept whole and trimmed
+  only as a last resort if the payload is still over budget. The authoritative
+  per-section signal is each section's `truncated` flag and `estimated_tokens` —
+  there is no per-section `priority` field; the overall trim order is
+  `token_budget.truncation_order`.
+- A trimmed section ends with the literal marker
+  `[truncated deterministically by token budget]` and has `truncated: true`.
+- `token_budget.truncated === true` means the payload as a whole was trimmed.
+
+Treat any `truncated` section as **incomplete**. Do not present a truncated
+section as exhaustive; if completeness matters, re-request with a higher
+`--budget` or recap the specific issue.
+
+## Writeback path: Hermes → Forge Kernel
+
+Evidence and decisions discovered during a Hermes session flow back into the
+Forge Kernel **only** through Forge CLI commands. Use the issue command surface
+documented in the Forge repo at
+`docs/reference/forge-kernel-issue-command-contract.md`:
+
+```bash
+forge comment <id> <body...>   # attach evidence, a decision, or a note to an issue
+forge update <id...> [flags]   # update issue state/fields
+forge create [title] [flags]   # open a new issue for follow-up work
+```
+
+> Note: `forge audit` is verify-only (`forge audit verify`) and does **not**
+> append evidence — record evidence as an issue comment via `forge comment`.
+
+These writes land in the Forge Kernel issue store, where they become part of the
+issue's durable history (view them via the issue itself, e.g. `forge show <id>`).
+Note the read/write asymmetry: the bounded `forge orient` / `forge recap`
+envelope is assembled from project docs, `docs/work` artifacts, and the issue
+summary — it surfaces issue/design/decision state but does **not** echo
+individual issue comments back. Do not assume evidence added via `forge comment`
+reappears verbatim in the next orient/recap payload; it lives in the issue
+history, reachable from the issue record.
+
+## No-profile-write guard (hard boundary)
+
+Hermes **MUST NOT write Hermes profile** state, conversation memory, or any
+Hermes-native artifact into Forge Kernel state — not into kernel storage, not
+into design/decision files, not into the issue backend. Hermes-native memory
+stays in Hermes' own store.
+
+- ✅ Read state via `forge orient` / `forge recap`.
+- ✅ Write evidence/decisions via `forge comment` / `forge update`.
+- ❌ Never persist Hermes profile/session memory into Forge Kernel state.
+- ❌ Never edit Forge state files directly to record Hermes-side context.
+
+If a piece of context only matters to Hermes, it belongs in Hermes-native
+memory. If it is a project fact, decision, or evidence item, write it through
+the Forge CLI so it becomes part of the shared, cited source of truth.
+
+## PR shepherd (external scheduler, not orientation)
+
+The PR shepherd runs **outside** Hermes. An external scheduler invokes
+`forge shepherd <pr>` as discrete bounded passes — each pass reads CI/check
+state, takes at most one idempotent action (re-run a flaky required check), or
+escalates, then exits. It **never merges** (the human merges in the GitHub UI)
+and **never resolves review threads**.
+
+Hermes does not run the shepherd and does not learn shepherd progress through
+`forge orient` (which is deterministic-source orientation with no live PR
+awareness). Shepherd progress is durable on the **PR itself** — its comments and
+labels. When a Hermes session needs PR/CI status, read the PR directly; do not
+expect `orient` to carry it.

package/skills/hermes-forge/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "I just started a Hermes session on this Forge repo — get me oriented on where the project stands before I touch anything.",
+    "should_trigger": true
+  },
+  {
+    "query": "The forge orient envelope came back with the active-work section flagged truncated. Can I treat that as the full list, or do I need to pull more?",
+    "should_trigger": true
+  },
+  {
+    "query": "Before I tell the user which approach we settled on, I need to point at the exact source file and how authoritative it is — where does that decision come from?",
+    "should_trigger": true
+  },
+  {
+    "query": "I uncovered a design decision in this session that the team needs to keep. What's the correct way to write it back into Forge without dragging my Hermes notes into kernel state?",
+    "should_trigger": true
+  },
+  {
+    "query": "Default orientation is clipping the decisions section at 2000 tokens — give me more headroom.",
+    "should_trigger": true
+  },
+  {
+    "query": "Don't rebuild the project picture by grepping the design docs yourself — go through the proper bounded orient/recap surface instead.",
+    "should_trigger": true
+  },
+  {
+    "query": "Which workflow stage am I sitting in right now, and has any of my work gone stale?",
+    "should_trigger": false
+  },
+  {
+    "query": "I'm kicking off a Forge session in Claude — which stage skill do I run to start planning a new feature?",
+    "should_trigger": false
+  },
+  {
+    "query": "Watch PR #418, rerun the flaky required check if it trips, and ping me when it's ready to merge.",
+    "should_trigger": false
+  },
+  {
+    "query": "Open a bug issue for the checkout timeout, set priority 1, and add a note about the repro steps.",
+    "should_trigger": false
+  },
+  {
+    "query": "What's the highest-priority ready issue I should pick up next?",
+    "should_trigger": false
+  }
+]

package/skills/issue-basics/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: issue-basics
+description: >
+  Everyday single-issue CRUD over the `forge issue` verbs:
+  create/update/show/list/search/close/reopen/comment, set priority/labels/assignee, claim or
+  release one issue, add/remove dependency edges, plus backlog `stats`. Use for ANY routine
+  one-off issue op: "create an issue/bug/task for X", "update/edit issue <id>", "close or
+  reopen this issue", "comment a handoff note on <id>", "list/filter open bugs by
+  status/label/priority", "bump this to P1", "reassign to alice", "mark <id> blocked by <id>".
+  Also the parity floor migrating off a Beads-style tracker (label/reopen/delete map to forge
+  equivalents). Single-operation plumbing only. Does NOT choose, rank, or explain the next
+  issue to work on or why it's blocked (use triage-ready); does NOT run
+  claim-then-prove-lease-ownership safety (use claim-safety); does NOT drive an issue through
+  the plan->dev->validate->ship pipeline or open a PR (use smith or stage skills); does NOT
+  report the current stage or what's in flight (use status).
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Issue basics — the CRUD floor
+
+Everyday issue operations over the Forge kernel. Every command here is a real
+`forge issue` verb (confirm with `forge issue --help`). The kernel is the single
+source of truth — never hand-edit the issue store.
+
+Every `--json` reply is the same envelope: `{ ok, schema_version, command, data,
+next_commands }` on success, or `{ ok:false, error:{ message, exit_code } }` on
+failure. **Gate on `ok`** — do not parse `data` until you confirm `ok:true`.
+
+## The core loop
+
+| Need | Command |
+|------|---------|
+| Create an issue | `forge issue create --title "…" --type <task\|bug\|epic\|decision>` |
+| Inspect one issue | `forge issue show <id> [--json]` |
+| List / filter issues | `forge issue list [--status … --type … --priority … --label …] [--json]` |
+| Full-text search | `forge issue search "…" [--json]` |
+| Backlog counts | `forge issue stats [--json]` |
+| Claim work (DB-enforced lease) | `forge issue claim <id>` |
+| Release a claim | `forge issue release <id>` |
+| Update fields | `forge issue update <id> [flags]` |
+| Add a handoff note | `forge issue comment <id> "…"` |
+| Close (one or many) | `forge issue close <id...> --reason "…"` |
+| Dependencies | `forge issue dep add\|remove <id> <blocks-id>` |
+
+## Create — the flags that matter
+
+```bash
+forge issue create --title "Add rate limiting" --type task \
+  --priority P1 --label "feature,api,security" --assignee alice \
+  --acceptance "429 returned after N req/min; covered by a test"
+```
+
+| Flag | Meaning | Default |
+|------|---------|---------|
+| `--title "…"` | Human title (a bare leading positional also works) | minted id |
+| `--type <…>` | `task` · `bug` · `epic` · `decision` | `task` |
+| `--priority <…>` | `P0`..`P4` (or bare `0`..`4`); `P0` is highest | unset |
+| `--label "a,b"` | Comma-separated set — one flag, split on `,` (repeats do NOT accumulate) | none |
+| `--body "…"` | Long description (`--description` is an accepted alias) | empty |
+| `--assignee <who>` | Persistent assignee | unset |
+| `--acceptance "…"` | Acceptance criteria (`--design`, `--notes` also persist) | unset |
+| `--parent <id>` | Parent/epic id | none |
+
+`--status` defaults to `open`. Status vocabulary: `open` · `in_progress` ·
+`review` · `done` · `cancelled`. Unlike `--priority` and `--status` (which reject
+unknown values), `--type` is stored verbatim — a non-canonical value like
+`feature` is accepted without error but carries no kernel behaviour, so stick to
+the four canonical types. Epics and decisions are excluded from the ready queue
+(non-claimability is a queue convention, not enforcement — `forge issue claim`
+currently returns `ok:true` on them too).
+
+## Update — same field flags, plus close
+
+`forge issue update <id>` takes `--status`, `--title`, `--body`/`--description`,
+`--priority`, `--label` (reparents the whole set), `--parent`, `--assignee`,
+`--acceptance`, `--design`, `--notes`. `forge issue close <id> --reason "…"`
+records the reason on the close event and accepts multiple ids in one call.
+
+## Migrating from a Beads-style tracker — verb disposition
+
+Nothing you relied on silently disappears; a few verbs map onto a `forge` flag or
+are intentionally unsupported:
+
+| Old verb | Forge equivalent |
+|----------|------------------|
+| `label` (add/remove) | **No subcommand** — pass the full set via `--label "a,b"` on `create`/`update` (last-value-wins). |
+| `reopen` | `forge issue update <id> --status open`. |
+| `delete` | **Unsupported by design** — the kernel is append-only/event-sourced. Use `forge issue close <id> --reason "…"` instead. |
+
+## Reliability
+
+- **Check `ok` before trusting output.** On `ok:false`, read `error.message` and
+  fix the input rather than retrying blindly.
+- **Claim before you mutate shared work.** `forge issue claim <id>` takes a
+  DB-enforced lease; hand off to the `claim-safety` procedure before acting on a
+  claimed issue you intend to change. `forge issue release <id>` if you abandon it.
+- **Record decisions as comments, not memory.** `forge issue comment <id> "…"`
+  survives the session; scratch notes do not.
+
+## Fork points
+
+Editable conventions — set these once for your team and this skill enforces them.
+It is a canonical source you fork, not a fixed policy.
+
+| Knob | Default | How to change |
+|------|---------|---------------|
+| **Default type** | `task` (kernel default) | Decide your create convention — e.g. always pass `--label feature` for user-facing work (feature is a label, not a canonical type), `--type bug` for regressions. |
+| **Default priority** | unset | Adopt a house scale (e.g. new work opens at `P2`, incidents at `P0`) and always pass `--priority`. |
+| **Fields required on create** | `--title` only | Require `--acceptance` (and `--label`/`--assignee`) on every create so issues are actionable from birth. |
+| **Id / reference convention** | kernel-minted ids | Standardize how you cite issues in commits/PRs (e.g. `Closes <id>`) and whether you pass an explicit `--id`. |
+| **Label taxonomy** | free-form | Pin an allowed label set your team agrees on and pass it consistently via `--label "a,b"`. |

package/skills/issue-basics/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "Open a bug ticket for the checkout 500 error and mark it P0",
+    "should_trigger": true
+  },
+  {
+    "query": "Add a note to forge-abc123 documenting why we chose JWT",
+    "should_trigger": true
+  },
+  {
+    "query": "Show me all open issues tagged backend",
+    "should_trigger": true
+  },
+  {
+    "query": "Reopen forge-77, it wasn't actually fixed",
+    "should_trigger": true
+  },
+  {
+    "query": "Add a dependency so forge-12 is blocked by forge-9",
+    "should_trigger": true
+  },
+  {
+    "query": "Claim forge-abc so I can start on it",
+    "should_trigger": true
+  },
+  {
+    "query": "What's the next ready issue I should pick up?",
+    "should_trigger": false
+  },
+  {
+    "query": "Explain why forge-55 is still blocked and what to unblock first",
+    "should_trigger": false
+  },
+  {
+    "query": "Claim this issue and confirm I hold the lease before I change anything",
+    "should_trigger": false
+  },
+  {
+    "query": "Drive forge-30 all the way through to a merged PR",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow right now and what's in flight?",
+    "should_trigger": false
+  }
+]

package/skills/kernel/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: kernel
+description: >
+  Forge kernel — umbrella index/router for a Forge project. Reach for this FIRST when
+  orienting rather than executing: at session start, when you need the map of how the system
+  fits together, or when unsure WHICH skill or `forge` verb a task belongs to. It indexes
+  `smith` (end-to-end orchestrator), the stage ladder (plan → dev → validate → ship → review →
+  verify), the utility/issue skills, and the day-to-day `forge` CLI verbs. Trigger on "how
+  does the Forge workflow work", "which forge command or skill for X", "I'm new here, how is
+  Forge set up", or "should this be a Forge issue or a TodoWrite". Index layer only — hand off
+  the doing: rank/pick the next ready issue → `triage-ready`; current stage / "where am I" /
+  active or stale work → `status`; create/update/close/search one issue → `issue-basics`;
+  claim-then-prove ownership before mutating → `claim-safety`; drive one issue from plan to a
+  merged PR under gates → `smith`; token-bounded state for the Hermes harness →
+  `hermes-forge`.
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Forge kernel surface
+
+Forge is a TDD-first workflow harness. The agent-facing surface is **skills + the
+`forge` CLI** — there are no slash-command files. This umbrella skill is the
+entry point: it tells you which stage skill to use and which `forge` verb runs
+each day-to-day operation. Every skill is a thin guide over a real `forge`
+command; the CLI remains the implementation, the skills are the surface.
+
+## Stage skills (the TDD ladder)
+
+The default workflow is a configurable ladder of per-stage skills. Use the whole
+flow when it fits, or invoke an individual stage when the active plan permits a
+smaller path.
+
+| Stage | Skill | Purpose |
+|-------|-------|---------|
+| utility | `status` | Check current context, active work, recent completions |
+| 1 | `plan` | Design intent → research → branch + worktree + task list |
+| 2 | `dev` | Subagent-driven TDD per task (implementer → spec → quality review) |
+| 3 | `validate` | Type check, lint, code review, security, tests — all fresh output |
+| 4 | `ship` | Push branch and open the PR with design-doc reference |
+| 5 | `review` | Address ALL PR feedback (GitHub Actions, Greptile, SonarCloud) |
+| 6 | `verify` | Post-merge health check (CI on main, close issues) |
+
+**Pre-merge gate** (not a numbered stage): before merge, finish the doc updates on
+the feature branch and confirm CI is green, then hand off the PR for manual merge.
+The gate is embedded in `ship` and `review` — it is not a standalone skill.
+
+Utility skills outside the linear ladder: `research` (deep web research),
+`rollback` (safe revert operations), `sonarcloud` (code-quality queries),
+`shepherd` (cross-harness PR monitoring).
+
+Procedure skills (reusable operations any stage/agent embeds): `claim-safety`
+(claim an issue and PROVE you own the lease via `forge issue owns <id>` before
+mutating it — a claim returning ok:true does not by itself prove ownership).
+
+```
+status → plan → dev → validate → ship → review → verify
+```
+
+## Orchestrator super-skill
+
+`smith` is the flagship: a thin orchestrator that COMPOSES the skills above into
+the right path for a piece of work — pick (`triage-ready`) → claim
+(`claim-safety`) → `plan` → `dev` → `validate` → `ship` → `review` → `verify` —
+driving autonomously between human gates and pausing AT them. The human gates are
+durable kernel EVENTS (`forge gate check|approve|reject|status <issue> <gate>`;
+gates `gate.intent` · `gate.plan-approval` · `gate.merge`), so a gated run is
+resume-safe across compaction. During planning `smith` calibrates how many gates
+the work needs from its size × importance × complexity and proposes that tier at
+the intent gate (the human confirms or overrides). Reach for `smith` to run a
+whole issue end to end under human control; invoke an individual stage skill to
+run a single step.
+
+## Kernel-native skills
+
+Read-and-repair skills that work directly against the kernel's issue store. They
+complement the ladder: reach for them to decide *what* to do and to run the
+everyday issue operations, then route into a stage skill to execute.
+
+| Skill | Purpose |
+|-------|---------|
+| `triage-ready` | Read-only "what should I work on" — ranks and *explains* the ready queue via `forge issue ready` / `blocked` / `stats` (never `board`), then hands off the pick. |
+| `issue-basics` | The everyday CRUD floor — create/update/claim/release/comment/close/show/list/search/stats over the `forge issue` verbs, plus the label/reopen/delete disposition for teams migrating in. |
+
+## Day-to-day verbs (the `forge` CLI)
+
+The kernel verbs are the operations you reach for inside any stage — find work,
+claim it, fix in place, query the board, orient. They are grouped in four
+families. Run them through Bash; never hand-edit the issue store.
+
+### A — Issue lifecycle (the core loop)
+
+| Need | Command |
+|------|---------|
+| Find ready work | `forge ready [--json]` |
+| Inspect an issue | `forge show <id> [--json]` |
+| List / filter issues | `forge list [--status …] [--json]` |
+| Create an issue | `forge create --title "…" --type <feature\|bug\|task>` |
+| Claim work (DB-enforced lease) | `forge claim <id>` |
+| Prove you own the lease | `forge issue owns <id>` — exit 0 iff you hold the live lease (see the `claim-safety` skill) |
+| Release a claim | `forge release <id>` |
+| Update fields | `forge update <id> --priority <n>` (etc.) |
+| Add a handoff comment | `forge comment <id> "…"` |
+| Close an issue | `forge close <id> --reason "…"` |
+| Dependencies | `forge issue dep add\|remove <id> <id>` |
+| Search / stats | `forge issue search "…"` · `forge issue stats` |
+| Blocked work | `forge blocked` |
+
+### B — Memory / knowledge
+
+`forge remember <note> [--tag <label>]... [--json]` and `forge recall` are live —
+they persist and retrieve project-memory notes from a file-backed store. Only
+`forge knowledge search` is not on the CLI yet; until it lands, capture durable
+decisions as `forge remember` notes or issue comments (`forge comment`).
+
+### C — Board / planning / admin
+
+| Need | Command |
+|------|---------|
+| Team board | `forge board [--json]` |
+| Export the issue projection | `forge export [--import]` |
+| Release-readiness gate | `forge release check --target <ref>` |
+| Sync team state | `forge sync` |
+
+### D — Orientation / session
+
+| Need | Command |
+|------|---------|
+| Prime a session | `forge prime [--json]` |
+| Full orientation | `forge orient [--json]` |
+| Recap an issue / context | `forge recap [<id>] [--json]` |
+
+## Forge issues vs. TodoWrite — decision table
+
+| Situation | Use |
+|-----------|-----|
+| Work spans sessions, has blockers, or needs recovery after compaction | **Forge issues** (`forge create`/`claim`/`close`) |
+| Cross-agent or cross-worktree coordination | **Forge issues** (DB-enforced leases) |
+| Durable decisions, design rationale, handoff notes | **Forge issue comments** |
+| Ephemeral, single-session checklist for the current task | **TodoWrite** |
+| Steps you will finish and discard within this turn | **TodoWrite** |
+
+When in doubt, prefer a Forge issue: it survives the session and is visible to
+the team. TodoWrite is for scratch tracking only.
+
+## Session protocol
+
+1. **Orient first.** Start with the `status` skill (or `forge prime` /
+   `forge orient`) — never reconstruct project state from raw files.
+2. **Claim before you build — then prove it.** `forge claim <id>` takes the lease;
+   one issue at a time. A claim's ok:true does not by itself prove ownership, so
+   confirm with `forge issue owns <id>` before working and again before
+   `close`/`release` (the `claim-safety` skill). `forge release <id>` if you abandon it.
+3. **Work the ladder.** `plan` → `dev` → `validate` → `ship` → `review` →
+   `verify`, skipping stages only when the plan allows. The pre-merge doc gate
+   runs inside `ship` and `review` before merge — it is not a separate stage.
+4. **Record evidence as you go.** Progress and decisions go to
+   `forge comment <id> "…"`, not to memory.
+5. **Hand off cleanly.** Close completed issues (`forge close <id> --reason …`)
+   and `forge sync` so the team sees the result.
+
+## Core principles
+
+- **TDD-first** — write tests before implementation (RED → GREEN → REFACTOR).
+- **Research-first** — understand before building; document decisions.
+- **Security built-in** — OWASP Top 10 analysis for every feature.
+- **Documentation progressive** — update at each stage, verify at the end.

package/skills/kernel/evals/evals.json

@@ -0,0 +1,50 @@
+[
+  {
+    "query": "I just cloned this Forge repo and I'm not sure how any of it works — give me the lay of the land: what's the workflow, what skills exist, and where do I even start?",
+    "should_trigger": true
+  },
+  {
+    "query": "There are a bunch of forge skills and I can't tell which one to use for what — lay out how they fit together and when I'd reach for each.",
+    "should_trigger": true
+  },
+  {
+    "query": "Which forge CLI command adds a dependency between two issues, and what's the verb for proving I hold a claim? Just the reference, don't run anything.",
+    "should_trigger": true
+  },
+  {
+    "query": "Is this small cleanup worth filing as a Forge issue, or should I just throw it on a TodoWrite checklist for this session?",
+    "should_trigger": true
+  },
+  {
+    "query": "Walk me through the Forge stage ladder from planning to post-merge verify and what each stage owns.",
+    "should_trigger": true
+  },
+  {
+    "query": "Give me the reference of all the day-to-day forge issue and board verbs — I want the index, not to execute a command yet.",
+    "should_trigger": true
+  },
+  {
+    "query": "What should I pick up next? Rank the ready queue and tell me the top unblocked issue and why.",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow right now, what's my active work, and has anything gone stale?",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a bug issue titled 'login times out after 30s', priority 1, and link it under the auth epic.",
+    "should_trigger": false
+  },
+  {
+    "query": "Claim forge-4h9 for me and confirm I actually hold the lease before I start editing.",
+    "should_trigger": false
+  },
+  {
+    "query": "Take forge-7c2 all the way from planning through a merged PR, pausing for my approval at the plan and the merge.",
+    "should_trigger": false
+  },
+  {
+    "query": "In the Hermes harness, give me the token-bounded project state to work from — treat forge orient as the source of truth.",
+    "should_trigger": false
+  }
+]