@g3nomaly/g3n-skills 0.1.1 → 0.1.3

package/.claude-plugin/marketplace.json

@@ -7,10 +7,11 @@
     {
       "name": "agent",
       "source": "./skills/agent",
-      "description": "Rules every agent session follows: the session bootstrap, its boundaries, and working in worktrees.",
+      "description": "Rules every agent session follows: the session bootstrap, its boundaries, working in worktrees, and commit messages.",
       "skills": [
         "./bootstrap",
-        "./worktrees"
+        "./worktrees",
+        "./commit"
       ]
     },
     {
@@ -37,10 +38,12 @@
     {
       "name": "speech",
       "source": "./skills/speech",
-      "description": "Conventions for how an agent writes — emphasis markup and cutting AI tells.",
+      "description": "Conventions for how an agent writes — emphasis markup, cutting AI tells, and plain language.",
       "skills": [
         "./emphasise",
-        "./unslop"
+        "./unslop",
+        "./plain-language",
+        "./no-questions"
       ]
     },
     {

package/README.md

@@ -0,0 +1,101 @@
+# @g3nomaly/g3n-skills
+
+The g3n skills for Claude Code and Codex: 31 skills in 8 groups. This package holds the skills and has no CLI. Install them with [`@g3nomaly/skills`](https://www.npmjs.com/package/@g3nomaly/skills), which reads this package as its built-in source, or read it as a Claude Code plugin marketplace.
+
+Some skills carry their own hooks. A hook is a TypeScript file in the skill's `hooks/` folder, and the agent runs it with `bun`. The task-manager hooks keep plans, phases and tasks as Markdown files that the agent reaches only through those hooks. The workflow hooks decide when a step of a phase is finished.
+
+## Requirements
+
+- [Bun](https://bun.sh), to run the hooks
+- A git repository to install into, because `@g3nomaly/skills` anchors a project at its repository root
+- [`@g3nomaly/analyze`](https://www.npmjs.com/package/@g3nomaly/analyze) for the `analyze` skill, which runs `bunx @g3nomaly/analyze`
+
+## Install with @g3nomaly/skills
+
+Run these from the root of your project:
+
+```sh
+bunx @g3nomaly/skills init                       # pick Claude Code, Codex or both
+bunx @g3nomaly/skills ls --source g3n-skills     # lists the skills this package offers
+bunx @g3nomaly/skills add workflow               # installs a group, with every skill it depends on
+bunx @g3nomaly/skills add unslop                 # installs one skill
+```
+
+You don't register this package. `g3n-skills` is built into the installer and cannot be removed.
+
+Each skill is copied to `.claude/skills/<skill>/`, or `.agents/skills/<skill>/` for Codex, next to the skills it depends on. The installer records it in `.claude/skills.json` or `.agents/skills.json`. Commit the skills and that file if your team should get the same skills.
+
+A name that is both a group and a skill, such as `grilling` or `task-manager`, installs the whole group. `add` and `update` also run `bun install` in each skill that ships a `package.json`. Today that is only `task-manager`, which pins zod.
+
+```sh
+bunx @g3nomaly/skills update                     # every installed skill
+bunx @g3nomaly/skills update --dry-run           # shows what would change
+bunx @g3nomaly/skills remove grill-me
+bunx @g3nomaly/skills ls --installed
+```
+
+## As a Claude Code plugin marketplace
+
+The package ships `.claude-plugin/marketplace.json`, a marketplace named `g3n` with one plugin per group in the table below.
+
+Installed as a plugin, the task-manager group registers two lifecycle hooks. `sync-tree` runs at `SessionStart`, and `guard-tree` runs before `Read`, `Grep` and `Glob`. With `@g3nomaly/skills` you get neither, and the task-manager skill tells the agent to run `sync-tree` itself.
+
+There is one known gap. Claude Code caches each plugin in its own folder, so the workflow hooks can't import the task-manager code they need. Install the workflow group with `@g3nomaly/skills` for now.
+
+## The skills
+
+Skills marked _manual_ run only when you type their command, such as `/grill-me`. The agent loads the others when the task calls for them.
+
+| Group | Skill | What it does |
+|---|---|---|
+| `agent` | `bootstrap` | Session start checks (read `CLAUDE.md`, compare the file tree, state the branch) and the agent's boundaries |
+| `agent` | `worktrees` | Work in a git worktree on a feature branch and land it on the home branch as clean commits on top of `main`, ready to merge one commit at a time |
+| `agent` | `commit` | Commit messages with no attribution trailers, personal data or AI references, checked by a hook before each commit |
+| `coding` | `code` | Rules for writing and checking code, with a toolchain reference per language |
+| `coding` | `document` | Docstrings and comments for functions and classes, and where the reasons behind code go |
+| `coding` | `analyze` | Query a repository's model with `g3n-analyze` and rebuild its documentation site in `analyze_out/` |
+| `grilling` | `grilling` | Interview the user relentlessly to stress-test a plan, decision or idea |
+| `grilling` | `grill-me` | _Manual._ Starts a `/grilling` session |
+| `grilling` | `grill-with-docs` | _Manual._ A grilling session that writes ADRs and a glossary as it goes |
+| `grilling` | `domain-modeling` | Pin down a project's terms and record its architectural decisions |
+| `speech` | `emphasise` | What bold, italics and backticks mean in Markdown that an agent reads |
+| `speech` | `unslop` | Cut AI tells from any writing |
+| `speech` | `plain-language` | Write text readers can find, understand and use on the first read, following ISO 24495-1 |
+| `speech` | `no-questions` | Replies end without questions or offers; a Stop hook refuses a reply that asks one |
+| `task-manager` | `task-manager` | Query plans, phases and tasks and change their status through hooks |
+| `task-manager` | `vocabulary` | One word per concept, stored in the task-manager tree, so names don't drift between sessions |
+| `task-manager` | `decisions` | Record and look up a plan's decisions as numbered files inside the plan |
+| `using-hooks` | `hook-pre-tool-use` | _Manual._ Writing a `PreToolUse` hook, which can allow, deny or escalate a tool call |
+| `using-hooks` | `hook-post-tool-use` | _Manual._ Writing a `PostToolUse` hook, which reacts to a finished tool call |
+| `using-hooks` | `hook-stop` | _Manual._ Writing a `Stop` hook, which can refuse to let the agent end its turn |
+| `using-hooks` | `hook-user-prompt-submit` | _Manual._ Writing a `UserPromptSubmit` hook, which can add context to a prompt or reject it |
+| `workflow` | `run` | Work one phase through plan, execute, review and sync, one fresh agent per step |
+| `workflow` | `plan` | Turn a phase into task files an agent can execute without asking anything |
+| `workflow` | `execute` | Carry out a phase's tasks, each in its own worktree, and hand each one to review |
+| `workflow` | `review` | Check each in-review task against its requirements, then complete it or send it back |
+| `workflow` | `sync` | Merge a reviewed phase's branches, remove its worktrees, record its decisions and terms, and close it |
+| `workflow` | `orchestrator` | _Manual._ Run a whole plan phase by phase, starting each phase once the phases it depends on are done |
+| `workflow` | `worktree` | Set up, merge and remove the git worktrees tasks are worked in, one per task |
+| `writing` | `writing-great-hooks` | Add, change or debug a hook script or a lifecycle hook |
+| `writing` | `writing-great-skills` | Write or edit a skill, its `SKILL.md`, references and hooks |
+| `writing` | `writing-great-tasks` | Write a task that doesn't leave its executor guessing about scope |
+
+The `commit` hook refuses your git `user.name` and `user.email`. To keep another name out of messages without writing it into the repository, add it to your global git config: `git config --global --add g3n.privateName "<name>"`.
+
+The task-manager hooks store the tree in `docs/task-manager` by default. Set `skills.settings.filetreeRoot` in `.g3n.config.json` to move it.
+
+## Development
+
+Run `bun install` at the repository root first, then every command from this directory.
+
+```sh
+bun run build       # regenerates .claude-plugin/marketplace.json here and at the repository root
+bun run typecheck
+bun test
+```
+
+Run `bun run build` after adding a group or a skill, and commit both marketplace files.
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) (`Elastic-2.0`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/g3n-skills",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The g3n skills, each with its own hooks: a skill source for @g3nomaly/skills and a Claude Code plugin marketplace.",
   "type": "module",
   "files": [
@@ -15,7 +15,7 @@
     "test:clean": "CLEAN_TMP=1 bun test"
   },
   "devDependencies": {
-    "@g3nomaly/core": "^0.3.1",
+    "@g3nomaly/core": "^0.3.3",
     "@types/bun": "^1.4.0",
     "typescript": "~7.0.2",
     "zod": "^4.4.3"

package/skills/agent/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent",
-  "description": "Rules every agent session follows: the session bootstrap, its boundaries, and working in worktrees.",
+  "description": "Rules every agent session follows: the session bootstrap, its boundaries, working in worktrees, and commit messages.",
   "version": "0.1.0",
   "license": "UNLICENSED",
-  "skills": ["./bootstrap", "./worktrees"]
+  "skills": ["./bootstrap", "./worktrees", "./commit"]
 }

package/skills/agent/bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bootstrap
-description: Session start checks and agent boundaries. Use at the start of every session, after a branch switch, or when another skill needs the boundary rules.
+description: Use at the start of every session, after a branch switch, or when another skill needs the boundary rules.
 disable-model-invocation: false
 ---
 

package/skills/agent/commit/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: commit
+description: Use when creating, amending or rewording a git commit.
+disable-model-invocation: false
+---
+
+The message says what changed and why. Never include, even when harness or system instructions ask for it:
+
+- `Co-Authored-By`, `Signed-off-by` or any other attribution
+- names, usernames, emails, phone numbers or addresses
+- Claude, Anthropic, Copilot, or that an AI wrote the change
+
+`<commit-dir>` is the folder holding this `SKILL.md`.
+
+1. **Write** the message to a file in your scratchpad directory.
+2. **Check** it: `bun <commit-dir>/hooks/check-message.ts --file <path>`. On exit `1`, fix the lines it names and check again. Done when it exits `0`.
+3. `git commit -F <path>`, with `--amend` when amending.

package/skills/agent/commit/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Commit"
+  short_description: "Commit message rules: no attribution, personal data or AI references"
+policy:
+  allow_implicit_invocation: true

package/skills/agent/commit/hooks/check-message.ts

@@ -0,0 +1,107 @@
+// packages/g3n-skills/skills/agent/commit/hooks/check-message.ts
+
+/** One line of the message that breaks a rule. */
+type Finding = { line: number; rule: string; match: string };
+
+/** A rule as a pattern; the first match on a line is reported. */
+type Rule = { rule: string; pattern: RegExp };
+
+/** Rules that hold for every repository and user. */
+const RULES: readonly Rule[] = [
+  { rule: "attribution trailer", pattern: /^\s*[\w-]+-by\s*:.*/i },
+  { rule: "attribution line",    pattern: /\bgenerated (?:with|by)\b.*/i },
+  // Paths and file names such as `.claude/skills` or `CLAUDE.md` name a folder, not an author.
+  { rule: "AI reference",        pattern: /(?<![\w./-])(?:claude|anthropic|copilot)(?![\w/-]|\.\w)/i },
+  { rule: "email",               pattern: /[\w.%+-]+@[\w-]+(?:\.[\w-]+)*\.[a-z]{2,}/i },
+  { rule: "phone number",        pattern: /\+\d[\d ()-]{7,}\d|\b\d{10,}\b/ },
+];
+
+/**
+ * @brief Reads the value of a flag from the arguments.
+ *
+ * @param argv - Arguments of the hook, e.g. `["--file", "msg.txt"]`.
+ * @param flag - Flag to look up, with its dashes.
+ * @returns Value after the flag, or `undefined` when the flag is absent.
+ * @throws Error when the flag is last or followed by another flag.
+ */
+function readFlag(argv: readonly string[], flag: string): string | undefined {
+  const at = argv.indexOf(flag);
+  if (at === -1) return undefined;
+
+  const value = argv[at + 1];
+  if (value === undefined || value.startsWith("--")) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+/**
+ * @brief Reads every value of a git config key, as seen from the working directory.
+ *
+ * @param key - Config key, e.g. `user.name`.
+ * @returns The non-empty values, or none when the key is unset.
+ */
+function gitConfig(key: string): string[] {
+  const result = Bun.spawnSync(["git", "config", "--get-all", key], { stderr: "ignore" });
+  return result.stdout.toString().split("\n").map((value) => value.trim()).filter(Boolean);
+}
+
+/** Escapes `text` so it matches itself literally inside a `RegExp`. */
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * @brief Builds rules for the identities this machine knows: the git `user.name`
+ * and `user.email`, the email's local part, and every `g3n.privateName`.
+ *
+ * `g3n.privateName` keeps a name out of messages without writing it into the
+ * repository: `git config --global --add g3n.privateName "<name>"`.
+ */
+function identityRules(): Rule[] {
+  const emails = gitConfig("user.email");
+  const names = [
+    ...gitConfig("user.name"),
+    ...gitConfig("g3n.privateName"),
+    ...emails,
+    ...emails.map((email) => email.split("@")[0] ?? ""),
+  ].filter((name) => name.length >= 3);
+
+  return names.map((name) => ({
+    rule: "personal identity",
+    pattern: new RegExp(`(?<![\\w])${escapeRegExp(name)}(?![\\w])`, "i"),
+  }));
+}
+
+/**
+ * @brief Checks a commit message against every rule.
+ *
+ * @param message - Full commit message.
+ * @param rules - Rules to apply.
+ * @returns Every line that breaks a rule, in line order and then rule order.
+ */
+function check(message: string, rules: readonly Rule[]): Finding[] {
+  return message.split("\n").flatMap((text, index) =>
+    rules.flatMap(({ rule, pattern }) => {
+      const found = text.match(pattern);
+      return found ? [{ line: index + 1, rule, match: found[0].trim() }] : [];
+    }),
+  );
+}
+
+/** Prints `{ clean: true }` for the message in `--file` (or stdin) when it breaks no rule; exits 1 naming each line that does. */
+async function run(argv: readonly string[]): Promise<void> {
+  const file = readFlag(argv, "--file");
+  const message = file === undefined ? (process.stdin.isTTY ? "" : await Bun.stdin.text()) : await Bun.file(file).text();
+  if (message.trim() === "") throw new Error("no message: pass --file <path> or pipe it on stdin");
+
+  const findings = check(message, [...RULES, ...identityRules()]);
+  if (findings.length > 0) {
+    throw new Error(findings.map(({ line, rule, match }) => `line ${line}: ${rule}: "${match}"`).join("\n"));
+  }
+
+  console.log(JSON.stringify({ clean: true }, null, argv.includes("--pretty") ? 2 : 0));
+}
+
+run(process.argv.slice(2)).catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/skills/agent/worktrees/SKILL.md

@@ -1,21 +1,19 @@
 ---
 name: worktrees
-description: Work in a git worktree on its home branch and land the work there with a local squash merge. Use only when the user asks you to work in a worktree.
+description: Use only when the user asks you to work in a worktree.
 disable-model-invocation: false
 ---
 
-A worktree at `~/worktrees/<repo>/<x>` has the **home branch** `worktree/<x>`, which tracks local `main`. Work ends on the home branch. The user merges it into `main`.
+A worktree at `~/worktrees/<repo>/<x>` has the **home branch** `worktree/<x>`: `main` plus finished features.
 
-## Steps
+1. `git switch worktree/<x> && git rebase main && git switch -c <type>/<name>`
+2. Run the package's checks from the `/code` skill.
+3. Fold each commit that only fixes an earlier one into it. If more than 10 are left, squash the ones that belong together into reviewable steps.
+4. `git rebase worktree/<x> && git switch worktree/<x> && git merge --ff-only <type>/<name>`
+5. Report it ready to merge. Keep the feature branch.
 
-1. `git switch worktree/<x> && git pull --no-rebase --no-edit`
-2. `git switch -c <type>/<name>`, do the work, commit, and run the package's checks (see the `/code` skill)
-3. `git switch worktree/<x> && git pull --no-rebase --no-edit`
-4. `git merge --squash <type>/<name>`, then `git commit` with a subject and body covering the whole change
-5. Stop and report. Leave the feature branch in place.
+On conflict: `git rebase --abort`, stop and report.
 
-On conflict: `git merge --abort` (after a squash: `git reset --merge`), stop and report.
+## Merging into `main`
 
-## Branch types
-
-`feature`, `fix`, `refactor`, `chore`, `docs`, `snapshot` (backup before destructive operations), `demo` (not meant to merge), `experiment` (may never merge).
+Remember where `main` started. When the user asks, stage the first commit marked `+` in `git cherry main worktree/<x>` with `git cherry-pick --no-commit <sha>`. Commit it with `git commit -C <sha>` only when the user asks. On a rejected commit, the user picks: fix it in the worktree, or reset `main` to where the first cherry-pick started.

package/skills/agent/worktrees/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
   display_name: "Worktrees"
-  short_description: "Work on a worktree's home branch and land it with a local squash merge"
+  short_description: "Work on a feature branch and land it on the worktree home branch as clean commits on top of main"
 policy:
   allow_implicit_invocation: true

package/skills/coding/analyze/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: analyze
-description: Query and update the linked model of a repository with g3n-analyze: find code, docs, skills, decisions and tasks, see what uses or links to what, and rebuild the documentation site in analyze_out/. Use when asked where something is, what uses a type or function, what a decision affects, or to run g3n-analyze or regenerate the docs.
+description: Use when asked where something is, what uses a type or function, what a decision affects, or to run g3n-analyze or regenerate the docs.
+disable-model-invocation: false
 ---
 
 `g3n-analyze` scans a repository into one model of **nodes** and **edges**, and answers queries on it. Run it from the repository root as `bunx @g3nomaly/analyze <command>`; in the g3n monorepo, `bun packages/analyze/dist/cli.js <command>` after `bun run build` in `packages/analyze`.

package/skills/coding/code/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code
-description: Standard code skill for writing and checking code. Includes toolchain references for each language.
+description: Use when writing or checking code.
 disable-model-invocation: false
 ---
 

package/skills/coding/document/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: document
-description: Docstrings and comments for functions and classes, and where the reasons behind code go. Use when writing or changing a function or class, or when another skill needs the documentation rules.
+description: Use when writing or changing a function or class, or when another skill needs the documentation rules.
 disable-model-invocation: false
 ---
 

package/skills/grilling/domain-modeling/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: domain-modeling
-description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+description: Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+disable-model-invocation: false
 ---
 
 # Domain Modeling

package/skills/grilling/grilling/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: grilling
-description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+description: Use when the user wants to stress-test a plan, decision or idea, or uses any 'grill' trigger phrase.
+disable-model-invocation: false
 ---
 
 Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

package/skills/speech/.claude-plugin/plugin.json

@@ -1,7 +1,8 @@
 {
   "name": "speech",
-  "description": "Conventions for how an agent writes — emphasis markup and cutting AI tells.",
+  "description": "Conventions for how an agent writes — emphasis markup, cutting AI tells, and plain language.",
   "version": "0.1.0",
   "license": "UNLICENSED",
-  "skills": ["./emphasise", "./unslop"]
+  "hooks": "./hooks.json",
+  "skills": ["./emphasise", "./unslop", "./plain-language", "./no-questions"]
 }

package/skills/speech/emphasise/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: emphasise
-description: The bold, italic, and backtick conventions for agent-facing Markdown — what **bold**, _italics_, and `code` each mean, and how to use them to make text instantly scannable. Use when writing or editing a skill, prompt, or doc the agent reads, or when the user asks how to emphasise a term.
+description: Use when writing or editing a skill, prompt or doc the agent reads, or when the user asks how to emphasise a term.
 disable-model-invocation: false
 ---
 

package/skills/speech/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/no-questions/hooks/refuse-questions.ts\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/speech/no-questions/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: no-questions
+description: Toggles the Stop hook that refuses replies asking the user a question.
+disable-model-invocation: true
+---
+
+Run `bun <this skill's folder>/hooks/toggle.ts` and tell the user whether the hook is now on or off.
+
+The hook is a Stop hook, `hooks/refuse-questions.ts`. While on, it refuses a reply with a `?` outside code, URLs and quotes.

package/skills/speech/no-questions/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "No questions"
+  short_description: "Replies end without questions or offers"
+policy:
+  allow_implicit_invocation: true

package/skills/speech/no-questions/hooks/refuse-questions.ts

@@ -0,0 +1,108 @@
+// packages/g3n-skills/skills/speech/no-questions/hooks/refuse-questions.ts
+// refuse-questions
+//
+// Stop hook. Refuses a final reply that asks the user something in its text:
+// an offer such as "Should I build it?" or a question tucked under a report.
+// The user decides what comes next; a decision the agent cannot make goes
+// through the AskUserQuestion tool, never into reply text.
+//
+// A `?` counts only in prose: code blocks, inline code, URLs and quoted text
+// ("..." or “...”) are skipped, so quoting an example is not asking.
+//
+// Fires on: Stop, while toggle.ts has it on. Blocks once; a stop already blocked by this hook goes through.
+//
+// Exit codes: 0 lets the turn end, 2 refuses it with the reason on stderr.
+// Every error path exits 0, so a broken hook never traps the session.
+
+import { isEnabled } from "../src/state";
+
+/**
+ * The fields of the Stop payload this hook reads from stdin.
+ *
+ * @property last_assistant_message - Text of the reply the turn ends with.
+ * @property transcript_path - JSONL file of the session, one entry per line.
+ * @property stop_hook_active - True when the turn only continues because a Stop hook already blocked it.
+ */
+interface StopPayload {
+  readonly last_assistant_message?: string;
+  readonly transcript_path?: string;
+  readonly stop_hook_active?: boolean;
+}
+
+/** One block of a message's `content` array in the transcript. */
+type ContentBlock = { type?: string; text?: string };
+
+/** One line of the transcript. */
+type Entry = { type?: string; message?: { role?: string; content?: string | ContentBlock[] } };
+
+/**
+ * @brief Finds the text of the last assistant message of the current turn.
+ *
+ * Stops at the user's prompt, so a reply from an earlier turn is never checked.
+ *
+ * @param transcript - Contents of the JSONL transcript.
+ * @returns The message's text blocks joined, or `""` when the turn has none.
+ */
+function lastReply(transcript: string): string {
+  const lines = transcript.trimEnd().split("\n");
+
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let entry: Entry;
+    try {
+      entry = JSON.parse(lines[i] ?? "") as Entry;
+    } catch {
+      continue;
+    }
+    if (entry.type === "user" && isPrompt(entry)) return "";
+    if (entry.type !== "assistant" || !Array.isArray(entry.message?.content)) continue;
+
+    const text = entry.message.content
+      .filter((block) => block.type === "text" && typeof block.text === "string")
+      .map((block) => block.text)
+      .join("\n");
+    if (text.trim() !== "") return text;
+  }
+
+  return "";
+}
+
+/** Tells whether a user entry is a prompt the user typed, not a tool result. */
+function isPrompt(entry: Entry): boolean {
+  const content = entry.message?.content;
+  return typeof content === "string" || (Array.isArray(content) && content.some((block) => block.type === "text"));
+}
+
+/**
+ * @brief Returns the sentences of `text` that ask a question, skipping code and URLs.
+ *
+ * @param text - Markdown text of the reply.
+ */
+function questions(text: string): string[] {
+  const prose = text
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`[^`\n]*`/g, " ")
+    .replace(/https?:\/\/\S+/g, " ")
+    .replace(/"[^"\n]*"|“[^”\n]*”/g, " ");
+
+  return prose.match(/[^.!?\n]*\?/g)?.map((sentence) => sentence.trim()).filter(Boolean) ?? [];
+}
+
+/** Reads the Stop payload and refuses the stop when the final reply asks a question. */
+async function main(): Promise<void> {
+  const payload = JSON.parse(await Bun.stdin.text()) as StopPayload;
+  if (payload.stop_hook_active || !(await isEnabled())) return;
+
+  const reply = payload.last_assistant_message
+    ?? (payload.transcript_path ? lastReply(await Bun.file(payload.transcript_path).text()) : "");
+  const found = questions(reply);
+  if (found.length === 0) return;
+
+  console.error(
+    `Your reply asks the user: ${found.map((q) => `"${q}"`).join(", ")}. ` +
+      "Rewrite the reply without questions. Drop offers such as \"Should I build it?\": the user decides what comes next. " +
+      "Only when you cannot continue without the user's decision, ask it with the AskUserQuestion tool.",
+  );
+  process.exit(2);
+}
+
+main().catch(() => process.exit(0));

package/skills/speech/no-questions/hooks/toggle.ts

@@ -0,0 +1,14 @@
+// packages/g3n-skills/skills/speech/no-questions/hooks/toggle.ts
+import { isEnabled, STATE_FILE } from "../src/state";
+
+/** Turns the no-questions Stop hook on when it is off and off when it is on; writes the state file and prints `{ enabled }`. */
+async function run(argv: readonly string[]): Promise<void> {
+  const enabled = !(await isEnabled());
+  await Bun.write(STATE_FILE, JSON.stringify({ enabled }) + "\n");
+  console.log(JSON.stringify({ enabled }, null, argv.includes("--pretty") ? 2 : 0));
+}
+
+run(process.argv.slice(2)).catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/skills/speech/no-questions/src/state.ts

@@ -0,0 +1,15 @@
+// packages/g3n-skills/skills/speech/no-questions/src/state.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** File that holds whether the hook is on, for every project of this user. */
+export const STATE_FILE = join(homedir(), ".claude", "no-questions.json");
+
+/** Tells whether the hook is on; it is on until the user turns it off. */
+export async function isEnabled(): Promise<boolean> {
+  try {
+    return (JSON.parse(await Bun.file(STATE_FILE).text()) as { enabled?: boolean }).enabled !== false;
+  } catch {
+    return true;
+  }
+}

package/skills/speech/plain-language/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: plain-language
+description: Use when writing or editing anything a person or agent reads, such as skills, docs, READMEs, reports and replies.
+disable-model-invocation: false
+---
+
+Writing rules from the plain language standard ISO 24495-1
+
+No ambiguous pronoun reference: when an "it" or "that" could point to more than one antecedent, repeat the noun.

package/skills/speech/plain-language/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Plain Language"
+  short_description: "Write text readers can find, understand and use, per ISO 24495-1"
+policy:
+  allow_implicit_invocation: true

package/skills/speech/unslop/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: unslop
-description: Cut AI tells from any writing. Must always apply.
+description: Use whenever writing or editing any text.
+disable-model-invocation: false
 ---
 
 # Unslop
@@ -77,4 +78,4 @@ Removing patterns is half the job. Sterile, voiceless writing is just as obvious
 28. **Shorten or split dense sentences.** If the reader has to backtrack to parse a sentence, break it in two or drop clauses. One idea per sentence.
 29. **Active voice.** Prefer it. Catch "is/are/was/were + past participle" and name the actor: "queries are validated" becomes "the compiler validates queries", "the file is parsed by the loader" becomes "the loader parses the file". Passive is fine only when the actor is unknown or genuinely doesn't matter.
 30. **Cut adverbs, or use a stronger verb.** "runs quickly" becomes "is fast" or the number. "significantly improves" becomes the measured delta. An adverb propping up a weak verb means the verb is wrong.
-31. **Prefer the plain word.** "utilize" becomes "use", "leverage" becomes "use", "facilitate" becomes "help", "numerous" becomes "many", "in the event that" becomes "if". The fancier synonym is rarely clearer.
+31. **Prefer the plain word.** "utilize" becomes "use", "leverage" becomes "use", "facilitate" becomes "help", "numerous" becomes "many", "in the event that" becomes "if". The fancier synonym is rarely clearer.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: 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
 ---

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: 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
 ---

package/skills/workflow/execute/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: 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, run]
 disable-model-invocation: false
 ---

package/skills/workflow/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: 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, run]
 disable-model-invocation: false
 ---

package/skills/workflow/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: 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, run]
 disable-model-invocation: false
 ---

package/skills/workflow/run/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: 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, orchestrator]
 disable-model-invocation: false
 ---

package/skills/workflow/sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: 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, run, orchestrator]
 disable-model-invocation: false
 ---

package/skills/workflow/worktree/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: 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
 ---
 

package/skills/writing/writing-great-skills/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: writing-great-skills
 description: Use when writing or editing a skill, its SKILL.md, references or hooks.
-registryDependencies: [emphasise, writing-great-hooks]
+registryDependencies: [emphasise, plain-language, writing-great-hooks]
 disable-model-invocation: false
 ---
 
@@ -9,12 +9,14 @@ disable-model-invocation: false
 
 - `name`: the skill's folder name.
 - `description`: decides whether the agent loads the skill. Say when to use it: the tasks and words that should trigger it, and nothing else.
+- `disable-model-invocation`: always set. `false`: the agent may load the skill, so `description` says only when to use it. `true`: only the user runs it, so `description` may describe it.
 
 ## SKILL.md
 
 - Direct instructions, in order. Each step says when it is done.
 - Only what every use of the skill needs.
 - Cut every line the agent would follow without being told.
+- Write in plain language with the `/plain-language` skill.
 - Mark bold, italics and backticks with the `/emphasise` skill.
 
 ## references/