@g3nomaly/skills 0.3.0 → 1.0.0

package/dist/plugins/workflow/skills/execute/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: execute
+description: Carry out the tasks of one phase, each in its own worktree, and hand every one to review. Use as the execute step of the workflow, when a phase has open or in-progress tasks, or when review sent a task back.
+registryDependencies: [task-manager, worktree, vocabulary, decisions]
+disable-model-invocation: false
+---
+
+The execute step ends when no task of the phase is `open` or `in-progress`. A task leaves your hands as `in-review`, or as `blocked` with the reason in your report.
+
+The hooks come from the `/task-manager` skill. Load it first when `g3n-skills` is not on `PATH`.
+
+1. **Take your tasks.** A brief that names tasks gives you exactly those. Otherwise `g3n-skills hook current-step --phase <phase>` lists them under `holding`. Work them in that order, and start a task only once every id in its `depends_on` is `in-review` or `completed`.
+2. **Open the task** with `g3n-skills hook get-entry --id <task>`, then claim it with `g3n-skills hook set-state --id <task> --to in-progress`. A task that is already `in-progress` came back from review. Its findings are in your brief, and they are the whole job this time.
+3. **Get a worktree** through the `/worktree` skill, from the task's `worktree_type` and `id`. All edits happen inside it. The checkout you started in stays untouched.
+4. **Do the work the brief describes.** Stay inside its goals. Something the brief did not foresee goes into your report, never into the diff. Use the `/vocabulary` skill on the task's `vocabulary` array before naming anything, and the `/decisions` skill before choosing between designs, since the plan may have chosen already.
+5. **Prove it.** Tick a requirement only after checking it against the running code. Run the package's own type check and tests from inside the worktree. Done when every box is ticked and both pass.
+6. **Commit inside the worktree**, one commit per task, with the task id in the subject line. Pushing belongs to nobody in this workflow.
+7. **Hand it over** with `g3n-skills hook set-state --id <task> --to in-review`. A task you cannot finish goes to `blocked` instead, and your report says what would release it.
+8. **Finish** once your tasks are handed over. Holding the whole phase, run `g3n-skills hook advance-step --phase <phase> --from execute`. Exit `1` lists the tasks still to be worked, so go back to step 1 for them. Holding only some of the tasks, leave `advance-step` to the parent.
+
+Your report lists, per task, the branch, the commit, the final status, and anything the brief did not foresee.

package/dist/plugins/workflow/skills/execute/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Execute"
+  short_description: "Carry out a phase's tasks, each in its own worktree, and hand them to review"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/orchestrator/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: orchestrator
+description: Runs a whole plan, phase by phase, opening each phase's gate once the phases it depends on are completed.
+registryDependencies: [task-manager, run]
+disable-model-invocation: true
+---
+
+A plan is a **graph**. Its phases are the nodes, and `depends_on` draws the edges. Each phase sits behind a **gate** that opens once everything it depends on is `completed`. You open gates. The `/run` skill does everything behind them.
+
+The hooks come from the `/task-manager` skill. Load it first when `g3n-skills` is not on `PATH`.
+
+`g3n-skills hook ready-phases --plan <plan>` sorts the plan's phases by gate:
+
+| Field | Holds |
+|---|---|
+| `ready` | phases whose gate is open, in queue order, each in full |
+| `waiting` | phases behind a closed gate, with the phases they are `waiting_on` |
+| `blocked` | phases set to `blocked` |
+| `completed` | finished phases |
+
+1. **Claim the plan** with `g3n-skills hook set-state --id <plan> --to in-progress`, unless it already is.
+2. **Read the gates** with `ready-phases`.
+   - `ready` and `waiting` both empty means no gate is left to open. Go to step 5.
+   - `ready` empty with anything in `waiting` means the graph is stuck behind a `blocked` phase. Go to step 5.
+3. **Pick what runs.** Take the first phase in `ready`. Add every other `ready` phase marked `parrallel: true`, provided the first one is marked so too. Otherwise run the first one alone.
+4. **Run each picked phase with the `/run` skill, from this session.** You are the parent of every agent in the plan, for the reason [`sub-agents.md`](../run/references/sub-agents.md) opens with, so a phase is never handed to one agent as a whole. With several phases picked, walk their `/run` loops side by side, spawning the agents of one round in one message. Done when each picked phase reads `done` or `blocked`. Then go to step 2.
+5. **Close out.** With every phase `completed`, run `g3n-skills hook set-state --id <plan> --to completed`. Otherwise leave the plan `in-progress`. Report each phase with its status, what blocks the blocked ones, and which `waiting` phases they hold back.

package/dist/plugins/workflow/skills/orchestrator/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Orchestrator"
+  short_description: "Run a whole plan, opening each phase's gate once its dependencies are completed"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/plan/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: plan
+description: Turn one phase of a plan into task files an agent can execute without asking anything. Use as the plan step of the workflow, when a phase has no tasks yet, or when the user wants a phase broken down.
+registryDependencies: [task-manager, writing-great-tasks, vocabulary, decisions, grilling]
+disable-model-invocation: false
+---
+
+The plan step ends with a phase whose every deliverable belongs to exactly one task. You write briefs here. Code comes in the next step.
+
+The hooks come from the `/task-manager` skill. Load it first when `g3n-skills` is not on `PATH`.
+
+1. **Read the phase** with `g3n-skills hook get-entry --id <phase>`. Its `trail` names the plan. Its `vocabulary` array lists the terms the phase mentions. Use the `/vocabulary` skill to read that array, and write every task in those terms.
+2. **Read what is already closed** with `g3n-skills hook list-decisions --in <plan> --status accepted`, through the `/decisions` skill. A task never reopens an accepted decision. It builds on it.
+3. **Close the open questions.** Where the phase leaves scope, an interface or an order of work undecided, use the `/grilling` skill with the user. Running as a spawned agent, you have no user to grill, so return the questions in your report and stop. Done when you could name every file the phase will touch.
+4. **Cut the tasks.** One task is one agent's uninterrupted work with one reviewable diff. Two tasks that edit the same file get a `depends_on` between them, so they never run side by side. Done when each deliverable in the phase body maps to one task and no task holds two unrelated ones.
+5. **Write each task** at `<phase folder>/tasks/<id>.md`. Copy the frontmatter from [`references/task-frontmatter.md`](references/task-frontmatter.md), which is the contract the hooks check. Use the `/writing-great-tasks` skill for the body only. Done when every task file opens with that frontmatter, filled in.
+6. **Record what you settled.** A choice that passes the three tests goes through the `/decisions` skill. A concept you had to name goes through the `/vocabulary` skill.
+7. **Finish** with `g3n-skills hook sync-tree`, then `g3n-skills hook advance-step --phase <phase> --from plan`. Exit `1` names what is missing. Fix that and run it again. The step is finished when it prints `"step": "execute"`.

package/dist/plugins/workflow/skills/plan/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Plan"
+  short_description: "Turn one phase into task files an agent can execute"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/plan/references/task-frontmatter.md

@@ -0,0 +1,33 @@
+# Task frontmatter
+
+The frontmatter every task file opens with. The hooks check it against `TaskSchema` and reject any key not listed here. This is the disclosed reference for the [`plan`](../SKILL.md) skill.
+
+```yaml
+---
+id: TASK-012
+title: Session table migration
+package: skills
+priority: high
+depends_on: [TASK-011]
+summary: Adds the sessions table and its indexes.
+complexity: 2
+worktree: true
+worktree_type: feature
+status: open
+---
+```
+
+| Key | Rule |
+|---|---|
+| `id` | A prefix, a hyphen, then digits. Equal to the file name. Unique across the whole tree, so continue from the highest in use, which `g3n-skills hook list-entries --in <phase>` shows per phase |
+| `title` | A few words naming the deliverable |
+| `package` | The package the work lands in |
+| `priority` | `critical`, `high`, `medium` or `low` |
+| `depends_on` | Ids of tasks that must be handed over first. Leave the key out when there are none |
+| `summary` | One sentence saying what is different once the task is done |
+| `complexity` | `1` to `5`. Optional |
+| `worktree` | Always `true` |
+| `worktree_type` | `feature`, `fix`, `refactor`, `chore`, `docs`, `snapshot`, `demo` or `experiment`. Becomes the branch prefix |
+| `status` | `open` at creation |
+
+Where the `/writing-great-tasks` skill shows another frontmatter, this one wins.

package/dist/plugins/workflow/skills/review/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: review
+description: Judge each in-review task of a phase against its own requirements and either complete it or send it back. Use as the review step of the workflow, when every remaining task of a phase is in-review, or when the user wants a phase's work checked before it is merged.
+registryDependencies: [task-manager, writing-great-tasks, vocabulary, decisions]
+disable-model-invocation: false
+---
+
+You are the **reviewer**, and you change no file. Your output is one verdict per task, moved through `set-state`, and findings exact enough that the next agent can act without asking you anything.
+
+The hooks come from the `/task-manager` skill. Load it first when `g3n-skills` is not on `PATH`.
+
+1. **List the tasks** with `g3n-skills hook current-step --phase <phase>`. `holding` names every task waiting for a verdict.
+2. **Read the brief before the diff**, with `g3n-skills hook get-entry --id <task>`. The `/writing-great-tasks` skill says what each section of it promises. Then read the work with `git diff <base>...<task branch>`, using the branch names from your own brief.
+3. **Check it, in this order.** Stop at the first failure only if it makes the rest unreadable.
+   - **Requirements.** Every ticked box is true of the diff. Check each one yourself.
+   - **Scope.** The diff stays inside the brief's goals and touches nothing listed under non-goals.
+   - **Proof.** The package's type check and tests pass when you run them in the task's worktree.
+   - **Words.** Through the `/vocabulary` skill: no avoided word in a new identifier, comment or doc.
+   - **Decisions.** Through the `/decisions` skill: nothing in the diff contradicts an `accepted` decision of the plan.
+4. **Give the verdict.**
+   - Pass: `g3n-skills hook set-state --id <task> --to completed`.
+   - Fail: `g3n-skills hook set-state --id <task> --to in-progress`. Each finding names the file and line, what is wrong, and what done looks like. A finding is a defect against the brief. Your taste is not a finding.
+5. **Finish** with `g3n-skills hook advance-step --phase <phase> --from review` once `holding` is empty. It prints `"step": "sync"` when everything passed and `"step": "execute"` when anything went back. Both are a finished review.
+
+Your report lists every task with its verdict, and the findings for each one sent back. The parent carries those findings into the next execute brief, so write them for a reader who has not seen the diff.

package/dist/plugins/workflow/skills/review/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Review"
+  short_description: "Judge each in-review task against its brief and complete it or send it back"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/run/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: run
+description: Work one phase of a plan through its four steps, plan, execute, review and sync, giving each step to a fresh agent and letting a hook decide when the step is finished. Use when the user wants a phase worked or names a phase to run, or when the orchestrator skill hands over a phase.
+registryDependencies: [task-manager, plan, execute, review, sync]
+disable-model-invocation: false
+---
+
+You are the **parent**. You never do a step's work. You find out which step the phase is on, hand that step to one agent, and check what came back. Holding to that is what keeps each agent's context down to a single step.
+
+The hooks come from the `/task-manager` skill. Load it first when `g3n-skills` is not on `PATH`.
+
+## The step is read, never remembered
+
+`g3n-skills hook current-step --phase <phase>` returns the phase's `step`:
+
+| `step` | Meaning | Hand it to |
+|---|---|---|
+| `plan` | the phase has no tasks, or is still `open` | an agent running the `/plan` skill |
+| `execute` | a task is `open` or `in-progress` | agents running the `/execute` skill |
+| `review` | every remaining task is `in-review` | the **reviewer** agent running the `/review` skill |
+| `sync` | every task is `completed` | an agent running the `/sync` skill |
+| `done` | the phase is `completed` | nobody. Report and stop |
+| `blocked` | the phase or a task in `holding` is `blocked` | nobody. Report and stop |
+
+The step is worked out from the statuses on disk each time, so a task the reviewer sends back puts the phase on `execute` again with nothing to reset. `holding` names the tasks keeping the phase on its step.
+
+## The loop
+
+1. **Name the phase.** Use the one the user gave. With only a plan named, take the first phase from `g3n-skills hook ready-phases --plan <plan>`. Done when you hold one phase name.
+2. **Read the step** with `current-step`. On `done` or `blocked`, go to step 5.
+3. **Spawn the agent** for that step, briefed as [`references/sub-agents.md`](references/sub-agents.md) lays out. Read that file before the first spawn of a session. Done when every agent you spawned has returned its report.
+4. **Read the step again.** The agent ends its own step with `advance-step`, so a finished step shows up here as a new `step`. After several execute agents side by side, run `g3n-skills hook advance-step --phase <phase> --from execute` yourself first, since none of them does. An unchanged `step` means the agent stopped early. Spawn that step again and put the last report and the `holding` list in the brief. After the third return with no change, run `g3n-skills hook set-state --id <phase> --to blocked` and go to step 5. Otherwise go to step 2.
+5. **Report.** Tell the user the final `step`, each task with its status, the decisions and terms recorded along the way, and for `blocked` what is holding it and what would release it. Blocked work waits for the user.

package/dist/plugins/workflow/skills/run/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Run"
+  short_description: "Work one phase through plan, execute, review and sync, one agent per step"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/run/references/sub-agents.md

@@ -0,0 +1,46 @@
+# Sub-agents
+
+How the parent of a workflow run spawns, briefs and retires the agent of each step. This is the disclosed reference for the [`run`](../SKILL.md) and [`orchestrator`](../../orchestrator/SKILL.md) skills.
+
+## One rule decides who spawns
+
+**A spawned agent cannot spawn agents.** Every agent of a run is therefore started by the session the user is talking to. That session is the **parent**. It stays the parent for the whole run and never becomes a step's agent, even when a whole plan is being worked.
+
+## Life cycle of one agent
+
+1. **Spawn** one agent per step. Execute is the exception and may get several, as laid out below.
+2. **Brief** it with the template below. The brief is everything the agent knows. It has not seen your conversation or the last agent's report.
+3. **Wait** for its report. Leave the branches and worktrees it is using alone while it runs.
+4. **Verify** with `g3n-skills hook current-step --phase <phase>`. The hook is the judge of whether the step is finished. The report only explains.
+5. **Retire** it. A finished agent is never resumed for the next step, and the next step gets a new one. What has to survive goes into the next brief, the tree, a decision, or a term.
+
+## The brief
+
+```
+Run the /<step> skill on phase <phase> of plan <plan>.
+Project root: <absolute path>. Phase branch: <branch>. Base branch: <branch>.
+Tasks: <ids, for execute and review>. Task branches: <id → branch, for review and sync>.
+Carried over: <findings from review, open questions, reports sync must read>.
+End with the report the skill asks for.
+```
+
+Give names, never contents. The agent reads the phase and its tasks through the hooks, which hand it the `vocabulary` along with them.
+
+## Which agent per step
+
+| Step | Agent | Can edit |
+|---|---|---|
+| `plan` | general purpose | the tree only |
+| `execute` | general purpose, one or several | its task's worktree |
+| `review` | **reviewer**, defined in the plugin's `agents/reviewer.md` | nothing |
+| `sync` | general purpose | the phase branch, the tree |
+
+Where no `reviewer` agent type is offered, which is the case after `g3n-skills add workflow`, spawn a general purpose agent for `review` and open its brief with _You change no file._
+
+## Running execute side by side
+
+Tasks whose `depends_on` are all `in-review` or `completed` can run at once, one agent per task, because each works in its own worktree. Spawn them in one message so they start together. A task waiting on another stays with the parent until that one is handed over. Each of these agents holds only some of the phase, so none of them calls `advance-step`. You run `g3n-skills hook advance-step --phase <phase> --from execute` once the last of them has returned.
+
+## Without sub-agents
+
+A harness with no agent tool, Codex among them, runs the same loop in one session. Load the step's skill, do the step, run its `advance-step`, then load the next skill. The hooks and gates are the same ones. What is lost is the fresh context per step, so re-read `current-step` before each step and trust it over your memory of the last one.

package/dist/plugins/workflow/skills/sync/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: sync
+description: Land a reviewed phase by merging its task branches, removing their worktrees, recording its decisions and terms, and closing the phase. Use as the sync step of the workflow, or when every task of a phase is completed and the phase is still open.
+registryDependencies: [task-manager, worktree, vocabulary, decisions]
+disable-model-invocation: false
+---
+
+The sync step leaves one branch holding the whole phase, no stray worktrees, and a tree that matches the code. It merges locally. Pushing and opening a pull request stay with the user.
+
+The hooks come from the `/task-manager` skill. Load it first when `g3n-skills` is not on `PATH`.
+
+1. **Confirm the step** with `g3n-skills hook current-step --phase <phase>`. Go on only when it prints `"step": "sync"`.
+2. **Merge the task branches** into the phase branch, in the order `current-step` lists the tasks, through the `/worktree` skill. A conflict you can settle from the two task briefs alone, settle. Any other conflict stops the step. Set the phase to `blocked` and put both sides in your report. Done when every task branch is merged and the package's type check and tests pass on the phase branch.
+3. **Remove what is merged**, again through the `/worktree` skill. Done when `git worktree list` shows no worktree of this phase.
+4. **Record what the phase decided.** Read the reports in your brief for choices the agents made along the way. Each one that passes the three tests goes through the `/decisions` skill. Each concept that got a name goes through the `/vocabulary` skill.
+5. **Close the phase** with `g3n-skills hook sync-tree`, then `g3n-skills hook advance-step --phase <phase> --from sync`. The step is finished when it prints `"step": "done"`.
+
+Your report names the phase branch, the merged commits, the decisions and terms recorded, and the next phases whose gate this one opened, from `g3n-skills hook ready-phases --plan <plan>`.

package/dist/plugins/workflow/skills/sync/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Sync"
+  short_description: "Merge a reviewed phase, record its decisions and terms, and close it"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/worktree/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: worktree
+description: Set up, merge and remove the git worktrees that tasks are worked in, one per task on its own branch. Use when a task is about to be started, when a finished phase is being merged, when worktrees are left over, or when another skill needs a worktree.
+disable-model-invocation: false
+---
+
+Every task gets its own **worktree**, a second checkout on its own branch, so agents working side by side never share a working directory and a half-finished task never dirties the checkout the user is in.
+
+## Names
+
+| Thing | Pattern | Example |
+|---|---|---|
+| Phase branch | `<type>/<plan>-<phase>` | `feature/auth-rework-01-schema` |
+| Task branch | `<worktree_type>/<task id>-<slug of the title>` | `feature/TASK-012-session-table-migration` |
+| Worktree folder | `../<repo folder>.worktrees/<task id>` | `../g3n.worktrees/TASK-012` |
+
+`worktree_type` comes from the task's frontmatter. The phase branch takes the type most of its tasks carry. The worktree folder sits beside the repository, outside it, so no search or build inside the repo walks into it.
+
+## Set up
+
+Run the commands under **Set up** in [`references/git-commands.md`](references/git-commands.md).
+
+- **Branch from the phase branch**, so a task sees the tasks it depends on once they are merged. A task whose `depends_on` names a task not merged yet branches from that task's branch instead.
+- **Install inside the worktree.** Dependencies are not shared between checkouts.
+- **An existing worktree for the task is reused.** `git worktree list` shows it. This is the normal case for a task sent back from review.
+
+## Merge
+
+Run the commands under **Merge** in [`references/git-commands.md`](references/git-commands.md).
+
+Run them from the main checkout, one task at a time, in the order the phase lists its tasks. `--no-ff` keeps one merge commit per task, which is what lets a single task be reverted later.
+
+## Remove
+
+Run the commands under **Remove** in [`references/git-commands.md`](references/git-commands.md).
+
+- **Only after the merge.** `git branch -d` refuses an unmerged branch, and that refusal is the safety net. Leave `-D` and `--force` to the user.
+- **A worktree with uncommitted changes stays.** Report it and let the user decide.

package/dist/plugins/workflow/skills/worktree/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Worktree"
+  short_description: "Set up, merge and remove one git worktree per task"
+policy:
+  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/worktree/references/git-commands.md

@@ -0,0 +1,27 @@
+# Git commands
+
+The commands behind each section of the [`worktree`](../SKILL.md) skill. The names follow its **Names** table. Swap in the real plan, phase and task.
+
+## Set up
+
+```bash
+git switch -c feature/auth-rework-01-schema        # once per phase, from the base branch
+git worktree add -b feature/TASK-012-session-table-migration \
+  ../g3n.worktrees/TASK-012 feature/auth-rework-01-schema
+cd ../g3n.worktrees/TASK-012 && bun install
+```
+
+## Merge
+
+```bash
+git switch feature/auth-rework-01-schema
+git merge --no-ff feature/TASK-012-session-table-migration
+```
+
+## Remove
+
+```bash
+git worktree remove ../g3n.worktrees/TASK-012
+git branch -d feature/TASK-012-session-table-migration
+git worktree prune
+```

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

@@ -0,0 +1,7 @@
+{
+  "name": "writing",
+  "description": "How to write skills, hooks and tasks that an agent can follow.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "skills": ["./skills/writing-great-hooks", "./skills/writing-great-skills", "./skills/writing-great-tasks"]
+}

package/dist/plugins/writing/skills/writing-great-hooks/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: writing-great-hooks
+description: How to write hooks — the self-contained scripts that carry deterministic work, both a skill's own hooks/ scripts and the lifecycle hooks the harness fires from settings.json. Use when adding, reviewing, or debugging a hook script, when a skill needs a query/filter/rank helper, when wiring UserPromptSubmit, PreToolUse, PostToolUse or Stop, or when the user asks how hooks should be written, registered, or documented.
+disable-model-invocation: false
+---
+
+A **hook** is a script that carries the part of a job which must come out the same every time. Where prose _steers_ the agent, a hook _replaces_ it: parsing, filtering, ranking, counting and formatting run as code, so the answer does not vary with the run. It is the strongest form of predictability available — reach for one wherever the work is mechanical.
+
+Two kinds. Everything below applies to both unless a section says otherwise.
+
+| Kind | Lives in | Fired by | Reach for it when |
+|---|---|---|---|
+| **Skill hook** | `<skill>/hooks/`, beside its `SKILL.md` | the agent, because the skill told it to | a skill needs a query, filter, or ranking answered the same way every run |
+| **Lifecycle hook** | anywhere `settings.json` can name it | the harness, at a fixed event | something must happen on every prompt, tool call, or stop, with no agent deciding to call it |
+
+The distinction that matters: a **skill hook** answers a question the agent chose to ask, so it can only ever inform. A **lifecycle hook** fires whether the agent wants it or not, which is what lets it inject context, block a tool call, or refuse a stop.
+
+## The two invariants
+
+Everything else here is negotiable. These are not.
+
+**Self-sufficient.** One file, zero dependencies. No `package.json`, no shared `lib/`, no `import` of a sibling, no install step — copy the file anywhere on the machine and it runs. When two hooks need the same parser or the same types, **each embeds its own copy**. That duplication is the price of the invariant and is paid on purpose: say so in a comment at the top of the shared block, and keep the copies in sync when the format changes. A hook that needs an install is a hook that fails the one time it matters.
+
+**Co-located.** A **skill hook** lives in `hooks/`, directly beside the `SKILL.md` that documents it — never in a repo-wide `scripts/` folder, never one directory up. The script and its instructions move, get read, and get reviewed as one unit. A hook nobody can find from the skill is a hook the agent will re-implement inline. A **lifecycle hook** belongs to the project rather than to a skill, so it lives in `.claude/hooks/` and is co-located instead with the `settings.json` entry that names it: registration and script are edited together or not at all.
+
+```
+<skill>/
+├── SKILL.md          # documents when to reach for each hook
+└── hooks/
+    ├── do-one-thing.ts
+    └── do-another-thing.ts
+```
+
+One hook does one thing and is named for it, in verb-first kebab-case: `get-top-priority-task.ts`, not `tasks.ts --mode=priority`. A flag that changes _what the script is for_ should have been a second file; a flag that narrows _the same job_ belongs where it is.
+
+## The skill-hook contract
+
+A **skill hook** is called by an agent that will not read a stack trace to work out what happened. Make the interface answer for itself.
+
+- **stdout is data; stderr is prose.** JSON on stdout, nothing else — no progress lines, no banners, no trailing "Done!". Every human-readable word goes to stderr. An agent piping stdout into a parser must never get a surprise.
+- **Exit code carries the verdict.** `0` ran, non-zero could not. Whether "nothing matched" is a failure is the script's decision and must be stated in its header: a hook that must return exactly one thing exits `1` with a reason on stderr; a search hook prints `[]` and exits `0`, because empty is a real answer.
+- **Flags, not positions**, and every flag defaults to the value that works from the repo root. `--index tasks/index.yaml` is a default, not a requirement. Reserve `--pretty` for indented JSON so the compact form stays pipeable.
+- **Deterministic output.** Every sort has an explicit final tie-breaker, so the same input yields the same order on every run. A hook whose output shuffles has given back the variance it existed to remove.
+- **Validate at the boundary, fail loudly.** Parse the input yourself, reject anything outside the documented shape, and name the offending line or field in the message. A loud failure costs one turn; a silent default costs the agent acting on a garbled answer.
+- **Read-only by default.** A hook that answers a question must not change state. If a hook has to write, say so in its first line of documentation and in the skill's table.
+
+## The lifecycle-hook contract
+
+A **lifecycle hook** never sees a flag. The harness pipes it a JSON **event payload** on stdin and reads three things back: the exit code, stderr, and — on exit `0` — stdout.
+
+Every payload carries the same four fields, plus whatever its event adds:
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/you/.claude/projects/<slug>/<session>.jsonl",
+  "cwd": "/home/you/project",
+  "hook_event_name": "PreToolUse"
+}
+```
+
+Three exit codes, and the meaning of the middle one is the whole reason lifecycle hooks exist:
+
+| Exit | Means | Where stderr goes |
+|---|---|---|
+| `0` | ran clean | transcript only; stdout handling is per-event |
+| `2` | **blocking error** — the hook is exercising its veto | to the agent, as the reason |
+| other | non-blocking error | to the user; the run continues regardless |
+
+Exit `2` does something different at every event — it erases a prompt, denies a tool call, or refuses a stop — so it is documented per event, not here.
+
+For anything richer than a veto, print a JSON object on stdout and exit `0`. Four fields work at every event:
+
+- **`continue`** (default `true`) — `false` halts the agent outright, after this hook.
+- **`stopReason`** — the string shown to the user when `continue` is `false`.
+- **`suppressOutput`** — keep stdout out of the transcript.
+- **`systemMessage`** — a warning surfaced to the user.
+
+Each event adds its own `hookSpecificOutput` object on top. Those are the per-event skills below.
+
+_The harness is the authority on payload and output shapes, and they gain fields over time._ Confirm against the live `/hooks` view before relying on a field that changes behaviour.
+
+## Registering a lifecycle hook
+
+Registration is an array per event, each entry pairing an optional **matcher** with the commands to run:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-types.ts",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- **`matcher` selects tools by name**, as a regex — `Edit|Write`, `Bash`, or omitted for every tool. Only `PreToolUse` and `PostToolUse` use it; `UserPromptSubmit` and `Stop` have no tool to match and take an entry with no matcher.
+- **Every matching entry runs, in parallel.** Two hooks matching the same tool both fire; neither sees the other's output. Never write one expecting to run after another.
+- **`$CLAUDE_PROJECT_DIR` resolves to the project root**, so registrations survive a different working directory. An absolute path outside the project is fine for a machine-wide tool.
+- **`timeout` is seconds, and the default is 60.** It bounds one command, and a hook that hits it is killed — a slow hook taxes every single event it is registered on.
+
+## The four events
+
+Each fires at a different moment and buys a different power. Read the one you are writing:
+
+| Event | Fires | What it can do | Skill |
+|---|---|---|---|
+| `UserPromptSubmit` | the user submits, before the agent reads it | inject context, rewrite the terms, reject the prompt | [`hook-user-prompt-submit`](../hook-user-prompt-submit/SKILL.md) |
+| `PreToolUse` | a tool is chosen, before it runs | allow, deny, or escalate the call to the user | [`hook-pre-tool-use`](../hook-pre-tool-use/SKILL.md) |
+| `PostToolUse` | a tool has finished | react to what happened; it cannot undo it | [`hook-post-tool-use`](../hook-post-tool-use/SKILL.md) |
+| `Stop` | the agent is about to end its turn | refuse the ending and say what remains | [`hook-stop`](../hook-stop/SKILL.md) |
+
+## The header block
+
+The agent frequently reads a hook before running it — the file has to explain itself without `SKILL.md` present. Directly under the shebang, a block comment with four parts:
+
+```ts
+#!/usr/bin/env bun
+/**
+ * get-top-priority-task
+ *
+ * Returns the open task with the most urgent priority. Ties break by
+ * creation order, so results are deterministic.
+ *
+ * Usage:
+ *   ./get-top-priority-task.ts [--index tasks/index.yaml] [--pretty]
+ *
+ * Output:
+ *   One task object as JSON on stdout; exit 1 with a message on stderr
+ *   when there are no open tasks.
+ */
+```
+
+Name, one paragraph of behaviour, real invocations, and the output shape with its exit codes. Anything a caller must know to use the script correctly goes here, not only in the skill. A **lifecycle hook** substitutes its event and matcher for the usage line, and states what each exit code makes the harness do.
+
+## Writing the script
+
+TypeScript on Bun, in this repo. The invariants force three specifics that look odd out of context, so comment them where they appear:
+
+- **`#!/usr/bin/env bun`** on line 1, so the file is directly executable. Still document `bun run hooks/<script>.ts` as an equivalent — the executable bit does not reliably survive a checkout, and that fallback is what keeps the hook runnable when it doesn't.
+- **`export {}` as the first statement.** Without a top-level import or export, TypeScript treats a `.ts` file as a global script, so several hooks in one folder collide on every shared name — duplicate `Task`, duplicate `main`, "cannot redeclare" on every constant. The marker scopes each file to itself.
+- **Hand-declared runtime globals** instead of `@types/node` or `bun-types`:
+
+  ```ts
+  declare const process: { readonly argv: string[]; exit(code?: number): never; cwd(): string };
+  declare const Bun: { file(path: string): { text(): Promise<string> }; stdin: { text(): Promise<string> } };
+  ```
+
+  This is what lets the file type-check with zero installs. Declare only the members used — a local `declare const` inside a module shadows a real ambient global rather than fighting it, so the file stays correct even in a package that _does_ have the types installed.
+
+Beyond that, ordinary production rules apply: `strict`-clean, no `any`, explicit types on every function that isn't a one-line local, errors handled rather than swallowed, and a single `main().catch(printError)` at the bottom so no rejection escapes.
+
+**A lifecycle hook runs with your credentials on input the agent influenced.** Treat every payload field as hostile: never interpolate one into a shell string, resolve any path before comparing it, and decide what an unrecognised shape does before shipping.
+
+## Documenting hooks in the skill
+
+The hook's own header says _what it does_; `SKILL.md` says _which one to reach for_. Give the skill a table with one row per hook:
+
+| Hook | Does | Use it when |
+|---|---|---|
+
+Then state, once, the facts shared by all of them: how they're invoked, what the common flags default to, and where their behaviour deliberately differs (one returns a single object, another an array; one filters by status implicitly, another doesn't). Every flag named in the table must exist in the script, and every script in `hooks/` must appear in the table.
+
+A **lifecycle hook** is documented by its registration instead: the event, the matcher, and what each exit code makes the harness do. A reader who cannot predict when it fires cannot debug it.
+
+## When not to write a hook
+
+**A hook computes; it never decides.** Ranking open tasks by priority is computation — the rule is fixed and the tie-breaker is written down. Deciding whether a task is worth doing today is judgement, and judgement in code is a rule nobody can see, argue with, or override. If the answer depends on context the script can't read, it belongs in the skill's prose.
+
+Nor is a hook worth writing for work the agent already does reliably in one step. Reading a single file, grepping for a string, or reformatting a small blob is cheaper inline than as a script that must be maintained, documented, and kept in sync.
+
+**A lifecycle hook additionally has to earn its event.** It runs on every prompt, every matching tool call, or every stop, forever, whether or not this session cares — so cost and false positives are paid continuously while the benefit arrives occasionally. A rule that matters only sometimes belongs in prose the agent reads when it applies.
+
+## Failure modes
+
+- _Hidden dependency._ An `import` of a sibling module, a `package.json` in `hooks/`, an assumed global install. The hook works in the repo it was written in and nowhere else, and the breakage surfaces at the call site as a stack trace the agent has no context for.
+- _Silent fallback._ Malformed input quietly coerced to a default — a missing field read as `""`, an unparseable line skipped. The script returns a confident wrong answer, and the agent acts on it. Throw instead, naming the input.
+- _Chatty stdout._ A log line, a warning, or a human sentence mixed into the JSON. Every caller that parses stdout breaks at once, and on a lifecycle hook the stray text is read as the hook's whole answer.
+- _Ambiguous exit._ Exiting `0` on "found nothing" in a hook whose contract is "returns one", or `1` on an empty search result. The caller cannot distinguish "no answer" from "broken", so it guesses. On a lifecycle hook, the near-miss is worse: `1` where `2` was meant is a veto that silently never happened.
+- _Unstable order._ A sort with no final tie-breaker, or output built from an unordered map. Two runs disagree and the skill's predictability is gone at exactly the point it was supposed to be guaranteed.
+- _Doc drift._ A flag renamed in the script but not the table, a hook added without a row, a registration whose matcher no longer matches the tools it names. The documentation is the interface; an edit to the script that skips it is half an edit.
+- _Judgement in code._ A weighting, threshold, or preference hardcoded into a hook where the skill should have stated the rule in prose for the agent to apply.
+- _Event tax._ A hook doing real work — a full typecheck, a network call — on an event that fires constantly. Every prompt or tool call now waits on it. Scope by matcher, exit early on the common case, and keep the slow path behind a cheap test.

package/dist/plugins/writing/skills/writing-great-hooks/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Writing Great Hooks"
+  short_description: "Self-contained scripts that carry deterministic work, in a skill or on a lifecycle event"
+policy:
+  allow_implicit_invocation: false