tokenfreez 0.1.0

package/.opencode/agent/build.md

@@ -0,0 +1,64 @@
+---
+description: Silent build agent - outputs only a task checklist and a final change summary. No narration, no code echo.
+mode: primary
+---
+
+You are the build agent. Work silently. Output discipline is absolute.
+
+## Forbidden in responses
+
+- Restating or summarizing context back to the user
+- Explaining what you are about to do before doing it
+- Echoing, quoting, or reading out code you write, edit, or delete (diffs already render in the UI)
+- Long explanations, preamble, postamble, apologies, filler
+- Announcing tool calls in prose
+
+## Required output format
+
+While working, your ONLY text output is a plain-text task checklist:
+
+```
+[ ] task one
+[ ] task two
+```
+
+Mark items done as work completes and reprint the updated list when statuses change:
+
+```
+[x] task one
+[x] task two
+```
+
+No other prose between steps.
+
+## End of task
+
+After the last item is checked, output ONLY a change summary:
+
+```
+Changes:
+- path/to/file — what changed (one line per file)
+```
+
+Nothing else. No conclusions, no explanations, no next-step suggestions unless asked.
+
+## Exceptions
+
+- Errors, blockers, and security findings: state them plainly and briefly.
+- Questions requiring user decisions: ask in one sentence.
+
+## Debug loops
+
+On the second failed fix attempt for the same error, invoke the debuglock skill and
+follow its protocol exactly. Do not attempt a third blind fix.
+
+## Exploration
+
+Before any multi-file exploration, invoke the scoutlock skill and follow its
+protocol - docs first, then targeted search.
+
+## Verbose tool output
+
+Before running a command or web fetch likely to produce long output (install,
+build, test, logs, page content), invoke the outputlock skill and follow its
+protocol - silence, redirect, or extract instead of dumping.

package/.opencode/plugins/tokenfreez.mjs

@@ -0,0 +1,3 @@
+// ponytail: empty entrypoint so npm package satisfies the opencode plugin contract;
+// all behavior lives in skills/ which opencode scans from the installed package.
+export default async () => ({})

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fdhill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# TokenFreez
+
+opencode skills that cut token waste in AI coding sessions. Each skill targets one of
+the four ways coding agents quietly burn tokens — so small tasks stop costing big money.
+
+## Why
+
+LLM APIs are stateless: every turn resends the whole conversation as input tokens.
+Anything that grows context — long histories, retry loops, broad searches, verbose tool
+output — gets paid for again on every subsequent turn. TokenFreez attacks all four.
+
+| Problem | Fix | Component |
+|---|---|---|
+| History resent every turn grows cost | Freeze session state to a file, restart cheap | [tokenfreez](skills/tokenfreez/SKILL.md) |
+| Retry-debug loops multiply cost | Stop blind fixes, hypothesize first, hard budget | [debuglock](skills/debuglock/SKILL.md) |
+| Unstructured codebase exploration | Docs first, narrow search, subagent delegation | [scoutlock](skills/scoutlock/SKILL.md) |
+| Verbose tool results flood context | Silence, redirect-and-grep, extract the one fact | [outputlock](skills/outputlock/SKILL.md) |
+| Narration and code echo during work | Silent `[ ]`/`[x]` checklist output only | [build agent override](.opencode/agent/build.md) |
+
+## Install
+
+Requires [opencode](https://opencode.ai).
+
+### One line (recommended)
+
+Add the package to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["tokenfreez"]
+}
+```
+
+Restart opencode — all four skills are available in every project.
+
+### Manual
+
+Copy the skills you want into your project, or globally into `~/.config/opencode/skills/`:
+
+```bash
+cp -r skills/tokenfreez  your-project/.opencode/skills/
+cp -r skills/debuglock   your-project/.opencode/skills/
+cp -r skills/scoutlock   your-project/.opencode/skills/
+cp -r skills/outputlock  your-project/.opencode/skills/
+```
+
+Optionally adopt the silent build agent:
+
+```bash
+mkdir -p your-project/.opencode/agent
+cp .opencode/agent/build.md your-project/.opencode/agent/
+```
+
+Restart opencode so the skills load.
+
+## Usage
+
+Skills auto-trigger from natural language — no slash commands needed:
+
+| Say / situation | Skill that kicks in |
+|---|---|
+| "freeze", "save session" | tokenfreez writes `FREEZE.md` |
+| "masih error", second failed fix on the same bug | debuglock stops blind retries |
+| multi-file exploration, "dimana", "carikan" | scoutlock reads docs before code |
+| install/build/test runs, web lookups | outputlock keeps logs out of context |
+
+### Freeze / resume cycle
+
+```
+(long session getting expensive)
+
+you: freeze        → AI writes FREEZE.md with state, decisions, next steps
+you: /new          → fresh, cheap session
+you: resume        → AI reads FREEZE.md — context restored at one file-read price
+```
+
+`FREEZE.md` is gitignored by default so session state never gets committed.
+
+## Notes
+
+- Skills are plain markdown (`SKILL.md`) — portable to any tool that uses the same convention.
+- scoutlock prefers an Obsidian vault when one is connected; otherwise it falls back to `README.md` / `docs/`.
+- The build agent override is opencode-specific.
+
+## License
+
+[MIT](LICENSE) © fdhill

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "tokenfreez",
+  "version": "0.1.0",
+  "description": "TokenFreez - opencode skills that cut token waste in AI coding sessions.",
+  "keywords": [
+    "opencode-plugin",
+    "opencode",
+    "tokenfreez",
+    "tokens",
+    "skills"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "fdhill",
+    "url": "https://github.com/fdhill"
+  },
+  "homepage": "https://github.com/fdhill/TokenFreez",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fdhill/TokenFreez.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fdhill/TokenFreez/issues"
+  },
+  "main": "./.opencode/plugins/tokenfreez.mjs",
+  "exports": {
+    ".": "./.opencode/plugins/tokenfreez.mjs",
+    "./plugin": "./.opencode/plugins/tokenfreez.mjs"
+  },
+  "files": [
+    "skills/",
+    ".opencode/",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/debuglock/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: debuglock
+description: >
+  Breaks retry-debug loops: stops blind fix attempts, forces root-cause analysis with
+  ranked hypotheses before touching code again. Use when the same error has been fixed
+  unsuccessfully twice in a row, when user says "masih error", "error lagi", "debug",
+  "loop", or whenever you notice you have made 2+ consecutive failed fix attempts on
+  the same issue. Auto-trigger; do not wait to be asked.
+---
+
+Retry loops burn tokens multiplicatively: error → fix → error → re-read → fix.
+When triggered, stop paying that tax and find the root cause instead.
+
+## Trigger
+
+- You have made 2+ consecutive failed fix attempts on the same error, OR
+- The user reports the error persists ("masih error", "error lagi", "debug", "loop").
+
+## Protocol (in order, no skipping)
+
+1. **STOP editing.** No more fixes until this protocol completes.
+2. **Inventory from history** (no re-running anything): list every attempt already
+   tried and the exact error each produced.
+3. **Read once, fully.** Read the complete relevant file(s) and full stack trace one
+   time. Never re-read a file that has not changed since your last read.
+4. **Ranked hypotheses.** Write a numbered list of hypotheses with evidence for and
+   against each. Rank by likelihood.
+5. **Verify cheapest first.** Discriminate hypotheses with logging, an assert, or a
+   minimal repro BEFORE editing any code.
+6. **Fix at the root.** Apply the fix at the choke point (the shared function all
+   callers route through), not per-caller symptom patches. Grep every caller first.
+7. **One change per cycle.** Each edit→test cycle changes exactly one thing, so
+   results isolate variables.
+8. **Trim logs.** From long output, extract only failing assertion/error lines;
+   never paste whole logs into context.
+
+## Hard budget
+
+After activation, if 2 fix attempts fail: STOP permanently on this bug. Report:
+
+- Attempts made and their errors
+- Hypothesis status (confirmed / refuted / untested)
+- What you need from the user (decision, access, or information)
+
+Never continue solo past this point.
+
+## Rules
+
+- No blind retries: never re-attempt a fix whose hypothesis is already refuted.
+- No shotgun edits: multiple simultaneous changes destroy signal.
+- If new evidence invalidates the hypothesis list mid-cycle, return to step 4,
+  not to editing.

package/skills/outputlock/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: outputlock
+description: >
+  Keeps verbose tool results out of context: silences or truncates bash output,
+  extracts single facts from web results, and summarizes oversized tool dumps instead
+  of echoing them. Use BEFORE running commands known to produce long output (install,
+  build, test, tail logs), before web search/fetch, when only one small fact is needed
+  from a big source, or when a huge tool result has just landed.
+---
+
+Tool results enter context whole and are resent every turn. One careless dump is paid
+for the rest of the session.
+
+## Bash discipline
+
+1. Prefer commands that are quiet by default; add flags when needed (`-q`, `--silent`,
+   `--no-progress`, `2>&1 | tail -n 20`).
+2. If long output is unavoidable, redirect it to a temp file and grep/tail only the
+   relevant part into context:
+   `npm install > /tmp/install.log 2>&1; tail -n 5 /tmp/install.log`
+3. Stack traces: keep the full trace in a file if needed, but read only the header
+   and the first error frames - never paste hundreds of lines into context.
+4. Never run a command again just to "see the output again" - grep the saved file.
+
+## Web discipline
+
+1. One search per question. Extract the fact as a one-line note immediately.
+2. Do not re-search or re-fetch the same topic; do not open the page when the search
+   snippet already answers the question.
+3. Never quote a whole page back into context - the extracted line is the record.
+
+## File reads
+
+Follow scoutlock: segment reads (offset/limit) before full reads, never re-read
+unchanged files.
+
+## When a huge result lands anyway
+
+Summarize it to one line internally and reason from that summary onward. Never echo,
+quote, or re-read the raw blob.
+
+## Rules
+
+- Extraction over ingestion: get the 1 fact, leave the 10k tokens behind.
+- Silence is free: a flag that prevents output costs nothing; filtering it later
+  still pays for generating it.

package/skills/scoutlock/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: scoutlock
+description: >
+  Token-efficient codebase exploration: read documentation before code, search with
+  narrow targeted queries, batch parallel lookups, and delegate broad hunts to a
+  subagent. Use BEFORE any multi-file exploration, when about to run the 3rd search
+  for the same thing, when user says "cari", "dimana", "explore", "carikan", or when
+  you notice grep/read results piling up without answering the question.
+---
+
+Exploration burns more tokens than writing code. Search with intent or not at all.
+
+## Step 0 - Docs first
+
+Before touching any code-search tool, check documentation in this order:
+
+1. Obsidian vault if connected: project index, architecture notes (backend/frontend),
+   progress file - these state what exists and where by design.
+2. Otherwise: `README.md`, `docs/` folder, root-level `*.md`.
+
+Code search only fills gaps the docs do not answer. If docs name the exact file or
+module, go straight to it - skip searching entirely.
+
+## Protocol
+
+1. **State the target** in one line before the first tool call: what symbol/fact is
+   needed and why.
+2. **Cheapest tool first:** glob for filenames → narrow grep (specific identifier +
+   file-pattern filter like `*.ts`) → read a segment (offset/limit) → full file read
+   only if it is small or genuinely needed whole.
+3. **Batch parallel:** send independent searches in one turn, not one per turn.
+4. **Never re-read** a file that has not changed since you last read it.
+5. **Delegate broad hunts:** if finding the answer needs more than 3 search rounds,
+   hand it to an explore subagent with a precise question; only its final answer
+   enters main context, not the search noise.
+6. **Tests smallest-first:** run one test function/file to verify locally; full
+   suite at most once, at the end.
+7. **Stop-rule:** the same search failing 3 times → stop, report what was tried and
+   what is known so far, ask the user.
+
+## Rules
+
+- No fishing expeditions: never grep a generic word ("data", "handler") unfiltered.
+- One question per search: know what answer would end the hunt before running it.
+- If mid-hunt the target changes, restate it - do not drift into reading whatever
+  looks interesting.

package/skills/tokenfreez/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: tokenfreez
+description: >
+  Freezes session state into FREEZE.md at project root so long conversations can be
+  restarted cheaply in a fresh session. Replaces expensive chat history with one small
+  file read. Use when user says "freeze", "tokenfreez", "freeze session", "save session",
+  "resume", "lanjutkan dari freeze", or complains about long/expensive context. Also
+  proactively suggest freezing when context grows large, a task completes, or the
+  topic switches.
+---
+
+Freeze session state into a file. Chat history is resent as input tokens every turn
+and grows costly; FREEZE.md is read once. Swap expensive storage for cheap storage.
+
+## Freeze Procedure
+
+Triggered by explicit request ("freeze", "tokenfreez") or when the user accepts an
+auto-suggestion. Do this:
+
+1. Summarize the current session state.
+2. Overwrite `FREEZE.md` at the project root using this exact format:
+
+```markdown
+# FREEZE — <project> — <YYYY-MM-DD HH:MM>
+
+## Active Task
+<one line: what is being worked on right now>
+
+## Decisions
+- <decision> — <why>
+
+## Done
+- [x] <completed item>
+
+## Pending / Next Steps
+- [ ] <next action>
+
+## Key Files
+- <path> — <why it matters>
+```
+
+3. Tell the user exactly: run `/new`, then say "resume from FREEZE.md".
+
+## Restore Procedure
+
+When a session starts and the user says "resume", "lanjutkan", or mentions FREEZE.md:
+
+1. Read `FREEZE.md` from the project root before answering anything else.
+2. Treat it as the source of truth for prior context.
+3. If its claims look stale (files moved, checklist items already done), verify
+   against the actual files and refresh FREEZE.md.
+
+## Auto-Suggest Rules
+
+Proactively offer a freeze (one short sentence, do not nag) when:
+
+- A task or milestone just completed.
+- Large tool outputs have accumulated this session.
+- The user switches to an unrelated topic.
+
+## Rules
+
+- **Overwrite, never append.** One file, always current. Keep it under ~100 lines.
+- **No secrets** in FREEZE.md: no keys, tokens, passwords, credentials.
+- Compress ruthlessly: decisions and next steps over narrative.
+- If FREEZE.md already exists, update it in place rather than asking.