tink-harness 1.0.0

package/commands/setup.md

@@ -0,0 +1,185 @@
+---
+description: Configure Tink language, install scope, git tracking, and hook policy.
+---
+
+# /tink:setup
+
+Set up Tink for Claude Code.
+
+## Goal
+Prepare one small self-growing harness system that helps Claude choose/build harnesses, avoid repeated mistakes, and remember reusable lessons only after approval.
+
+## Interaction policy
+Always call the `AskUserQuestion` tool for choice prompts. Do not render `❯` text format. Do not ask the user to type a number inline.
+
+Map prompt content to `AskUserQuestion` fields:
+- `question`: the full question text
+- `header`: max 12-character tag (e.g. "언어 선택", "설치 범위", "Git 설정")
+- `label`: 1–5 word option name. Add "(권장)" if recommended.
+- `description`: explanatory text for the option
+
+Use Korean field values when `.tink/config.json` language is `ko` or `auto` with Korean input; use English otherwise.
+
+## Setup review mode
+If `.tink/config.json` already exists, do not jump straight to git tracking. First show a short current-settings review, then ask what to change.
+
+Use this wording in Korean:
+
+```text
+현재 Tink 설정입니다.
+
+- 언어: {language}
+- 범위 (Scope): {install_scope}
+- 톤 (Tone): calm, clear, concise, no jokes
+- Hook: {hook_scope}
+- Git 추적: {git_policy_or_inferred_policy}
+
+톤은 선택 항목이 아니라 Tink의 고정 정책입니다. 조용하고 명확하게, 농담 없이 답하는 것을 기본으로 합니다.
+
+? 무엇을 바꿀까요?
+❯ 1. 그대로 사용 (권장)
+  2. 언어 변경
+  3. 범위 변경
+  4. 훅/Git 변경
+```
+
+If the user chooses `그대로 사용`, summarize available commands and stop. Do not re-ask git tracking.
+If the user chooses `훅/Git 변경`, first walk through the Git tracking question, then the Hook registration question.
+
+## Legacy Tiny migration
+If `.tiny/`, `.claude/commands/tiny/`, `.claude/commands/tiny-use.md`, or output that recommends `/tiny:use` is present, treat it as legacy state from the old Tiny/Tink prototype. Do not keep recommending `/tiny:use`.
+
+Show this short explanation before changing files:
+
+```text
+이전 Tiny 설정이 보입니다.
+
+Tink v1에서는 `/tiny:use` 대신 `/tink:cast`를 사용합니다.
+필요하면 기존 `.tiny/`의 harness/config/memory를 `.tink/`로 옮기고, 앞으로의 안내를 `/tink:cast` 기준으로 정리할 수 있습니다.
+
+? 어떻게 할까요?
+❯ 1. 이전 Tiny 설정을 Tink로 옮기기
+  2. 이전 Tiny 설정은 그대로 두고 Tink만 사용하기
+  3. 취소
+```
+
+Only migrate after the user chooses option 1. Migration means copying useful `.tiny/harnesses/`, `.tiny/config.json`, and `.tiny/memory/` into `.tink/` without deleting the original unless the user explicitly asks. Update stale guidance so future next steps say `/tink:cast`, not `/tiny:use`.
+
+## First question: language
+Always ask language first if it is not already clear from `.tink/config.json`.
+
+```text
+? 언어를 선택해주세요.
+❯ 1. 한국어
+  2. English
+  3. 中文
+```
+
+Use the selected language for setup prompts, run files, approval prompts, and final reports. Keep built-in harness IDs in English for stable filenames.
+
+## Before asking choices
+Explain the current files in plain language before asking the user to choose. Keep the explanation short.
+
+Use this wording in Korean:
+
+```text
+Tink는 두 종류의 파일을 씁니다.
+
+1. 재사용 하네스 (Reusable Harnesses): `.tink/harnesses/`
+   작업 방식 템플릿입니다. 예: bug-fix, research, review.
+   팀이 같이 쓰면 유용하므로 보통 git에 커밋합니다.
+
+2. 실행 상태 (Run State): `.tink/current/`, `.tink/runs/`, `.tink/cache/`
+   이번 작업 계획, 체크, 임시 메모입니다.
+   개인/임시 기록이라 기본적으로 git에서 제외합니다.
+```
+
+## Setup questions
+Ask these questions in order. Use the `AskUserQuestion` tool for all choice prompts (see Interaction policy above).
+
+### 1. Scope
+```text
+? Tink를 어디에 설정할까요?
+❯ 1. Repo 범위 (Repo Scope, 권장)
+     이 프로젝트에만 `.claude/`와 `.tink/`를 둡니다. 팀 공유와 프로젝트별 하네스에 적합합니다.
+  2. Global 범위 (Global Scope)
+     사용자 홈의 Claude Code 설정에 둡니다. 여러 프로젝트에서 같은 명령을 쓰고 싶을 때 적합합니다.
+```
+
+There is no `Both` option by default.
+
+### 2. Git tracking
+Ask only after explaining consequences.
+
+```text
+? 프로젝트 하네스 (Harness)를 git에 커밋할까요?
+
+먼저 차이를 설명합니다.
+
+❯ 1. 하네스만 커밋 (Harnesses only, 권장)
+   좋은 점:
+   - 팀원과 같은 작업 방식, 체크리스트, 선호를 공유합니다.
+   - 다른 PC나 새 clone에서도 Tink가 같은 기준으로 동작합니다.
+   - 실행 기록은 빠져서 repo가 지저분해지지 않습니다.
+
+   실제로 커밋되는 것:
+   - `.tink/harnesses/`: 작업 방식 템플릿
+   - `.tink/config.json`: 언어/scope 같은 기본 설정
+   - `.tink/memory/`: 승인된 반복 실수, 선호, 교훈
+
+   제외되는 것:
+   - `.tink/current/`, `.tink/runs/`, `.tink/cache/`: 이번 실행 기록/임시 상태
+
+  2. 전부 커밋
+   좋은 점:
+   - 실행 과정까지 전부 남길 수 있습니다.
+   주의:
+   - 임시 메모, 작업 중 파일, 개인 맥락이 섞일 수 있어 대부분 비권장입니다.
+
+  3. 커밋 안 함
+   좋은 점:
+   - repo에는 아무 흔적을 남기지 않고 개인 도구로만 씁니다.
+   결과:
+   - 다른 팀원, 다른 PC, 새 clone에서는 harness가 공유되지 않습니다.
+   - 프로젝트별로 쌓은 개선이 유실되거나 재설정이 필요할 수 있습니다.
+```
+
+### 3. Hook registration
+Hook is optional and off by default. If selected in the installer, it is registered as a Claude Code `UserPromptSubmit` hook. Do not ask for hook scope again. Use the already selected repo/global scope.
+
+Explain:
+
+```text
+Hook은 선택 사항입니다.
+
+무엇을 하나요?
+- Claude Code `UserPromptSubmit`에 등록되어 일반 사용자 프롬프트를 보고 “/tink:cast를 먼저 쓰면 좋겠다”는 추천만 합니다.
+- 작업을 자동 실행하지 않습니다.
+- 메모리 (Memory)나 하네스 (Harness)를 자동 저장하지 않습니다.
+- `/grill-me` 같은 다른 slash skill 명령은 가로채지 않습니다.
+
+지금은 hook 없이 `/tink:cast`를 직접 쓰는 흐름을 권장합니다.
+```
+
+## Command map after setup
+Explain the five commands:
+
+```text
+사용 가능한 Tink 명령입니다.
+
+- `/tink:setup`: 언어, repo/global 범위 (Scope), git 추적, 훅 (Hook) 정책을 정합니다.
+- `/tink:cast`: 작업에 맞는 하네스 (Harness)를 고르거나 만들고, 적용하고, 재사용 교훈을 저장 제안합니다. 가장 자주 쓰는 명령입니다.
+- `/tink:list`: 사용 가능한 하네스 (Harness)와 최근 사용 신호를 짧게 보여줍니다.
+- `/tink:frog`: 거의 쓰지 않는 하네스 (Harness)를 근거와 함께 제거 후보로 제안합니다. 승인 전 삭제하지 않습니다.
+- `/tink:weave`: 자주 쓰는 하네스 (Harness)를 실제 실패/반복/피드백 기준으로 개선합니다. 승인 전 저장하지 않습니다.
+```
+
+## Do not
+- Do not edit `CLAUDE.md` automatically.
+- Do not ask the user to choose before explaining the consequences.
+- Do not ask for tone selection. Tone is a fixed Tink policy, not a setup choice.
+- Do not use jokes.
+- Do not intercept other slash commands with Tink hooks.
+
+## Tone
+Calm, clear, concise. No jokes. Show this as a fixed policy during setup review; do not turn it into another preference menu.

package/commands/update.md

@@ -0,0 +1,90 @@
+---
+description: Detect install source, diagnose user-modified files, and show the safe update command.
+---
+
+# /tink:update
+
+Tink를 최신 버전으로 안전하게 업데이트하는 방법을 안내합니다.
+
+## What this command does
+This command does not run the update itself. It detects how Tink was installed in this project, diagnoses whether any user-modified files are at risk, and shows the correct command to run.
+
+## Procedure
+1. **Source-repo guard (first):** If the project root contains all of `templates/tink/`, `bin/install.js`, and a `package.json` whose `name` is `"tink-harness"`, this is the tink-harness source repository itself — not a consumer install. Skip the rest of the procedure and emit the "source repo" output (see below). Do not show plugin or npx update commands in this case.
+2. Detect install source:
+   - If the project root (or `cwd`) has `.claude-plugin/plugin.json` and a top-level `commands/` directory, Tink was installed via Claude Code plugin marketplace.
+   - Otherwise, treat it as an `npx tink-harness install` (standalone) installation.
+3. Scan for files that have diverged from the latest installed templates (read-only inspection only):
+   - **Always updated**: `.claude/commands/tink/`, `.claude/skills/tink/`, `.tink/maintenance/` — template changes always propagate here.
+   - **Preserved if user-modified**: `.tink/harnesses/`, `.tink/hooks/`, `.tink/memory/`, `.tink/config.json` — respects `weave` customizations and local configuration.
+4. Show the appropriate update path and a short list of files in the "preserved" category that have diverged.
+
+## Update path: Claude Code plugin
+```text
+/plugin marketplace update tink-harness
+/plugin update tink@tink-harness
+/reload-plugins
+```
+If update is not detected, uninstall and reinstall:
+```text
+/plugin uninstall tink@tink-harness
+/plugin install tink@tink-harness
+```
+The plugin path is handled by Claude Code and does not touch the local `.tink/` directory.
+
+## Update path: npx (standalone)
+```text
+npx tink-harness update
+```
+Before v1.0.0 publish:
+```text
+npx github:dotoricode/tink-harness update
+```
+
+The `update` subcommand:
+- **Always overwrites**: commands, skills, and maintenance files (`.claude/commands/tink/`, `.claude/skills/tink/`, `.tink/maintenance/`) — so you get the latest harness runner and command behavior automatically.
+- **Preserves if modified**: harnesses, hooks, memory, and config (`.tink/harnesses/`, `.tink/hooks/`, `.tink/memory/`, `.tink/config.json`) — respects your `weave` customizations and local settings.
+
+## Output format (source repo)
+
+If the source-repo guard triggers, print only this and stop — do not present plugin or npx commands:
+
+```text
+### 🧶 Tink 업데이트 안내
+
+이 디렉토리는 tink-harness **소스 리포지토리**입니다. 일반 사용자 업데이트 대상이 아니에요.
+
+- 개발 변경 반영: `git pull` 후 일반적인 빌드/테스트 흐름을 사용하세요.
+- 사용자 환경에서 업데이트 흐름을 검증하려면 별도의 프로젝트 디렉토리에서 이 명령을 실행하세요.
+```
+
+## Output format
+
+```text
+### 🧶 Tink 업데이트 안내
+
+**설치 경로**: <plugin marketplace | npx standalone>
+
+**항상 업데이트됨**: commands, skills, maintenance (최신 버전으로 자동 반영)
+
+**사용자 수정 파일** (업데이트 시 보존):
+- <path1>
+- <path2>
+- (보존할 파일 없음)
+
+**업데이트 명령**:
+<command lines>
+
+? 어떻게 할까요?
+1. 위 명령 복사해서 직접 실행
+2. 변경 사항 미리 보기 (`npx tink-harness update --dry-run`)  ← npx standalone에서만 표시
+3. 취소
+```
+
+Use `AskUserQuestion`. Show option 2 (dry-run) **only on the npx standalone path** — Claude Code plugin updates have no dry-run equivalent. So: plugin path → 2 options (run / cancel); npx path → 3 options (run / dry-run / cancel).
+
+## Do not
+- Do not actually run the update command — show it for the user to run in their shell or Claude Code.
+- Do not modify `.tink/` files during diagnosis.
+- Do not bypass the user choice; always offer cancel.
+- Do not present plugin or npx update commands when the source-repo guard triggers — the user is editing tink-harness itself and would get misleading instructions.

package/commands/weave.md

@@ -0,0 +1,81 @@
+---
+description: Improve active harnesses based on real use, failures, and corrections.
+---
+
+# /tink:weave
+
+Improve harnesses that are actually being used.
+
+## Purpose
+Tink should get sharper through use, not grow randomly.
+
+## Interaction policy
+Always call the `AskUserQuestion` tool for choice prompts. Do not render `❯` text format. Do not ask the user to type a number inline.
+
+Map prompt content to `AskUserQuestion` fields:
+- `question`: the full question text
+- `header`: max 12-character tag (e.g. "진행 방식", "저장 여부")
+- `label`: 1–5 word option name. Add "(권장)" if recommended.
+- `description`: explanatory text for the option
+
+Use Korean field values when `.tink/config.json` language is `ko` or `auto` with Korean input; use English otherwise.
+
+## Procedure
+1. Read `.tink/harnesses/index.json`. If invoked from `/tink:frog`, first read the purge output, `.tink/current/notes.md`, or `.tink/maintenance/weave-queue.json` for the weave handoff packet.
+2. Identify one or a few active harnesses to improve using real failures and evidence:
+   - repeated mistakes
+   - user corrections
+   - failed checks
+   - confusing approval prompts
+   - too much context footprint
+   - missing done criteria
+3. Require concrete evidence handles before proposing a save:
+   - run record path or run ID
+   - current notes path when same-conversation certainty exists
+   - failed check name
+   - compact user correction snippet
+   - purge handoff ID from `.tink/maintenance/weave-queue.json`
+4. Classify the evidence as repeated or single-run. Single-run evidence may suggest a trial edit, but should not become broad policy unless the user explicitly approves.
+5. Explain why the change belongs in the harness rather than `.tink/memory/` or `.tink/current/notes.md`.
+6. Read only the target harness files.
+7. Propose small edits:
+   - clearer when-to-use trigger
+   - better ask-first question
+   - tighter checks
+   - smaller context footprint
+   - explicit failure recovery
+8. Show an approval payload: destination files, exact patch summary, evidence handles, repeated vs single-run classification, why reusable, context-cost delta, sensitive content excluded, rollback path.
+9. Ask for approval before saving.
+10. Apply surgical changes, update index metadata if needed, mark the weave queue item status, and append the approval/result to `.tink/maintenance/ledger.jsonl`.
+
+## Approval format
+```text
+Hone target:
+- code-change
+
+Evidence:
+- source: `.tink/runs/2026-05-22-code-change.md`
+- classification: repeated
+- observed failure: verification command was unclear in two runs
+
+Approval payload:
+- operation: weave
+- destination files: `.tink/harnesses/code-change.md`, `.tink/harnesses/index.json` if metadata changes
+- context-cost delta: neutral or smaller
+- ledger: append op ID to `.tink/maintenance/ledger.jsonl`
+- rollback: revert this patch or rerun `/tink:weave` with the previous trigger
+
+Proposed improvement:
+- Checks 섹션에 “검증 명령과 실패 시 마지막 안전 지점 기록” 추가
+
+? 진행할까요?
+❯ 1. 승인 — 이 개선 저장
+  2. 조정
+  3. 취소
+```
+
+## Do not
+- Do not rewrite a harness from scratch unless the user asks.
+- Do not add broad principles that do not change behavior.
+- Do not save one-off task progress as harness knowledge.
+- Do not propose a harness edit without evidence handles.

package/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/templates/tink/hooks/user-prompt-submit.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "tink-harness",
+  "version": "1.0.0",
+  "description": "Self-growing harnesses for Claude Code.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "tink-harness": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    ".claude-plugin/",
+    "commands/",
+    "skills/",
+    "hooks/",
+    "README.md",
+    "CHANGELOG.md",
+    "VERSIONING.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "python tests/test_templates.py && node --check bin/install.js",
+    "check": "npm test"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "agent-harness",
+    "developer-tools",
+    "cli",
+    "automation",
+    "agentic-coding",
+    "llm",
+    "workflow-automation",
+    "code-agents",
+    "hooks",
+    "skills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotoricode/tink-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dotoricode/tink-harness/issues"
+  },
+  "homepage": "https://github.com/dotoricode/tink-harness#readme",
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/skills/tink/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: tink
+description: Self-growing harnesses for Claude Code. Use to cast, apply, frog, and weave task harnesses.
+---
+
+# Tink
+
+Tink helps Claude cast the smallest useful harness, materialize it as run state, and start the work. It keeps the active harness/tool set small because too many tools can hurt performance, and it can suggest small habit-aware calibrations from observed signals.
+
+## Core philosophy
+Tink is one self-growing skill, not a pile of commands and not a skill recommendation list.
+
+It should:
+1. understand the task,
+2. choose the smallest effective harness/tool set,
+3. replace heavy harnesses when the current stage or token budget makes them harmful,
+4. build or synthesize a narrow harness when none fits,
+5. apply it only after approval,
+6. create `.tink/current/` run state before deeper work,
+7. recommend small habit-aware calibrations from observed context/token/input/output/reset signals,
+8. execute the first safe step after approval,
+9. avoid repeating the same mistake,
+10. remember reusable lessons only after approval,
+11. keep the harness set small by purging or honing it over time.
+
+## Command surface
+Use only these commands:
+
+- `/tink:setup`: configure language, scope, git tracking, and hook policy.
+- `/tink:cast`: main path. Choose/build/synthesize a harness, run Stitch, create run state, start work, and propose reusable learning.
+- `/tink:list`: inspect harnesses and lightweight usage signals.
+- `/tink:frog`: propose unused or redundant harness removal. Never delete without approval.
+- `/tink:weave`: improve active harnesses based on real use, failures, and corrections.
+- `/tink:update`: detect install source, diagnose user-modified files, and show the safe update command.
+
+## Operating rules
+1. Read `.tink/harnesses/index.json` before loading harness bodies.
+2. Read small approved memory files when present: `.tink/memory/mistakes.md`, `preferences.md`, `lessons.md`.
+3. Prefer the smallest useful harness set. Use context footprint, not a universal hard cap: tiny harnesses may stack, large harnesses load one at a time after approval, and meta harnesses should reduce or replace context rather than pile on.
+4. If `.tink/current/` exists and continuity is uncertain, read the five current files, summarize goal / last safe point / next step / open questions / verification, then ask resume/archive/replace/cancel before continuing.
+5. Run the synthesis probe on the initial harness choice. The probe produces one of three outcomes: strong fit (0-1 yes), generic fit (2-3 yes), or no fit (4-5 yes or no harness matches). Strong fit keeps the harness; generic fit adds a run-only draft; no fit loads `harness-synthesis`.
+6. If no existing harness fits, use `harness-synthesis` to draft a narrow domain-specific harness instead of forcing a bad fit.
+7. If too many tools, skills, agents, or harnesses are available, use `harness-curation` to choose the smallest effective set before loading more context.
+8. If lightweight signals show recurring context, token, prompt-quality, output-length, reset, or evidence habits, use `harness-curation` to make one advisory recommendation.
+9. When research notes, examples, prior failures, or user corrections are available, extract behavior-shaping rules: triggers, decision rules, checks, stop conditions, recovery, and evidence.
+10. Run Stitch once before committing to `.tink/current/`: evaluate every time, show exactly one proposal only for high-impact quality or safety branches, and use configured language.
+11. Use soft Stitch choices `Approve`, `Add requirements`, `Continue as-is` or localized equivalents; use hard choices `Approve`, `Add requirements`, `Cancel` only.
+12. Hard gates must not offer `Continue as-is` or `이대로 진행`, and Stitch may change method or order but not the user's goal without separate approval.
+13. Treat Reusable State Save Gate as a separate hard approval gate for `.tink/memory/*`, `.tink/harnesses/*`, `.tink/config.json`, `.claude/`, and template/plugin files that affect future installs.
+14. Current-run approval never authorizes reusable-state writes; before saving reusable state, show operation, destination files, exact entry or patch summary, reusable reason, sensitive content excluded, and rollback/removal path.
+15. Ask for approval before applying, saving, purging, or honing.
+16. After approval, create `.tink/current/plan.md`, `checks.md`, `steps.json`, `notes.md`, and `answers.md`.
+17. Do not stop at recommendation. Execute the first safe step after run state exists.
+18. Store reusable memory under `.tink/memory/` only after separate Reusable State Save Gate approval.
+19. If a check fails, update `.tink/current/notes.md`, state the failure, last safe point, and next single action.
+20. Keep context compact. Do not paste raw logs or full diffs.
+21. Use calm, clear, concise language. Prefer plain everyday words over technical terms — if a simpler word works, use it. No jokes.
+
+## Quality bar
+The user should not have to repeat themselves. If the same mistake appears twice, propose `/tink:weave` or a memory update through `/tink:cast`.
+
+A successful Tink run leaves evidence:
+- current run files exist or were intentionally archived,
+- checks were verified or explicitly blocked,
+- the final answer reports changed files and evidence,
+- reusable learning is proposed only when it will matter again.