@intentic/claude-plugin 1.317.0

package/generated/iq-nudge.txt

@@ -0,0 +1,3 @@
+`iq` is installed here — intent-first code search returning ranked `path:line` anchors. Prefer it over grep/find chains for locating code, symbols, and natural-language questions. Use bare `iq "…"` (not `iq search`); run `iq --help` or load the iq skill for the verb cheat-sheet.
+
+Read the capsule it opens with (`answer:`, `candidates:`, `more:`) and stop there. Size the response with `--budget <tokens>`, never `| head` — the capsule is reserved against the budget, so `head` cuts the anchors rather than the noise.

package/generated/output-styles/intentic.md

@@ -0,0 +1,13 @@
+---
+name: Intentic
+description: Intentic's working habits — batch independent lookups into one response, reuse what is already in context, and run long commands in the background instead of sleeping.
+keep-coding-instructions: true
+---
+
+# Working habits
+
+While you are ORIENTING, locating code, checking what exists, reading the files around a change, put every probe you can already name into ONE response rather than one per response. Their results do not depend on each other, and what a search costs here is the round trip, not the search. Order calls one-per-response only when a later one genuinely needs an earlier one's output.
+
+A file you have already read this session is still in your context, and so is the output of a command you already ran. Re-reading either to check it costs a round trip and tells you nothing you do not have. Read a path a second time only when you have reason to think it CHANGED: something you wrote, something a command you ran wrote. An Edit's result already states what the file became, so it never needs confirming by re-Read.
+
+Never idle in the shell. A command that will outlive a few seconds takes `run_in_background: true`, and you collect its output when it finishes rather than polling it. `sleep N` in a Bash command is not a way to wait: it bills the wait to the turn and costs a model round trip per poll, and a sleep sized to land just under the tool timeout is the most expensive way to do nothing.

package/generated/skills/field-notes/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: field-notes
+description: Rewrite this project's field notes, the brief every Claude Code session here opens with, from the sessions already run in this project. Run it every few weeks, or after a stretch of sessions lost time to the same trap.
+disable-model-invocation: true
+allowed-tools: Bash(intentic-notes-evidence *)
+---
+
+Rewrite this project's field notes: `${CLAUDE_PROJECT_DIR}/.claude/intentic/field-notes.toon`, the brief every turn opens with.
+
+It exists because the project map cannot carry this. The map is recomputed from the TREE each conversation, so it already says what a scan can see — which directories exist, what each is for. Yours is the other half, drawn from what has actually HAPPENED here: which commands really verify in this workspace and which lie about their exit code, what the machine can take, where sessions lost calls to a trap the code does not mention, and how the owner asks for things. If a fact could be found by reading the repository, it belongs in the map and not in your file.
+
+The evidence is the digest below: this project's own Claude Code sessions, read back and counted by the plugin (failures by how many sessions hit them, the commands that ran and how often they failed, the files edited most, how sessions opened). Open a transcript it names when a count needs its story. Work from counts, not impressions: how MANY sessions hit a thing is what decides its rank, and one bad afternoon is not a standing problem.
+
+Rank by what it costs a turn NOT to know: how often sessions hit it, how much it costs when they do, and whether they could have found it out cheaply themselves. Rank 1 is the costliest gap.
+
+VERIFY EVERY FACT AGAINST THIS PROJECT BEFORE YOU WRITE IT DOWN. A transcript from six weeks ago is a hypothesis: run the command, list the directory, check the port. A brief that is confidently wrong is worse than no brief, because every turn reads it and none of them will doubt it.
+
+The file is TOON. Keep its shape, because the intentic plugin reads it by rank and sends as much as the owner's budget allows: a `meta` block, a `priority` table whose columns begin `rank,id` and whose every id is also a top-level key in the file, then one block per id. Ranks are integers and ids are kebab-case words.
+
+This is a REWRITE, not a fresh start. Read the existing file first: carry forward what still holds, drop what the project has outgrown, re-rank on the latest evidence. Finish with a short note saying what changed rank and why, what you added, and what you removed as no longer true — the next one of these should not have to rediscover your reasoning. If the sessions since the last rewrite genuinely showed nothing worth changing, say so in one line and leave the file alone: a rewrite that says the same thing in new words costs the measurement its baseline for nothing.
+
+If the file does not exist yet, start from this shape and replace every value:
+
+```
+meta:
+  title: Field notes for this project
+  written: 2026-01-31
+  basis: 42 sessions from 2026-01-01 to 2026-01-31
+priority[2]{rank,id,title,cost}:
+  1,verify,Which commands really verify,"a passing run that proved nothing"
+  2,traps,Traps the code does not mention,"calls lost to the same failure"
+verify:
+  tests: pnpm test runs the unit suites only; integration needs pnpm test:int
+traps:
+  generated: src/schema.ts is generated; edit schema.graphql and run the generator
+```
+
+## Evidence
+
+!`intentic-notes-evidence --project "${CLAUDE_PROJECT_DIR}"`

package/generated/skills/fileq/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: fileq
+description: Read binary workspace files (docx, odt, xlsx, pptx, pdf, epub, ipynb, images, audio, zip and tar archives, V8 CPU and heap profiles) as clean budgeted markdown with the `fileq` CLI, and read big text-shaped files (csv, json, logs) without flooding your context. Use whenever a task needs the contents of a document, the text layer of a PDF, the metadata of an image or recording, what is inside an archive, or a look inside a file too large to cat — instead of guessing from the filename or shelling out to ad-hoc converters.
+---
+
+# fileq: binary files as markdown
+
+The `fileq` CLI (on PATH) turns the workspace files you cannot open as text into markdown, and keeps a
+sidecar copy fresh so reading twice derives once.
+
+## Read a file
+`fileq <file>` (or `fileq read <file> --budget 8000`)
+- Prints a capsule (format, token cost), the content up to the budget, and `saved:` — the sidecar path
+  carrying the whole thing. Over budget, the cut is announced with that exact path to Read.
+- Formats: docx and odt (headings, lists, tables), xlsx (capped tables), pptx (slides + speaker notes),
+  pdf (text layer; a scan is OCR'd when `tesseract` is on PATH, and the note says the words are
+  recognised, not exact), epub (chapters in reading order), ipynb (cells, fenced code, capped outputs),
+  png/jpg/gif/webp (dimensions + EXIF), mp3/wav/flac/mp4/… (duration + tags), html, and V8 profiles
+  (`.cpuprofile` from `node --cpu-prof`, `.heapprofile` from `--heap-prof`) as functions ranked by self and total cost.
+- Archives (zip, jar, whl, tar, tgz, and what tar can open: xz, bzip2, zstd) derive to a MEMBER LISTING —
+  paths and sizes, capped — never their contents: unpack one if you need what is inside. A single
+  compressed file (`server.log.gz`) is the exception and derives to its text, since there the archive is
+  the document. 7z and rar answer that nothing here opens them.
+
+## Check the sidecar first
+A file may already have a shadow at `.intentic/local/cache/derived/<path>.md` — front matter says which
+source hash it was derived from. `fileq read` checks freshness for you, so prefer it over trusting a
+shadow's age by eye.
+
+## What it refuses, and why
+- A scanned PDF with no `tesseract` on PATH answers "no usable text layer … OCR is not part of this tier"
+  rather than an empty page; images say "no visual description". Treat those notes as "not generated",
+  never as "nothing there". Installing tesseract turns the first into OCR.
+- Plain text (md, csv, txt, code) is not fileq's business: Read it directly — but see below for the big ones.
+- Web pages belong to `webq`; images for a vision model belong to the Read tool, which shows the pixels.
+
+Exit codes: 0 content, 1 nothing derivable, 2 broken invocation or install.
+
+## Text-shaped files that are too big to cat
+The commonest way to lose a context window is `cat` on a file you have not sized. Stat first, then read
+the shape, then only what the question needs:
+- **Size first**: `wc -c <file>`. Under ~20 KB, Read it whole. Over, `head -100` and `tail -100` to
+  orient, `rg` for what the task actually asks about, the whole file only if you genuinely need all of it.
+- **CSV / TSV**: never `head -n 5` blindly — a 50 KB quoted cell in row 1 wrecks it. `head -c 4000` for
+  a glance; for the shape, python with `csv` and a row cap, or `fileq` after converting to xlsx is
+  overkill: `python3 -c 'import csv,sys; r=csv.reader(open(sys.argv[1])); print(next(r)); print(sum(1 for _ in r))' <file>`
+  gives header and row count without loading it all.
+- **JSON**: structure before content — `jq 'type' <file>`, then `jq 'if type=="array" then length elif type=="object" then keys else . end'`
+  (guarded: `keys` errors on a scalar root). Drill only into what was asked. **JSONL**: never `jq` the
+  whole file; `head -3 <file> | jq .` and `wc -l`.
+- **Logs**: the end is what matters — `tail -200`, then `rg` for the error text.
+- **Archives (zip, tar.*)**: list, never auto-extract — `unzip -l`, `tar -tf` (auto-detects compression).
+  Extract one member with `unzip -p <zip> <path>` or `tar -xOf <tar> <path>`. A single `.gz` has no
+  listing: `zcat <file> | head -50`.
+- **Unknown extension**: `file <path>` then `xxd <path> | head -5`; if the bytes mean nothing to you,
+  ask rather than guess.

package/generated/skills/iq/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: iq
+description: Workspace code search — one call from a question to ranked path:line anchors. Use for definitions, references, natural-language code questions, file skeletons, and git history.
+---
+
+# iq
+
+Pick by what you already know:
+
+- **You know the symbol you want to read** → `iq read X` — the body, one call. Read the file only when you need the whole file; a `Read` with no offset returns up to 2000 lines whether you wanted them or not.
+- **You know the file** (stack trace, failing test) → `iq outline <path>` for its shape, then `iq read <path>::<symbol>`; `iq context path:line` when all you have is a line.
+- **You know the symbol, but want its anchor or callers** → `iq def X` / `iq refs X` — one call, not grep-then-filter.
+- **You don't know where it lives** → bare `iq "…"`. No separate verb for questions.
+- **Checking your own edit** → `grep`/`rg`. Verification is not discovery.
+
+```
+iq "where do we enforce the secrets floor?"
+```
+
+| I want… | Run |
+|---|---|
+| natural language | `iq "how does auth refresh?"` |
+| text/regex match | `iq find 'createServer\(' --lang ts` |
+| where defined | `iq def createIgnoreScope` |
+| who uses it | `iq refs createIgnoreScope --kind call` |
+| file by name | `iq files wkignore` |
+| file skeleton | `iq outline src/app.ts` |
+| a symbol's body | `iq read createIgnoreScope`, `iq read src/app.ts::Server::start` |
+| code around a hit | `iq context src/app.ts:48` |
+| recent changes | `iq recent --since 2d` |
+| git history | `iq log "MAX_MATCHES" --path src` |
+| several at once | `iq multi "def foo" "refs bar"` |
+
+Every answer opens with a capsule (`answer:`, `candidates:`, `more:`). Read that and stop — do not pipe through `head`; `--budget` already caps output. Scope with `--in`, `--repo`, `--lang`, `--glob`. Wrong grep habits (`iq search`, `iq ask`) are rewritten to `q`; use canonical forms next time. Full verb list: `iq --help`.
+
+**Session recall:** `iq sessions grab "topic"` for ranked excerpts from past sessions; `iq sessions files "topic"` for files those sessions touched. Verify load-bearing hits against current code.
+
+**Another conversation**, rather than what past sessions touched, is the `agents` CLI: `agents show <handle>` answers one whole (its task, where it got to, branch, worktree, delta, record) from any spelling of its name — id, branch, id prefix, session id, or title words. `agents ls` is the fleet, `agents find '<text>'` is who said a phrase. Never search `/history` by hand for one.

package/generated/skills/stats/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: stats
+description: Show what the intentic plugin saved in this project — Bash output trimmed, and what the project map, field notes and iq teaching changed against the sessions held out without them. Add "all" for every project.
+disable-model-invocation: true
+allowed-tools: Bash(intentic-stats *)
+argument-hint: "[all]"
+---
+
+!`intentic-stats --data "${CLAUDE_PLUGIN_DATA}" --project "${CLAUDE_PROJECT_DIR}" $ARGUMENTS`
+
+Show the report above to the person as it is. Then say, in one or two sentences, what stands out: a cleaner worth switching off, a mechanism whose reading is not moving, or a comparison that needs a larger held-out share (`holdout`, `output_holdout` in /config) to resolve. Run nothing else.

package/hooks/hooks.json

@@ -0,0 +1,49 @@
+{
+    "description": "intentic: session context (map, field notes, iq teaching), Bash output cleaning, document shadows. Each script reads its own /config switch and answers nothing when it is off. Without node on PATH the tool hooks stand down silently and each session opens with one line saying why nothing ran.",
+    "hooks": {
+        "SessionStart": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "if command -v node >/dev/null 2>&1; then node \"${CLAUDE_PLUGIN_ROOT}/dist/session-start.mjs\"; else echo '{\"systemMessage\":\"intentic: the plugin needs Node.js 20.11 or later on PATH, so none of it ran this session.\"}'; fi; exit 0",
+                        "timeout": 20
+                    }
+                ]
+            }
+        ],
+        "UserPromptSubmit": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "command -v node >/dev/null 2>&1 && node \"${CLAUDE_PLUGIN_ROOT}/dist/prompt-submit.mjs\"; exit 0",
+                        "timeout": 10
+                    }
+                ]
+            }
+        ],
+        "PostToolUse": [
+            {
+                "matcher": "Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "command -v node >/dev/null 2>&1 && node \"${CLAUDE_PLUGIN_ROOT}/dist/post-bash.mjs\"; exit 0",
+                        "timeout": 15
+                    }
+                ]
+            },
+            {
+                "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "command -v node >/dev/null 2>&1 && node \"${CLAUDE_PLUGIN_ROOT}/dist/post-edit.mjs\"; exit 0",
+                        "timeout": 10
+                    }
+                ]
+            }
+        ]
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@intentic/claude-plugin",
+  "version": "1.317.0",
+  "description": "The intentic Claude Code plugin: trimmed Bash output, a project map and field notes at session start, iq search and fileq teaching, background document shadows, and a /intentic:stats report of what each saved",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intentic/intentic.git",
+    "directory": "_sandbox/claude-plugin"
+  },
+  "homepage": "https://github.com/intentic/intentic/tree/main/_sandbox/claude-plugin",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "agent",
+    "context",
+    "token-savings"
+  ],
+  "files": [
+    ".claude-plugin",
+    "hooks",
+    "bin",
+    "generated",
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "executableFiles": [
+      "./bin/fileq",
+      "./bin/intentic-notes-evidence",
+      "./bin/intentic-stats",
+      "./bin/retrieve-output"
+    ]
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "devDependencies": {
+    "@intentic/agent-context": "0.0.0",
+    "@intentic/fileq": "1.317.0",
+    "@intentic/iq": "0.0.0",
+    "@intentic/output-cleaners": "0.0.0",
+    "@intentic/testing": "0.0.0",
+    "@intentic/tsconfig": "0.0.0",
+    "@types/bun": "1.4.2",
+    "@types/node": "24.13.6",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "esbuild": "0.28.2"
+  },
+  "scripts": {
+    "build": "tsgo --noEmit && node build.mjs",
+    "typecheck": "tsgo --noEmit -p tsconfig.test.json",
+    "test": "suites",
+    "test:watch": "suites --watch",
+    "validate": "node build.mjs --validate"
+  }
+}