@deltafleet/goalkeeper 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to Goalkeeper are documented here.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.2.1] - 2026-05-18
+
+- Simplified public invocation copy to `Use goalkeeper for this goal.`
+- Rewrote the README problem example around a clearer long-session payment bug scenario.
+- Shortened the UI default prompt so users are not asked to spell out Goalkeeper internals.
+
 ## [0.2.0] - 2026-05-18
 
 - Renamed the public project to `goalkeeper`.

package/README.ja.md

@@ -39,15 +39,15 @@ Skill-compatible agent は、リクエストが metadata と強く一致する i
 
 そのため、次のような goal だけで有効になることがあります。
 
-> `/goal` Harden this release over a long-running session. Keep the goal, constraints, rejected paths, failed attempts, verification state, and next action recoverable after compact/resume.
+> `/goal` Harden this release over a long-running session. Use goalkeeper.
 
 ただし skill activation は routing decision であり、private agent runtime hook ではありません。Goalkeeper がすべての goal に強制的に自分を適用することはできません。
 
 重要な長期作業では、goal を作る時点、または goal 作成直後で本格作業に入る前に、明示的に呼び出すのがもっとも安全です。
 
-> Use goalkeeper for this `/goal`. Keep the goal, constraints, decisions, verification state, failed attempts, and next action recoverable across compaction.
+> Use goalkeeper for this goal.
 
-その後、ユーザーが Goalkeeper の helper script を手で実行する必要はありません。agent が skill workflow の一部として実行します。
+ユーザーが覚える必要がある文はここまでです。checkpoint、context pack、event log、失敗した試行、検証状態、helper script は、Goalkeeper workflow の中で agent が扱います。
 
 ## 問題
 
@@ -57,15 +57,15 @@ Skill-compatible agent は、リクエストが metadata と強く一致する i
 
 実際のセッションを想像してください。
 
-1. agent にリリース hardening を任せます。
-2. いちばん分かりやすい patch は目の前の bug を直しますが、rollback compatibility を壊す可能性があります。
-3. ユーザーは強い制約を置きます。database schema は変更せず、backward compatibility を維持する。
-4. 2 回目の試行は unit test を通りますが、integration edge case で失敗します。
-5. agent は compatibility shim と targeted regression test の組み合わせに決めます。
-6. regression test が通ります。このルートが安全なルートになります。
+1. agent に決済バグの修正を任せます。
+2. 早い段階で、`refunds` 周りのコードは legacy なので触るべきではないと分かります。
+3. 最速の patch は `refunds` を直接編集する方法なので、ユーザーはその方針を拒否します。
+4. agent は webhook handler 側に移そうとしますが、duplicate event のケースで失敗します。
+5. 最終的に service layer に idempotency guard を置き、regression test で検証するルートが通ります。
+6. テストが通ります。このルートが維持すべき安全なルートになります。
 7. コンテキストが compact されます。
-8. 後でエージェントは「release hardening はほぼ完了」というきれいな要約で戻ってきます。
-9. goal は残っています。しかし、なぜ schema shortcut を禁止し続ける必要があるのか、なぜ前の patch が失敗したのか、なぜその regression test が重要なのかは薄れているかもしれません。
+8. 後でエージェントは「決済バグはほぼ修正済み」というきれいな要約で戻ってきます。
+9. goal は残っています。しかし、`refunds` が触ってはいけない場所だったこと、webhook の試行が失敗したこと、service-layer test が安全なルートを証明したことは薄れているかもしれません。
 
 ここから drift が始まります。
 

package/README.ko.md

@@ -39,15 +39,15 @@ Skill-compatible agent는 설치된 skill 중 요청과 관련성이 높은 skil
 
 그래서 아래처럼 goal 자체가 충분히 분명하면 자동으로 붙을 수 있습니다.
 
-> `/goal` 이번 릴리스를 장기 세션으로 안정화해줘. compact/resume 이후에도 목표, 제약, 거부한 경로, 실패한 시도, 검증 상태, 다음 액션이 복구 가능하게 관리해줘.
+> `/goal` 이번 릴리스를 장기 세션으로 안정화해줘. goalkeeper를 사용해줘.
 
 하지만 skill 활성화는 agent runtime hook이 아니라 routing 판단입니다. Goalkeeper가 모든 goal에 자신을 강제로 붙일 수는 없습니다.
 
 중요한 장기 작업이라면 goal을 만들 때, 또는 goal을 만든 직후 본격 작업 전에 명시적으로 호출하는 편이 가장 안전합니다.
 
-> 이 `/goal`에는 goalkeeper를 사용해줘. 목표, 제약, 결정, 검증 상태, 실패한 시도, 다음 액션이 compact 이후에도 복구 가능하게 관리해줘.
+> 이 goal에는 goalkeeper를 사용해줘.
 
-그 다음부터 사용자가 Goalkeeper의 helper script를 직접 실행할 필요는 없습니다. agent가 skill workflow의 일부로 실행합니다.
+사용자가 기억할 문장은 여기까지입니다. checkpoint, context pack, event log, 실패한 시도, 검증 상태, helper script 같은 것은 Goalkeeper workflow 안에서 agent가 관리합니다.
 
 ## 문제
 
@@ -57,15 +57,15 @@ Skill-compatible agent는 설치된 skill 중 요청과 관련성이 높은 skil
 
 실제 세션을 상상해보면 이렇습니다.
 
-1. agent에게 릴리스 hardening을 맡깁니다.
-2. 가장 쉬운 patch는 눈앞의 bug는 고치지만 rollback compatibility를 깨뜨릴 수 있습니다.
-3. 사용자는 강한 제약을 둡니다. database schema는 바꾸지 말고, backward compatibility를 유지해야 합니다.
-4. 두 번째 시도는 unit test를 통과하지만 integration edge case에서 실패합니다.
-5. agent는 compatibility shim과 targeted regression test 조합으로 방향을 정합니다.
-6. regression test가 통과합니다. 이제 이 경로가 안전한 경로입니다.
+1. agent에게 결제 버그 수정을 맡깁니다.
+2. 초반 조사에서 `refunds` 쪽 코드는 레거시라 건드리면 안 된다는 사실이 드러납니다.
+3. 가장 빠른 patch는 `refunds`를 직접 고치는 방식이라, 사용자가 그 경로를 명시적으로 거부합니다.
+4. agent는 webhook handler 쪽으로 옮겨보지만, duplicate event 케이스에서 실패합니다.
+5. 결국 service layer에 idempotency guard를 두고 regression test로 막는 경로를 검증합니다.
+6. 테스트가 통과합니다. 이제 이 경로가 유지되어야 하는 안전한 경로입니다.
 7. 컨텍스트가 compact됩니다.
-8. 나중에 에이전트는 “release hardening은 거의 됨” 같은 깔끔한 요약으로 돌아옵니다.
-9. goal은 기억하지만, 왜 schema shortcut이 계속 금지되어야 하는지, 앞선 patch들이 왜 실패했는지, 그 regression test가 왜 중요한지는 희미해질 수 있습니다.
+8. 나중에 에이전트는 “결제 버그는 거의 해결됨” 같은 깔끔한 요약으로 돌아옵니다.
+9. goal은 기억하지만, `refunds`를 건드리면 안 된다는 점, webhook 시도가 실패했다는 점, service-layer test가 안전한 경로를 증명했다는 점은 희미해질 수 있습니다.
 
 여기서 drift가 시작됩니다.
 

package/README.md

@@ -39,15 +39,15 @@ Skill-compatible agents can automatically load installed skills when a request s
 
 So this can be enough:
 
-> `/goal` Harden this release over a long-running session. Keep the goal, constraints, rejected paths, failed attempts, verification state, and next action recoverable after compact/resume.
+> `/goal` Harden this release over a long-running session. Use goalkeeper.
 
 But skill activation is still a routing decision, not a private runtime hook. Goalkeeper cannot force itself onto every goal.
 
 For important long-running work, the safest path is to be explicit when you create the goal, or immediately after creating it:
 
-> Use goalkeeper for this `/goal`. Keep the goal, constraints, decisions, verification state, failed attempts, and next action recoverable across compaction.
+> Use goalkeeper for this goal.
 
-After that, you should not have to run Goalkeeper's helper scripts yourself. The agent runs them as part of the skill workflow.
+That is the whole user-facing instruction. After that, you should not have to name the checkpoint, context pack, event log, failed attempts, verification state, or helper scripts yourself. The agent runs Goalkeeper as part of the skill workflow.
 
 ## The Problem
 
@@ -57,15 +57,15 @@ But long goals are different.
 
 Imagine a real session:
 
-1. You ask an agent to harden a release.
-2. The obvious patch fixes the visible bug, but would break rollback compatibility.
-3. You set a hard constraint: no database schema change, keep backward compatibility.
-4. A second attempt passes unit tests, but fails an integration edge case.
-5. The agent settles on a compatibility shim plus a targeted regression test.
-6. The regression test passes. That path is now the safe one.
+1. You ask an agent to fix a payment bug.
+2. Early in the work, it discovers `refunds` is legacy code and should not be touched.
+3. The quickest patch would edit `refunds`, so you reject that path.
+4. The agent tries moving the fix into a webhook handler, but duplicate events break it.
+5. It finally proves the safe route: put an idempotency guard in the service layer and cover it with a regression test.
+6. The test passes. That route is now the one you want preserved.
 7. The context compacts.
-8. Later, the agent resumes from a clean summary: "release hardening mostly done."
-9. It still knows the goal, but may no longer feel why the schema shortcut stayed forbidden, why the first patches failed, or why that regression test mattered.
+8. Later, the agent resumes from a clean summary: "payment bug mostly fixed."
+9. It still knows the goal, but may no longer remember that `refunds` was off-limits, that the webhook attempt failed, or that the service-layer test is what made the route safe.
 
 That is where drift starts.
 

package/README.zh-CN.md

@@ -39,15 +39,15 @@ npx skills add deltafleet/goalkeeper --agent claude-code codex
 
 所以像下面这样的 goal 可能已经足够触发它：
 
-> `/goal` Harden this release over a long-running session. Keep the goal, constraints, rejected paths, failed attempts, verification state, and next action recoverable after compact/resume.
+> `/goal` Harden this release over a long-running session. Use goalkeeper.
 
 但 skill activation 仍然是 routing decision，不是私有的 agent runtime hook。Goalkeeper 不能强制自己附着到每一个 goal。
 
 对于重要的长期任务，最稳妥的做法是在创建 goal 时，或创建 goal 后正式开始工作前，明确调用它：
 
-> Use goalkeeper for this `/goal`. Keep the goal, constraints, decisions, verification state, failed attempts, and next action recoverable across compaction.
+> Use goalkeeper for this goal.
 
-之后用户不需要手动执行 Goalkeeper 的 helper scripts。agent 会把它们作为 skill workflow 的一部分来运行。
+用户需要记住的句子到这里就够了。checkpoint、context pack、event log、失败尝试、验证状态和 helper scripts，都由 agent 在 Goalkeeper workflow 中处理。
 
 ## 问题
 
@@ -57,15 +57,15 @@ npx skills add deltafleet/goalkeeper --agent claude-code codex
 
 想象一个真实会话：
 
-1. 你让 agent 做 release hardening。
-2. 最显眼的 patch 能修掉眼前的 bug，但会破坏 rollback compatibility。
-3. 你设下硬约束：不能改 database schema，必须保持 backward compatibility。
-4. 第二次尝试通过了 unit tests，但在 integration edge case 上失败。
-5. agent 选择 compatibility shim 加 targeted regression test。
-6. regression test 通过了。这条路线现在是安全路线。
+1. 你让 agent 修一个支付 bug。
+2. 早期调查发现，`refunds` 相关代码是 legacy，不能轻易动。
+3. 最快的 patch 是直接改 `refunds`，所以你明确拒绝这条路。
+4. agent 尝试把修复放到 webhook handler，但 duplicate event 场景会失败。
+5. 最后它验证了安全路线：在 service layer 加 idempotency guard，并用 regression test 覆盖。
+6. 测试通过了。这条路线现在是需要保留下来的安全路线。
 7. 上下文被 compact。
-8. 后来 agent 带着整洁摘要回来：“release hardening 基本完成。”
-9. 它还记得 goal，但可能不再清楚为什么 schema shortcut 必须继续禁止，为什么前几个 patch 失败，以及为什么那个 regression test 很关键。
+8. 后来 agent 带着整洁摘要回来：“支付 bug 基本修好了。”
+9. 它还记得 goal，但可能不再清楚 `refunds` 为什么不能动，webhook 尝试为什么失败，以及 service-layer test 为什么证明了正确路线。
 
 drift 就从这里开始。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deltafleet/goalkeeper",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A small Agent Skill for keeping long-running goals oriented across compaction, resumes, and handoffs.",
   "license": "MIT",
   "type": "module",

package/src/goalkeeper/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
   display_name: "Goalkeeper"
   short_description: "Keep long goals oriented"
-  default_prompt: "Use $goalkeeper for this long-running goal so checkpoint, context pack, and event log preserve direction across compaction."
+  default_prompt: "Use $goalkeeper for this long-running goal."
   brand_color: "#2563EB"