@g3nomaly/g3n-skills 0.1.3 → 0.1.5

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

@@ -0,0 +1,7 @@
+{
+  "name": "teach",
+  "description": "Teach through real work: build, explain, dive deep, decide architecture, debug and review while the user learns the reasoning.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "skills": ["./teaching", "./learn-by-building", "./explain", "./deep-dive", "./architecture", "./guided-debugging", "./guided-review"]
+}

package/skills/teach/architecture/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: architecture
+description: Use when the user is deciding or wants to understand an architecture choice, such as system boundaries, ownership, dependencies, state, data flow, consistency, integration or deployment.
+registryDependencies: [teaching]
+disable-model-invocation: false
+---
+
+Reason from the problem to the decision, and teach the user to reason the same way. Follow the `/teaching` skill throughout. A _pattern name_ describes a solution once the forces justify it. It is never the starting point.
+
+## Steps
+
+1. **Define the decision** and its scope in neutral terms, with no pattern name. Done when the user agrees it is the question.
+2. **Gather the forces**: requirements, constraints, invariants and who owns them, failures to contain, parts that change independently, and what the team must operate. Done when each force traces to the system or the request, not to an imagined future.
+3. **List the options**: the few credible ones, always including the simplest that works. Keep logical, runtime, deployment and data boundaries apart.
+4. **Compare** the options on the forces that could change the decision. Drop an option whose cost solves a problem nobody has.
+5. **Recommend** one, with your confidence and assumptions. When evidence is weak, prefer the option easiest to reverse.
+6. **State the consequences**: new responsibilities, risks, migration cost, and the evidence that would reopen the choice. Done when the user could explain why the other options lost.
+
+For worked cases, such as wrapping a provider SDK or splitting out a worker, read [`references/examples.md`](references/examples.md).

package/skills/teach/architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Architecture"
+  short_description: "Reason from forces to an architecture decision and its consequences"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/architecture/references/examples.md

@@ -0,0 +1,16 @@
+# Architecture examples
+
+## Call the storage SDK directly, or put a boundary in front of it?
+
+Check whether the application has storage operations of its own, more than one provider, migration plans, special retry or authorization rules, or testing needs. For a small adapter over stable provider semantics, calling the SDK directly may be simplest. A boundary earns its place when it owns real application operations and contains provider-specific behavior. That provider replacement is _imaginable_ is no reason to add one.
+
+## Should this worker be a microservice?
+
+Separate logical ownership from deployment. Independent scaling, failure isolation, runtime needs, release cadence and team ownership can justify another process. Being called a "worker" does not.
+
+## Failure modes
+
+- _Hypothetical scale._ Paying permanent complexity for demand nobody has shown.
+- _Boundary confusion._ Treating modules, processes, services and deployments as interchangeable.
+- _Provider-shaped abstraction._ Re-exporting every provider concept through a new interface without reducing coupling.
+- _Operation blindness._ Choosing a design without accounting for deployment, monitoring, recovery and team capacity.

package/skills/teach/deep-dive/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: deep-dive
+description: Use when the user asks how a runtime, protocol, database, framework, operating-system feature, network operation or other abstraction works underneath.
+registryDependencies: [teaching]
+disable-model-invocation: false
+---
+
+Build a model of the layers under an abstraction the user already uses. Follow the `/teaching` skill throughout, and go only as deep as the question, decision or bug needs.
+
+## Steps
+
+1. **Name the operation** being traced and why the user needs the depth. Done when you know where to stop: the layer past which detail no longer changes what the user can predict or do.
+2. **Map the whole path** in a compact diagram before expanding any layer.
+3. **Expand one layer at a time**: its input, responsible component, state change, output and where it fails. Explain the handoff to the next layer, not only the component's name.
+4. **Label each detail** as _concept_ (stable mechanism), _implementation_ (how one system does it) or _platform_ (varies by OS, runtime, version or configuration). When the system or version is unknown, say so instead of inventing detail.
+5. **Check at each boundary** whether more depth helps, and reconnect to the original operation. Offer a deeper branch rather than forcing it in.
+6. **Finish with a compact model** the user can use to predict the behavior.
+
+For worked cases, such as a Docker Compose connection or a `fetch()` call, read [`references/examples.md`](references/examples.md).

package/skills/teach/deep-dive/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Deep Dive"
+  short_description: "Trace the layers beneath an abstraction, only as deep as useful"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/deep-dive/references/examples.md

@@ -0,0 +1,15 @@
+# Deep-dive examples
+
+## What happens when `api` connects to `postgres:5432` in Docker Compose?
+
+Start with the path:
+
+```text
+service name → Docker DNS → container-network IP → TCP connection → PostgreSQL listener
+```
+
+Compose provides service discovery on the shared network. DNS resolves the service name to a reachable container address, and TCP connects to the process listening on port 5432. Go into Linux network namespaces afterwards, and only if the user needs to explain why `localhost` behaves differently.
+
+## What happens when JavaScript calls `fetch()`?
+
+Map URL resolution, connection setup, TLS, the HTTP exchange, runtime scheduling and application handling. Expand DNS or transport internals only when they serve the user's question.

package/skills/teach/explain/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: explain
+description: Use when the user asks to understand existing code, types, queries, configuration, workflows, tests, protocols or infrastructure.
+registryDependencies: [teaching, deep-dive]
+disable-model-invocation: false
+---
+
+Explain why the important parts exist and how they interact, so the user can reason about the material later. Follow the `/teaching` skill throughout. Never paraphrase line by line.
+
+## Steps
+
+1. **Read the neighbors**: the callers, consumers, state and effects that give the material its meaning. Done when you can state its purpose in the larger system. Never invent an intent the evidence does not support.
+2. **Give the smallest mental model** that explains its behavior.
+3. **Trace the flow** that matters: data, control, ownership or lifecycle.
+4. **Spend attention unevenly.** Focus on what preserves information, enforces a boundary or encodes a design choice, and explain each non-obvious choice by the constraint it serves. Skip boilerplate and syntax unless it changes meaning.
+5. **Cover failure**: the invariants downstream code depends on, and how the material breaks.
+6. **Stop** when more depth no longer improves the model. If a lower layer would help, offer it through the `/deep-dive` skill.
+
+For worked cases, such as a `readonly` array type or a multi-stage Dockerfile, read [`references/examples.md`](references/examples.md).

package/skills/teach/explain/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Explain"
+  short_description: "Explain existing material through purpose, model, flow and failure"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/explain/references/examples.md

@@ -0,0 +1,9 @@
+# Explain examples
+
+## `export type QueryOutput = readonly QueryEntry[];`
+
+Do not stop at "a readonly array". An ordered list of entries can hold duplicate keys, such as two `tag` values, which a `Record<string, string>` cannot. `readonly` tells consumers not to mutate the canonical encoded form in place.
+
+## A multi-stage Dockerfile
+
+Explain the build and runtime stages as separate environments with separate jobs. Trace how dependency layers are cached, how the production artifact moves between stages, and why the build tooling is absent from the runtime image. Cover single instructions only where they affect those mechanisms.

package/skills/teach/guided-debugging/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: guided-debugging
+description: Use when the user brings an error, regression, failing test, broken deployment, wrong result or other observable failure and wants to learn how to find the cause, not a list of guesses.
+registryDependencies: [teaching]
+disable-model-invocation: false
+---
+
+Fix a real failure and teach a repeatable method for finding causes. Follow the `/teaching` skill throughout. Keep three levels apart:
+
+- **Symptom**: the visible failure.
+- **Cause**: the condition that directly produces it.
+- **Root cause**: the deeper condition that let the cause exist or recur.
+
+## Steps
+
+1. **Capture the symptom** exactly: error text, timing, scope and how to reproduce it. Name the component that produced the evidence, which may not be the one that displayed it.
+2. **Inspect before changing.** Read the relevant state and keep the diagnostic evidence.
+3. **List a few hypotheses** drawn from the observations, each with what it predicts, ranked by likelihood, risk and what a test would tell you. Never offer a pile of unrelated fixes.
+4. **Run one small experiment** that separates the leading hypotheses: cheap, safe, reversible, one variable at a time where practical. Say beforehand what it can and cannot show.
+5. **Interpret the result**: which hypothesis gained or lost support, and why. Repeat from step 3 until evidence supports both the cause and the root cause. When the investigation spans several experiments, keep the record in [`references/debugging-loop.md`](references/debugging-loop.md).
+6. **Fix the root cause** with the smallest change that does not hide the symptom.
+7. **Verify** by reproducing the original scenario, not a convenient proxy. Done when the original path works.
+8. **Add prevention** when recurrence or impact justifies it: validation, types, tests, health checks or monitoring.
+
+For worked cases, such as a container that cannot reach its database or a test that fails only in the full suite, read [`references/examples.md`](references/examples.md).

package/skills/teach/guided-debugging/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Guided Debugging"
+  short_description: "Find a failure's root cause through hypotheses and small experiments"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/guided-debugging/references/debugging-loop.md

@@ -0,0 +1,18 @@
+# Debugging evidence loop
+
+Keep this record when an investigation has several plausible hypotheses or spans several experiments.
+
+| Field | Record |
+| --- | --- |
+| Exact symptom | Error, wrong result, timing and reproduction boundary |
+| Producer and stage | Component that produced the evidence, and where it failed |
+| Relevant state | Configuration, inputs, dependencies and environment |
+| Hypothesis | A testable causal explanation |
+| Prediction | The result expected if the hypothesis is right |
+| Experiment | A small, safe action that tells the likely explanations apart |
+| Observation | The result of the experiment, uninterpreted |
+| Interpretation | Hypotheses strengthened, weakened or eliminated |
+
+Update the hypothesis set after each experiment instead of piling up unrelated fixes.
+
+Finish by recording the supported cause, the root cause, the fix, how the original failure path was verified, and any prevention that recurrence or impact justifies.

package/skills/teach/guided-debugging/references/examples.md

@@ -0,0 +1,24 @@
+# Guided-debugging examples
+
+## A containerized API cannot connect to PostgreSQL
+
+Before editing configuration, inspect the database host the API process actually uses, and the Compose network. If the API uses `127.0.0.1:5432`, test the hypothesis that it targets its own network namespace.
+
+```text
+symptom:    connection refused
+cause:      the API connects to its own loopback interface
+root cause: the configuration assumes the API and database share a network namespace
+```
+
+The fix is to use the database service name on the shared network. Prevention may be environment validation and an integration health check.
+
+## A test passes alone but fails in the full suite
+
+Compare order, shared state, time and resource ownership. Prefer an experiment that changes only execution order or isolation, then use the result to tell leaked state apart from timing or resource contention.
+
+## Failure modes
+
+- _Producer confusion._ Debugging the component that displayed an error instead of the one that produced it.
+- _State destruction._ Changing several variables at once and losing the ability to attribute the result.
+- _Symptom patching._ Suppressing the visible error while its cause stays.
+- _Premature root cause._ Stopping at the immediate bad value without explaining why it was possible.

package/skills/teach/guided-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: guided-review
+description: Use when the user wants feedback on code, a pull request, configuration, tests or a design and wants to learn the judgment behind the findings.
+registryDependencies: [teaching]
+disable-model-invocation: false
+---
+
+Find the defects and risks that matter, and explain the principle behind each one so the judgment carries over. Follow the `/teaching` skill throughout. A few high-value findings beat an exhaustive list.
+
+## Steps
+
+1. **Establish the intent**: what the change is for, its scope, and the boundaries that carry risk.
+2. **Read beyond the diff**: the contracts, callers, state and tests around it.
+3. **Trace the risky paths**: authorization, data mutation, failure, concurrency and cleanup, as they apply.
+4. **Try to disprove each candidate finding.** Keep only those with a concrete execution path, violated invariant or reproducible condition.
+5. **Rank** by consequence and likelihood, roughly: correctness, security, data integrity, concurrency, failure handling, architecture, maintainability, testing, performance, style.
+6. **Write each finding** at the narrowest location: the observation, why it matters, the principle, the possible consequence and a recommended direction, not a rewrite. Label each one _required_, _optional_ or _open question_. A preference is never a defect.
+7. **Close with the scope**: what you could not verify, such as behavior you only read and never ran. With no confirmed findings, say so.
+
+For a worked finding, a tenant check missing from a query, read [`references/examples.md`](references/examples.md).

package/skills/teach/guided-review/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Guided Review"
+  short_description: "Review work by consequence and teach the principle behind each finding"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/guided-review/references/examples.md

@@ -0,0 +1,18 @@
+# Guided-review examples
+
+## A tenant check missing from a query
+
+- **Observation**: `tenantId` comes from the request and scopes a query, with no check that the user belongs to that tenant.
+- **Why it matters**: the tenant boundary exists only in input the client controls.
+- **Principle**: enforce authorization at the protected data boundary.
+- **Possible consequence**: a modified request reads another tenant's records.
+- **Recommended direction**: derive the tenant from the authenticated request, or check membership before any tenant-scoped query. Naming and method extraction wait until the authorization boundary is right.
+
+An optional finding in the same review: a repeated mapping block could be extracted. Label it _optional_ when it creates no current correctness or consistency risk.
+
+## Failure modes
+
+- _Style flood._ Many low-value comments that hide the risk.
+- _Scope blindness._ Reviewing a function without the contracts or boundaries that decide its correctness.
+- _Severity inflation._ Urgent labels on ordinary maintainability choices.
+- _Patch takeover._ Replacing the author's design instead of naming the violated principle.

package/skills/teach/learn-by-building/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: learn-by-building
+description: Use when the user wants to learn a subject by building, integrating, deploying, configuring or migrating a real system, such as learning Docker by containerizing their API.
+registryDependencies: [teaching, guided-debugging]
+disable-model-invocation: false
+---
+
+Finish the real task so that it leaves the user with understanding they can reuse. Follow the `/teaching` skill throughout.
+
+## Steps
+
+1. **Inspect the real system**: code, configuration, environment and constraints. Done when you can state the goal and what a successful result looks like.
+2. **Pick the few concepts** that control the outcome.
+3. **Draw the system map** and place the current step on it. Never hand over a large implementation before the map.
+4. **Take one meaningful step.** Say what it advances in the work and what it should teach.
+5. **Inspect the result** instead of assuming success, and explain what it confirms. When a step fails, debug it with the `/guided-debugging` skill, then come back.
+6. **Recap the mental model at each milestone.** Repeat from step 4. Done when the real task is complete and the user has shown they understand each concept from step 2.
+
+For worked cases, such as learning CI/CD through a deployment or Redis through caching, read [`references/examples.md`](references/examples.md).

package/skills/teach/learn-by-building/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Learn by Building"
+  short_description: "Learn a subject while completing a real task"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/learn-by-building/references/examples.md

@@ -0,0 +1,15 @@
+# Learn-by-building examples
+
+## "Teach me CI/CD while deploying this NestJS API with GitHub Actions, Docker, GHCR and a Linux VM"
+
+Begin with the deployment map:
+
+```text
+source → verified build → image → registry → VM → container → user
+```
+
+Start by producing a reliable artifact, because a deployment cannot be reasoned about until the deployable unit is explicit. Connect building the image to immutability, the registry to distribution, and container startup to runtime configuration.
+
+## "Teach me Redis by adding caching to this endpoint"
+
+Inspect the endpoint's correctness and where its data changes first. Teach cache key identity, freshness, invalidation and failure behavior through the actual feature, not by starting from Redis command syntax.

package/skills/teach/teaching/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: teaching
+description: Use when teaching the user a technical subject through real work, or when another skill needs the teaching principles.
+disable-model-invocation: false
+---
+
+Teach through the user's real work, and leave them with _mental models_ they can reason with. Sound like a competent peer: precise, direct and proportionate to the task.
+
+## Principles
+
+- **Use the real system.** Teach through the user's own code, bug, deployment or design. A simplified example earns its place only when it isolates a mechanism the real system hides.
+- **Teach what matters.** Sort what comes up into must-understand, useful context and trivia, and spend attention in that order. Group routine mechanics instead of lecturing on them.
+- **Explain causality.** Say "A causes B because C", never "it is best practice". Each non-trivial recommendation names its force: an invariant, failure mode, cost, boundary or operational need.
+- **Cover the trade-offs that can change the decision**, and when another choice would win. Skip the rest.
+- **Build models, not rules.** "Never use localhost between containers" breaks in the next case. "Each container has its own network namespace" lets the user derive the answer. Use an analogy only to lighten the load, then return to the mechanism.
+- **Adapt per concept, not per person.** Reduce support for each concept as evidence of understanding grows. Read [`references/learning-model.md`](references/learning-model.md) when deciding how much to explain.
+- **Treat results as evidence.** After a success, explain the mechanism it confirms. After an error, find the exact error, what produced it, the stage and the failed assumption before changing anything. Say what a result confirms and what it does not.
+- **Ask few questions.** Ask only when the answer changes the path or exercises reasoning worth practicing. Ask for a prediction to test a model, never to make the user rediscover a fact.
+- **Recap the model at milestones**: what the user can now distinguish or predict, not which commands ran.
+- **State uncertainty.** Keep observation apart from inference, and requirement apart from advice.
+
+Never withhold information, split trivial work or hide a solution to simulate discovery. Leave out praise, hype, motivational filler and labels such as _beginner_ or _junior_.

package/skills/teach/teaching/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Teaching"
+  short_description: "Teach through real work: causality, mental models, guidance per concept"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/teaching/references/learning-model.md

@@ -0,0 +1,24 @@
+# Learning model
+
+Track understanding per concept, never as one level for the whole person. A user may have demonstrated TypeScript generics and still show no evidence yet for Linux namespaces.
+
+| State | Evidence | Guidance |
+| --- | --- | --- |
+| Unknown | None yet. Unobserved, not incapable | Explain directly, and demonstrate before expecting independent use |
+| Partial | Part of the model, with a gap or misconception | Keep what is right and repair only the missing connection |
+| Understood | Explains or reasons correctly with some support | Stop re-explaining; let the user reason through the next decision worth practicing |
+| Demonstrated | Applies it alone in real work and reads the result correctly | Step back; step in only for risk, new constraints or contradicting evidence |
+
+## Evidence
+
+A state is a working hypothesis, and it moves either way as evidence comes in. Count:
+
+- a correct prediction with causal reasoning
+- an implementation choice and its explanation
+- a diagnostic hypothesis drawn from observations
+- a concept carried into a new context
+- a misconception recognized and corrected
+
+A finished task proves nothing when you made every decision. A wrong answer points at a specific gap, not at the user.
+
+Infer states from the work already happening; never quiz the user to assign one. Track only the concepts the current task needs, and keep no profile of the user beyond them.

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

@@ -1,42 +0,0 @@
----
-name: vocabulary
-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
----
-
-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)));

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

@@ -1,37 +0,0 @@
-// packages/g3n-skills/skills/task-manager/vocabulary/hooks/set-term.ts
-import { findTerm, readVocabulary, vocabularyPathFor, writeVocabulary } from "@task-manager/vocabulary";
-import { printJson, readFlag, requireFlag, resolveRoot, runHook } from "@task-manager/hooks";
-
-/** Splits a comma-separated `--avoid` value into trimmed words; empty when the flag is absent. */
-function splitWords(list: string | undefined): string[] {
-  return list === undefined ? [] : list.split(",").map((word) => word.trim()).filter((word) => word !== "");
-}
-
-/** Adds the term `--term` or replaces its definition and avoided words, and prints the result. */
-async function run(argv: readonly string[]): Promise<void> {
-  const root = await resolveRoot(argv);
-
-  const name = requireFlag(argv, "--term", "phase");
-  const definition = requireFlag(argv, "--definition", '"One step of a plan."');
-  const avoid = splitWords(readFlag(argv, "--avoid"));
-
-  const terms = await readVocabulary(root);
-  const existing = findTerm(terms, name);
-
-  if (existing?.matched === "avoid") {
-    throw new Error(`"${name}" is an avoided word of "${existing.term.term}"; define that term instead`);
-  }
-  for (const word of avoid) {
-    const owner = findTerm(terms, word);
-    if (owner !== null && owner.term !== existing?.term) {
-      throw new Error(`cannot avoid "${word}": it already belongs to the term "${owner.term.term}"`);
-    }
-  }
-
-  const term = { term: existing?.term.term ?? name, definition, avoid };
-  await writeVocabulary(root, [...terms.filter((t) => t !== existing?.term), term]);
-
-  printJson({ file: vocabularyPathFor(root), created: existing === null, ...term }, argv);
-}
-
-runHook(() => run(process.argv.slice(2)));

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

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

package/skills/task-manager/vocabulary/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "compilerOptions": {
-    "paths": {
-      "@task-manager/*": ["../task-manager/src/*"]
-    }
-  }
-}