# Kernel

> 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`.

- Skill: `harshanandak/kernel` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add harshanandak/kernel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/harshanandak/kernel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: harshanandak (https://skillmd.com/u/harshanandak)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/harshanandak/kernel

---


# 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
```

### Chain map (each skill declares its successor)

Every skill carries chain metadata in its frontmatter (`next`, `terminal`,
`subskills`, `handoffs`); each workflow STAGE skill additionally carries a
HARD-GATE chain line in its body, so each stage announces the next one. The
linear ladder:

| Skill | `next` | `terminal` |
|-------|--------|-----------|
| `plan` | `dev` | `false` |
| `dev` | `validate` | `false` |
| `validate` | `ship` | `false` |
| `ship` | `review` | `false` |
| `review` | `verify` | `false` |
| `verify` | `ship` | `false` |

The `next` column is each stage's DEFAULT / critical-path successor (`plan`
composes `research`; `ship` and `review` also carry a `shepherd` handoff). The
actual successor after `ship`, `review`, and `verify` is classification-dependent
— see the note below. `verify`'s `next` (`ship`) is the `docs`-only pre-ship
reuse; in every other flow nothing follows `verify`.

Feeders into the chain: `triage-ready` → `claim-safety` → `dev` (rank the pick,
prove the live lease, then work it). `research` is standalone / callable
mid-workflow and returns to its CALLER (no forced `next`); it is also a `subskill`
of `plan`. The `smith` orchestrator composes the six stages (`subskills`).
Utility/terminal skills (`status`, `shepherd`, `kernel`, `issue-basics`, `memory`,
`rollback`, `research`, `sonarcloud`, `sonarcloud-analysis`,
`parallel-deep-research`, `using-forge`) declare no forward-stage `next`. Meta
skills (`hermes-forge`) are chain-exempt.

The stage `next` values above are the DEFAULT / critical-path successors. The
actual successor after `ship`, `review`, and `verify` is
classification-dependent — the authoritative matrix is `lib/workflow/stages.js`
(Simple/Hotfix/Refactor end at `ship`; Standard ends at `review`; Critical runs
through `verify`; the `docs` classification reuses `verify` → `ship`).

## 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.