@g3nomaly/g3n-skills 0.1.0 → 0.1.2

package/.claude-plugin/marketplace.json

@@ -16,10 +16,11 @@
     {
       "name": "coding",
       "source": "./skills/coding",
-      "description": "How to write, check and document code, per language.",
+      "description": "How to write, check and document code, per language, and query a repository with analyze.",
       "skills": [
         "./code",
-        "./document"
+        "./document",
+        "./analyze"
       ]
     },
     {

package/README.md

@@ -0,0 +1,96 @@
+# @g3nomaly/g3n-skills
+
+The g3n skills for Claude Code and Codex: 28 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 its home branch and land it with a local squash merge |
+| `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 |
+| `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 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.0",
+  "version": "0.1.2",
   "description": "The g3n skills, each with its own hooks: a skill source for @g3nomaly/skills and a Claude Code plugin marketplace.",
   "type": "module",
   "files": [

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

@@ -1,7 +1,7 @@
 {
   "name": "coding",
-  "description": "How to write, check and document code, per language.",
+  "description": "How to write, check and document code, per language, and query a repository with analyze.",
   "version": "0.1.0",
   "license": "UNLICENSED",
-  "skills": ["./code", "./document"]
+  "skills": ["./code", "./document", "./analyze"]
 }

package/skills/coding/analyze/SKILL.md

@@ -0,0 +1,32 @@
+---
+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.
+---
+
+`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`.
+
+## Query
+
+1. **Find** the node: `search <words>`. It matches names first, then meaning. Done when a hit's `id` names what you want.
+2. **Read** it: `show <id>`. Text, signature, parameters, fields and every edge.
+3. **Follow** its edges: `refs <id>`. Add `--incoming` for what uses it, `--outgoing` for what it uses, `--edge <kind>` to keep one kind, such as `type` or `affects`.
+4. **Narrow** any of these with `--kind`, `--section` and `-n`. `list --kind <kind>` lists every node of a kind.
+
+Add `--json` when a script reads the output. A `<node>` may be an `id`, a file path or a name; a name that fits several nodes prints the candidates.
+
+A _member_, a parameter, field, operation or definition, is found by search but returns its _owner_: the function, the type or the file. Its exact `id` opens the member itself.
+
+Flags, kinds and edge kinds: [`references/commands.md`](references/commands.md).
+
+## Update
+
+- **Queries rescan by themselves.** The scan is cached in `analyze_out/cache/` and redone when a file changes. `--no-cache` forces it.
+- **Rebuild the site** with `create_docs`. It writes `analyze_out/index.html` and nothing else.
+- **Change what is scanned** in `.analyzeignore` at the root, written with the defaults on the first run. `--exclude <glob>` skips more for one run.
+- **Never edit `analyze_out/`.** It is output.
+
+What makes a repository show more, such as glossaries, decisions and doc tags: [`references/repository.md`](references/repository.md).
+
+## From code
+
+Hooks and scripts call the same queries as a typed library, without the CLI: [`references/api.md`](references/api.md).

package/skills/coding/analyze/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Analyze"
+  short_description: "Query and rebuild the linked model of a repository with g3n-analyze"
+policy:
+  allow_implicit_invocation: true

package/skills/coding/analyze/references/api.md

@@ -0,0 +1,27 @@
+# Library
+
+`@g3nomaly/analyze` exports the queries as functions. They take the CLI options as fields, never print, and throw `OptionsError`, `QueryError` or `SourceError`.
+
+```ts
+import { createDocs, list, refs, search, show } from '@g3nomaly/analyze';
+
+const repo = '/home/me/app';
+const { hits } = await search({ repo, query: 'route price', limit: 5 });
+const node = await show({ repo, target: hits[0].id });
+const users = await refs({ repo, target: 'choose_route', incoming: true, edges: ['type'] });
+const tasks = await list({ repo, kinds: ['task'] });
+await createDocs({ repo });
+```
+
+| Field | Functions | CLI flag |
+|---|---|---|
+| `repo`, `skillDirs`, `docDirs`, `excludes`, `embeddings` | all | `--repo`, `--skills`, `--docs`, `--exclude`, `--no-embeddings` |
+| `from`, `cache` | queries | `--from`, `--no-cache` |
+| `kinds`, `section` | queries | `--kind`, `--section` |
+| `query`, `by`, `limit` | `search` | `<query>`, `--by`, `-n` |
+| `target` | `show`, `refs` | `<node>` |
+| `incoming`, `outgoing`, `edges` | `refs` | `--incoming`, `--outgoing`, `--edge` |
+| `title` | `createDocs` | `--title` |
+| `onWarning` | all | — |
+
+Warnings go to `onWarning` and are dropped without it.

package/skills/coding/analyze/references/commands.md

@@ -0,0 +1,54 @@
+# Commands
+
+| Command | Does |
+|---|---|
+| `create_docs` | Writes `analyze_out/index.html`, one offline HTML file |
+| `search <query>` | Finds nodes by words and by meaning |
+| `show <node>` | Prints one node in full |
+| `refs <node>` | Lists its edges, both ways |
+| `list` | Lists nodes in display order |
+
+## Flags
+
+| Flag | Commands | Does |
+|---|---|---|
+| `--repo <dir>` | all | Repository to read. Default: the working directory |
+| `--skills <dir>`, `--docs <dir>` | all | Read skills or docs from this directory only. Repeatable |
+| `--exclude <glob>` | all | Skip matching paths. Repeatable |
+| `--no-embeddings` | all | No search by meaning |
+| `--title <text>` | `create_docs` | Site title |
+| `--from <file>` | queries | Query a built `index.html` instead of scanning |
+| `--no-cache` | queries | Scan again even when nothing changed |
+| `--json` | queries | JSON instead of text |
+| `--kind <kind>` | queries | Only this kind. Repeatable |
+| `--section <name>` | queries | `skills`, `docs`, `code`, `database` or `tasks` |
+| `-n, --limit <n>` | `search`, `list` | Most results |
+| `--by <way>` | `search` | `name`, `meaning` or `both` |
+| `--incoming`, `--outgoing` | `refs` | One direction only |
+| `--edge <kind>` | `refs` | Only this edge kind. Repeatable |
+
+Each flag has an `ANALYZE_*` variable, such as `ANALYZE_REPO`. A flag wins over its variable.
+
+## Kinds
+
+- **Structure**: `folder`, `package`, `file`
+- **Code**: `namespace`, `class`, `interface`, `struct`, `enum`, `trait`, `type`, `function` (methods included)
+- **Docs and data**: `term`, `decision`, `table`, `query`
+- **Tasks**: `plan`, `phase`, `task`
+- **Members**, returned as their owner: `operation`, `definition`, `parameter`, `field`
+
+The JSON of a node has its `kind` and its `type`, the finer sort, such as `method` or `api`.
+
+## Edge kinds
+
+| Edge | From → to |
+|---|---|
+| `type` | parameter or field → its type |
+| `returns`, `throws` | function → type it returns or throws |
+| `extends` | type → type it extends or implements |
+| `mentions` | page or description → node it links to |
+| `uses` | text → glossary term |
+| `affects` | decision → node it is about |
+| `references` | table → table of its foreign key |
+| `reads`, `writes` | query → table |
+| `names`, `depends` | plan, phase or task → node it names, task it waits for |

package/skills/coding/analyze/references/repository.md

@@ -0,0 +1,13 @@
+# What analyze reads
+
+| Shows as | Write |
+|---|---|
+| **Skill** | A `SKILL.md` inside an AI directory: `.claude`, `.codex`, `.cursor`, `.gemini`, `.agents`, `.windsurf`, `.opencode`. Elsewhere it is a doc |
+| **Package** | A directory with a manifest: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `composer.json`, `.csproj`, `.gemspec`, `Gemfile`. A declared executable makes it an app |
+| **Glossary** | A `glossary.md`. Each term is a node, and its first use in any text links to it |
+| **Decisions** | A `decisions.md`. Each decision is a node; a link or inline code in it that names a node becomes an `affects` edge |
+| **Code docs** | Doc comments. `@param`, `@returns`, `@throws` and `@property` attach to the parameter, return value, error and field |
+| **Database** | `.sql` files. One with `CREATE TABLE` is a schema, any other a query |
+| **Tasks** | The task-manager tree in `docs/task-manager`, or the directory `.g3n.config.json` names |
+
+Inline code that names a type or function, such as `` `choose_route` ``, links to it from any text.

package/skills/coding/document/SKILL.md

@@ -4,33 +4,50 @@ description: Docstrings and comments for functions and classes, and where the re
 disable-model-invocation: false
 ---
 
-Documentation describes the code as it is now: _what_ it does and _how_. The _why_ goes in `decisions.md`.
+Documentation describes _what_ code does and _how_. The _why_ goes in `decisions.md`.
+
+These rules apply to existing docstrings too. **Rewrite docstrings that breaks them when applicable**, and never copy the style of one that does.
 
 ## Files
 
-Line 1 of every file is a comment with its relative path, such as `// path/to/file.ts`. No file-level docstring.
+Line 1 of every file is a comment with its relative path. No file-level docstring.
+
+## Docstrings
+
+Functions, classes and other type declarations get a docstring; the language reference lists which. **A property, field or enum member is a tag in the docstring of its owner**, not a docstring of its own. 
+
+A _tag_ is a marked line in a docstring that documents one thing, such as `@param` in TypeScript.
+
+**What a tag can say goes in the docstring, never in a code comment.** Any tag the language has is fine.
 
 ## Functions
 
-Every function gets a docstring that says what it does in one or two sentences.
+The function its docstring is declarative of _what_ / _how_ it works. Use @brief to summarize the function in one line or two lines.
 
-`@param` and `@returns` important. Add one when the type alone hides the meaning, such as the form of an id, whether a path is absolute or relative to what, the unit of a number, or when the result can be empty. Leave them out when the name and the types already make it clear.
+Tag a parameter or the return value when its name and type hide the meaning. Custom types are always tagged.
 
 ## Classes
 
 A class docstring says:
 
-- what the class does and what it holds,
-- where it is used: the modules that create it and the ones that consume it,
-- how to create one, as an `@example`, when the constructor takes more than the obvious.
+- what it does and holds,
+- which modules create and consume it,
+- how to create one.
+
+## Other types
+
+The summary says what the type _holds_. Tag its properties under the same rule as function parameters.
 
 ## Comments
 
-An inline comment explains how a piece of code works when the code itself does not show it. Use sparingly! 
+An inline comment explains how code works when neither the code nor a tag shows it. Use sparingly!
 
 ## Decisions
 
-The reason code is the way it is goes in `decisions.md` as an entry. Decisions are never written directly in the code.
+A decision is a choice **the user** made, with its _why_, never the _how_. A choice made while implementing is not one.
+
+- **Never add an entry without the user's explicit approval.**
+- Decisions are never written in the code.
 
 ## Languages
 

package/skills/coding/document/references/typescript.md

@@ -1,6 +1,10 @@
 # TypeScript
 
-TSDoc: a `/** */` block directly above the declaration. The first sentence is the summary. Tags are `@param name - text` and `@returns text`.
+TSDoc: a `/** */` block directly above the declaration.
+
+- **Declarations with a docstring**: functions, classes, interfaces, type aliases and enums.
+- **Summary**: `/** Adds two numbers. */` on one line. A longer block opens with `@brief` and the summary.
+- **Tags**: `@param name - text`, `@returns text`, and for the members of a class, interface, type or enum `@param name - text` or `@property name - text`. Any other TSDoc tag that fits is fine: `@throws {Type} When ...`, `@example`, `@see`, `@deprecated`.
 
 ```ts
 /** Adds two numbers. */
@@ -45,9 +49,20 @@ export class FileValidationError extends Error {
     // ...
   }
 }
-```
 
-Exported types and interfaces get a one-line docstring. A field gets its own `/** */` line only when its name and type leave its meaning open.
+/**
+ * @brief Entries a set of requests resolved to, and the requests that did not resolve.
+ *
+ * @property entries - Resolved entries by key, e.g. `emphasise`.
+ * @property unknown - Requests no source offers, e.g. `ghost@mine`.
+ * @property notes - Why an entry nobody named is in the set, e.g. `{ vocabulary: "dep of plan" }`.
+ */
+export interface Resolution {
+  entries: Map<string, SourceOffer>;
+  unknown: string[];
+  notes: Record<string, string>;
+}
+```
 
 ## Bad
 
@@ -84,6 +99,32 @@ export function add(a: number, b: number): number
 ```
 The tags repeat the signature. The summary line is enough.
 
+```ts
+/** Entries one request names. */
+function matchRequest(request: EntryRequest, offers: readonly SourceOffer[]): Match
+```
+A noun phrase that names the result, and no tags. The summary says what the function does: _Finds the entries one request names_. `EntryRequest`, `SourceOffer` and `Match` are custom types, so `request`, `offers` and the return value each need a tag.
+
+```ts
+/** Entries a set of requests resolved to. */
+export interface Resolution {
+  /** Resolved entries by key. */
+  entries: Map<string, SourceOffer>;
+  /** Requests no source offers. */
+  unknown: string[];
+}
+```
+A docstring on each property. Properties go in the interface's docstring as `@property` tags, as in `Resolution` above.
+
+```ts
+/**
+ * Resolves the dependencies of one entry against every offer.
+ *
+ * @param preferred - Source to take a key from when several offer it.
+ */
+```
+More than one line without `@brief`. It opens with `@brief Resolves the dependencies...`.
+
 ```ts
 /** Loads a user by id. Uses a surrogate key because auth ids changed format in 2024. */
 ```

package/skills/task-manager/decisions/src/paths.ts

@@ -3,11 +3,23 @@ import { join } from "node:path";
 import { DECISIONS_DIR } from "@task-manager/schemas/decision";
 import { MARKDOWN } from "@task-manager/filetree/levels";
 
-/** Folder holding a plan's decision files. */
+/**
+ * @brief Finds the folder holding a plan's decision files.
+ *
+ * @param planDir - Plan folder.
+ * @returns Path of the plan's `decisions/` folder.
+ */
 export function decisionsDirFor(planDir: string): string {
   return join(planDir, DECISIONS_DIR);
 }
 
+/**
+ * @brief Builds the path of one decision file in a plan.
+ *
+ * @param planDir - Plan folder.
+ * @param id - File name without extension, e.g. `0001-use-jwt`.
+ * @returns Path of the `<id>.md` file.
+ */
 export function decisionPathFor(planDir: string, id: string): string {
   return join(decisionsDirFor(planDir), `${id}${MARKDOWN}`);
 }

package/skills/task-manager/decisions/src/read.ts

@@ -6,14 +6,25 @@ import { MARKDOWN } from "@task-manager/filetree/levels";
 import { readDocument } from "@task-manager/filetree/frontmatter";
 import { decisionPathFor, decisionsDirFor } from "./paths";
 
-/** One decision as it sits on disk: where it was read from, its fields, its prose. */
+/**
+ * @brief Holds one decision as it sits on disk: where it was read from, its fields, its prose.
+ *
+ * @property file - Path of the decision's Markdown file.
+ * @property meta - Fields from the frontmatter, checked against `DecisionSchema`.
+ * @property body - Prose after the closing fence of the frontmatter.
+ */
 export interface DecisionDocument {
   file: string;
   meta: Decision;
   body: string;
 }
 
-/** Ids of a plan's decisions, in numbered order. A plan with no `decisions/` folder has none. */
+/**
+ * @brief Lists the ids of a plan's decisions, in numbered order.
+ *
+ * @param planDir - Plan folder holding the `decisions/` folder.
+ * @returns File names without extension; none when the plan has no `decisions/` folder.
+ */
 export async function listDecisionIds(planDir: string): Promise<string[]> {
   let files;
 
@@ -31,11 +42,14 @@ export async function listDecisionIds(planDir: string): Promise<string[]> {
 }
 
 /**
- * Reads one decision of a plan and checks it against its schema.
+ * @brief Reads one decision of a plan and checks it against its schema.
  *
- * @param id file name without extension, e.g. `0001-use-jwt`
- * @throws FileValidationError when a field fails its schema, or when the `id`
- *   inside the file disagrees with the file it was read from
+ * @param planDir - Plan folder holding the `decisions/` folder.
+ * @param id - File name without extension, e.g. `0001-use-jwt`.
+ * @returns The decision's path, its validated fields and its prose.
+ * @throws {Error} When no decision file has that `id`.
+ * @throws {FileValidationError} When a field fails its schema, or when the `id`
+ *   inside the file disagrees with the file it was read from.
  */
 export async function readDecision(planDir: string, id: string): Promise<DecisionDocument> {
   const file = decisionPathFor(planDir, id);

package/skills/task-manager/decisions/src/write.ts

@@ -6,15 +6,28 @@ import { setStatusLine } from "@task-manager/filetree/status";
 import { decisionPathFor, decisionsDirFor } from "./paths";
 import { listDecisionIds, readDecision, type DecisionDocument } from "./read";
 
-/** What `addDecision` needs from its caller; the id and date are worked out here. */
+/**
+ * @brief Holds what `addDecision` needs from its caller; the id and date are worked out in `addDecision`.
+ *
+ * @property title - Title of the decision, also the source of its id slug.
+ * @property status - Status the new decision starts with.
+ * @property supersedes - Id of the earlier decision this one replaces; that file is moved to `superseded`.
+ * @property body - Decision text, written below the frontmatter.
+ */
 export interface NewDecision {
   title: string;
   status: DecisionStatus;
-  /** Id of the earlier decision this one replaces; that file is moved to `superseded` */
   supersedes?: string;
   body: string;
 }
 
+/**
+ * @brief Turns a title into a lowercase, dash-separated slug for a decision id.
+ *
+ * @param title - Decision title, e.g. `Use JWT for sessions`.
+ * @returns Slug, e.g. `use-jwt-for-sessions`.
+ * @throws {Error} When the title has no letters or digits.
+ */
 function slugFor(title: string): string {
   const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   if (slug === "") throw new Error(`title "${title}" has no letters or digits to build an id from`);
@@ -22,7 +35,14 @@ function slugFor(title: string): string {
   return slug;
 }
 
-/** Next free id in a plan: one above the highest number in use, then the title as a slug. */
+/**
+ * @brief Builds the next free decision id in a plan: one above the highest number in use, then the title as a slug.
+ *
+ * @param planDir - Plan folder.
+ * @param title - Title the id's slug is made from.
+ * @returns Id such as `0005-use-jwt`.
+ * @throws {Error} When every decision number up to 9999 is in use.
+ */
 export async function nextDecisionId(planDir: string, title: string): Promise<string> {
   const numbers = (await listDecisionIds(planDir)).map((id) => Number.parseInt(id.slice(0, 4), 10));
   const next = Math.max(0, ...numbers.filter((n) => Number.isInteger(n))) + 1;
@@ -33,10 +53,13 @@ export async function nextDecisionId(planDir: string, title: string): Promise<st
 }
 
 /**
- * Writes a new decision file into a plan, numbered after the ones already
+ * @brief Writes a new decision file into a plan, numbered after the ones already
  * there and dated today. Called by the `add-decision` hook.
  *
- * @throws Error when `supersedes` names no decision of this plan
+ * @param planDir - Plan folder.
+ * @param decision - Fields of the new decision; `supersedes` names the one it replaces.
+ * @returns The decision as read back from the file it was written to.
+ * @throws {Error} When `supersedes` names no decision of this plan.
  */
 export async function addDecision(planDir: string, decision: NewDecision): Promise<DecisionDocument> {
   const replaced = decision.supersedes === undefined

package/skills/task-manager/task-manager/hooks/cleanup.ts

@@ -3,6 +3,12 @@ import { generateTree, listAllEntries, readEntry, removeEntry, type EntryLocatio
 import type { TaskStatus } from "../src/schemas";
 import { hasFlag, printJson, resolveRoot, runHook } from "../src/hooks";
 
+/**
+ * @brief Holds one entry to delete, with the status that marked it for deletion.
+ *
+ * @property location - Where the entry sits, as `listAllEntries` reports it.
+ * @property status - Status that matched: `completed`, or `blocked` with `--blocked`.
+ */
 interface Removal {
   location: EntryLocation;
   status: TaskStatus;

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

@@ -6,13 +6,25 @@ import { resolveFiletreeRoot } from "../src/filetree";
 const GUARDED_TOOLS = ["Read", "Grep", "Glob"];
 const PATH_FIELDS = ["file_path", "path", "notebook_path"];
 
+/**
+ * @brief Holds the fields of a `PreToolUse` payload the guard reads.
+ *
+ * @property tool_name - Name of the tool being called, e.g. `Read`.
+ * @property tool_input - Arguments of the call, empty when the payload has none.
+ * @property cwd - Directory the session runs in, the base for relative paths.
+ */
 interface Payload {
   tool_name: string;
   tool_input: Record<string, unknown>;
   cwd: string;
 }
 
-/** The fields of a `PreToolUse` payload the guard reads, or `null` when the JSON is not one. */
+/**
+ * @brief Reads the fields of a `PreToolUse` payload the guard needs.
+ *
+ * @param raw - JSON text read from stdin.
+ * @returns The payload, or `null` when the JSON is not one.
+ */
 function readPayload(raw: string): Payload | null {
   const parsed: unknown = JSON.parse(raw);
   if (typeof parsed !== "object" || parsed === null) return null;
@@ -29,7 +41,13 @@ function readPayload(raw: string): Payload | null {
   };
 }
 
-/** The path the call names, made absolute against the session's directory. */
+/**
+ * @brief Finds the path a tool call names, made absolute against the session's directory.
+ *
+ * @param input - Arguments of the call.
+ * @param cwd - Session directory that relative paths resolve against.
+ * @returns The absolute path, or `null` when the call names no path.
+ */
 function targetPath(input: Record<string, unknown>, cwd: string): string | null {
   for (const field of PATH_FIELDS) {
     const value = input[field];
@@ -41,12 +59,21 @@ function targetPath(input: Record<string, unknown>, cwd: string): string | null
   return null;
 }
 
-/** Whether `path` is `folder` itself or anything below it; both absolute. */
+/**
+ * @brief Checks whether `path` is `folder` itself or anything below it.
+ *
+ * @param path - Absolute path to check.
+ * @param folder - Absolute folder.
+ */
 function isInside(path: string, folder: string): boolean {
   return path === folder || path.startsWith(`${folder}${sep}`);
 }
 
-/** Prints the `PreToolUse` answer that denies the call, with `reason` shown to the agent. */
+/**
+ * @brief Prints the `PreToolUse` answer that denies the call.
+ *
+ * @param reason - Text shown to the agent.
+ */
 function deny(reason: string): void {
   console.log(
     JSON.stringify({

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

@@ -2,7 +2,7 @@
 import { ensureTree, generateTree } from "../src/filetree";
 import { readFlag, resolveRoot, runHook } from "../src/hooks";
 
-/** The session payload, read only for the directory the session opened in. */
+/** Reads the directory the session opened in from the session payload on stdin. */
 async function projectFromPayload(): Promise<string | undefined> {
   if (process.stdin.isTTY) return undefined;