create-yss-spec 1.0.0

package/template/.pi/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern.

package/template/.pi/skills/kb-retriever/README.md

@@ -0,0 +1,197 @@
+# Kb Retriever Skill — Local Knowledge-Base Retriever
+
+> A skill for AI agents to efficiently answer questions over a **local, multi-format knowledge directory** using hierarchical index navigation and progressive retrieval — without ever loading whole files into context.
+
+[中文文档](./README.zh-CN.md) · [Back to collection root](../../README.md)
+
+![Kb Retriever Skill](https://cdn.jsdelivr.net/gh/ConardLi/assets@main/imgs/kb-retriever-skill.webp)
+
+## What it does
+
+Point the agent at a local directory full of mixed-format files (Markdown, PDF, Excel, …) and ask questions in natural language. The skill:
+
+1. **Walks a hierarchical index** of `data_structure.md` files to figure out *which* files are likely to contain the answer.
+2. **Forces a learn-before-process step** when it hits a PDF or Excel — it must read the corresponding `references/*.md` first and use the recommended tool, instead of blindly reading the whole file.
+3. **Retrieves progressively** with `grep` + small windowed reads (offset/limit) instead of dumping entire files into context.
+4. **Iterates up to 5 rounds**, narrowing keywords each round until it has enough evidence to answer.
+
+---
+
+## Core features
+
+- ✅ **Multi-format**: Markdown / text, PDF, Excel — extensible per file type.
+- ✅ **Hierarchical index**: each directory carries its own `data_structure.md`, forming an index tree the agent navigates.
+- ✅ **Progressive retrieval**: grep-first, windowed reads, never whole-file loads — keeps token usage low even on large corpora.
+- ✅ **Mandatory learning step**: PDF/Excel processing is gated on reading the right `references/*.md` first.
+- ✅ **Bounded iteration**: at most 5 retrieval rounds, with explicit termination conditions.
+
+---
+
+## Skill structure
+
+```
+skills/kb-retriever/
+├── SKILL.md                            Main skill (frontmatter name: kb-retriever)
+├── README.md  /  README.zh-CN.md       This document
+├── references/
+│   ├── pdf_reading.md                  How to handle PDFs (pdftotext / pdfplumber / pypdf)
+│   ├── excel_reading.md                How to read Excel with pandas (nrows, dtype, etc.)
+│   └── excel_analysis.md               How to filter / aggregate / derive metrics on Excel
+└── scripts/
+    └── convert_pdf_to_images.py        Convert PDF pages to images when text extraction fails
+```
+
+---
+
+## Setting up your knowledge base
+
+This skill **does not ship a knowledge base** — you bring your own. Two ways to wire it up:
+
+### Default location
+
+Put a `knowledge/` directory at the root of the workspace where you invoke the agent:
+
+```
+your-project/
+├── .claude/skills/  or  .agents/skills/
+│   └── kb-retriever/             ← this skill folder
+└── knowledge/                    ← ← ← your knowledge base
+    ├── data_structure.md         (root-level index, see template below)
+    ├── <domain-1>/
+    │   ├── data_structure.md
+    │   └── ...
+    └── <domain-2>/
+        └── ...
+```
+
+### Custom location
+
+Tell the agent which path to use in your question, e.g. *"answer from `./docs`"* or *"my knowledge base is at `/data/kb`"*. The skill will use that path instead.
+
+If the default `knowledge/` does not exist and the user hasn't specified a path, the skill will ask rather than guess.
+
+### `data_structure.md` template
+
+Each indexed directory should carry one of these:
+
+```markdown
+# [Directory name]
+
+## Purpose
+What this directory is for and when it should be searched.
+
+## Files
+- file1.pdf — what it contains, time / version range
+- file2.xlsx — schema summary, key columns
+- subdir/ — what lives in this subdirectory
+
+## Coverage
+Time range, version, source, anything else that helps the agent prioritize.
+```
+
+---
+
+## How it retrieves
+
+### 1. Hierarchical index navigation
+
+For each directory level the skill reads `data_structure.md`, picks the most relevant child(ren) for the user's question, and recurses — so it doesn't fan out across the whole tree.
+
+### 2. Learn before process (PDF / Excel)
+
+When the candidate set contains a PDF or Excel file, the skill **must** first read the corresponding reference doc:
+
+```
+✅ Read references/pdf_reading.md  /  excel_reading.md  /  excel_analysis.md
+✅ Understand the recommended tool & flags
+✅ Convert / extract the file with that tool
+⏭️  Then start retrieving
+```
+
+Forbidden:
+
+- ❌ Trying to process a PDF without reading `pdf_reading.md`
+- ❌ Trying to process an Excel without reading `excel_reading.md` / `excel_analysis.md`
+- ❌ Skipping the conversion step and grepping the raw binary
+
+### 3. Progressive retrieval
+
+- Don't read whole files.
+- Use `grep` to locate keywords first.
+- Read only the matching window (`limit` ≈ 200–500 lines).
+- Iterate up to 5 rounds, refining keywords.
+
+### 4. Per-format tool strategy
+
+| Format | Tool | Notes |
+|---|---|---|
+| Markdown / text | `grep` + windowed `read_file` | Always offset/limit; never whole-file. |
+| PDF | `pdftotext input.pdf output.txt` → `grep` on the text | **Always extract to a file**, never to stdout. Use `-f / -l` for page ranges on huge PDFs. |
+| Excel | pandas with `nrows` first to learn schema, then filtered reads | Identify key columns (id / time / category) before querying. |
+
+### 5. Iteration loop
+
+Each round:
+
+1. Generate / update keywords
+2. Pick under-explored candidate files
+3. Run grep / windowed reads
+4. Inspect snippets
+5. Decide: enough to answer? → stop. Otherwise iterate.
+
+Stops on either: answer found ✅, or 5 rounds reached ⏱️.
+
+---
+
+## Best practices
+
+### Recommended
+
+1. Always start from `data_structure.md`.
+2. Read the matching `references/*.md` *before* touching a PDF or Excel.
+3. Retrieve from the most relevant file first; expand only if needed.
+4. Use `offset` + `limit` to read precise windows.
+5. Extract PDFs to files, then grep — never paste the binary into context.
+
+### Avoid
+
+1. ❌ Reading entire large files in one go.
+2. ❌ Processing PDF / Excel without reading the references first.
+3. ❌ `pdftotext input.pdf -` (stdout) — eats tokens.
+4. ❌ Loading a whole Excel sheet at once.
+5. ❌ Blind search across all directories.
+
+---
+
+## FAQ
+
+**Q1: Why force the agent to read `references/*.md` first?**
+To make sure the agent uses the right tool with the right flags — otherwise it tends to either dump huge files into context or pick a slow / broken tool.
+
+**Q2: How do I handle a very large PDF?**
+Use page-ranged extraction (`pdftotext -f 1 -l 10`), grep the resulting text, then read only the matching pages.
+
+**Q3: Can my knowledge base live anywhere?**
+Yes. Just say so in your question: *"answer from `/data/my-kb`"*.
+
+**Q4: How do I improve retrieval accuracy?**
+Use specific keywords, narrow down with time / file-name hints, and prefer domain-specific terminology over generic words.
+
+---
+
+## Tool requirements
+
+The skill assumes the agent has access to:
+
+- `grep` — text search
+- `read_file` — windowed reads with offset / limit
+- `pdftotext` (poppler) or `pdfplumber` — PDF text extraction
+- `pandas` — Excel reads & analysis
+
+`scripts/convert_pdf_to_images.py` is provided for the fallback case where text extraction yields nothing useful (scanned PDFs).
+
+---
+
+## License
+
+MIT

package/template/.pi/skills/kb-retriever/README.zh-CN.md

@@ -0,0 +1,197 @@
+# Kb Retriever Skill — 本地知识库检索
+
+> 让 AI Agent 高效回答基于**本地多格式知识库目录**的问题。靠分层索引导航 + 渐进式检索完成，不把整文件塞进 context。
+
+[English](./README.md) · [返回集合首页](../../README.zh-CN.md)
+
+![Kb Retriever Skill](https://cdn.jsdelivr.net/gh/ConardLi/assets@main/imgs/kb-retriever-skill.webp)
+
+## 这个 Skill 干什么
+
+把 Agent 指向一个本地的混合格式知识库目录（Markdown / PDF / Excel 等），用自然语言提问。Skill 会：
+
+1. **走分层索引**：沿着每层目录的 `data_structure.md`，判断答案大概率在哪些文件里。
+2. **强制先学习再处理**：碰到 PDF / Excel 时，必须先读对应的 `references/*.md`，按推荐工具去处理，不允许蛮力直接读。
+3. **渐进式检索**：先 `grep` 定位，再用 offset/limit 局部读取，避免整文件加载。
+4. **最多 5 轮迭代**：每轮根据已读到的内容收紧关键词，直到信息足够回答。
+
+---
+
+## 核心特性
+
+- ✅ **多格式支持**：Markdown / 文本、PDF、Excel——按文件类型可扩展。
+- ✅ **分层索引**：每层目录都带一份 `data_structure.md`，组成一棵索引树供 Agent 导航。
+- ✅ **渐进式检索**：grep 优先 + 窗口读取，从不整文件加载，大语料下也能控制住 token。
+- ✅ **强制学习机制**：PDF / Excel 的处理必须先读对应 references。
+- ✅ **有界迭代**：最多 5 轮，带明确终止条件。
+
+---
+
+## Skill 结构
+
+```
+skills/kb-retriever/
+├── SKILL.md                            主技能（frontmatter name: kb-retriever）
+├── README.md  /  README.zh-CN.md       本文档
+├── references/
+│   ├── pdf_reading.md                  PDF 处理指南（pdftotext / pdfplumber / pypdf）
+│   ├── excel_reading.md                pandas 读取 Excel 的方法（nrows / dtype 等）
+│   └── excel_analysis.md               Excel 的过滤 / 聚合 / 派生指标方法
+└── scripts/
+    └── convert_pdf_to_images.py        当文本抽取失败时把 PDF 转图像的兜底脚本
+```
+
+---
+
+## 准备你的知识库
+
+本 Skill **不自带**知识库——需要你自己提供。两种方式：
+
+### 默认路径
+
+在调用 Agent 的工作区根目录放一个 `knowledge/`：
+
+```
+your-project/
+├── .claude/skills/  或  .agents/skills/
+│   └── kb-retriever/             ← 本 Skill 目录
+└── knowledge/                    ← ← ← 你的知识库
+    ├── data_structure.md         （根级索引，模板见下）
+    ├── <领域-1>/
+    │   ├── data_structure.md
+    │   └── ...
+    └── <领域-2>/
+        └── ...
+```
+
+### 自定义路径
+
+在你的问题里直接告诉 Agent，例如"用 `./docs` 这个目录回答"或"我的知识库在 `/data/kb`"，Skill 会改用你指定的路径。
+
+如果默认 `knowledge/` 不存在、用户也没指定路径，Skill 会主动询问而不是瞎猜。
+
+### `data_structure.md` 模板
+
+每个被索引的目录都建议放一份：
+
+```markdown
+# [目录名称]
+
+## 用途
+本目录是干什么的、什么场景下应该被检索。
+
+## 文件说明
+- file1.pdf —— 内容是什么、时间 / 版本范围
+- file2.xlsx —— 表结构概要、关键列
+- subdir/ —— 子目录用途
+
+## 数据范围
+时间范围、版本、数据来源等帮助 Agent 排序优先级的信息。
+```
+
+---
+
+## 检索是怎么进行的
+
+### 1. 分层索引导航
+
+每层目录都先读 `data_structure.md`，挑出与问题最相关的子目录或文件，**再递归向下**——不会一次性铺开整棵树。
+
+### 2. 先学习，再处理（PDF / Excel）
+
+候选集合里出现 PDF 或 Excel 时，**必须**先读对应的 references：
+
+```
+✅ 读 references/pdf_reading.md  /  excel_reading.md  /  excel_analysis.md
+✅ 理解推荐的工具与参数
+✅ 用该工具完成转换 / 抽取
+⏭️  现在才能开始检索
+```
+
+禁止行为：
+
+- ❌ 没读 `pdf_reading.md` 就直接处理 PDF
+- ❌ 没读 `excel_reading.md` / `excel_analysis.md` 就直接处理 Excel
+- ❌ 跳过文件处理直接对原始 PDF / Excel 检索
+
+### 3. 渐进式检索
+
+- 不读整文件。
+- 先用 `grep` 定位关键词。
+- 只读匹配处的窗口（`limit` ≈ 200–500 行）。
+- 最多 5 轮，每轮收紧关键词。
+
+### 4. 按文件类型选工具
+
+| 格式 | 工具 | 注意 |
+|---|---|---|
+| Markdown / 文本 | `grep` + 窗口 `read_file` | 必须 offset/limit，不要整文件读。 |
+| PDF | `pdftotext input.pdf output.txt` → 对结果文本 `grep` | **必须输出到文件**，不要走 stdout。超大 PDF 用 `-f / -l` 控制页范围。 |
+| Excel | pandas，先 `nrows` 学结构，再带条件读取 | 先识别关键列（id / time / category），再查询。 |
+
+### 5. 迭代循环
+
+每轮：
+
+1. 生成 / 更新关键词
+2. 选择尚未充分检索的候选文件
+3. 执行 grep / 局部读取
+4. 分析返回的片段
+5. 判断信息是否够回答 → 够则停止；不够进入下一轮。
+
+终止条件：信息足够 ✅ 或 达到 5 轮 ⏱️。
+
+---
+
+## 最佳实践
+
+### 推荐
+
+1. 永远先从 `data_structure.md` 开始。
+2. 碰到 PDF / Excel 之前**先**读匹配的 `references/*.md`。
+3. 从最相关的文件开始检索，必要时才扩展范围。
+4. 用 `offset` + `limit` 精确控制读取窗口。
+5. PDF 先抽取到文件再 grep，**不要**把二进制塞进 context。
+
+### 避免
+
+1. ❌ 一次性读取大文件
+2. ❌ 没读 references 就处理 PDF / Excel
+3. ❌ `pdftotext input.pdf -`（stdout）—— 吃 token
+4. ❌ 一次性读取整张 Excel
+5. ❌ 在所有目录里盲目搜索
+
+---
+
+## 常见问题
+
+**Q1：为什么要强制先读 `references/*.md`？**
+保证 Agent 用对的工具配对的参数——否则它要么把整个文件塞进 context，要么挑了个慢 / 坏掉的方法。
+
+**Q2：超大 PDF 怎么办？**
+按页范围抽取（`pdftotext -f 1 -l 10`），对结果文本 grep，然后只读匹配页面附近的内容。
+
+**Q3：知识库可以放别处吗？**
+可以，问问题时明确告诉 Agent 路径即可（"用 `/data/my-kb` 回答"）。
+
+**Q4：怎么提高检索准确率？**
+使用更具体的关键词、缩小时间 / 文件名范围、用领域术语而非通用词汇。
+
+---
+
+## 工具依赖
+
+本 Skill 假定 Agent 可以使用：
+
+- `grep` —— 文本搜索
+- `read_file` —— 带 offset / limit 的窗口读取
+- `pdftotext`（poppler）或 `pdfplumber` —— PDF 文本抽取
+- `pandas` —— Excel 读取 / 分析
+
+`scripts/convert_pdf_to_images.py` 是兜底脚本，给那种文本抽取一无所获的扫描版 PDF 用。
+
+---
+
+## 许可证
+
+MIT