@g3nomaly/g3n-skills 0.1.2 → 0.1.4

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/.claude-plugin/plugin.json

@@ -1,12 +1,11 @@
 {
   "name": "task-manager",
-  "description": "Query and drive a tree of plans, phases and tasks through hooks, with the plan's decisions and the project vocabulary kept beside them.",
+  "description": "Query and drive a tree of plans, phases and tasks through hooks, with the plan's decisions kept beside them.",
   "version": "0.1.0",
   "license": "UNLICENSED",
   "hooks": "./hooks.json",
   "skills": [
     "./task-manager",
-    "./vocabulary",
     "./decisions"
   ]
 }

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/task-manager/hooks/get-entry.ts

@@ -1,9 +1,9 @@
 // packages/g3n-skills/skills/task-manager/task-manager/hooks/get-entry.ts
 import { locateEntry, readEntry } from "../src/filetree";
-import { readVocabulary, termsMentioned } from "../src/vocabulary";
-import { hasFlag, printJson, requireFlag, resolveRoot, runHook } from "../src/hooks";
+import { readGlossary, termsMentioned } from "../src/vocabulary";
+import { hasFlag, printJson, requireFlag, resolveProject, resolveRoot, runHook } from "../src/hooks";
 
-/** Prints the plan, phase or task named by `--id` with its body and the vocabulary terms it mentions. */
+/** Prints the plan, phase or task named by `--id` with its body and the glossary terms it mentions. */
 async function run(argv: readonly string[]): Promise<void> {
   const root = await resolveRoot(argv);
   const name = requireFlag(argv, "--id", "auth-rework");
@@ -19,7 +19,7 @@ async function run(argv: readonly string[]): Promise<void> {
       trail: location.trail,
       meta,
       ...(hasFlag(argv, "--meta-only") ? {} : { body }),
-      vocabulary: termsMentioned(`${meta.title}\n${meta.summary}\n${body}`, await readVocabulary(root)),
+      vocabulary: termsMentioned(`${meta.title}\n${meta.summary}\n${body}`, await readGlossary(resolveProject(argv))),
     },
     argv,
   );

package/skills/task-manager/task-manager/hooks/guard-tree.ts

@@ -104,8 +104,8 @@ async function run(): Promise<void> {
     deny(
       `${target} is inside the task-manager tree, which is read through its hooks. ` +
         "Use get-entry --id <name> for one plan, phase or task in full, next-entry for the " +
-        "front of a queue, list-entries --in <name> to see what a folder holds, get-term --term <word> " +
-        "for the vocabulary, or list-decisions --in <plan> for a plan's decisions.",
+        "front of a queue, list-entries --in <name> to see what a folder holds, or list-decisions " +
+        "--in <plan> for a plan's decisions.",
     );
   }
 }

package/skills/task-manager/task-manager/hooks/next-entry.ts

@@ -1,8 +1,8 @@
 // packages/g3n-skills/skills/task-manager/task-manager/hooks/next-entry.ts
 import { ENTRY_TYPE, listEntryNames, readEntry, resolveParent } from "../src/filetree";
 import type { TaskStatus } from "../src/schemas";
-import { readVocabulary, termsMentioned } from "../src/vocabulary";
-import { hasFlag, printJson, readFlag, resolveRoot, runHook } from "../src/hooks";
+import { readGlossary, termsMentioned } from "../src/vocabulary";
+import { hasFlag, printJson, readFlag, resolveProject, resolveRoot, runHook } from "../src/hooks";
 
 const FINISHED: readonly TaskStatus[] = ["completed"];
 const NOT_WORKABLE: readonly TaskStatus[] = ["completed", "blocked"];
@@ -20,7 +20,7 @@ async function run(argv: readonly string[]): Promise<void> {
     const { file, meta, body } = await readEntry(dir, level, name);
     if (skipped.includes(meta.status)) continue;
 
-    const vocabulary = termsMentioned(`${meta.title}\n${meta.summary}\n${body}`, await readVocabulary(root));
+    const vocabulary = termsMentioned(`${meta.title}\n${meta.summary}\n${body}`, await readGlossary(resolveProject(argv)));
 
     printJson({ type: ENTRY_TYPE[level], name, file, meta, body, vocabulary }, argv);
     return;

package/skills/task-manager/task-manager/references/hooks.md

@@ -16,7 +16,7 @@ JSON on stdout, messages on stderr.
 
 - `next-entry` and `get-entry` return one entry; none found exits `1`.
 - `list-entries` and `cleanup` return a list; `[]` exits `0`.
-- `get-entry` and `next-entry` attach a `vocabulary` array: the terms the entry mentions.
+- `get-entry` and `next-entry` attach a `vocabulary` array: the terms of `docs/glossary.md` the entry mentions.
 - `set-state`, `cleanup` and `sync-tree` write; the others only read.
 
 ## Fired by the plugin

package/skills/task-manager/task-manager/references/tree.md

@@ -3,7 +3,6 @@
 ```
 <filetreeRoot>/                    # skills.settings.filetreeRoot, default docs/task-manager
 ├── root-index.json
-├── vocabulary.md
 └── <plan>/
     ├── <plan>.md
     ├── plan-index.json

package/skills/task-manager/task-manager/src/hooks/cli.ts

@@ -82,7 +82,17 @@ export async function resolveRoot(argv: readonly string[]): Promise<string> {
   const override = readFlag(argv, "--root");
   if (override !== undefined) return resolve(override);
 
-  return resolveFiletreeRoot(resolve(readFlag(argv, "--project") ?? process.cwd()));
+  return resolveFiletreeRoot(resolveProject(argv));
+}
+
+/**
+ * @brief Resolves the project the hook works in: `--project`, or the working directory.
+ *
+ * @param argv - Arguments of the hook.
+ * @returns Absolute project root.
+ */
+export function resolveProject(argv: readonly string[]): string {
+  return resolve(readFlag(argv, "--project") ?? process.cwd());
 }
 
 /** Reads everything piped to the hook on stdin, or returns `""` when run from a terminal. */

package/skills/task-manager/task-manager/src/hooks/index.ts

@@ -1,3 +1,3 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/hooks/index.ts
-export { readFlag, requireFlag, hasFlag, oneOf, resolveRoot, readStdin, printJson, runHook } from "./cli";
+export { readFlag, requireFlag, hasFlag, oneOf, resolveRoot, resolveProject, readStdin, printJson, runHook } from "./cli";
 export type { Hook } from "./cli";

package/skills/task-manager/task-manager/src/schemas/index.ts

@@ -32,8 +32,8 @@ export {
 } from "./decision";
 export type { DecisionStatus, Decision, DecisionIndex } from "./decision";
 
-export { TermSchema, VocabularySchema } from "./term";
-export type { Term, Vocabulary } from "./term";
+export { TermSchema, GlossarySchema } from "./term";
+export type { Term, Glossary } from "./term";
 
 export { CONFIG_FILE, DEFAULT_FILETREE_ROOT, FiletreeConfigSchema } from "./config";
 export type { FiletreeConfig } from "./config";

package/skills/task-manager/task-manager/src/schemas/term.ts

@@ -1,38 +1,25 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/schemas/term.ts
 import { z } from "zod";
 
-/** One line of text that cannot be mistaken for a Markdown heading. */
-const TermNameSchema = z
-  .string()
-  .regex(/^[^\s#][^\n]*$/, "must be a single line that does not start with # or a space");
-
-/** One entry of `vocabulary.md`: the word to use, what it means, and the words it replaces. */
+/** One term of `docs/glossary.md`: the word to use, what it means, and the words it replaces. */
 export const TermSchema = z.strictObject({
-  term: TermNameSchema,
-  definition: z
-    .string()
-    .min(1)
-    .refine(
-      (text) => !text.split("\n").some((line) => line.startsWith("#") || line.startsWith("_Avoid_:")),
-      "must not contain a line starting with # or _Avoid_:",
-    ),
-  avoid: z
-    .array(TermNameSchema.refine((word) => !word.includes(","), "must not contain a comma"))
-    .default([]),
+  term: z.string().min(1),
+  definition: z.string(),
+  avoid: z.array(z.string().min(1)).default([]),
 });
 
 /**
- * One entry of `vocabulary.md`, as `TermSchema` parses it.
+ * One term of `docs/glossary.md`, as `TermSchema` parses it.
  *
  * @property term - The word to use.
- * @property definition - What the term means, as written under its heading.
+ * @property definition - What the term means, as written below its name.
  * @property avoid - Words that mean the same thing and must not be used in its place.
  */
 export type Term = z.infer<typeof TermSchema>;
 
-export const VocabularySchema = z.strictObject({
+export const GlossarySchema = z.strictObject({
   terms: z.array(TermSchema).default([]),
 });
 
-/** Every term of `vocabulary.md`, as `VocabularySchema` parses it. */
-export type Vocabulary = z.infer<typeof VocabularySchema>;
+/** Every term of `docs/glossary.md`, as `GlossarySchema` parses it. */
+export type Glossary = z.infer<typeof GlossarySchema>;

package/skills/task-manager/task-manager/src/vocabulary/file.ts

@@ -1,114 +1,70 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/vocabulary/file.ts
 import { join } from "node:path";
 import { FileValidationError, parseFile } from "../schemas/validation";
-import { VocabularySchema, type Term } from "../schemas/term";
+import { GlossarySchema, type Term } from "../schemas/term";
 
-/** File at the tree root holding every term. Written by the term hooks only. */
-export const VOCABULARY_FILE = "vocabulary.md";
+/** File holding every term, relative to the project root. Written by hand, as the `vocabulary` skill describes. */
+export const GLOSSARY_FILE = join("docs", "glossary.md");
 
-const TITLE = "# Vocabulary";
-const TERM_HEADING = "## ";
-const AVOID_PREFIX = "_Avoid_:";
+/** `**Phase**:` or `**Phase:**`, optionally followed by the start of the definition. */
+const TERM_LINE = /^\*\*(.+?):?\*\*:?\s*(.*)$/;
+/** `_Avoid_: stage, milestone` */
+const AVOID_LINE = /^_Avoid_:\s*(.*)$/i;
 
 /**
- * @brief Builds the path of the vocabulary file in a tree.
+ * @brief Reads every term of the project's glossary, in the order they sit in the file.
  *
- * @param root - Absolute tree root folder.
- * @returns Path of `vocabulary.md` inside `root`.
- */
-export function vocabularyPathFor(root: string): string {
-  return join(root, VOCABULARY_FILE);
-}
-
-/**
- * @brief Reads every term of the tree at `root`, in the order they sit in the file.
+ * Text that is not part of a term, such as the title, the intro and the group headings, is skipped.
  *
- * @param root - Absolute tree root folder.
- * @returns Terms in file order, or an empty list when there is no vocabulary file yet.
- * @throws FileValidationError when the file strays from the layout
- *   `writeVocabulary` produces, or names one term twice
+ * @param projectRoot - Absolute folder holding `docs/glossary.md`.
+ * @returns Terms in file order, or an empty list when the project has no glossary.
+ * @throws FileValidationError when one term is defined twice.
  */
-export async function readVocabulary(root: string): Promise<Term[]> {
-  const file = vocabularyPathFor(root);
+export async function readGlossary(projectRoot: string): Promise<Term[]> {
+  const file = join(projectRoot, GLOSSARY_FILE);
   if (!(await Bun.file(file).exists())) return [];
 
-  const terms = parseFile(VocabularySchema, file, { terms: parseTerms(file, await Bun.file(file).text()) }).terms;
+  const terms = parseFile(GlossarySchema, file, { terms: parseTerms(await Bun.file(file).text()) }).terms;
   rejectDuplicates(file, terms);
 
   return terms;
 }
 
 /**
- * @brief Replaces the vocabulary file with `terms`, sorted by name so the file reads the same on every write.
+ * @brief Splits the glossary text into raw terms, one per bold term line.
  *
- * @param root - Absolute tree root folder.
- * @param terms - Terms to write; validated and checked for duplicate names first.
- */
-export async function writeVocabulary(root: string, terms: readonly Term[]): Promise<void> {
-  const file = vocabularyPathFor(root);
-  const validated = parseFile(VocabularySchema, file, { terms }).terms;
-  rejectDuplicates(file, validated);
-
-  const sorted = [...validated].sort(
-    (a, b) => a.term.localeCompare(b.term, "en", { sensitivity: "base" }) || a.term.localeCompare(b.term),
-  );
-
-  await Bun.write(file, `${[TITLE, ...sorted.map(renderTerm)].join("\n\n")}\n`);
-}
-
-/**
- * @brief Renders one term as its `## ` block in the vocabulary file.
+ * A term runs until the next term line or heading. Its `_Avoid_:` line is its avoid list, the rest its definition.
  *
- * @param term - Term to render.
+ * @param text - Full text of the glossary.
+ * @returns One raw term per bold term line, ready for `parseFile`.
  */
-function renderTerm(term: Term): string {
-  const lines = [`${TERM_HEADING}${term.term}`, "", term.definition.trim()];
-  if (term.avoid.length > 0) lines.push("", `${AVOID_PREFIX} ${term.avoid.join(", ")}`);
-
-  return lines.join("\n");
-}
-
-/**
- * @brief Splits the file text at its `## ` headings into raw term entries.
- *
- * The last `_Avoid_:` line of a block is its avoid list.
- *
- * @param file - Path of the file, used in the error message.
- * @param text - Full text of the vocabulary file.
- * @returns One raw entry per heading, ready for `parseFile`.
- * @throws FileValidationError when text sits above the first heading.
- */
-function parseTerms(file: string, text: string): unknown[] {
-  const terms: { term: string; lines: string[] }[] = [];
-
-  text.split("\n").forEach((line, index) => {
-    if (line.startsWith(TERM_HEADING)) {
-      terms.push({ term: line.slice(TERM_HEADING.length).trim(), lines: [] });
-      return;
+function parseTerms(text: string): unknown[] {
+  const terms: { term: string; lines: string[]; avoid: string[] }[] = [];
+  let open = false;
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#")) {
+      open = false;
+      continue;
     }
 
-    const current = terms.at(-1);
-    if (current !== undefined) {
-      current.lines.push(line);
-      return;
+    const termMatch = TERM_LINE.exec(trimmed);
+    if (termMatch) {
+      terms.push({ term: (termMatch[1] ?? "").trim(), lines: [termMatch[2] ?? ""], avoid: [] });
+      open = true;
+      continue;
     }
 
-    if (line.trim() !== "" && line.trim() !== TITLE) {
-      throw new FileValidationError(file, [
-        { field: `line ${index + 1}`, message: `"${line}" sits above the first ${TERM_HEADING.trim()} heading` },
-      ]);
-    }
-  });
+    const current = terms.at(-1);
+    if (!open || current === undefined) continue;
 
-  return terms.map(({ term, lines }) => {
-    const avoidAt = lines.map((line) => line.startsWith(AVOID_PREFIX)).lastIndexOf(true);
-    const avoid = avoidAt === -1
-      ? []
-      : (lines[avoidAt] ?? "").slice(AVOID_PREFIX.length).split(",").map((word) => word.trim()).filter((word) => word !== "");
-    const definition = lines.filter((_, index) => index !== avoidAt).join("\n").trim();
+    const avoidMatch = AVOID_LINE.exec(trimmed);
+    if (avoidMatch) current.avoid = (avoidMatch[1] ?? "").split(",").map((word) => word.trim()).filter((word) => word !== "");
+    else current.lines.push(line);
+  }
 
-    return { term, definition, avoid };
-  });
+  return terms.map(({ term, lines, avoid }) => ({ term, definition: lines.join("\n").trim(), avoid }));
 }
 
 /**

package/skills/task-manager/task-manager/src/vocabulary/index.ts

@@ -1,5 +1,5 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/vocabulary/index.ts
-export { VOCABULARY_FILE, vocabularyPathFor, readVocabulary, writeVocabulary } from "./file";
+export { GLOSSARY_FILE, readGlossary } from "./file";
 
-export { findTerm, termsMentioned } from "./match";
-export type { TermMatch, TermMention } from "./match";
+export { termsMentioned } from "./match";
+export type { TermMention } from "./match";

package/skills/task-manager/task-manager/src/vocabulary/match.ts

@@ -1,22 +1,11 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/vocabulary/match.ts
 import type { Term } from "../schemas/term";
 
-/**
- * Term found by `findTerm`, with how the name matched it.
- *
- * @property term - The matched term.
- * @property matched - `"term"` when the name is the term itself, `"avoid"` when it is one of the term's avoided words.
- */
-export interface TermMatch {
-  term: Term;
-  matched: "term" | "avoid";
-}
-
 /**
  * Term a text uses, with the avoided words the text used for it.
  *
  * @property term - Name of the term.
- * @property definition - Definition of the term, as the vocabulary file holds it.
+ * @property definition - Definition of the term, as the glossary holds it.
  * @property avoided - Avoided words the text uses in place of `term`.
  */
 export interface TermMention {
@@ -25,26 +14,6 @@ export interface TermMention {
   avoided: string[];
 }
 
-/** Tells whether two words are equal, ignoring case. */
-function sameWord(a: string, b: string): boolean {
-  return a.toLowerCase() === b.toLowerCase();
-}
-
-/**
- * @brief Finds the term that answers to `name`, by its own name first and by an avoided word second.
- *
- * @param terms - Vocabulary to search.
- * @param name - Word to look up, compared ignoring case.
- * @returns The match, or `null` when no term has the name.
- */
-export function findTerm(terms: readonly Term[], name: string): TermMatch | null {
-  const own = terms.find((term) => sameWord(term.term, name));
-  if (own !== undefined) return { term: own, matched: "term" };
-
-  const replaced = terms.find((term) => term.avoid.some((word) => sameWord(word, name)));
-  return replaced === undefined ? null : { term: replaced, matched: "avoid" };
-}
-
 /** Tells whether `word` occurs in `text` as a whole word, ignoring case. */
 function mentions(text: string, word: string): boolean {
   const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -54,10 +23,10 @@ function mentions(text: string, word: string): boolean {
 /**
  * @brief Finds the terms `text` uses, by name or by an avoided word, in the order of `terms`.
  *
- * Used by the `get-entry` hook, which attaches each mention to its entry.
+ * Used by the `get-entry` and `next-entry` hooks, which attach each mention to its entry.
  *
  * @param text - Text to search, such as an entry's title, summary and body.
- * @param terms - Vocabulary to search.
+ * @param terms - Glossary to search.
  * @returns One mention per term the text uses.
  */
 export function termsMentioned(text: string, terms: readonly Term[]): TermMention[] {

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/

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

@@ -1,42 +0,0 @@
----
-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.
-
-Its hooks are scripts in its own `hooks/` folder, run as `bun <vocabulary-dir>/hooks/<hook>.ts`, where `<vocabulary-dir>` is this skill's base directory: the folder holding this `SKILL.md`.
-
-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/skills/task-manager/vocabulary/agents/openai.yaml

@@ -1,5 +0,0 @@
-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/skills/task-manager/vocabulary/hooks/get-term.ts

@@ -1,18 +0,0 @@
-// packages/g3n-skills/skills/task-manager/vocabulary/hooks/get-term.ts
-import { findTerm, readVocabulary } from "@task-manager/vocabulary";
-import { printJson, requireFlag, resolveRoot, runHook } from "@task-manager/hooks";
-
-/** Prints the term `--term` names, found by its name or by one of its avoided words. */
-async function run(argv: readonly string[]): Promise<void> {
-  const root = await resolveRoot(argv);
-  const name = requireFlag(argv, "--term", "phase");
-
-  const match = findTerm(await readVocabulary(root), name);
-  if (match === null) {
-    throw new Error(`"${name}" is not in the vocabulary, as a term or as an avoided word`);
-  }
-
-  printJson({ ...match.term, matched: match.matched }, argv);
-}
-
-runHook(() => run(process.argv.slice(2)));

package/skills/task-manager/vocabulary/hooks/list-terms.ts

@@ -1,12 +0,0 @@
-// packages/g3n-skills/skills/task-manager/vocabulary/hooks/list-terms.ts
-import { readVocabulary } from "@task-manager/vocabulary";
-import { printJson, resolveRoot, runHook } from "@task-manager/hooks";
-
-/** Prints every term in the vocabulary. */
-async function run(argv: readonly string[]): Promise<void> {
-  const root = await resolveRoot(argv);
-
-  printJson(await readVocabulary(root), argv);
-}
-
-runHook(() => run(process.argv.slice(2)));

package/skills/task-manager/vocabulary/hooks/remove-term.ts

@@ -1,22 +0,0 @@
-// packages/g3n-skills/skills/task-manager/vocabulary/hooks/remove-term.ts
-import { findTerm, readVocabulary, vocabularyPathFor, writeVocabulary } from "@task-manager/vocabulary";
-import { printJson, requireFlag, resolveRoot, runHook } from "@task-manager/hooks";
-
-/** Removes the term named by `--term` from the vocabulary and prints it. */
-async function run(argv: readonly string[]): Promise<void> {
-  const root = await resolveRoot(argv);
-  const name = requireFlag(argv, "--term", "phase");
-
-  const terms = await readVocabulary(root);
-  const match = findTerm(terms, name);
-
-  if (match === null || match.matched !== "term") {
-    throw new Error(`"${name}" is not a term in the vocabulary`);
-  }
-
-  await writeVocabulary(root, terms.filter((term) => term !== match.term));
-
-  printJson({ file: vocabularyPathFor(root), removed: match.term }, argv);
-}
-
-runHook(() => run(process.argv.slice(2)));