@winspan/claude-forge 8.54.3 → 9.2.0

package/dist/skills/distilled/distilled-karpathy-guidelines.md

@@ -0,0 +1,104 @@
+---
+name: distilled-karpathy-guidelines
+version: 0.2.0-distilled
+description: "Karpathy 4 条 LLM 编程铁律 — moved as-is, not re-distilled (already a distillation of multica-ai/andrej-karpathy-skills)"
+keywords:
+  - karpathy
+  - guidelines
+  - 编程原则
+  - 编程铁律
+  - simplicity
+  - surgical
+  - goal-driven
+  - 简洁优先
+  - 外科手术
+  - 目标可验证
+  - 行数预算
+  - 可验证判据
+  - 事前思考
+  - think before coding
+distilled_from:
+  - upstream: https://github.com/multica-ai/andrej-karpathy-skills
+    license: MIT
+    commit: as-is-moved
+    paths:
+      - "andrej-karpathy-skills/SKILL.md (via local official-karpathy-guidelines.md)"
+distilled_at: '2026-05-27T01:02:33.000Z'
+distilled_by: "as-is-copy (Q8 spec 0849; not re-distilled to avoid lossy compression)"
+it_universal_score: 5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 1
+  d5: 1
+it_universal_rationale: "Karpathy 4 principles are themselves an IT-universal distillation; re-distilling would be lossy."
+move_provenance: "copied as-is from upstream per spec 0849 Q8"
+---
+
+# Karpathy 编程铁律（4 条）
+
+源自 Andrej Karpathy 总结的 LLM 常见踩坑（multica-ai/andrej-karpathy-skills，
+MIT），转成事前提示 + 自查清单。这 4 条与「任何项目」开发流程中常见的「自检 →
+Plan-then-Implement → Agent 委托」模式一致；本 skill 把它们提炼成任何任务开始
+前可快速过一遍的具体动作。
+
+## 1. Think Before Coding（事先思考）
+
+把**模糊**换成**明确**，把**隐式假设**换成**显式问题**。
+
+实操：
+- 任务里有不确定的地方 → 在 spec / agent prompt / commit message 里**写出来**
+- 强烈推荐采用 Plan-then-Implement 工作流（先出 spec → review → 实施），
+  本身就是这条原则的强制路径
+- 自查："这个改动假设了什么？任何一个假设错了会怎样？"
+- 触发 → 用 planner-type agent 出 spec；spec 必须包含 "Open questions" 段
+
+## 2. Simplicity First（简洁优先）
+
+LLM 倾向于过度设计：加抽象层、写"以后可能用"的代码、引入新依赖。**默认拒绝**。
+
+实操：
+- 3 行重复优于 1 个早熟抽象
+- 不要为"未来可能的需求"留 hook
+- 改动**行数预算**：bug fix ≤ 50 行 / feature ≤ 200 行 / 超出 → 拆分
+- 重写优于打补丁：旧代码改动 > 60% 时，整段重写比逐处 patch 更易读
+- 对应通用原则："Do what has been asked; nothing more, nothing less"
+
+## 3. Surgical Changes（外科手术式修改）
+
+只改用户**明确**要求的代码。保留：
+- 现有 dead code（不在你 scope 内）
+- 现有命名风格（一致性 > 个人审美）
+- 现有"看起来糟糕但能跑"的代码
+
+实操：
+- 改 1 个函数的 bug，不要顺手"清理"邻居函数
+- 用 `git diff` 自查改动范围：超出 scope → 拆分另一个 commit
+- 涉及 ≥2 文件 → 推荐 spawn 专门 agent 处理；agent prompt 写明
+  "DO NOT touch X, Y, Z"
+- 反模式："顺手把这块也优化了" → 多半要回滚 + 拆 PR
+
+## 4. Goal-Driven Execution（目标可验证）
+
+**不要**写不可验证的目标。LLM 在不可验证目标上倾向"自我宣告成功"。
+
+❌ 反例：
+- "修复 X bug" / "性能更好" / "代码更清晰" / "完整修复"
+
+✅ 正例：
+- "后台服务重启 → 100 个工具调用全部入事件表 → SELECT COUNT(*) > 0"
+- "tasks-routes.test.ts 21/21 通过 + agent_detail.subagent_type === 'researcher'"
+- "DB 文件大小 275MB → 50MB；events 表行数 42k → 30k"
+
+实操：
+- 任何 spec 必须有 `## Success criteria` 段（planner-type agent 应强制）
+- 判据要可执行（命令 / SQL / 测试名 / 浏览器步骤 / 数字阈值）
+- 主线程交付前自查："这条判据能 run 吗？" 不能 → 改写
+
+## 触发条件
+
+本 skill 适合在以下任务前注入：
+- 新功能 / 重构 / Bug 修复（任何 ≥3 文件改动）
+- Plan-then-Implement 流程的 spec 撰写阶段
+- 主线程委托 sub-agent 前（让 agent prompt 引用本 skill 4 条）

package/dist/skills/distilled/distilled-performance-optimization.md

@@ -0,0 +1,175 @@
+---
+name: distilled-performance-optimization
+version: 1.0.0-portable
+description: 'Distilled IT-universal skill: performance optimization workflow (portable, hand-rewritten 2026-05-27)'
+keywords:
+  - performance
+  - optimization
+  - profiling
+  - latency
+  - bottleneck
+  - optimize
+  - 优化
+  - 瓶颈
+  - 慢
+  - slow
+  - timeout
+  - 超时
+  - 卡顿
+  - 性能
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/winspan/claude-forge.git
+    license: MIT
+    commit: 7d96b86c
+    paths:
+      - official/official-performance-optimization.md
+distilled_at: '2026-05-27T02:12:00.000Z'
+distilled_by: hand-rewrite (D4-reverse)
+it_universal_score: 4.5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 1
+  d5: 0.5
+it_universal_rationale: Measure-first methodology + bottleneck hierarchy; lang-agnostic and stack-agnostic.
+is_stub: false
+---
+
+## Goal
+
+Make the system meaningfully faster (or cheaper, or less resource-hungry) by **measuring first, locating the dominant bottleneck, fixing only that bottleneck, and proving the gain with a re-measurement**. Avoid the seductive trap of "obvious" optimizations that turn out to address the wrong thing.
+
+## When to trigger
+
+- A user-facing latency budget (P95, P99) is being missed under realistic load.
+- Throughput is below the required rate.
+- Costs are scaling super-linearly with traffic (CPU, memory, I/O, database calls, money).
+- A recent change caused a measurable regression (compare to baseline).
+- A planned scale-up (10x users, larger dataset) needs validation before launch.
+
+Do NOT trigger on: gut feelings, "feels slow", or single-instance anecdotes. Confirm with a measurement first.
+
+## Steps
+
+1. **Establish a baseline.** Before touching anything:
+   - Pick metrics that match the user-visible goal: latency percentiles (P50 / P95 / P99), throughput (req/sec), memory peak / steady-state, CPU utilization, cost per unit work.
+   - Define the workload: representative input distribution, concurrency, duration. Synthetic load that doesn't match production patterns produces lies.
+   - Record the numbers somewhere durable (a baseline file, a dashboard snapshot, a test report). You will compare against this later.
+
+2. **Locate the bottleneck — profile, do not guess.** Use the right tool for the suspected dimension:
+   - **CPU-bound**: sampling profiler, flame graph. Look for the widest stack frames.
+   - **Memory-bound**: heap dump, allocation profiler. Look for the largest retained objects and the highest-allocation call sites.
+   - **I/O-bound**: slow-query log, network trace, syscall trace. Look for waits, not active time.
+   - **Concurrency-bound**: lock contention profiler, goroutine / thread dump, event-loop lag. Look for blocked time.
+   - **End-to-end**: distributed tracing. Look for the single longest span on a slow request.
+
+3. **Confirm the bottleneck with a measurement, not a hypothesis.** Before optimizing, you should be able to say "the slowest thing is X, accounting for Y% of total time", backed by numbers. If you cannot, you do not yet know the bottleneck.
+
+4. **Optimize, in the priority order that has the best return on effort.** Generally:
+   1. **Algorithmic / complexity** — switching from O(n^2) to O(n log n) on a hot path beats almost any micro-optimization.
+   2. **Eliminate work** — remove duplicated queries (N+1), unnecessary serialization, debug logging on hot paths.
+   3. **Cache** — memoize results that are expensive and repeated; cache hot read paths with explicit invalidation.
+   4. **Batch** — replace per-item I/O with bulk operations.
+   5. **Concurrency / async** — overlap waitable work; use connection pools and bounded parallelism.
+   6. **Lower-level tuning** — data layout, allocations, compiler flags, query plans. High effort, situational gains.
+
+5. **Re-measure.** Run the same workload against the same metrics. The diff between baseline and post-change is your evidence. If the gain is smaller than expected, return to step 2 — you misidentified the bottleneck.
+
+6. **Verify correctness.** Functional tests must still pass. Performance changes are a frequent source of subtle bugs (race conditions, stale caches, batch boundary errors). Treat any failing test as blocking; speed is worthless if behavior is wrong.
+
+7. **Stop when the budget is met.** Performance work has diminishing returns. The third optimization usually contributes less than the first. Lock in the gain, document the baseline-vs-now in a short note, and move on. Iterate again only when the next budget or regression triggers it.
+
+## Anti-patterns
+
+- **Optimizing without measuring.** "It looks slow here" is a hypothesis, not a finding. Profile first.
+- **Optimizing the wrong layer.** Spending a week on micro-allocations when the dominant cost is a missing database index.
+- **Micro-benchmarks divorced from real workload.** A benchmark that runs the function 1M times in a tight loop can look fine while production is hitting cache, GC, and contention effects the loop never sees.
+- **Caching as a first response.** Caching covers up bottlenecks but does not remove them, and introduces invalidation as a new failure mode. Reach for it after you understand the actual cost.
+- **Premature parallelism.** Adding threads / async to a single-threaded bottleneck can hurt — increasing contention, scheduler overhead, or amplifying I/O storms.
+- **Multiple changes at once.** Changing the algorithm AND the cache AND the batch size in one commit makes it impossible to attribute the gain (or loss). One change, one measurement.
+- **Skipping the post-change measurement.** Without the re-measurement, you don't actually know if you helped. Sometimes "optimizations" regress.
+- **Confusing average with tail.** A change that improves P50 but worsens P99 may be a regression for a latency-sensitive system.
+
+## Success criteria
+
+- [ ] A baseline measurement exists and is recorded somewhere reproducible.
+- [ ] The bottleneck has been named explicitly, backed by profiler output or trace data.
+- [ ] The change addresses **only** that bottleneck (single-axis change).
+- [ ] A post-change measurement on the same workload shows the targeted metric improved.
+- [ ] Functional tests still pass.
+- [ ] The improvement meets the budget that triggered the work (or the work is escalated as "harder than expected").
+- [ ] A short note records: baseline numbers, identified bottleneck, change made, post-change numbers.
+
+## Failure modes
+
+- **No improvement after the fix.** Most common: you misidentified the bottleneck. Re-profile. The next candidate is likely something you saw in profiler output but dismissed.
+- **Improvement on the benchmark, no improvement in production.** Benchmark didn't match real workload. Re-profile in production-like conditions (real data sizes, real concurrency, real network).
+- **One metric improved, another regressed.** A trade-off you didn't notice — e.g. lower latency at the cost of more memory. Decide explicitly which matters; document the trade.
+- **Fix introduced a correctness bug.** Roll back, restore the failing test as a guard, and approach the optimization with that constraint visible in the design.
+- **Optimization works, then degrades over time.** Often a cache that grows unboundedly, a connection pool exhausting, or a data-set growth pattern. Add a size / eviction policy and a monitoring signal.
+- **The bottleneck is in code you don't own.** A library, a managed service, a network hop. Options in order: ask the vendor / open an issue; route around the slow call (cache, batch, async); replace the dependency. Document the constraint either way.
+
+## Examples
+
+### Imagine a typical web service: a "list orders" endpoint at 1.2s P95
+
+**Step 1 — Baseline.** Hit the endpoint with the realistic mix: 80% logged-in users, average 50 orders per account, 100 concurrent requests for 60 seconds.
+
+```
+P50: 320ms   P95: 1180ms   P99: 2400ms
+DB query count per request: 51
+CPU: 35%   Memory: stable   Error rate: 0
+```
+
+**Step 2 — Profile.** Trace one slow request end-to-end. The trace shows:
+
+```
+GET /orders                        1180ms total
+  auth middleware                    8ms
+  load user                         12ms
+  load orders list                  20ms   (1 query)
+  load items per order             1100ms  (50 queries, 22ms each)  <-- here
+  serialize response                40ms
+```
+
+50 sub-queries, one per order — a textbook N+1.
+
+**Step 3 — Confirm.** "The slowest thing is the per-order item fetch, contributing ~93% of P95 latency."
+
+**Step 4 — Optimize.** The right tool is **eliminate work / batch**, not cache: rewrite the loader to fetch items for all 50 orders in one query using `WHERE order_id IN (...)`. Single-axis change, no caching, no concurrency.
+
+**Step 5 — Re-measure.** Same workload:
+
+```
+P50: 90ms    P95: 180ms    P99: 280ms
+DB query count per request: 2 (1 for orders, 1 for items)
+```
+
+P95 from 1180 → 180ms. The targeted metric moved by the order of magnitude the bottleneck analysis predicted.
+
+**Step 6 — Verify.** Functional tests for the endpoint still pass; pagination still works; orders without items still render correctly.
+
+**Step 7 — Document and stop.** P95 budget was 300ms; we're at 180ms with healthy margin. No further optimization is justified right now. A note in the perf log records baseline, fix, and post-change numbers.
+
+### A second example: misidentified bottleneck
+
+Same endpoint, different team's first attempt: they noticed the response serialization showed up "near the top" of the profile and spent two days swapping the JSON library. After the change:
+
+```
+P50: 310ms   P95: 1170ms   (no meaningful change)
+```
+
+The serialization was 40ms out of 1180. Even a perfect 0ms serialization could only have moved P95 to ~1140ms. Lesson: always confirm the **share** of total time before optimizing a layer, not just its position in the profiler list.
+
+## Adoption notes
+
+To bake this into a project's practice:
+
+- Define explicit latency / throughput / cost budgets per endpoint or per workload. Targets without numbers cannot be met.
+- Keep a per-service "perf log" file (e.g. `docs/perf/<service>.md`) recording baselines, identified bottlenecks, and dated optimizations. Old entries are the institutional memory of what worked.
+- Standardize on one profiler / tracer per language in the stack so engineers do not relearn tools each time.
+- Add load tests against the realistic workload to CI (or at least to a pre-release checklist) so regressions surface before users notice.
+- Pair this skill with the systematic-debugging skill: both rest on "measure before changing"; both reward small, isolated, verifiable changes over speculative rewrites.
+- Treat the post-change measurement as a deliverable, not an afterthought — a perf PR without before/after numbers is incomplete review material.

package/dist/skills/distilled/distilled-spec-driven-design.md

@@ -0,0 +1,193 @@
+---
+name: distilled-spec-driven-design
+version: 1.0.0-portable
+description: 'Distilled IT-universal skill: spec-driven design + file-based planning (portable, hand-rewritten 2026-05-27)'
+spawn_agent: planner
+keywords:
+  - spec
+  - sdd
+  - plan
+  - design
+  - requirements
+  - acceptance
+  - spec-driven
+  - 规格
+  - 需求文档
+  - planning
+  - 规划
+  - task plan
+  - organize
+  - 组织任务
+  - 怎么做
+  - 方案
+  - 步骤
+  - 计划
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/winspan/claude-forge.git
+    license: MIT
+    commit: 7d96b86c
+    paths:
+      - official/official-spec-driven-design.md
+      - official/planning-with-files.md
+distilled_at: '2026-05-27T02:10:00.000Z'
+distilled_by: hand-rewrite (D4-reverse)
+it_universal_score: 5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 1
+  d5: 1
+it_universal_rationale: SDD methodology + persistent file-based planning; both stack-agnostic, SDLC-universal, principle-level.
+is_stub: false
+---
+
+## Goal
+
+Before writing code, write a clear specification. A spec is a contract: the code's job is to satisfy the spec exactly, no more, no less. Keep the plan and findings in persistent files so context survives session boundaries, tool resets, and team handoff.
+
+## When to trigger
+
+- Starting a new feature, module, or non-trivial change (3+ steps or 3+ files)
+- Requirements are ambiguous, debated, or only verbally agreed
+- A change crosses multiple modules / has cross-cutting effects
+- A task is expected to span multiple sessions or tool calls
+- After a long debugging session — write the failure mode down before fixing
+- Re-attempting a task that previously stalled or got muddled
+
+## Steps
+
+1. **Draft the spec file.** Create `SPEC.md` (or `docs/design/<task>-spec.md`) with:
+   - **Goal**: one sentence describing the change.
+   - **Inputs / outputs**: types, examples, edge values, error cases.
+   - **Out of scope**: explicit list of things this change will NOT do.
+   - **Acceptance criteria**: bullet list of testable conditions. Each item must be verifiable with a test, manual check, or measurable signal.
+   - **Risks / open questions**: things you are unsure about; mark each as resolved before implementation.
+
+2. **Review the spec.** Walk every acceptance criterion and ask:
+   - Could a competent reader misinterpret this?
+   - Can each criterion become a single test?
+   - Are boundary cases (empty input, max size, missing field, concurrent calls) covered?
+   - If you cannot answer "yes" to all three, revise the spec before moving on.
+
+3. **Create planning files (for multi-phase work).** Alongside the spec, maintain:
+   - `task_plan.md` — phases, status (`pending` / `in_progress` / `complete`), decisions log.
+   - `findings.md` — discoveries, research notes, references collected while working.
+   - `progress.md` — session log: what was done, what failed, what test results look like.
+
+4. **Implement strictly to the spec.** Code only what the spec describes. If you encounter a situation the spec did not cover, **stop, update the spec, then resume**. Never silently expand scope.
+
+5. **Update planning files after each phase.** When a phase completes:
+   - Flip its status in `task_plan.md`.
+   - Append a session entry to `progress.md` with what changed and which tests ran.
+   - Record any new errors and how they were resolved.
+
+6. **Acceptance pass.** Walk the acceptance criteria one by one and verify each is met by a test or a concrete observation. A criterion without a green check is unfinished work.
+
+7. **Continue or close.** If the user requests follow-up, add new phases to `task_plan.md` and loop back to step 1 for any non-trivial extension. If done, archive the plan files into a per-task directory.
+
+## Anti-patterns
+
+- Starting to code before the spec exists ("I'll write it down later").
+- Acceptance criteria that are vague ("works correctly", "feels fast") instead of testable.
+- Adding features the spec did not call for, even when they "obviously" belong.
+- Treating the spec as immutable. Specs are living documents; just update them BEFORE the code.
+- Keeping the plan only in the chat / context window — it evaporates on `/clear` or session reset.
+- Using a TODO list utility for persistence; durable plans go in tracked files.
+- Repeating a failed action without changing approach.
+- Hiding errors silently and retrying — every error belongs in the plan file with attempt count and resolution.
+
+## Success criteria
+
+- [ ] A `SPEC.md` (or equivalent) exists before any production code change.
+- [ ] Every acceptance criterion is paired with a test, assertion, or measurable check.
+- [ ] An "Out of scope" section exists and is non-empty.
+- [ ] Planning files (`task_plan.md`, `findings.md`, `progress.md`) exist for tasks spanning 3+ phases or 5+ tool calls.
+- [ ] After implementation, the diff contains nothing not described in the spec.
+- [ ] All acceptance criteria are individually checked off (manual or automated).
+- [ ] The plan files reflect final state — no "in progress" leftovers.
+
+## Failure modes
+
+- **Spec drift during implementation.** You discover a missing case. Resist patching code; pause, edit the spec, flag the new requirement, then code.
+- **Acceptance criteria not testable.** Often a sign the criterion is a hope, not a behavior. Rewrite it as a deterministic check ("returns 404 when X" instead of "handles errors").
+- **Planning files go stale.** Set a rule: after every 2 search / read / browse operations, write findings to disk; after every phase, update plan status. If you haven't updated in 5+ tool calls, you're likely losing state.
+- **Three failed attempts at the same step.** Escalate: stop, summarize what you tried in `progress.md`, ask the user / collaborator for direction. Do not loop a 4th time.
+- **Spec was right, code is wrong.** Walk the acceptance criteria backwards from the test failure and locate the violated contract; fix code to match spec.
+- **Spec was wrong, code reveals it.** Revise the spec (note the revision in `progress.md`), then continue. Do not let the code silently lead the spec.
+
+## Examples
+
+### Imagine a typical web service: adding a "rate-limit per API key" feature
+
+**Spec file** (`docs/design/rate-limit-spec.md`):
+
+```markdown
+# Rate Limit per API Key
+
+## Goal
+Throttle requests to <= N per minute per API key, returning 429 on overflow.
+
+## Inputs / Outputs
+- Input: HTTP request with `X-API-Key` header.
+- Output: normal response, or HTTP 429 with `Retry-After: <seconds>` header.
+- Default limit: 60/min. Configurable per key.
+
+## Out of scope
+- IP-based throttling.
+- Burst allowance / token-bucket smoothing.
+- Distributed coordination across multiple instances (single-node only for v1).
+
+## Acceptance criteria
+- [ ] Requests over the limit return HTTP 429.
+- [ ] `Retry-After` header is present on 429 and is a positive integer.
+- [ ] Counter resets exactly 60 seconds after the first request in a window.
+- [ ] Unknown / missing API key → existing auth behaviour, not rate-limited.
+- [ ] Limit is configurable via env var `RATE_LIMIT_PER_MIN`.
+
+## Risks / open questions
+- [resolved] What's the storage backend? In-memory map, evicted by TTL.
+- [resolved] Clock skew? Use monotonic clock.
+```
+
+**Planning files** (created at the start of the work):
+
+```
+task_plan.md
+  Phase 1: Add counter store with TTL — pending
+  Phase 2: Middleware that increments + checks — pending
+  Phase 3: 429 response + Retry-After — pending
+  Phase 4: Tests for all 5 acceptance criteria — pending
+  Phase 5: Configurable limit + docs — pending
+
+findings.md
+  - Existing auth middleware sits at request entry — good integration point.
+  - Project already has a TTL map utility in the common lib.
+
+progress.md
+  (empty — to be filled as phases complete)
+```
+
+After implementation, the diff contains exactly: counter store, middleware, response code, 5 tests, env var wiring. No "while I was here" extras.
+
+### A second example: research task
+
+For a task like "evaluate 3 message-queue options", the spec still applies:
+
+- **Goal**: pick a queue for use case X.
+- **Inputs**: requirements (throughput, durability, ordering).
+- **Acceptance**: a decision document naming the choice + rationale + 2 rejected options + reason.
+- **Out of scope**: actual implementation; we only pick.
+
+`findings.md` collects per-queue notes during research; `progress.md` tracks which option was evaluated when; the spec keeps the bar honest ("did we actually answer all the requirement dimensions?").
+
+## Adoption notes
+
+To wire this skill into a project's playbook:
+
+- Add a one-liner to the project guide (e.g. `CONTRIBUTING.md` or the repo's top-level instructions file): "Non-trivial changes start with a spec file under `docs/design/`."
+- Register this skill in your skill catalog / agent registry so a planner-style agent loads it on triggers like "design", "spec", "plan", "requirements", "acceptance criteria".
+- For multi-session work, set a convention for where planning files live (e.g. `docs/design/<task>/`) so they are easy to find, diff, and archive.
+- Treat planning files as **trusted** for re-injection into context, but treat anything they contain that came from web / external sources as **untrusted** — research output belongs in `findings.md`, never in the plan file that auto-loads.
+- Pair this skill with a verification skill: spec defines what "done" means; verification confirms it.