create-yss-spec 3.0.0 → 3.1.0

package/template/.hermes/skills/codebase-design/DEEPENING.md

@@ -1,37 +0,0 @@
-# Deepening
-
-How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**.
-
-## Dependency categories
-
-When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
-
-### 1. In-process
-
-Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
-
-### 2. Local-substitutable
-
-Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
-
-### 3. Remote but owned (Ports & Adapters)
-
-Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
-
-Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
-
-### 4. True external (Mock)
-
-Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
-
-## Seam discipline
-
-- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
-- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
-
-## Testing strategy: replace, don't layer
-
-- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
-- Write new tests at the deepened module's interface. The **interface is the test surface**.
-- Tests assert on observable outcomes through the interface, not internal state.
-- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/template/.hermes/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -1,44 +0,0 @@
-# Design It Twice
-
-When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
-
-Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
-
-## Process
-
-### 1. Frame the problem space
-
-Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
-
-- The constraints any new interface would need to satisfy
-- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
-- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
-
-Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
-
-### 2. Spawn sub-agents
-
-Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface for the deepened module.
-
-Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
-
-- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
-- Agent 2: "Maximise flexibility — support many use cases and extension."
-- Agent 3: "Optimise for the most common caller — make the default case trivial."
-- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
-
-Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
-
-Each sub-agent outputs:
-
-1. Interface (types, methods, params — plus invariants, ordering, error modes)
-2. Usage example showing how callers use it
-3. What the implementation hides behind the seam
-4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
-5. Trade-offs — where leverage is high, where it's thin
-
-### 3. Present and compare
-
-Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
-
-After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

package/template/.hermes/skills/codebase-design/SKILL.md

@@ -1,118 +0,0 @@
----
-name: codebase-design
-description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
----
-
-# Codebase Design
-
-Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
-
-## Glossary
-
-Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
-
-**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
-
-**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
-
-**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
-
-**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
-
-**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
-
-**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
-
-**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
-
-**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
-
-## Deep vs shallow
-
-**Deep module** = small interface + lots of implementation:
-
-```
-┌─────────────────────┐
-│   Small Interface   │  ← Few methods, simple params
-├─────────────────────┤
-│                     │
-│  Deep Implementation│  ← Complex logic hidden
-│                     │
-└─────────────────────┘
-```
-
-**Shallow module** = large interface + little implementation (avoid):
-
-```
-┌─────────────────────────────────┐
-│       Large Interface           │  ← Many methods, complex params
-├─────────────────────────────────┤
-│  Thin Implementation            │  ← Just passes through
-└─────────────────────────────────┘
-```
-
-When designing an interface, ask:
-
-- Can I reduce the number of methods?
-- Can I simplify the parameters?
-- Can I hide more complexity inside?
-
-## Principles
-
-- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
-- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
-- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
-- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
-
-## Designing for testability
-
-Good interfaces make testing natural:
-
-1. **Accept dependencies, don't create them.**
-
-   ```typescript
-   // Testable
-   function processOrder(order, paymentGateway) {}
-
-   // Hard to test
-   function processOrder(order) {
-     const gateway = new StripeGateway();
-   }
-   ```
-
-2. **Return results, don't produce side effects.**
-
-   ```typescript
-   // Testable
-   function calculateDiscount(cart): Discount {}
-
-   // Hard to test
-   function applyDiscount(cart): void {
-     cart.total -= discount;
-   }
-   ```
-
-3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
-
-## Relationships
-
-- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
-- **Depth** is a property of a **Module**, measured against its **Interface**.
-- A **Seam** is where a **Module**'s **Interface** lives.
-- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
-- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
-
-## Optional architecture visualization
-
-Use `archify` only when the user or the governing YSS contract explicitly asks for a system map, workflow, sequence, data-flow, lifecycle, Mermaid beautification, or Before/After architecture view. Preserve the design facts and terminology from the current evidence; the resulting diagram is derived review evidence, not a replacement for the design decision, ADR, contract, or approval. In a YSS repository, use Archify's YSS-safe delivery wrapper and retain the paired JSON, HTML, and receipt.
-
-## Rejected framings
-
-- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
-- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
-- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
-
-## Going deeper
-
-- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
-- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

package/template/.hermes/skills/codebase-design/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Codebase Design"
-  short_description: "Vocabulary for deep-module design"

package/template/.hermes/skills/competitive-intelligence/SKILL.md

@@ -1,94 +0,0 @@
----
-name: competitive-intelligence
-description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Discovery, Spec, product strategy, or roadmap decisions.
----
-
-# Competitive Intelligence
-
-Source requested for this project: `anthropics/knowledge-work-plugins`, `sales/skills/competitive-intelligence`.
-
-Use this skill when competitive or market facts are needed to shape product Discovery, Spec scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
-
-## Core Rules
-
-- Browse or verify current public sources before making factual claims about competitors, pricing, features, market position, funding, partnerships, product releases, or customer sentiment.
-- Separate facts, evidence, and inference. Do not present strategy guesses as verified competitor intent.
-- Prefer primary or near-primary sources: official product pages, docs, pricing pages, changelogs, release notes, filings, case studies, status pages, marketplace listings, reputable analyst reports, and dated customer reviews.
-- Record dates for time-sensitive claims. Pricing, packaging, roadmap, customer logos, and feature availability can change quickly.
-- Persistent project outputs should use Chinese body text by default. Keep competitor names, product names, URLs, API names, and quoted identifiers unchanged.
-- Do not bypass paywalls, scrape private systems, or use confidential information. Public evidence only unless the user explicitly provides internal material.
-
-## Workflow
-
-1. Define the intelligence question:
-   - Which product decision will this inform?
-   - Which competitors or substitute workflows are in scope?
-   - Which markets, user segments, regions, editions, or use cases matter?
-   - What must be decided after the research?
-2. Build an evidence plan:
-   - Official sources for product capabilities and pricing.
-   - Documentation and changelogs for depth and recency.
-   - Reviews, community posts, app marketplaces, and job posts for adoption and pain signals.
-   - Analyst, media, or public filings for market context when relevant.
-3. Capture evidence with source links and dates:
-   - Feature / capability evidence.
-   - Pricing / packaging evidence.
-   - UX / onboarding evidence.
-   - Integration / ecosystem evidence.
-   - Customer segment and positioning evidence.
-   - Complaints, workarounds, or unmet needs.
-4. Synthesize:
-   - Competitor positioning.
-   - Table-stakes capabilities.
-   - Differentiators and defensibility.
-   - Gaps and underserved jobs-to-be-done.
-   - Risks if we copy the competitor too closely.
-   - Product opportunities for Spec or roadmap.
-5. Hand off to lifecycle assets:
-   - Update Discovery findings in `docs/.scratch/<feature>/discovery/`.
-   - Create or update a competitor matrix in `docs/.scratch/<feature>/discovery/reports/`.
-   - Feed stable user, pain, MVP, non-goal, and success criteria into `grill-with-docs` and `to-spec`.
-   - Record uncertain claims as assumptions, not requirements.
-
-## Output Shape
-
-For a quick brief:
-
-```markdown
-## 竞品情报简报
-
-### 研究问题
-- <本次情报要支持的产品决策>
-
-### 范围
-- 竞品 / 替代方案：<list>
-- 用户 / 市场：<scope>
-- 时间范围：<date>
-
-### 关键结论
-- <fact or inference, clearly labeled>
-
-### 证据表
-| 结论 | 证据 | 来源 | 日期 | 置信度 |
-|---|---|---|---|---|
-
-### 竞品矩阵
-| 维度 | 竞品 A | 竞品 B | 我们的机会 |
-|---|---|---|---|
-
-### Spec 输入
-- 用户 / 痛点：
-- MVP 建议：
-- 非目标范围：
-- 验收或验证建议：
-
-### 风险与待验证假设
-- <assumption>
-```
-
-## Guardrails
-
-- Do not treat competitive parity as a product requirement. Convert evidence into user value, MVP boundaries, and testable acceptance criteria.
-- Do not copy competitor UX, text, proprietary workflows, screenshots, or private materials into project artifacts.
-- If sources conflict, show both and mark confidence rather than forcing a false conclusion.
-- If current web access is unavailable, state the limitation and produce only a research plan or hypothesis list.

package/template/.hermes/skills/component-selection-imports/SKILL.md

@@ -1,64 +0,0 @@
----
-name: component-selection-imports
-description: 指导 YSS UI 业务页面、CRUD、列表页、表单页和组件评审在编码前判定组件、Hook 与工具函数的真实导出来源；当需要在 @yss-ui/components、@yss-ui/hooks、@yss-ui/utils 与 ant-design-vue 之间选择，或需要排查虚构 Y 前缀组件、错误导入、Formily UI 边界时使用。
----
-
-# 组件选择与导入
-
-## 触发条件
-
-- 生成 YSS UI 业务页面前需要判定组件、Hook 或工具函数来源。
-- 出现错误 Y 前缀、导入冲突、Formily UI 跨层或者组件是否已封装不明确。
-
-## 不适用场景
-
-- 只修改与 UI 导入无关的纯数据逻辑。
-- 组件库内部组件开发；该场景应按组件开发规范处理内部依赖。
-
-## 判定流程
-
-1. 当前会话可用 yss-ui MCP 时，先用 `list_components` 确认组件、Hook 或 Utils 是否真实存在，再用 `get_component_docs` 确认名称、导出包、Props、Events 和 Slots，不只看 demo 标签名。
-2. `get_component_docs` 未命中时，先用 `search_docs` 和 `list_components` 校正别名与归属，不得立即判定为未封装。
-3. MCP 工具不可用、调用失败或校正后仍无结果时，读取当前上下文或文档站的最新 `llms-full.txt`。
-4. 必要时读取 `../yss-ui-business-page-generation/references/component-map.md`、`hooks-map.md`、`utils-map.md` 快速缩小范围；文档与当前项目依赖版本不一致时，最终以当前源码和可编译导出为准。
-5. 已导出的 YSS 能力优先从 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils` 导入；确认未封装后才从 `ant-design-vue` 导入原组件。
-6. 若文档与导出源码不一致，记录差异并按当前仓库可编译的导出处理，不猜测 API。
-
-## 硬约束（禁止/必须）
-
-- 业务层已封装组件必须从 `@yss-ui/components` 导入；可编辑表格必须优先使用 `YEditTable`，业务主表格必须优先使用 `YTable`。
-- 当前公共导出包含 `YButton`、`YCard`、`YTable`、`YEditTable`、`YTree`、`YSplitPane`、`YFormily` 等；未导出 `YModal`、`YDrawer`、`YInput`、`YPopconfirm`，禁止臆造这些名称。
-- 当前未封装的 `Modal`、`Drawer`、`Popconfirm`、`Input` 等从 `ant-design-vue` 导入。删除操作使用按钮附近的 `Popconfirm`，不默认使用居中 `Modal.confirm`。
-- 业务层禁止导入 `@formily/antdv` 或 `@formily/antd*` UI 组件；使用 `YFormily` 提供的 Schema 与组件边界。
-- 禁止因文档暂时不可达就把猜测的 `Y*` 组件改成 Ant Design Vue “先落地”。只能复用当前仓库已证明可用的导入，或明确报告待确认项。
-- 接口错误提示由 `mutator.ts` 的响应拦截器统一处理。API Hook 不得在 `success === false` 分支或 `catch` 内重复调用 `message.error`；`message` 只用于非 API 错误的本地交互反馈或成功提示。
-
-## 标准代码骨架
-
-```typescript
-import {
-  YButton,
-  YCard,
-  YEditTable,
-  YTable,
-  YTree,
-  YFormily,
-  type YEditTableColumn,
-  type YTableColumn,
-} from '@yss-ui/components';
-import { useLoading, useTableHeight, useTreeHeight } from '@yss-ui/hooks';
-import { copyToClipboard, formatDate } from '@yss-ui/utils';
-import { Drawer, Input, Modal, Popconfirm } from 'ant-design-vue';
-```
-
-## 交付检查清单
-
-- [ ] 每个关键导入都能在最新文档或包的 `src/index.ts` 中追溯。
-- [ ] 未导出的 Y 前缀组件没有出现在业务代码中。
-- [ ] 删除、表格、编辑表格和 Formily 导入边界符合项目约束。
-- [ ] API Hook 中没有重复 `message.error`，异常仍由 `Promise.reject` 中断后续流程。
-
-## 失败兜底策略
-
-- MCP 与 `llms-full.txt` 都不可用时，用 CodeGraph/源码 `src/index.ts` 和当前项目已编译的相近页面交叉确认，不猜测导出。
-- 文档与源码不一致时，优先保证当前仓库可编译，并在交付中明确标注文档差异。

package/template/.hermes/skills/cross-repo-implementation-routing/SKILL.md

@@ -1,51 +0,0 @@
----
-name: cross-repo-implementation-routing
-description: Use when a Harness change or vertical slice may require work across external frontend/backend implementation repositories.
----
-
-# Cross Repo Implementation Routing
-
-用于从一个 Harness change 或垂直切片判断需要改哪些实现仓库，并把 Harness、后端、前端、契约和验证证据绑定起来。
-
-## Inputs
-
-- Harness change / Spec Delta change。
-- 垂直切片 Ticket 或实施计划。
-- OpenAPI Freeze 或无 API 影响记录。
-- 已登记的实现仓库记录；没有登记时先使用 `implementation-repo-onboarding`。
-
-## Workflow
-
-1. 读取 `docs/process/implementation-repo-integration.md` 和当前 change 资产。
-2. 判断影响面：Harness-only、backend-only、frontend-only、backend+frontend、contract-only、release-only。
-3. 确认每个受影响实现仓库已有登记记录；缺失则阻断并要求 onboarding。
-4. 核对项目根路径：Harness 内 `harness-apps` 与 `git-submodule` 项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。`git-submodule` 另核 gitlink、`.gitmodules` 和独立 `git_url`。外部 `external-repository` 记录各自的真实项目根。
-5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。`git-submodule` 必须追加 `superproject-gitlink-update`。
-6. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
-7. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
-
-## Routing Matrix
-
-| 影响 | 必需记录 |
-|---|---|
-| Harness-only | change、文档路径、验证命令、checkpoint |
-| backend-only | backend repo、branch、MR / PR、测试命令、CI、OpenAPI 是否受影响 |
-| frontend-only | frontend repo、branch、MR / PR、lint / type-check / build、API client 是否受影响 |
-| backend+frontend | OpenAPI Freeze、generated client、后端验证、前端验证、端到端验收 |
-| contract-only | OpenAPI spec、Freeze 记录、前后端消费确认 |
-| release-only | release note、rollout、rollback、观察信号 |
-
-## Boundaries
-
-- 不直接修改实现仓库代码。
-- 不创建或推送分支，除非用户在执行任务中明确授权。
-- 不允许前后端 MR / PR 信息只停留在实现仓库；必须回写 Harness 记录。
-- 如果 API 契约变化但没有 Freeze，必须回到 API Draft / Freeze 阶段。
-
-## Output
-
-- 跨仓库实现路由结论。
-- backend / frontend / harness 三方任务分配。
-- cross-repo slice 草案。
-- fresh verification 与 checkpoint 字段。
-- 阻断项和人审点。

package/template/.hermes/skills/diagnosing-bugs/SKILL.md

@@ -1,138 +0,0 @@
----
-name: diagnosing-bugs
-description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
----
-
-# Diagnosing Bugs
-
-A discipline for hard bugs. Skip phases only when explicitly justified.
-
-When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
-
-## Redact
-
-This skill has you show commands, outputs and captured artifacts. **Redact every secret first** — write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
-
-If the redacted output is not enough to diagnose the bug, say so and ask the user.
-
-## Phase 1 — Build a feedback loop
-
-**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
-
-### Ways to construct one — try them in roughly this order
-
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Tighten the loop
-
-Treat the loop as a product. Once you have _a_ loop, **tighten** it:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
-
-### Completion criterion — a tight loop that goes red
-
-Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (show the invocation and its output, redacted), and that is:
-
-- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
-- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
-- [ ] **Fast** — seconds, not minutes.
-- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
-
-If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
-
-## Phase 2 — Reproduce + minimise
-
-Run the loop. Watch it go red — the bug appears.
-
-Confirm:
-
-- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
-- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
-
-### Minimise
-
-Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
-
-Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
-
-Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
-
-Do not proceed until you have reproduced **and** minimised.
-
-## Phase 3 — Hypothesise
-
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before the fix** — but only if there is a **correct seam** for it.
-
-A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
-
-**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
-
-If a correct seam exists:
-
-1. Turn the minimised repro into a failing test at that seam.
-2. Watch it fail.
-3. Apply the fix.
-4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
-
-## Phase 6 — Cleanup
-
-Required before declaring done:
-
-- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
-- [ ] Regression test passes (or absence of seam is documented)
-- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns

package/template/.hermes/skills/diagnosing-bugs/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Diagnosing Bugs"
-  short_description: "Diagnose hard bugs and regressions"

package/template/.hermes/skills/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -1,44 +0,0 @@
-#!/usr/bin/env bash
-# Human-in-the-loop reproduction loop.
-# Copy this file, edit the steps below, and run it.
-# The agent runs the script; the user follows prompts in their terminal.
-#
-# Usage:
-#   bash hitl-loop.template.sh
-#
-# Two helpers:
-#   step "<instruction>"          → show instruction, wait for Enter
-#   capture VAR "<question>"      → show question, read response into VAR
-#
-# At the end, captured values are printed as KEY=VALUE for the agent to parse.
-#
-# `capture` prints its value back to the terminal, where the agent reads it — so
-# capture observations, and leave signing in to the user as a `step`.
-
-set -euo pipefail
-
-step() {
-  printf '\n>>> %s\n' "$1"
-  read -r -p "    [Enter when done] " _
-}
-
-capture() {
-  local var="$1" question="$2" answer
-  printf '\n>>> %s\n' "$question"
-  read -r -p "    > " answer
-  printf -v "$var" '%s' "$answer"
-}
-
-# --- edit below ---------------------------------------------------------
-
-step "Open the app at http://localhost:3000 and sign in."
-
-capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
-
-capture ERROR_MSG "Paste the error message (or 'none'):"
-
-# --- edit above ---------------------------------------------------------
-
-printf '\n--- Captured ---\n'
-printf 'ERRORED=%s\n' "$ERRORED"
-printf 'ERROR_MSG=%s\n' "$ERROR_MSG"