@g3nomaly/g3n-skills 0.1.6 → 0.1.8

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

@@ -2,16 +2,16 @@
 
 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 |
+| 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.
 

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

@@ -2,12 +2,12 @@
 
 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 |
+| 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
 

package/skills/using-hooks/.claude-plugin/plugin.json

@@ -1,7 +1,12 @@
 {
   "name": "using-hooks",
   "description": "How to write each Claude Code lifecycle hook.",
-  "version": "0.1.0",
+  "version": "0.1.7",
   "license": "UNLICENSED",
-  "skills": ["./hook-pre-tool-use", "./hook-post-tool-use", "./hook-stop", "./hook-user-prompt-submit"]
+  "skills": [
+    "./hook-pre-tool-use",
+    "./hook-post-tool-use",
+    "./hook-stop",
+    "./hook-user-prompt-submit"
+  ]
 }

package/skills/using-hooks/hook-post-tool-use/SKILL.md

@@ -20,8 +20,15 @@ The four common fields, the call, and what came back:
   "cwd": "/home/you/project",
   "hook_event_name": "PostToolUse",
   "tool_name": "Edit",
-  "tool_input": { "file_path": "/home/you/project/src/index.ts", "old_string": "…", "new_string": "…" },
-  "tool_response": { "filePath": "/home/you/project/src/index.ts", "success": true }
+  "tool_input": {
+    "file_path": "/home/you/project/src/index.ts",
+    "old_string": "…",
+    "new_string": "…"
+  },
+  "tool_response": {
+    "filePath": "/home/you/project/src/index.ts",
+    "success": true
+  }
 }
 ```
 
@@ -34,7 +41,12 @@ Same tool-name regex as [`hook-pre-tool-use`](../hook-pre-tool-use/SKILL.md), an
 ```json
 {
   "matcher": "Edit|MultiEdit|Write",
-  "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-edited-file.ts" }]
+  "hooks": [
+    {
+      "type": "command",
+      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-edited-file.ts"
+    }
+  ]
 }
 ```
 

package/skills/using-hooks/hook-pre-tool-use/SKILL.md

@@ -20,7 +20,10 @@ The four common fields, plus the call about to be made:
   "cwd": "/home/you/project",
   "hook_event_name": "PreToolUse",
   "tool_name": "Write",
-  "tool_input": { "file_path": "/home/you/project/src/index.ts", "content": "…" }
+  "tool_input": {
+    "file_path": "/home/you/project/src/index.ts",
+    "content": "…"
+  }
 }
 ```
 
@@ -33,7 +36,12 @@ This event selects by tool name, as a regex:
 ```json
 {
   "matcher": "Edit|MultiEdit|Write",
-  "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-protected-paths.ts" }]
+  "hooks": [
+    {
+      "type": "command",
+      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-protected-paths.ts"
+    }
+  ]
 }
 ```
 

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

@@ -1,10 +1,14 @@
 {
   "name": "workflow",
   "description": "Work a phase of a plan through plan, execute, review and sync, one agent per step, with hooks deciding when a step is finished.",
-  "version": "0.1.0",
+  "version": "0.1.7",
   "license": "UNLICENSED",
-  "dependencies": ["task-manager@g3n"],
-  "agents": ["./review/agents/reviewer.md"],
+  "dependencies": [
+    "task-manager@g3n"
+  ],
+  "agents": [
+    "./review/agents/reviewer.md"
+  ],
   "skills": [
     "./run",
     "./plan",

package/skills/workflow/orchestrator/SKILL.md

@@ -11,12 +11,12 @@ Hooks are scripts in a skill's `hooks/` folder, run with `bun`. `<task-manager-d
 
 `bun <orchestrator-dir>/hooks/ready-phases.ts --plan <plan>` sorts the plan's phases by gate:
 
-| Field | Holds |
-|---|---|
-| `ready` | phases whose gate is open, in queue order, each in full |
-| `waiting` | phases behind a closed gate, with the phases they are `waiting_on` |
-| `blocked` | phases set to `blocked` |
-| `completed` | finished phases |
+| Field       | Holds                                                              |
+| ----------- | ------------------------------------------------------------------ |
+| `ready`     | phases whose gate is open, in queue order, each in full            |
+| `waiting`   | phases behind a closed gate, with the phases they are `waiting_on` |
+| `blocked`   | phases set to `blocked`                                            |
+| `completed` | finished phases                                                    |
 
 1. **Claim the plan** with `bun <task-manager-dir>/hooks/set-state.ts --id <plan> --to in-progress`, unless it already is.
 2. **Read the gates** with `ready-phases`.

package/skills/workflow/plan/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: plan
 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]
+registryDependencies:
+  [task-manager, writing-great-tasks, vocabulary, decisions, grilling, run]
 disable-model-invocation: false
 ---
 

package/skills/workflow/review/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: review
 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]
+registryDependencies:
+  [task-manager, writing-great-tasks, vocabulary, decisions, run]
 disable-model-invocation: false
 ---
 

package/skills/workflow/run/SKILL.md

@@ -13,14 +13,14 @@ Hooks are scripts in a skill's `hooks/` folder, run with `bun`. `<task-manager-d
 
 `bun <run-dir>/hooks/current-step.ts --phase <phase>` returns the phase's `step`:
 
-| `step` | Meaning | Hand it to |
-|---|---|---|
-| `plan` | the phase has no tasks, or is still `open` | an agent running the `/plan` skill |
-| `execute` | a task is `open` or `in-progress` | agents running the `/execute` skill |
-| `review` | every remaining task is `in-review` | the **reviewer** agent running the `/review` skill |
-| `sync` | every task is `completed` | an agent running the `/sync` skill |
-| `done` | the phase is `completed` | nobody. Report and stop |
-| `blocked` | the phase or a task in `holding` is `blocked` | nobody. Report and stop |
+| `step`    | Meaning                                       | Hand it to                                         |
+| --------- | --------------------------------------------- | -------------------------------------------------- |
+| `plan`    | the phase has no tasks, or is still `open`    | an agent running the `/plan` skill                 |
+| `execute` | a task is `open` or `in-progress`             | agents running the `/execute` skill                |
+| `review`  | every remaining task is `in-review`           | the **reviewer** agent running the `/review` skill |
+| `sync`    | every task is `completed`                     | an agent running the `/sync` skill                 |
+| `done`    | the phase is `completed`                      | nobody. Report and stop                            |
+| `blocked` | the phase or a task in `holding` is `blocked` | nobody. Report and stop                            |
 
 The step is worked out from the statuses on disk each time, so a task the reviewer sends back puts the phase on `execute` again with nothing to reset. `holding` names the tasks keeping the phase on its step.
 

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

@@ -28,12 +28,12 @@ Give names, never contents. The agent reads the phase and its tasks through the
 
 ## Which agent per step
 
-| Step | Agent | Can edit |
-|---|---|---|
-| `plan` | general purpose | the tree only |
-| `execute` | general purpose, one or several | its task's worktree |
-| `review` | **reviewer**, defined in the plugin's `agents/reviewer.md` | nothing |
-| `sync` | general purpose | the phase branch, the tree |
+| Step      | Agent                                                      | Can edit                   |
+| --------- | ---------------------------------------------------------- | -------------------------- |
+| `plan`    | general purpose                                            | the tree only              |
+| `execute` | general purpose, one or several                            | its task's worktree        |
+| `review`  | **reviewer**, defined in the plugin's `agents/reviewer.md` | nothing                    |
+| `sync`    | general purpose                                            | the phase branch, the tree |
 
 Where no `reviewer` agent type is offered, which is the case after `g3n-skills add workflow`, spawn a general purpose agent for `review` and open its brief with _You change no file._
 

package/skills/workflow/sync/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: sync
 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]
+registryDependencies:
+  [task-manager, worktree, vocabulary, decisions, run, orchestrator]
 disable-model-invocation: false
 ---
 

package/skills/workflow/worktree/SKILL.md

@@ -8,11 +8,11 @@ Every task gets its own **worktree**, a second checkout on its own branch, so ag
 
 ## Names
 
-| Thing | Pattern | Example |
-|---|---|---|
-| Phase branch | `<type>/<plan>-<phase>` | `feature/auth-rework-01-schema` |
-| Task branch | `<worktree_type>/<task id>-<slug of the title>` | `feature/TASK-012-session-table-migration` |
-| Worktree folder | `../<repo folder>.worktrees/<task id>` | `../g3n.worktrees/TASK-012` |
+| Thing           | Pattern                                         | Example                                    |
+| --------------- | ----------------------------------------------- | ------------------------------------------ |
+| Phase branch    | `<type>/<plan>-<phase>`                         | `feature/auth-rework-01-schema`            |
+| Task branch     | `<worktree_type>/<task id>-<slug of the title>` | `feature/TASK-012-session-table-migration` |
+| Worktree folder | `../<repo folder>.worktrees/<task id>`          | `../g3n.worktrees/TASK-012`                |
 
 `worktree_type` comes from the task's frontmatter. The phase branch takes the type most of its tasks carry. The worktree folder sits beside the repository, outside it, so no search or build inside the repo walks into it.
 

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

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

package/skills/writing/writing-great-hooks/references/lifecycle-hook.md

@@ -10,7 +10,13 @@ In a plugin's `hooks.json`, or in `settings.json`:
     "PreToolUse": [
       {
         "matcher": "Read|Grep|Glob",
-        "hooks": [{ "type": "command", "command": "bun \"${CLAUDE_PLUGIN_ROOT}/task-manager/hooks/guard-tree.ts\"", "timeout": 10 }]
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/task-manager/hooks/guard-tree.ts\"",
+            "timeout": 10
+          }
+        ]
       }
     ]
   }
@@ -28,19 +34,19 @@ A JSON payload on stdin with `session_id`, `transcript_path`, `cwd`, `hook_event
 
 ## Output
 
-| Exit | Effect |
-|---|---|
-| `0` | ran; stdout is read per event |
-| `2` | blocks; stderr goes to the agent as the reason |
-| other | error shown to the user; the run continues |
+| Exit  | Effect                                         |
+| ----- | ---------------------------------------------- |
+| `0`   | ran; stdout is read per event                  |
+| `2`   | blocks; stderr goes to the agent as the reason |
+| other | error shown to the user; the run continues     |
 
 For more than a block, print JSON on stdout and exit `0`: `continue`, `stopReason`, `suppressOutput`, `systemMessage`, and the event's `hookSpecificOutput`.
 
 ## Events
 
-| Event | Fires | Skill |
-|---|---|---|
+| Event              | Fires                           | Skill                     |
+| ------------------ | ------------------------------- | ------------------------- |
 | `UserPromptSubmit` | before the agent reads a prompt | `hook-user-prompt-submit` |
-| `PreToolUse` | before a tool runs | `hook-pre-tool-use` |
-| `PostToolUse` | after a tool ran | `hook-post-tool-use` |
-| `Stop` | when the agent is about to stop | `hook-stop` |
+| `PreToolUse`       | before a tool runs              | `hook-pre-tool-use`       |
+| `PostToolUse`      | after a tool ran                | `hook-post-tool-use`      |
+| `Stop`             | when the agent is about to stop | `hook-stop`               |

package/skills/writing/writing-great-hooks/references/skill-hook.md

@@ -16,7 +16,12 @@
 
 ```ts
 // packages/g3n-skills/skills/<group>/<skill>/hooks/get-term.ts
-import { printJson, requireFlag, resolveRoot, runHook } from "@task-manager/hooks";
+import {
+  printJson,
+  requireFlag,
+  resolveRoot,
+  runHook,
+} from "@task-manager/hooks";
 
 /** Prints the term `--term` names. */
 async function run(argv: readonly string[]): Promise<void> {
@@ -39,8 +44,18 @@ From task-manager's `src/hooks/`: `readFlag`, `requireFlag`, `hasFlag`, `oneOf`,
 - **Code shared between skills** lives in the `src/` of the skill that owns it. Import it as `@<owner>/<module>`, mapped in the importing skill's `tsconfig.json`, and list the owner in `registryDependencies`:
 
   ```json
-  { "compilerOptions": { "paths": { "@task-manager/*": ["../task-manager/src/*", "../../task-manager/task-manager/src/*"] } } }
+  {
+    "compilerOptions": {
+      "paths": {
+        "@task-manager/*": [
+          "../task-manager/src/*",
+          "../../task-manager/task-manager/src/*"
+        ]
+      }
+    }
+  }
   ```
 
   The first path is the owner installed beside the skill; the second is its folder in another group in the repo.
+
 - **Packages** go in the owning skill's `package.json` with a pinned version and a `bun.lock`. Installers run `bun install` in that skill folder.

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

@@ -15,17 +15,17 @@ A task is a _brief_: one agent reads it, works alone, and is done when every box
 
 ## Sections
 
-| Section | Holds |
-|---|---|
-| Description | Prose: the problem, the outcome, the context needed to start |
-| Goals | `- [ ]` outcomes the task is judged on |
-| Non-Goals | `- [ ]` outcomes a reasonable agent would pursue from the Description, which stay out |
-| Deliverables | `- [ ]` one per file: **new** or **edit**, the path, a one-line contract. Files added later go in Findings |
-| Package Dependencies | `- [ ]` packages the task may use, each with why |
-| Contracts | Optional: a settled schema, type or signature small enough to write out |
-| Requirements | `- [ ]` constraints on how, each checkable in the diff; a goal is never restated here |
-| Findings | Empty; the executor appends what it discovers |
-| Blockers | Empty; filled when the task is blocked, cleared when it is released |
-| Decisions | ADR paths only, in the `/domain-modeling` format |
-| References | Files, skills and task ids to read first, each with why |
-| Amendments | Empty; whoever edits the task after creation logs what changed and which later tasks are now suspect |
+| Section              | Holds                                                                                                      |
+| -------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Description          | Prose: the problem, the outcome, the context needed to start                                               |
+| Goals                | `- [ ]` outcomes the task is judged on                                                                     |
+| Non-Goals            | `- [ ]` outcomes a reasonable agent would pursue from the Description, which stay out                      |
+| Deliverables         | `- [ ]` one per file: **new** or **edit**, the path, a one-line contract. Files added later go in Findings |
+| Package Dependencies | `- [ ]` packages the task may use, each with why                                                           |
+| Contracts            | Optional: a settled schema, type or signature small enough to write out                                    |
+| Requirements         | `- [ ]` constraints on how, each checkable in the diff; a goal is never restated here                      |
+| Findings             | Empty; the executor appends what it discovers                                                              |
+| Blockers             | Empty; filled when the task is blocked, cleared when it is released                                        |
+| Decisions            | ADR paths only, in the `/domain-modeling` format                                                           |
+| References           | Files, skills and task ids to read first, each with why                                                    |
+| Amendments           | Empty; whoever edits the task after creation logs what changed and which later tasks are now suspect       |

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

@@ -1,27 +0,0 @@
-# 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

@@ -1,54 +0,0 @@
-# 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

@@ -1,13 +0,0 @@
-# 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.