tink-harness 1.0.0

package/templates/tink/harnesses/harness-synthesis.md

@@ -0,0 +1,52 @@
+# harness-synthesis
+
+## When to use
+Existing harnesses feel generic, or the task needs a domain-specific procedure built from research, failures, user feedback, or repeated work. Use it for both `no fit` and `generic fit` cases when the synthesis probe shows reusable domain rules.
+
+Use this to create harnesses such as:
+- `accessibility-regression-gate`
+- `customer-interview-synthesis`
+- `nextjs-rsc-boundary-refactor`
+- `pre-pr-security-gate`
+- `pricing-copy-experiment`
+- `weekly-trend-report-validation`
+
+## Ask first
+- What recurring task or failure should this harness improve?
+- What research, notes, run history, or examples should it learn from?
+- What must the harness do better than a generic skill recommendation?
+- Should the draft be used once, saved after this run, or saved immediately after approval?
+
+Do not repeat questions already answered in `.tink/current/answers.md`.
+
+## Plan
+1. Gather only the relevant inputs: harness index, approved memory, user correction, run notes, research notes, and target files.
+2. Extract behavior-shaping rules, not trivia: triggers, decisions, checks, stop conditions, recovery, and evidence.
+3. Decide the draft level: run-only draft by default, save candidate only when reuse evidence is strong or the user asks.
+4. Draft one small harness with a specific name and clear `When to use` boundary.
+5. Make it operational: include ask-first questions, step order, checks, done criteria, and failure recovery.
+6. Score the draft before proposing save:
+   - specificity: not just a generic checklist
+   - actionability: changes what Claude does next
+   - verifiability: has evidence and checks
+   - reuse likelihood: likely to apply again
+   - context cost: small enough to load often
+7. Use it for the current run after approval.
+8. Save to `.tink/harnesses/<name>.md` and update `index.json` only after separate save approval. A normal run approval only permits a run-only draft in `.tink/current/`.
+
+## Checks
+- The new harness or run-only draft has the required sections for its level.
+- The name is specific, lowercase, and hyphenated.
+- It does not duplicate an existing harness.
+- It includes `.tink/current/answers.md` reuse guidance.
+- It contains no secrets, raw logs, full diffs, or one-off task state.
+- It would have changed at least one decision in the current task.
+- A run-only draft is not written to `.tink/harnesses/`, `index.json`, or the ledger without separate save approval.
+
+## Done means
+- The draft harness is either applied to this run as a run-only draft, saved with separate approval, or explicitly rejected.
+- If saved, `.tink/harnesses/index.json` includes the new harness metadata.
+- The final report states the source inputs, what rules were extracted, and why the harness is reusable.
+
+## If it fails, Tink back
+Return to a run-only draft. Do not save. State what made the harness too generic, duplicated, unverifiable, or too expensive in context, then propose the next smallest improvement.

package/templates/tink/harnesses/index.json

@@ -0,0 +1,157 @@
+[
+  {
+    "name": "code-change",
+    "kind": "built-in",
+    "context": "small",
+    "use_when": "Add, change, or refactor code with a clear scope.",
+    "asks": [
+      "What is the target?",
+      "What should not change?"
+    ],
+    "checks": [
+      "Related files only",
+      "Tests or clear reason not run",
+      "Diff evidence"
+    ]
+  },
+  {
+    "name": "bug-fix",
+    "kind": "built-in",
+    "context": "small",
+    "use_when": "Something is broken and needs a minimal fix.",
+    "asks": [
+      "How can it be reproduced?",
+      "Expected vs actual?"
+    ],
+    "checks": [
+      "Reproduced or reason stated",
+      "Root cause identified",
+      "Regression checked"
+    ]
+  },
+  {
+    "name": "research",
+    "kind": "built-in",
+    "context": "small",
+    "use_when": "Compare options, read docs, or collect grounded facts.",
+    "asks": [
+      "What decision should this support?",
+      "What sources matter?"
+    ],
+    "checks": [
+      "Decision named",
+      "Facts separated from guesses",
+      "Recommendation follows evidence"
+    ]
+  },
+  {
+    "name": "review",
+    "kind": "built-in",
+    "context": "small",
+    "use_when": "Review changes, risks, or a PR/diff.",
+    "asks": [
+      "What is the base?",
+      "What risks matter most?"
+    ],
+    "checks": [
+      "Correctness/security/data/UX risk addressed",
+      "Severity labeled per finding",
+      "No speculative blockers"
+    ]
+  },
+  {
+    "name": "docs",
+    "kind": "built-in",
+    "context": "tiny",
+    "use_when": "Write or improve README, guides, PRDs, or user-facing docs.",
+    "asks": [
+      "Who is the reader?",
+      "What should they do next?"
+    ],
+    "checks": [
+      "Audience clear",
+      "Examples included if useful",
+      "Plain language"
+    ]
+  },
+  {
+    "name": "ship",
+    "kind": "built-in",
+    "context": "small",
+    "use_when": "Prepare a PR, release, deployment, or public handoff.",
+    "asks": [
+      "What is shipping?",
+      "What rollback or risk matters?"
+    ],
+    "checks": [
+      "CI checks pass or skip reason stated",
+      "Rollback documented",
+      "Known risks explicit"
+    ]
+  },
+  {
+    "name": "harness-synthesis",
+    "kind": "meta",
+    "context": "small",
+    "use_when": "Create a domain-specific harness from research, failures, user feedback, or repeated work when generic harnesses are not enough.",
+    "asks": [
+      "What recurring task or failure should improve?",
+      "What research or examples should it learn from?"
+    ],
+    "checks": [
+      "Specific and non-duplicative",
+      "Operational checks and done criteria",
+      "Saved only after approval"
+    ]
+  },
+  {
+    "name": "harness-curation",
+    "kind": "meta",
+    "context": "small",
+    "use_when": "Choose, replace, synthesize, weave, or frog harnesses when too many tools or heavy workflows would hurt the current task. Also use when context or prompt habits need calibration across runs.",
+    "asks": [
+      "What is the current task and success evidence?",
+      "What constraint makes heavy harnesses risky?"
+    ],
+    "checks": [
+      "Smallest effective set chosen",
+      "Heavy harnesses rejected or deferred with reason",
+      "Maintenance saved only after approval"
+    ]
+  },
+  {
+    "name": "pre-publish-multi-agent-verify",
+    "kind": "synthesized",
+    "context": "small",
+    "use_when": "Verify a public publish/release across multiple isolated environments with parallel agents — install matrix, UX walkthrough, doc consistency, leak audit, slash/contract coverage. Use when generic ship checks miss broad surface (npm/PyPI/GitHub Release/Docker Hub).",
+    "asks": [
+      "What package/artifact ships to which medium?",
+      "What 2-4 user-target scenarios should agents share as the verification target?",
+      "What isolation mechanism (git worktree, temp dir, container)?"
+    ],
+    "checks": [
+      "Build artifact produced and recorded",
+      "User-target scenarios locked before agents start",
+      "Each agent owns one concern, ≤300 words, evidence-only",
+      "Findings classified blocker/major/minor/nit",
+      "CHANGELOG [Unreleased] merged into the shipping version",
+      "No secrets, credentials, or private paths in published files",
+      "Advertised commands/API present in shipped artifact (sha 1:1)"
+    ]
+  },
+  {
+    "name": "tink-feedback-apply",
+    "kind": "built-in",
+    "context": "small",
+    "use_when": "User gives feedback about Tink's behavior, interaction pattern, or output quality — classify the feedback layer and apply the minimum fix.",
+    "asks": [
+      "What exactly went wrong or felt wrong?",
+      "Should this fix persist for future sessions?"
+    ],
+    "checks": [
+      "Correct layer identified",
+      "Minimum viable change only",
+      "Triggering scenario verified"
+    ]
+  }
+]

package/templates/tink/harnesses/pre-publish-multi-agent-verify.md

@@ -0,0 +1,44 @@
+# pre-publish-multi-agent-verify
+
+## When to use
+공개 publish/release/배포 직전 — 단일 에이전트 검토로는 놓치기 쉬운 광범위한 표면(install, UX, docs, leak, slash, contract)을 여러 격리 환경에서 병렬 검증해야 할 때. `ship`의 일반 체크리스트로는 부족하고, npm/crates/PyPI 같은 되돌리기 어려운 매체로 배포할 때 특히 가치 있음.
+
+## Ask first
+- 어떤 패키지/아티팩트를 어떤 매체로 publish하는가? (npm/PyPI/GitHub Release/Docker Hub …)
+- 사용자 표적 시나리오 3개는 무엇인가? (검증 시작 *전*에 잠그기)
+- 격리 환경은 무엇인가? (git worktree / 임시 디렉토리 / 컨테이너)
+
+## Domain rules
+1. **시나리오 사전 잠금**: 검증 시작 전에 사용자 표적 시나리오 2~4개를 못박는다. 에이전트가 각자 다르게 해석하면 보고가 흩어진다.
+2. **격리 강제**: 각 에이전트는 별도 worktree 또는 임시 디렉토리에서 작업. 본 repo의 working tree를 더럽히지 않는다.
+3. **에이전트당 관심사 1개**: install matrix / UX walkthrough / doc consistency / leak audit / slash·contract coverage. 한 에이전트가 두 관심사를 겸하지 않는다.
+4. **Evidence-only**: 보고는 "느낌상 불편함" 거부. file:line, 명령 stdout, exit code, sha 비교 같은 재현 가능한 증거만 인정.
+5. **300단어 상한**: 에이전트당 보고 ≤300단어. 합산이 가능해진다.
+6. **분류 4단계**: blocker / major / minor / nit. 각 에이전트가 자체 분류 후 메인이 합산 시 재조정 가능.
+7. **CHANGELOG 정직성**: docs-consistency는 반드시 `[Unreleased]` ↔ `[버전]` 병합 여부 확인. 이번 버전이 ship하는 모든 항목이 해당 버전 entry에 적혀 있어야 한다.
+
+## Plan
+1. tarball/build artifact 생성 (`npm pack`, `cargo package`, `python -m build` 등) — 정상 산출 확인.
+2. 사용자 표적 시나리오를 사용자와 함께 잠근다 (소프트 게이트가 아닌 하드 게이트).
+3. 5개(또는 도메인에 맞춰 3~6개) 에이전트를 격리 환경에서 병렬 실행.
+4. 보고 합산 + blocker/major/minor/nit 분류.
+5. publish 가/부 권고 + 사용자 결정.
+
+## Checks
+- Build artifact 생성 정상 (sha 기록).
+- 모든 에이전트 verdict 수집.
+- blocker 0건 확인 후에만 publish 권고.
+- CHANGELOG `[Unreleased]` 비어 있거나 v+1을 위한 것만 남아 있음.
+- 광고된 모든 명령/슬래시/API surface가 실제로 출하 산출물에 존재 (sha 1:1 또는 명시적 차이 문서화).
+- 비밀/credentials/개인 경로 누출 없음.
+
+## Done means
+- 각 에이전트 PASS/FAIL + evidence가 합산 보고에 기록됨.
+- blocker/major/minor/nit 분류 명시.
+- publish 가/부 권고와 그 근거가 사용자에게 전달됨.
+
+## If it fails
+- blocker 1+ → publish 차단. 마지막 안전 지점(이전 정상 버전)에서 fix 후 재검증.
+- major 2+ → 사용자에게 go/no-go 결정 요청. 각 major 별 fix 후보 제시.
+- minor만 → publish OK 권고 + 후속 fix 큐에 추가.
+- 에이전트 보고가 모순될 때는 사용자 표적 시나리오를 기준으로 재해석.

package/templates/tink/harnesses/research.md

@@ -0,0 +1,31 @@
+# research
+
+## When to use
+Compare options, read docs, or collect grounded facts.
+
+## Ask first
+- What decision should this support?
+- Which sources or constraints matter?
+- How current does the answer need to be?
+
+## Plan
+1. Define the question.
+2. Collect sources.
+3. Separate facts from guesses.
+4. Summarize tradeoffs.
+5. Recommend the next action.
+
+## Checks
+- Decision this research supports is named.
+- At least two options or sources are compared.
+- Facts and guesses are explicitly labeled.
+- Recommendation follows from evidence, not preference.
+- Do not repeat questions already answered in `.tink/current/answers.md`.
+
+## Done means
+- Sources are linked.
+- Uncertainty is labeled.
+- Recommendation follows from evidence.
+
+## If it fails, Tink back
+Return to the last safe step. State what failed, the last safe point, and the next single action.

package/templates/tink/harnesses/review.md

@@ -0,0 +1,31 @@
+# review
+
+## When to use
+Review changes, risks, or a PR/diff.
+
+## Ask first
+- What should be reviewed?
+- What is the base or expected behavior?
+- Which risks matter most?
+
+## Plan
+1. Inspect changed files.
+2. Prioritize correctness, security, data, and UX risks.
+3. Check tests or evidence.
+4. Write actionable findings only.
+5. Avoid unsupported style noise.
+
+## Checks
+- Correctness, security, data, and UX risk each addressed or noted absent.
+- Each finding has a severity label (blocker / major / minor / nit).
+- No speculative blockers — each is reproducible or evidence-based.
+- No unrelated style or preference noise.
+- Do not repeat questions already answered in `.tink/current/answers.md`.
+
+## Done means
+- Findings are reproducible or evidence-based.
+- Severity is clear.
+- No speculative blockers.
+
+## If it fails, Tink back
+Return to the last safe step. State what failed, the last safe point, and the next single action.

package/templates/tink/harnesses/ship.md

@@ -0,0 +1,33 @@
+# ship
+
+## When to use
+Prepare a PR, release, deployment, or public handoff.
+
+Release/publish/deploy/PR are hard-gate territory: cast triggers a Stitch safety hard gate during initial approval when this harness is selected.
+
+## Ask first
+- What is shipping?
+- What checks are required?
+- What rollback or risk matters?
+
+## Plan
+1. Summarize changes.
+2. Run or verify required checks.
+3. Draft PR or release summary: what changed, what risks, what rollback.
+4. State risks and rollback.
+5. Confirm final handoff.
+
+## Checks
+- All required CI checks pass, or reason for skip is stated.
+- Rollback or revert procedure is documented.
+- Changed artifacts (files, package, version) are listed.
+- Known risks are explicitly stated, not implied.
+- Do not repeat questions already answered in `.tink/current/answers.md`.
+
+## Done means
+- Checks are complete or clearly blocked.
+- Known risks are stated.
+- Handoff is short and usable.
+
+## If it fails, Tink back
+Return to the last safe step. State what failed, the last safe point, and the next single action.

package/templates/tink/harnesses/tink-feedback-apply.md

@@ -0,0 +1,37 @@
+# tink-feedback-apply
+
+## Trigger
+사용자가 Tink의 동작, 상호작용 패턴, 출력 품질에 대해 피드백을 줄 때 — 멈춰야 할 것, 바꿔야 할 것, 개선해야 할 것.
+
+## Domain rules
+
+### 1. 피드백 분류
+- **behavioral rule**: cast/frog/weave가 어떻게 행동해야 하는지
+- **UX pattern**: 상호작용 흐름 (무엇을 보여줄지, 무엇을 건너뛸지)
+- **preference**: 지속 선호 (톤, 언어, 상세도)
+- **harness procedure**: 특정 하네스 절차가 틀렸거나 빠진 단계가 있음
+- **new harness**: 반복 작업에 별도 하네스 필요
+
+### 2. 레이어 위치
+- behavioral / UX → `commands/cast.md` — 3-layer 동시 수정: `.claude/commands/tink/`, `templates/claude/commands/tink/`, `commands/`
+- preference → `.tink/memory/preferences.md`
+- harness procedure → `.tink/harnesses/<name>.md`
+- new harness → `.tink/harnesses/<name>.md` 생성 + `index.json` 업데이트
+
+### 3. 최소 유효 변경
+- 한 줄 또는 한 단락. 구조 재작성 금지.
+- "Do not" 규칙 → `## Do not` 섹션에 추가
+- 절차 단계 → 해당 단계만 수정
+
+### 4. 트리거 시나리오 검증
+- 피드백을 유발한 상황을 설명 형태로 재현
+- 변경이 그 상황을 방지했을지 확인
+
+## Checks
+- 올바른 레이어에 변경됐는지 (preference ≠ harness ≠ command)
+- 변경이 최소한인지 — 관련 없는 수정 없음
+- 트리거 시나리오 통과 (설명 형태)
+- command / harness / memory 파일 변경 시 Reusable State Save Gate 페이로드 직접 제시
+
+## Recovery
+변경이 다른 동작을 깨뜨리면, git으로 되돌리고 변경 범위를 더 좁혀서 재시도.

package/templates/tink/hooks/user-prompt-submit.json

@@ -0,0 +1,7 @@
+{
+  "name": "tink-cast-suggestion",
+  "description": "Optional Claude Code hook template. Use only after /tink:setup approval. It should provide short advisory-only automatic suggestions, not auto-apply harnesses.",
+  "event": "UserPromptSubmit",
+  "command": "node .tink/hooks/user-prompt-submit.mjs",
+  "behavior": "Registered as a Claude Code UserPromptSubmit hook only when the user selects the hook component. It reads the prompt from stdin, emits at most one advisory line when /tink:cast would help, and never auto-applies harnesses or saves memory."
+}

package/templates/tink/hooks/user-prompt-submit.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function safeJson(text) {
+  try {
+    return JSON.parse(text || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function readConfigLanguage() {
+  try {
+    const cfg = safeJson(fs.readFileSync('.tink/config.json', 'utf8'));
+    return cfg.language || 'auto';
+  } catch {
+    return 'auto';
+  }
+}
+
+const payload = safeJson(readStdin());
+const prompt = String(payload.prompt || payload.user_prompt || payload.message || '');
+const language = readConfigLanguage();
+
+if (!prompt.trim()) process.exit(0);
+if (prompt.trim().startsWith('/')) process.exit(0);
+
+const nonTrivialSignals = [
+  /fix|debug|refactor|implement|review|ship|deploy|research|investigate/i,
+  /버그|수정|구현|검토|배포|조사|정리|개선/,
+  /\b(파일|repo|PR|테스트|CI|로그)\b/i
+];
+
+if (nonTrivialSignals.some((pattern) => pattern.test(prompt))) {
+  const message = language === 'en'
+    ? 'Tink suggestion: for complex work, run /tink:cast first to choose a harness and create run state.'
+    : language === 'zh'
+      ? 'Tink 建议：复杂任务可以先运行 /tink:cast，选择 harness 并创建运行状态。'
+      : 'Tink 제안: 복잡한 작업이면 /tink:cast로 하네스와 실행 상태를 먼저 잡을 수 있습니다.';
+  console.log(message);
+}

package/templates/tink/maintenance/weave-queue.json

@@ -0,0 +1,3 @@
+{
+  "items": []
+}

package/templates/tink/memory/lessons.md

@@ -0,0 +1,17 @@
+# Lessons
+
+Record reusable lessons that improve future harness choices.
+
+Rules:
+- Save only after user approval.
+- Save generalized lessons, not raw transcripts.
+- Keep entries short.
+- Prefer harness updates when the lesson belongs inside a specific harness.
+- Use compact evidence handles so future hone/purge decisions can trace the entry.
+
+Entry shape:
+```text
+- [YYYY-MM-DD] kind=lesson; source=<run-id|user>; applies_to=<harness|global>; note=<one sentence>; approval=<op-id>
+```
+
+## Entries

package/templates/tink/memory/mistakes.md

@@ -0,0 +1,16 @@
+# Mistakes
+
+Record repeated mistakes that should not happen again.
+
+Rules:
+- Save only after user approval.
+- Keep entries short and reusable.
+- Do not store raw logs, full diffs, secrets, private data, or one-off task progress.
+- Use compact evidence handles so future hone/purge decisions can trace the entry.
+
+Entry shape:
+```text
+- [YYYY-MM-DD] kind=mistake; source=<run-id|user>; applies_to=<harness|global>; note=<one sentence>; approval=<op-id>
+```
+
+## Entries

package/templates/tink/memory/preferences.md

@@ -0,0 +1,16 @@
+# Preferences
+
+Record stable project or user preferences that reduce repeated steering.
+
+Rules:
+- Save only after user approval or explicit instruction.
+- Use short declarative bullets.
+- Do not store temporary task state.
+- Use compact evidence handles when the preference came from a run.
+
+Entry shape:
+```text
+- [YYYY-MM-DD] kind=preference; source=<run-id|user>; applies_to=<harness|global>; note=<one sentence>; approval=<op-id|explicit-user>
+```
+
+## Entries