@g3nomaly/skills 0.3.0 → 1.0.0

package/dist/plugins/task-manager/hooks/hooks.json

@@ -0,0 +1,19 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "g3n-skills hook sync-tree", "timeout": 30 }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Grep|Glob",
+        "hooks": [
+          { "type": "command", "command": "g3n-skills hook guard-tree", "timeout": 10 }
+        ]
+      }
+    ]
+  }
+}

package/dist/plugins/task-manager/skills/decisions/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: decisions
+description: Record and look up the decisions a plan has made, stored as numbered files inside the plan and reached through hooks. Use when a hard-to-reverse choice is made while planning or working a phase, when a choice replaces an earlier one, when the user asks why something was done a certain way, or when another skill needs a plan's decisions.
+registryDependencies: [task-manager, domain-modeling]
+disable-model-invocation: false
+---
+
+A **decision** is one paragraph saying what was chosen and why, filed under the plan it belongs to. Its job is to stop the next session from reopening a question this one closed.
+
+The hooks come from the `/task-manager` skill. Load it first when `g3n-skills` is not on `PATH`.
+
+**Reach decisions through the hooks only.** They sit inside the tree, in `<plan>/decisions/<id>.md`, so `guard-tree` denies a direct read.
+
+| Hook | Does | Use it when |
+|---|---|---|
+| `list-decisions` | Returns a plan's decisions in numbered order, metadata only | starting a phase, or checking whether a question is already closed |
+| `get-decision` | Returns one decision in full | the title is not enough |
+| `add-decision` | Numbers, dates and writes a new decision from stdin. **Writes.** | a choice passed the three tests below |
+
+Copy each invocation from [`references/usage.md`](references/usage.md). `add-decision` takes the decision text on stdin, as shown there.
+
+- **`--in <plan>`** is required everywhere. Numbers restart per plan.
+- **`--status`** is `proposed`, `accepted`, `deprecated` or `superseded`. `add-decision` defaults to `accepted`. `list-decisions` filters by it.
+- **`--supersedes <id>`** also moves the named decision to `superseded`.
+- `get-decision` exits `1` for an unknown id. `list-decisions` prints `[]` for a plan with none. `add-decision` exits `1` when nothing was piped in.
+
+## When to record
+
+All three must hold. The `/domain-modeling` skill argues each one in its ADR format, with examples of what qualifies.
+
+1. **Hard to reverse.** Changing course later costs real work.
+2. **Surprising without context.** A reader of the code would ask why.
+3. **A real trade-off.** There was an alternative, and it lost for a reason.
+
+## Writing one
+
+One to three sentences: the context, the choice, the reason. Name the alternative that lost. The title is the choice itself in a few words, because `list-decisions` shows titles only and the title has to close the question unaided.
+
+**A decision is never edited.** A changed mind is a new decision with `--supersedes`, so the trail of reasons stays readable.

package/dist/plugins/task-manager/skills/decisions/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Decisions"
+  short_description: "Record and look up a plan's decisions through the task-manager hooks"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/task-manager/skills/decisions/references/usage.md

@@ -0,0 +1,26 @@
+# Decision hooks — usage
+
+Where decisions sit and how each hook is called. This is the disclosed reference for the [`decisions`](../SKILL.md) skill.
+
+## On disk
+
+```
+docs/task-manager/auth-rework/
+├── auth-rework.md
+└── decisions/
+    ├── 0001-use-jwt-for-sessions.md
+    └── 0002-use-opaque-tokens.md
+```
+
+## Invocations
+
+```bash
+g3n-skills hook list-decisions --in auth-rework --status accepted
+g3n-skills hook get-decision --in auth-rework --id 0001-use-jwt-for-sessions
+
+g3n-skills hook add-decision --in auth-rework --title "Use opaque tokens" \
+  --supersedes 0001-use-jwt-for-sessions <<'TEXT'
+Sessions move to opaque tokens looked up per request. Revoking a JWT before
+expiry needed a denylist, which cost the statelessness we chose JWTs for.
+TEXT
+```

package/dist/plugins/task-manager/skills/task-manager/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: task-manager
+description: Query and drive a tree of plans, phases and tasks that lives on disk as folders of Markdown files with a rebuilt index per folder. Use whenever the user asks what to work on next, refers to a plan, phase or task by name or TASK-### id, wants something moved to open, in-progress, in-review, completed or blocked, or wants finished work cleared out. Every read and every write goes through the `g3n-skills hook` commands — never open a tree file directly.
+disable-model-invocation: false
+---
+
+## Before anything else
+
+```bash
+command -v g3n-skills >/dev/null 2>&1 || bun add -g @g3nomaly/skills
+```
+
+If the command exists, print nothing and carry on.
+
+The tree is **three levels deep** and nothing else: the root holds **plans**, a plan holds **phases**, a phase holds **tasks**.
+
+```
+docs/task-manager/                 # set by skills.settings.filetreeRoot
+├── root-index.json                # the plans, in order
+└── auth-rework/
+    ├── auth-rework.md             # the plan itself
+    ├── plan-index.json            # the phases, in order
+    └── 01-schema/
+        ├── 01-schema.md           # the phase itself
+        ├── phase-index.json       # the tasks, in order
+        └── tasks/
+            └── TASK-006.md
+```
+
+Every `.md` file opens with frontmatter carrying exactly the fields its index entry carries. **The index is rebuilt from the files, never edited** — a hand-written index is overwritten on the next sync.
+
+**Order is the alphabetical order of the names on disk.** There is no rank field, no queue number and nothing to renumber: `01-schema` runs before `02-api` because `0` sorts before `2`. To reorder, rename.
+
+**States** are `open`, `in-progress`, `in-review`, `completed` and `blocked`, and every level uses the same five.
+
+## Never open a tree file
+
+`Read`, `Grep` and `Glob` are the wrong tools here — **`guard-tree` denies them** on anything inside the tree, and says which hook to run instead. They are the interface: each one names its flags in this table and reports what went wrong on stderr.
+
+| Hook | Does | Use it when |
+|---|---|---|
+| `next-entry` | Returns the first entry of a queue that is not `completed` or `blocked`, in full | starting work — "what's next", "give me the next task" |
+| `get-entry` | Returns one named plan, phase or task, in full | the user names something — "open auth-rework", "show TASK-006" |
+| `list-entries` | Returns one folder's entries in queue order, metadata only | surveying — "what phases are in this plan", "what's blocked" |
+| `set-state` | Moves one entry to a new state and rebuilds its index | work starts, stalls, lands, or goes up for review |
+| `cleanup` | Deletes every `completed` entry, and `blocked` too with `--blocked` | the tree has filled up with finished work |
+| `sync-tree` | Creates what is missing and rebuilds every index | a file was added or renamed by hand; otherwise it runs itself |
+| `guard-tree` | Denies a file tool aimed at the tree | never by hand — the harness fires it |
+
+The last two are **registered in `hooks/hooks.json` and fire on their own**; never invoke them as a step:
+
+| Hook | Event | Matcher | What it does |
+|---|---|---|---|
+| `sync-tree` | `SessionStart` | — | Rebuilds every index. Exit `1` is non-blocking: the session opens with stale indexes and the reason goes to the user. |
+| `guard-tree` | `PreToolUse` | `Read\|Grep\|Glob` | Returns `deny` for a guarded path, nothing otherwise. Only a path the call states outright is checked, so an unscoped `Grep` still runs. |
+
+Run the other four from the plugin root:
+
+```bash
+g3n-skills hook next-entry --in auth-rework --pretty
+g3n-skills hook get-entry --id TASK-006
+g3n-skills hook list-entries --in auth-rework --status blocked
+g3n-skills hook set-state --id TASK-006 --to in-progress
+g3n-skills hook cleanup --blocked --dry-run --pretty
+```
+
+## Flags they share
+
+- **`--project <dir>`** — the folder holding `.g3n.config.json`, default the working directory. The tree root comes from `skills.settings.filetreeRoot` in it.
+- **`--root <dir>`** — the tree folder verbatim, skipping the config. Use it only when there is no config to read.
+- **`--pretty`** — indented JSON. Leave it off when piping.
+- **`--id <name>`** — a plan or phase name, or a task id like `TASK-006`. One name is searched for across the whole tree; two entries answering to it is an error, not a choice to make.
+- **`--in <name>`** — whose entries to list. Omit it for the plans at the root.
+
+Where they deliberately differ:
+
+- `next-entry` and `get-entry` **return exactly one thing**, so nothing found is a failure — exit `1`.
+- `list-entries` and `cleanup` **return a list**, so `[]` is a real answer — exit `0`.
+- `get-entry`, `next-entry` and `list-entries` are read-only; **`set-state`, `cleanup` and `sync-tree` write to disk.** Run `cleanup` with `--dry-run` before running it for real.
+
+## Terms and decisions
+
+Two more things live in the tree, each with its own hooks and its own skill:
+
+- **The vocabulary**, one file at the tree root. `get-entry` and `next-entry` attach a `vocabulary` array naming every term the entry mentions. Use the `/vocabulary` skill to read that array, look a word up, or record one.
+- **A plan's decisions**, in `<plan>/decisions/`. Use the `/decisions` skill to list, read or record them.
+
+## What the hooks will not do
+
+- **A state change is only the `status:` line.** What the transition implies — the reason a task is blocked, the outcome written into the body — is prose, and prose is written afterwards with an ordinary edit to the body of that one file.
+- **Creating a plan, phase or task is not a hook.** Write the `.md` file where the tree expects it, then run `sync-tree`; the index picks it up.
+- **`cleanup` deletes.** A removed plan takes its phases and tasks with it. Confirm with the user before running it without `--dry-run`.
+
+## When it goes wrong
+
+Everything is checked against its schema on the way in, and a failure names the file and the field. Two are worth recognising:
+
+- _`"<name>" is ambiguous`_ — two entries share a name. Rename one; nothing else will work until then.
+- _`is "X" but it was read as "Y"`_ — the `name` or `id` in the frontmatter disagrees with the folder or file holding it. Fix the frontmatter, or rename the file, then `sync-tree`.

package/dist/plugins/task-manager/skills/vocabulary/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: vocabulary
+description: Keep one word per concept across sessions, stored in the task-manager tree and reached through hooks. Use when about to name a domain concept in code, a task or a doc, when the user corrects a word, when two words are in use for one thing, or when another skill needs a term looked up or recorded.
+registryDependencies: [task-manager, domain-modeling]
+disable-model-invocation: false
+---
+
+Every session starts without the last one's words, so names _drift_: the _phase_ of Monday is the _stage_ of Tuesday, and by Friday the code has both. The vocabulary is the one list that stops it. Each **term** carries a definition and the **avoided words** it replaces.
+
+The hooks come from the `/task-manager` skill. Load it first when `g3n-skills` is not on `PATH`.
+
+The terms live in `vocabulary.md` at the tree root. **Reach them through the hooks only.** `guard-tree` denies a direct read, and a hand edit is overwritten by the next `set-term`.
+
+| Hook | Does | Use it when |
+|---|---|---|
+| `get-term` | Returns one term, found by its name or by an avoided word | about to use a word for a domain concept |
+| `list-terms` | Returns every term, sorted by name | starting work in an unfamiliar area |
+| `set-term` | Adds a term, or replaces its definition and avoided words. **Writes.** | a concept got a name, or a name got sharper |
+| `remove-term` | Deletes one term. **Writes.** | the concept left the project |
+
+Copy each invocation from [`references/usage.md`](references/usage.md).
+
+They share `--project`, `--root` and `--pretty` with the task-manager hooks. `get-term` and `remove-term` exit `1` when nothing answers to the name. `list-terms` prints `[]` for an empty vocabulary.
+
+## Reading an answer
+
+`get-term` reports how it found the term in `matched`:
+
+- **`"term"`** means the word is the right one. Use it as spelled.
+- **`"avoid"`** means the word is a retired synonym. Use the returned `term` instead, in prose and in identifiers alike.
+
+`get-entry` and `next-entry` attach a `vocabulary` array to every plan, phase and task they return. It lists each term the entry mentions, and under `avoided` the retired words the entry still uses. Treat a non-empty `avoided` as a defect in the entry and write the term in whatever you produce from it.
+
+## Recording a term
+
+**Record on the second sighting.** One use of a word is prose. The same concept named twice, or named differently by two people, is a term. A correction from the user is always a term.
+
+- **Definition.** One or two sentences saying what the thing _is_. Leave out how it is built.
+- **`--avoid`.** The synonyms actually seen, comma-separated. `set-term` refuses a word another term already owns, which is how two terms are kept from claiming one meaning.
+- **`set-term` replaces.** Pass the full definition and the full avoid list every time, since flags left out are cleared.
+
+A term whose meaning is still contested is sharpened with the `/domain-modeling` skill first, then stored here.

package/dist/plugins/task-manager/skills/vocabulary/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Vocabulary"
+  short_description: "One word per concept across sessions, kept in the task-manager tree through hooks"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/task-manager/skills/vocabulary/references/usage.md

@@ -0,0 +1,26 @@
+# Term hooks — usage
+
+How each hook is called, and what the file they write looks like. This is the disclosed reference for the [`vocabulary`](../SKILL.md) skill.
+
+## Invocations
+
+```bash
+g3n-skills hook get-term --term stage
+g3n-skills hook list-terms --pretty
+g3n-skills hook set-term --term Phase --definition "One step of a plan, holding tasks." --avoid "stage, milestone"
+g3n-skills hook remove-term --term Phase
+```
+
+## The file
+
+`set-term` and `remove-term` rewrite `vocabulary.md` whole, terms sorted by name:
+
+```md
+# Vocabulary
+
+## Phase
+
+One step of a plan, holding tasks.
+
+_Avoid_: stage, milestone
+```

package/dist/plugins/using-hooks/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "using-hooks",
+  "description": "How to write each Claude Code lifecycle hook.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "skills": ["./skills/hook-pre-tool-use", "./skills/hook-post-tool-use", "./skills/hook-stop", "./skills/hook-user-prompt-submit"]
+}

package/dist/plugins/using-hooks/skills/hook-post-tool-use/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: hook-post-tool-use
+description: Writing a PostToolUse lifecycle hook — the one that reacts to a finished tool call and can feed the result back to the agent.
+registryDependencies: [writing-great-hooks]
+disable-model-invocation: true
+---
+
+Shared rules for every hook — the invariants, the script mechanics, registration: [`writing-great-hooks`](../writing-great-hooks/SKILL.md).
+
+`PostToolUse` fires immediately after a tool has run. **The work is already done** — nothing this hook returns can undo it. What it can do is see the result and put a consequence in front of the agent, which makes it the event for verification, bookkeeping, and anything that must happen _because_ a file changed.
+
+## Payload
+
+The four common fields, the call, and what came back:
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/you/.claude/projects/<slug>/<session>.jsonl",
+  "cwd": "/home/you/project",
+  "hook_event_name": "PostToolUse",
+  "tool_name": "Edit",
+  "tool_input": { "file_path": "/home/you/project/src/index.ts", "old_string": "…", "new_string": "…" },
+  "tool_response": { "filePath": "/home/you/project/src/index.ts", "success": true }
+}
+```
+
+`tool_input` and `tool_response` are both shaped by the tool. Branch on `tool_name` before reading either.
+
+## Matcher
+
+Same tool-name regex as [`hook-pre-tool-use`](../hook-pre-tool-use/SKILL.md), and the same reason to keep it tight:
+
+```json
+{
+  "matcher": "Edit|MultiEdit|Write",
+  "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-edited-file.ts" }]
+}
+```
+
+## What the exit code does
+
+- **`0` — nothing further happens.** stdout goes to the transcript, not to the agent.
+- **`2` — stderr is fed to the agent** as something it must address. The tool result still stands; this is a correction, not a rollback.
+- **anything else** — a non-blocking error; stderr goes to the user.
+
+The JSON form does the same job with a reason attached:
+
+```json
+{
+  "decision": "block",
+  "reason": "tsc reported 2 errors in src/index.ts:\n  L14 Property 'id' does not exist on type 'Order'\n  L22 Object is possibly 'undefined'"
+}
+```
+
+To hand the agent information without framing it as a failure, use `hookSpecificOutput.additionalContext` instead — it lands in context without asserting that something went wrong.
+
+_Return the diagnostic, not the fact of it._ "Typecheck failed" costs the agent a whole turn rediscovering what this hook already knew; the compiler's actual lines let it fix the problem immediately.
+
+## What it is for
+
+- **Formatting and linting what was just edited** — the deterministic pass that should never be a request in prose.
+- **Typechecking the touched file** and returning the errors, so a broken edit is corrected in the same turn it was made.
+- **Tracking what changed.** Recording edited paths gives later turns, and a `Stop` hook, something concrete to act on.
+- **Feeding back a consequence the agent cannot see** — a failing test, a schema that no longer matches, a generated file now stale.
+
+## What it is not for
+
+**Do not use it to prevent anything.** The tool has run; a hook that reads like a guard here is a guard that arrives too late. Prevention is [`hook-pre-tool-use`](../hook-pre-tool-use/SKILL.md).
+
+Be careful making it write. A hook that reformats the file the agent just edited changes content the agent believes it knows, and the next edit is built on a stale picture. Either keep the rewrite small and mechanical, or report instead of rewriting.
+
+## Failure modes
+
+- _Whole-project work on one file's event._ Typechecking the entire monorepo because one file changed. It fires on every edit; scope it to `tool_input.file_path` or don't do it here.
+- _Verdict without evidence._ Blocking with "lint failed" and swallowing the output. The agent has to re-run the tool it can't see to learn what this hook already had.
+- _Silent rewrite._ Reformatting the edited file and returning `0`. The agent's next edit targets text that no longer exists, and the failure looks like the agent's mistake.
+- _Blocking on the expected._ Returning `decision: "block"` for a condition that is normal mid-task — a half-written module that doesn't typecheck yet. The agent is dragged into fixing something it was already about to finish.
+- _Assuming success._ Reading `tool_response` without checking whether the call actually succeeded, then reporting failures caused by a tool that never ran.

package/dist/plugins/using-hooks/skills/hook-post-tool-use/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Hook: PostToolUse"
+  short_description: "React to a finished tool call and feed the result back"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/using-hooks/skills/hook-pre-tool-use/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: hook-pre-tool-use
+description: Writing a PreToolUse lifecycle hook — the one that can allow, deny, or escalate a tool call before it runs.
+registryDependencies: [writing-great-hooks]
+disable-model-invocation: true
+---
+
+Shared rules for every hook — the invariants, the script mechanics, registration: [`writing-great-hooks`](../writing-great-hooks/SKILL.md).
+
+`PreToolUse` fires after the agent has chosen a tool and filled in its arguments, but **before the tool runs**. It is the only event that can stop an action from happening at all, which makes it the place for guardrails and policy, and the wrong place for anything that merely wants to observe.
+
+## Payload
+
+The four common fields, plus the call about to be made:
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/you/.claude/projects/<slug>/<session>.jsonl",
+  "cwd": "/home/you/project",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Write",
+  "tool_input": { "file_path": "/home/you/project/src/index.ts", "content": "…" }
+}
+```
+
+`tool_input` is shaped by the tool, so a hook matching more than one tool must branch on `tool_name` before reading a field. Never assume `file_path` exists.
+
+## Matcher
+
+This event selects by tool name, as a regex:
+
+```json
+{
+  "matcher": "Edit|MultiEdit|Write",
+  "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-protected-paths.ts" }]
+}
+```
+
+Omit `matcher` to see every tool call. **Scope it as tightly as the rule allows** — an unmatched hook is a process spawned on every tool call for the life of the session.
+
+## What the exit code does
+
+- **`0` — the call proceeds.** stdout goes to the transcript, not to the agent.
+- **`2` — the call is denied**, and stderr is fed to the agent as the reason. This is the veto, and the agent can read the reason and try something else.
+- **anything else** — a non-blocking error: the call still runs, and stderr goes to the user.
+
+For the full decision, print JSON and exit `0`:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "src/generated/ is written by `bun run codegen`. Edit the template instead."
+  }
+}
+```
+
+- **`allow`** runs the call and skips the permission prompt the user would otherwise see.
+- **`deny`** blocks it and hands the reason to the agent.
+- **`ask`** puts it to the user, whatever the current permission mode would have done.
+
+_Write the reason to the agent, not to a log._ It is the only thing the agent gets, and a good one turns a dead end into a corrected second attempt: name what was refused and what to do instead.
+
+## What it is for
+
+- **Protecting paths and resources** — generated directories, lockfiles, anything with a real source elsewhere.
+- **Steering to the project's own tooling.** This repo registers a `PreToolUse` guard on `Bash|Grep` and `Read|Glob` that pushes the agent to query the graph before raw searching — policy that would otherwise be a paragraph of prose the agent may or may not honour.
+- **Pre-flight validation** — refusing a command whose arguments are malformed, out of scope, or aimed outside the project.
+
+## What it is not for
+
+**Do not put a slow check here.** Every matching tool call waits on it, and the agent is idle while it runs. Verification of a result belongs in [`hook-post-tool-use`](../hook-post-tool-use/SKILL.md), which pays its cost after the work rather than in front of it.
+
+Nor should it encode judgement. A hard rule — this path is generated, that command is forbidden — is a guardrail. "Is this edit a good idea" is not, and hardcoding it produces a veto nobody can see or argue with.
+
+## Failure modes
+
+- _Blanket matcher._ No `matcher`, or `.*`, for a rule that concerns two tools. Every call in the session now pays for it.
+- _Wrong field, wrong tool._ Reading `tool_input.file_path` on a `Bash` call, getting `undefined`, and treating that as "not a protected path". Branch on `tool_name` first, and fail closed when the shape is unfamiliar.
+- _Reasonless denial._ Exit `2` with an empty stderr, or a JSON `deny` with no `permissionDecisionReason`. The agent knows only that it was stopped, so it retries the same thing.
+- _Path comparison by string._ Matching `"src/generated"` against a raw argument, which `./src/../src/generated` and an absolute path both defeat. Resolve, then compare.
+- _Shell interpolation._ Pasting a payload field into a shell command. The agent's arguments reach a shell running with the user's credentials.

package/dist/plugins/using-hooks/skills/hook-pre-tool-use/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Hook: PreToolUse"
+  short_description: "Allow, deny, or escalate a tool call before it runs"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/using-hooks/skills/hook-stop/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: hook-stop
+description: Writing a Stop lifecycle hook — the one that can refuse to let the agent end its turn, and the one that can loop forever if written carelessly.
+registryDependencies: [writing-great-hooks]
+disable-model-invocation: true
+---
+
+Shared rules for every hook — the invariants, the script mechanics, registration: [`writing-great-hooks`](../writing-great-hooks/SKILL.md).
+
+`Stop` fires when the agent is about to finish its response. Its power is refusal: exit `2` and the turn does not end — the agent reads your reason and keeps working. That makes it the place for "not done until…" conditions, and the one event that can trap a session in a loop.
+
+It takes **no matcher**. `SubagentStop` is the sibling event for subagents finishing, and needs its own registration.
+
+## Payload
+
+The four common fields, plus the loop guard:
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/you/.claude/projects/<slug>/<session>.jsonl",
+  "cwd": "/home/you/project",
+  "hook_event_name": "Stop",
+  "stop_hook_active": false
+}
+```
+
+**`stop_hook_active` is `true` when the agent is only still running because this hook already blocked it.** Check it first and let the stop through when it is set. Without that guard, a condition the agent cannot satisfy — a test failing for an unrelated reason, a check with a bug — blocks, prompts, blocks again, and never terminates.
+
+```ts
+if (payload.stop_hook_active) process.exit(0);
+```
+
+## What the exit code does
+
+- **`0` — the turn ends** as it was going to.
+- **`2` — the agent is not allowed to stop**, and stderr becomes its instruction for what to do next.
+- **anything else** — a non-blocking error; the turn ends and stderr goes to the user.
+
+The JSON form requires the reason, because the reason _is_ the next instruction:
+
+```json
+{
+  "decision": "block",
+  "reason": "bun test failed in packages/core: 2 failing in tests/registry/io.test.ts. Fix these before finishing."
+}
+```
+
+A blocked stop with a vague reason is worse than no hook: the agent knows only that it may not stop, so it produces filler and tries again.
+
+## What it is for
+
+- **Refusing to finish over a broken build** — a failing typecheck or test suite in the package that was touched this turn.
+- **Enforcing a completion criterion the agent tends to skip** — the changelog entry, the regenerated artifact, the doc updated alongside the code.
+- **Closing the loop on tracked work**, using the paths a [`hook-post-tool-use`](../hook-post-tool-use/SKILL.md) hook recorded, so the check only covers what actually changed.
+
+## What it is not for
+
+**Do not use it as a chore runner.** Blocking is expensive — it spends a full turn of the agent's attention and the user's time. If the work is mechanical and does not need the agent's judgement, do it in the hook and exit `0`.
+
+And keep it cheap on the common path. It runs at the end of every turn, including the ones that only answered a question; a full test suite there taxes the entire session. Check whether anything relevant changed before doing real work.
+
+## Failure modes
+
+- _The infinite loop._ Blocking without honouring `stop_hook_active`, on a condition the agent cannot fix. This is the defining failure of the event and the reason the field exists.
+- _Blocking on the pre-existing._ Refusing the stop over a test that was already failing before the turn started. The agent is held responsible for something it did not touch and cannot resolve.
+- _Reason without a next step._ `"Checks failed."` The agent cannot act on it, so it stalls or invents work.
+- _Turn-end tax._ A full build on every stop, including turns that changed nothing. Gate on the tracked file list first.
+- _Silent success._ Exiting `0` when the check itself errored — a missing binary, a bad path — so a hook that has quietly stopped working looks exactly like a passing one. Report the breakage as a non-blocking error instead.

package/dist/plugins/using-hooks/skills/hook-stop/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Hook: Stop"
+  short_description: "Refuse to let the agent end its turn until a condition is met"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/using-hooks/skills/hook-user-prompt-submit/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: hook-user-prompt-submit
+description: Writing a UserPromptSubmit lifecycle hook — the one that can add context to a prompt or reject it before the agent reads it.
+registryDependencies: [writing-great-hooks]
+disable-model-invocation: true
+---
+
+Shared rules for every hook — the invariants, the script mechanics, registration: [`writing-great-hooks`](../writing-great-hooks/SKILL.md).
+
+`UserPromptSubmit` fires the instant the user submits, **before the agent has seen the prompt**. That position is the whole point: it is the only event that can put words in front of the agent that nobody typed, and the only one that can make a prompt never happen.
+
+It takes **no matcher** — there is no tool to match. Register it with an entry that has only a `hooks` array.
+
+## Payload
+
+The four common fields, plus the prompt itself:
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/you/.claude/projects/<slug>/<session>.jsonl",
+  "cwd": "/home/you/project",
+  "hook_event_name": "UserPromptSubmit",
+  "prompt": "add a migration for the orders table"
+}
+```
+
+## What the exit code does
+
+- **`0` — stdout is injected into the agent's context.** This event and `SessionStart` are the only places where plain stdout reaches the agent as content rather than transcript noise. Print nothing and nothing is added.
+- **`2` — the prompt is blocked and erased.** It never reaches the agent, and stderr is shown to the user alone. Use it to refuse, not to advise.
+- **anything else** — the prompt proceeds untouched; stderr goes to the user as a non-blocking error.
+
+Because bare stdout is already the injection channel, the simplest useful hook is an `echo` and an exit `0`. Reach for JSON when you need a field the plain channel can't express:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "Current sprint: S-42. Active branch: fix/orders-migration."
+  }
+}
+```
+
+To reject from JSON instead of exit `2`, print `{"decision": "block", "reason": "..."}` — the reason is shown to the user in place of the prompt.
+
+## What it is for
+
+- **Injecting state the agent cannot see** — current branch, sprint, ticket, today's date, which service the user is in. Cheap, and it lands before the first token of reasoning.
+- **Routing to skills.** Match the prompt against trigger patterns and inject a line naming the skill that fits, so activation stops depending on the agent noticing.
+- **Refusing prompts that must not run** — a production-touching phrase, a missing ticket reference — by exiting `2` with a reason.
+
+## What it is not for
+
+**Do not use it to rewrite what the user meant.** Injected context is invisible to the person who typed the prompt: they see their words, the agent sees yours, and every downstream surprise is unattributable. Add facts, not instructions that contradict the prompt.
+
+Keep it fast. It sits between the user pressing enter and anything at all happening, so its latency is felt directly on every single turn.
+
+## Failure modes
+
+- _Silent hijack._ Injected text that redirects the task rather than informing it. The user cannot see it, cannot tell why the agent went sideways, and cannot turn it off.
+- _Context creep._ A paragraph injected on every prompt, most of it irrelevant to this one. It is paid on every turn for the whole session — inject the fields that change, not a status dump.
+- _Blocking too eagerly._ Exit `2` on a pattern that also matches innocent prompts. The user has no override and the prompt is already gone; prefer injecting a warning unless the action is genuinely unrecoverable.
+- _Leaking the payload._ Echoing the whole prompt into a log or an error message. Prompts carry secrets, and this hook sees every one of them.

package/dist/plugins/using-hooks/skills/hook-user-prompt-submit/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Hook: UserPromptSubmit"
+  short_description: "Add context to a prompt, or reject it, before the agent reads it"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/workflow/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "workflow",
+  "description": "Work a phase of a plan through plan, execute, review and sync, one agent per step, with hooks deciding when a step is finished.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "dependencies": ["task-manager@g3n"],
+  "skills": [
+    "./skills/run",
+    "./skills/plan",
+    "./skills/execute",
+    "./skills/review",
+    "./skills/sync",
+    "./skills/orchestrator",
+    "./skills/worktree"
+  ]
+}

package/dist/plugins/workflow/agents/reviewer.md

@@ -0,0 +1,9 @@
+---
+name: reviewer
+description: Read-only reviewer for the review step of the workflow. Judges each in-review task of a phase against its own brief and moves it to completed or back to in-progress. Use for the review step of a workflow run.
+disallowedTools: Edit, Write, NotebookEdit
+---
+
+You review the tasks of one phase by following the `/review` skill. Load it before anything else.
+
+You change no file. The only state you move is a task's status, through `g3n-skills hook set-state`. Your findings go into your final report, which is the one thing the agent that spawned you will read, so each finding names the file and line, what is wrong, and what done looks like.