@winspan/claude-forge 8.54.4 → 9.12.0

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-receiving-code-review.md

@@ -0,0 +1,185 @@
+---
+name: distilled-receiving-code-review
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: receiving-code-review (score 4/5)'
+keywords:
+  - receiving
+  - code
+  - review
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/obra/superpowers.git
+    license: MIT
+    commit: f2cbfbefebbfef77321e4c9abc9e949826bea9d7
+    paths:
+      - receiving-code-review/SKILL.md
+  - upstream: https://github.com/obra/superpowers.git
+    license: MIT
+    commit: f2cbfbefebbfef77321e4c9abc9e949826bea9d7
+    paths:
+      - requesting-code-review/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - flutter-dart-code-review/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - scientific-thinking-literature-review/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - flutter-dart-code-review/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - flutter-dart-code-review/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - prediction-market-risk-review/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - scientific-thinking-literature-review/SKILL.md
+distilled_at: '2026-06-15T00:52:05.047Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 4
+it_universal_dims:
+  d1: 1
+  d2: 0.5
+  d3: 1
+  d4: 0.5
+  d5: 1
+it_universal_rationale: >-
+  Language-neutral code-review reception methodology (verify → evaluate → implement) applicable to
+  any codebase and review workflow; project-specific terms removed.
+---
+
+# Receiving Code Review: Verify Before You Implement
+
+## When to use
+- When receiving code review feedback (from teammates, CI bots, or external reviewers)
+- Before implementing any review suggestion, especially if it seems unclear or technically questionable
+- When you feel the urge to say "You're absolutely right!" and immediately start coding
+- When feedback items are partially unclear and you're tempted to implement what you understand now
+
+## Core idea
+
+Code review reception is a **technical evaluation exercise**, not a social performance. The only correct response to feedback is to verify it against codebase reality before acting. Performative agreement ("Great point!", "You're absolutely right!") is a red flag that you are about to implement something without understanding it. Clarity on all items must precede implementation of any item — partial understanding produces wrong implementations. External reviewers often lack full context; skepticism paired with careful checking is the right posture.
+
+## Steps
+
+### 1. Full read first
+Read all feedback completely before reacting or touching any code.
+
+### 2. Clarify before acting
+```
+IF any item is unclear:
+  STOP — do not implement anything yet
+  ASK for clarification on ALL unclear items
+
+Rationale: Items may be interdependent. Partial understanding → wrong implementation.
+
+Example:
+  Feedback: "Fix items 1–6"
+  You understand 1,2,3,6. Unclear on 4,5.
+  ✅ "I understand 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+  ❌ Implement 1,2,3,6 now and ask about 4,5 later
+```
+
+### 3. Evaluate by feedback source
+
+**From project lead / code owner (trusted)**
+- Implement after understanding, no sycophancy
+- Still ask if scope is unclear
+- Skip to action or a brief technical acknowledgment
+
+**From external reviewers (skeptical)**
+```
+BEFORE implementing, check:
+  1. Is this technically correct for THIS codebase?
+  2. Does it break existing functionality?
+  3. Is there a reason the current impl exists (legacy, compat)?
+  4. Does it work across all required platforms/versions?
+  5. Does the reviewer have full context?
+
+IF suggestion seems wrong → push back with technical reasoning
+IF you can't easily verify → say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+IF it conflicts with a prior architectural decision → discuss with project lead first
+```
+
+### 4. YAGNI check for "proper" feature suggestions
+```
+IF reviewer suggests implementing a feature "properly":
+  Search codebase for actual usage
+
+  IF unused: "This endpoint/function isn't called anywhere. Remove it (YAGNI)?"
+  IF used:   Then implement properly
+```
+
+### 5. Implement in priority order
+```
+1. Blocking issues (breaks, security)
+2. Simple fixes (typos, wrong imports)
+3. Complex fixes (refactoring, logic changes)
+
+Test each fix individually. Verify no regressions before moving to next.
+```
+
+### 6. Acknowledge correctly
+```
+✅ "Fixed. [One-sentence description of what changed]"
+✅ "Good catch — [specific issue]. Fixed in [location]."
+✅ [Just fix it and show the diff]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!" / any gratitude expression
+```
+Actions speak. The code itself shows you heard the feedback.
+
+### 7. Gracefully correct a wrong pushback
+```
+If you pushed back and were wrong:
+✅ "Checked [X] — you're right, it does [Y]. Implementing now."
+✅ "Verified this; my initial read was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending the pushback
+❌ Over-explaining
+```
+State the correction factually and move on.
+
+## When to push back
+
+Push back when:
+- The suggestion breaks existing functionality or tests
+- The reviewer lacks full codebase context
+- YAGNI: the feature/endpoint is not actually used
+- It is technically incorrect for this stack/version
+- Legacy or compatibility constraints exist that the reviewer missed
+- It conflicts with a prior architectural decision by the project lead
+
+**How to push back:** Use technical reasoning, not defensiveness. Ask specific questions. Reference working tests or existing code. Escalate to project lead if architectural.
+
+## Anti-patterns
+
+| Anti-pattern | Correct alternative |
+|---|---|
+| Performative agreement ("Absolutely right!") | State the requirement or just act |
+| Blind implementation without verification | Grep/read codebase first |
+| Batching all fixes without testing each | One fix → test → next |
+| Assuming reviewer is always right | Check whether it breaks things |
+| Avoiding pushback to stay comfortable | Technical correctness > social comfort |
+| Implementing understood items while skipping unclear ones | Clarify ALL items first |
+| Can't verify → proceed anyway | State the limitation, ask for direction |
+
+## References
+- Upstream: https://github.com/obra/superpowers.git

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.

package/dist/skills/distilled/distilled-subagent-driven-development.md

@@ -0,0 +1,124 @@
+---
+name: distilled-subagent-driven-development
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: subagent-driven-development (score 3.5/5)'
+keywords:
+  - subagent
+  - driven
+  - development
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/obra/superpowers.git
+    license: MIT
+    commit: f2cbfbefebbfef77321e4c9abc9e949826bea9d7
+    paths:
+      - subagent-driven-development/SKILL.md
+distilled_at: '2026-06-15T00:53:29.788Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 3.5
+it_universal_dims:
+  d1: 1
+  d2: 0.5
+  d3: 0.5
+  d4: 0.5
+  d5: 1
+it_universal_rationale: >-
+  Language-neutral orchestration methodology with transferable status taxonomy, model-selection
+  heuristics, and two-stage review pattern; only minor framework-specific template filenames require
+  renaming in a new codebase.
+---
+
+# Subagent-Driven Development
+
+## When to use
+- You have a concrete implementation plan with multiple, mostly-independent tasks
+- You want continuous execution without human check-ins between each task
+- You need systematic quality gates (spec compliance + code quality) that self-loop until passing
+- You want each implementer to have clean, unpolluted context rather than inheriting the coordinator's history
+
+## Core idea
+
+Dispatch a **fresh subagent** for each task in your plan, giving it exactly the context it needs — no more, no less. After each task, run two sequential review subagents: first a **spec compliance reviewer** (did the implementer build precisely what was asked — nothing missing, nothing extra?), then a **code quality reviewer** (is it well-structured and maintainable?). Each review stage loops — reviewer finds issues → implementer fixes → reviewer re-reviews — until the stage is ✅ before advancing.
+
+The coordinator reads the entire plan once upfront, extracts all task text, creates a task tracker, then executes sequentially without stopping to narrate progress. The only valid stops are: BLOCKED status that cannot be resolved, genuine ambiguity preventing progress, or all tasks complete.
+
+## Steps
+
+### 0 — Setup (once)
+1. Read the plan file once. Extract all tasks with their **full text** and any cross-task context notes.
+2. Create a task tracker (e.g., todo list) with every task marked pending.
+3. Do not re-read the plan during execution.
+
+### 1 — Dispatch implementer subagent (per task)
+- Provide: full task text, scene-setting (where this task fits in the overall plan), any files or interfaces relevant to this task.
+- **Never** let the subagent read the plan file itself — construct exactly what it needs.
+- If the subagent asks questions before starting, answer completely before it proceeds.
+
+### 2 — Handle implementer status
+
+| Status | Action |
+|---|---|
+| `DONE` | Proceed to spec compliance review |
+| `DONE_WITH_CONCERNS` | Read concerns. Correctness/scope concerns → address before review. Observations ("file is getting large") → note and proceed |
+| `NEEDS_CONTEXT` | Provide the missing information, re-dispatch same subagent |
+| `BLOCKED` | Assess root cause: (a) provide more context + re-dispatch, (b) upgrade to a more capable model, (c) split the task into smaller pieces, (d) escalate to human. Never force retry without changing something. |
+
+### 3 — Spec compliance review
+- Dispatch a spec reviewer subagent with: original task spec + committed code (provide git SHAs or diff).
+- Question it answers: **Did the implementation match the spec exactly?** Nothing missing, nothing extra.
+- If issues found → implementer subagent fixes → spec reviewer re-reviews. Loop until ✅.
+- **Do not start code quality review until spec compliance is ✅.**
+
+### 4 — Code quality review
+- Dispatch a code quality reviewer subagent with: the committed code.
+- Question it answers: **Is this well-structured, tested, and maintainable?**
+- If issues found → implementer subagent fixes → code quality reviewer re-reviews. Loop until ✅.
+
+### 5 — Mark complete, advance
+- Mark the task complete in the task tracker.
+- Move immediately to the next task. No progress summaries.
+
+### 6 — Final review (after all tasks)
+- Dispatch a final code reviewer for the entire implementation holistically.
+- Proceed to branch finalization (full test run, linting, PR preparation).
+
+## Model Selection
+
+Choose the least powerful model that can handle each role — reduces cost and increases speed.
+
+| Role / Task Type | Suggested model tier |
+|---|---|
+| Mechanical implementation: isolated function, clear spec, 1–2 files | Cheapest / fastest |
+| Integration tasks: multi-file coordination, pattern matching, debugging | Standard |
+| Architecture, design decisions, broad codebase understanding | Most capable |
+| Spec compliance review | Standard (needs judgment, not brute force) |
+| Code quality review | Most capable (architectural patterns, test adequacy) |
+
+## Anti-patterns
+
+- **Never start on main/master** without explicit user consent — work on a feature branch
+- **Never skip spec compliance review** before code quality review — wrong order wastes cycles
+- **Never skip code quality review** even if spec passes — both gates are required
+- **Never dispatch multiple implementer subagents in parallel** — they will conflict on shared files
+- **Never make the subagent read the plan file** — provide the extracted task text directly
+- **Never skip scene-setting context** — subagent needs to understand where the task fits
+- **Never let implementer self-review substitute for reviewer subagents** — self-review is supplementary
+- **Never accept "close enough" on spec compliance** — it is either ✅ or the fix loop runs
+- **Never skip re-review after fixes** — reviewer found issues → implementer fixes → same reviewer reviews again
+- **Never pause between tasks to ask "should I continue?"** — the human asked you to execute the plan; execute it
+- **Never ignore BLOCKED status** — something must change before retry (model, context, or task scope)
+
+## Key Principles
+
+**Fresh context = focused subagents.** Each implementer subagent is constructed from scratch by the coordinator. It inherits no session history, no tool call history, no side conversations. This keeps it on-task and prevents compounding confusion across tasks.
+
+**Spec before quality.** Spec compliance first ensures the right thing was built. Code quality second ensures it was built well. Reversing the order wastes quality review effort on implementations that may be refactored or scrapped.
+
+**Review loops are the mechanism, not optional.** A reviewer finding issues does not mean failure — it means the loop is working. The loop closes when the reviewer explicitly approves.
+
+**Continuous execution is a contract.** The human asked you to execute the plan. Pausing to narrate progress or ask "shall I continue?" breaks the contract and wastes their time.
+
+**Context curation is the coordinator's core job.** The coordinator's value is in extracting exactly the right text, interfaces, and background from the plan and codebase, and handing it to each subagent. Get this right and subagents succeed on the first attempt.
+
+## References
+- Upstream: https://github.com/obra/superpowers.git