@tanlinfeng/project-docs-workflow 0.0.0-stage → 2.1.0

package/skills/project-docs-workflow/references/deps/tdd.md

@@ -0,0 +1,35 @@
+# 回退：tdd
+
+> 当需要调用 `tdd` 但环境未安装该 skill 时，按本文执行。
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 tdd（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+以测试先行的方式构建功能或修 bug：red → green 循环。
+
+## 步骤
+
+1. **先定 seam**：seam 是你据以测试的公共边界（无需伸手进内部即可观察行为）。写测试前先写下待测 seam 并与用户确认；**未确认的 seam 上不写测试**。
+2. **红**：写一个失败的测试。测试通过公共接口验证行为，读起来像规格（描述 WHAT 而非 HOW），每个测试一个逻辑断言。不要 mock 内部协作者，不要走旁路（绕过接口查数据库）。
+3. **绿**：只写刚好让这个测试通过的实现。不加预判未来测试的投机功能。
+4. **重复**：以**纵向切片**推进——一个测试 → 一个实现 → 重复，每个测试是回应上一轮所学的一发**曳光弹**。不要「先写完所有测试再写所有实现」。
+5. **重构**不属于 red → green 循环；它属于评审阶段。
+
+探索代码库时读 `CONTEXT.md`（若存在），让测试名匹配领域语言，并遵守相关 ADR。
+
+## 期望值
+
+期望值必须来自**独立真相源**：已知良好的字面量、算好的例子、规格。不要以代码的算法重算期望值（`expect(add(a, b)).toBe(a + b)`、手工按同样方式推出的快照）——那是同义反复，只会通过，永远无法与代码唱反调。
+
+## mock
+
+**只在系统边界 mock**：外部 API、数据库（有时——优先测试库）、时间/随机性、文件系统（有时）。**不要 mock** 你自己的类/模块、内部协作者、任何你控制得了的东西。
+
+便于 mock 的边界设计：用依赖注入把外部依赖传进来；优先 SDK 式接口（每个操作一个具体函数）而非带条件的通用 fetcher。
+
+## 反模式速查
+
+- 耦合实现：重构后行为未变测试却坏。
+- 同义反复：断言由构造保证为真。
+- 横切切片：批量测试验证想象的行为，测的是形状而非用户行为。
+
+当 seam 形状本身存疑（模块多深、seam 在哪、接口暴露什么）时，参考 `codebase-design` 的 module / interface / depth / seam / adapter / leverage / locality 词汇。

package/skills/project-docs-workflow/references/issues.md

@@ -0,0 +1,51 @@
+# Issue tracker
+
+Default profile. Projects may override in their materialized `docs/agents/issues.md`; that copy governs runtime behavior.
+
+## Directory contract
+
+```
+docs/issues/
+├── bug/{human,agent}/        # defect fixes
+├── feature/{human,agent}/    # new features
+├── chore/{human,agent}/      # maintenance / refactor / misc
+├── suggestion/{human,agent}/ # improvement ideas (no history, no status; terminus ADR / PDR)
+└── <bug|feature|chore>/history/   # archived: filename suffixed -done / -drop
+```
+
+- `human/` and `agent/` = current responsible party. Transfer responsibility with `git mv` to the other directory.
+- Keep near-term work only (~1-week window). Whoever finishes or abandons an entry archives it; humans sweep periodically.
+- `history/` holds archived entries: suffix the filename `-done.md` (completed) or `-drop.md` (abandoned).
+- `suggestion` is special: no `history/`, no status.
+
+## Entry format
+
+- An issue is the workflow's work unit: one feature-level deliverable (bug / chore share the shape, simplified). See `workflow.md`.
+- Filename: short title in the project language, no number (e.g. `修复-波形首屏卡顿.md`). Archive by adding the status suffix.
+- Metadata line: `> Status: open|doing|blocked | 责任: human|agent | 创建: YYYY-MM-DD | 关联: ...` (关联 holds links such as `ADR-XXXX` or other entries).
+- Body: background and goal, as prose.
+- `## 完成判据` — completion criteria.
+- `## 结果（完成后填写，可选）` — outcome, filled in on completion (optional).
+- `## 步骤` — the five-step checklist from `workflow.md`; update it in place, and append a Log line on every step change. Materialized (Chinese) copies show:
+
+  ```
+  ## 步骤
+  - [ ] 规划（完成判据与方案已对齐）
+  - [ ] 骨架（最小可运行切片 + 证据；纯修复可跳过并注明理由）
+  - [ ] 细节（主路径实现与质量）
+  - [ ] 异常（失败路径、边界与稳定性）
+  - [ ] 回顾（收尾回顾：文档同步）
+  ```
+
+- `## Log` — dated lines appended in place; never rewrite history lines.
+- `Status` is updated in place.
+- Work that changes an ADR or PDR must sync those documents.
+- If the skill is installed, the skeleton lives at `~/.agents/skills/project-docs-workflow/assets/templates/entries/issue-entry.md`; otherwise create from the format above.
+
+## `suggestion` routing
+
+When a suggestion is resolved:
+
+- Accepted → land the conclusion in an ADR (or update the PDR), then remove the entry (`采纳 → 结论落 adr（或更新 pdr），随后删除本条目；`).
+- Rejected → delete it. Record a rejection ADR only if a human explicitly asks.
+- Actually a bug / feature / chore → move it to that directory.

package/skills/project-docs-workflow/references/pdr.md

@@ -0,0 +1,33 @@
+# PDR product specs
+
+PDR = target-state product spec ("产品规格书"): what the product should become, its modules, outward contracts, and mechanism design. Default profile; overridable in project copies.
+
+## Structure
+
+- Module directories numbered by reading order (e.g. `01-architecture/`, `02-ui/`). Root `00-README.md` = module index + reading order.
+- Each module:
+  - `00-README.md` — role / scope-boundary / dependencies / doc map.
+  - `01-spec.md` — functional requirements, each with an `FR-<MODULE>-NN` ID and 验收判据 (acceptance criteria). FR IDs are stable and never reused; numbering is continuous per module.
+  - `02-interfaces.md` — interface contracts. The providing module owns its outward interfaces; consumers reference them.
+  - `03-nfr.md` — non-functional requirements.
+  - `04-current.md` — current-state snapshot vs the spec; dated, ≤1 page, conclusions and gaps only. See "Goal / current & gap→issues".
+  - `design/` — optional mechanism-level design, **not numbered**.
+- Cross-module architecture and research material may live in module-external directories.
+
+## Goal / current & gap→issues
+
+- **The spec is the goal.** `NN/01-spec.md` is the target state; there are no separate goal files — the details of the end state live in the module specs, not in root docs.
+- **Root README carries two sections.** `docs/pdr/00-README.md` gains 「最终目标」(one-paragraph end state; details live in the module specs) and 「当前进展」(one line of status per module, each pointing to that module's `04-current.md`).
+- **Per-module `04-current.md`** is a current-state snapshot measured against the spec: dated, ≤1 page, conclusions and gaps only (never a log). Updated by the agent at issue completion, as part of the wrap-up review (see `workflow.md`).
+- **Scope & adoption.** Applies to numbered modules. Existing projects adopt it lazily — per module, when that module is next touched; init reports the diff and never overwrites.
+- **Gap → issue.** At the Plan step the agent reads goal (spec) plus current, derives gap candidates (module / FR, suggested type, slice, acceptance criteria), and the user picks. Accepted candidates land as entries in `docs/issues/` whose 关联 records the module / FR. No idle auto-creation of issues.
+
+## PDR ↔ ADR boundary
+
+- PDR = what the product should be (target state).
+- ADR = decisions with rationale and trade-offs.
+- A suggestion's acceptance routes into an ADR or the PDR (see `issues.md`).
+
+## Example (DA_AGENT) — not part of the general rules
+
+DA_AGENT is a concrete instance of this pattern: modules ui / agent / cpp-core / FPGA, plus architect and research as module-external areas; each module uses the spec layer `00-README / 01-spec / 02-interfaces / 03-nfr` with an unnumbered `design/` sub-area; FR prefixes read `FR-AGENT-NN`, `FR-UI-NN`, …; product scenarios sit in a separate `07-scenarios.md`. Source: DA_AGENT ADR-0026.

package/skills/project-docs-workflow/references/terminology.md

@@ -0,0 +1,21 @@
+# Domain terminology
+
+Two layers. Default profile; overridable in project copies.
+
+## 1. Primary glossary — `CONTEXT.md`
+
+- Per term: `**Term**：definition` followed by `_Avoid_: synonyms`.
+- Group terms under sections when clusters emerge; a flat list is fine for a single cohesive area.
+- Project-specific concepts only — zero implementation detail.
+
+## 2. Domain glossary — e.g. `docs/common/glossary.md`
+
+- Numbered index table (one line per term) + per-term sections + cross-links.
+
+## Usage rules
+
+- Read `CONTEXT.md` plus the relevant ADRs before exploring.
+- Use glossary vocabulary in every artifact (issue titles, refactor proposals, hypotheses, test names). Never drift to `_Avoid_` synonyms.
+- A novel concept is a signal: rethink whether you are inventing language the project does not use, or record the gap (hand it to `domain-modeling`, 未安装则按 `references/deps/domain-modeling.md` 执行).
+- If these files are missing, continue silently; creation happens when terms or decisions finalize, typically via `domain-modeling`（兜底 `references/deps/domain-modeling.md`）.
+- Flag ADR conflicts explicitly (`> _与 ADR-XXXX … 冲突，但…_`); never silently override.

package/skills/project-docs-workflow/references/workflow.md

@@ -0,0 +1,45 @@
+# Development workflow
+
+Default profile. Projects may override in their materialized `docs/agents/workflow.md`; that copy governs runtime behavior.
+
+The default shape for developing a single issue: align, build a thin slice, fill it in, harden it, then sync docs. The flow is a recommendation — projects may override any step — but while it is in use, its one hard rule is that alignment and planning come before implementation.
+
+## Work unit & granularity
+
+- The work unit is the **issue** (see `issues.md`): one feature-level deliverable. Bug / chore use the same shape, simplified.
+- **Granularity is a suggestion**, never forced: size a slice for a single reviewable push (heuristic ≈ 0.5 person-day), elastic per task.
+- **Stage slicing is agent-perceived** — which slice of the feature to take next never becomes directories or files; the only materialized tracking is the issue's own `## 步骤` checklist. An optional one-line note inside the issue can make the current stage explicit.
+
+## Alignment
+
+- **Align before building**: implementation starts only after the alignment is done and the plan / steps are written (align → plan & steps → build).
+- Alignment is **conversational and soft**: no freeze, no ceremonial "aligned" record. Re-align proactively when needs change (feature-requirement drift).
+- On an ambiguous direction, invoke `grilling`（未安装则按 `references/deps/grilling.md` 执行）; `grill-me` is only an entry alias; `grill-with-docs` = `grilling` + `domain-modeling`（兜底 `references/deps/grilling.md` + `references/deps/domain-modeling.md`）.
+- **Gap analysis** happens here, at Plan: read the goal (spec) plus current state, derive gap candidates (module / FR, suggested type, slice, acceptance criteria), and let the user pick. No idle auto-creation of issues.
+
+## The five steps
+
+1. **规划 / Plan** — refine acceptance criteria, set the step checklist status, and write a 1–2 sentence approach. Minimal output; no new sections. Gap analysis happens here.
+2. **骨架 / Skeleton** — a minimal runnable vertical slice (ignore output / formatting polish); leave one piece of run evidence and show it to the user — the first review point. Skippable for pure fixes (Log the reason); mandatory for features and structural work.
+3. **细节 / Details** — main-path implementation, detail completion, code quality. `tdd`（未安装则按 `references/deps/tdd.md` 执行）is an optional internal loop.
+4. **异常 / Exceptions** — failure paths, boundaries, and stability after the main path. Real development blockers are handled immediately and Logged, never queued for this step.
+5. **回顾 / Wrap-up review** (收尾回顾) — a lightweight docs-sync checklist at issue completion (pdr/current, adr, context, issues, agents); if nothing needs updating, one Log line. Doc sync only; session / agent retrospectives belong to `retro`（未安装则按 `references/deps/boundaries.md` 执行）.
+
+## Progress & resume
+
+- The issue entry carries a `## 步骤` checklist (the five steps); update it **in place**. Every step change appends a Log line.
+- **Sessions are soft.** A session is the user's attention window; the user controls pace (they may new / compact between issues). The agent must not absorb work beyond the aligned scope.
+- **On resume**, read the issue's 步骤 plus Log first, then confirm the continuation point with the user.
+
+## Docs sync hooks
+
+- **Plan**: gap → issue candidates land in `docs/issues`; the entry's 关联 records the module / FR.
+- **Wrap-up review**: update the module's `04-current.md` as part of completing the issue (see `pdr.md`); touch `adr` / `context` / `issues` / `agents` when the change warrants it.
+- **Archival**: archive the issue per `issues.md` when done / dropped.
+
+## Boundaries
+
+- Large or high-risk multi-phase work → `deepwork`（未安装则按 `references/deps/boundaries.md` 执行）; never stack it with this flow.
+- `tdd`（未安装则按 `references/deps/tdd.md` 执行）nests inside Details; seam confirmation folds into the Plan alignment (no second gate).
+- `retro`（未安装则按 `references/deps/boundaries.md` 执行）owns session / agent retrospectives; the fifth step is docs sync only.
+- See `coexistence.md` for how this profile sits beside these skills.

package/skills/retro/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: retro
+description: 对编码会话或 agent 表现做回顾，输出针对 agent 环境的改进建议。
+disable-model-invocation: true
+---
+
+# Retro（会话回顾）
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 retro（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+会话/agent 回顾的所有权属于本 skill；`project-docs-workflow` 第五步「回顾」只是文档同步，不做会话回顾。
+
+最小回顾至少覆盖三问：
+
+1. **发生了什么**：读指定会话的原始记录（未指定则默认当前会话），尽量取原始来源。
+2. **保留什么**：哪些做法或环境配置有效，值得延续。
+3. **改变什么**：给出针对 agent **环境**的改进候选（导航指针、自动化检查、编码规范、全局指令瘦身、工具经济性、多余指令、信息可达性），按严重程度排序呈现给用户。
+
+若环境未安装完整 skill，按 `project-docs-workflow/references/deps/boundaries.md` 的最小三问回顾执行。

package/skills/tdd/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: tdd
+description: 测试驱动开发。当用户想以测试先行方式构建功能或修 bug、提到 "red-green-refactor"、或需要集成测试时使用。
+---
+
+# TDD（测试驱动开发）
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 tdd（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+TDD 就是 red → green 循环。本 skill 是让这个循环产出**值得保留**的测试的参考：什么算好测试、测试放哪里、反模式、以及循环的规则。每一节在**每个循环**都适用——在循环前和循环中都查阅，而不是事后。
+
+探索代码库时读 `CONTEXT.md`（若存在），让测试名与接口词汇匹配项目领域语言，并遵守所涉区域的 ADR。
+
+## 什么是好测试
+
+测试通过**公共接口**验证行为，而非实现细节。代码可以整个换掉，测试不应跟着变。好测试读起来像规格说明：「user can checkout with valid cart」准确告诉你存在什么能力，且因为不关心内部结构，能扛住重构。
+
+特征：测试用户/调用方真正关心的行为；只用公共 API；重构后仍存活；描述 WHAT 而非 HOW；每个测试一个逻辑断言。
+
+## Seam：测试放哪里
+
+**seam（接缝）** 是你据以测试的公共边界：无需伸手进内部即可观察行为的接口。测试住在 seam 上，绝不针对内部。
+
+- **只在事先约定的 seam 上测试。** 写任何测试前，先写下待测 seam 并与用户确认。未确认的 seam 上不写测试。你无法测试一切，事先约定 seam 才能把测试精力落在关键路径和复杂逻辑上，而不是每个边界情况。
+- 问：「公共接口是什么？我们该测哪些 seam？」
+
+当接口形状本身存疑（模块多深、seam 该在哪、接口暴露什么）时，调用 `codebase-design` skill 获取 module / interface / depth / seam / adapter / leverage / locality 的共享词汇；它是参考，不是要跑的一次会话。
+
+## 反模式
+
+- **耦合实现**：mock 内部协作者、测私有方法、或走旁路验证（绕过接口直接查数据库）。信号：重构后行为未变，测试却坏了。
+- **同义反复（tautological）**：断言以代码的算法重算期望值（`expect(add(a, b)).toBe(a + b)`、手工按同样方式推出的快照、常量自比），于是它只会通过、永远无法与代码唱反调。期望值必须来自独立真相源：已知良好的字面量、算好的例子、规格。
+- **横切切片**：先写完所有测试，再写所有实现。批量测试验证的是**想象中**的行为：测的是事物的**形状**而非面向用户的行为，测试对真实变化变得迟钝，且你在理解实现前就锁定了测试结构。改用**纵向切片**：一个测试 → 一个实现 → 重复，每个测试都是**曳光弹**，回应上一轮学到的东西。
+
+## 循环规则
+
+- **先红后绿。** 先写失败的测试，再只写刚好让它通过的代码。不要预判未来测试或加投机功能。
+- **一次一片。** 每个循环一个 seam、一个测试、一个最小实现。
+- **重构不属于循环。** 它属于评审阶段（见 `code-review` skill），不属于 red → green 实现循环。
+
+## 模拟（mock）
+
+**只在系统边界 mock**：外部 API（支付、邮件等）、数据库（有时——优先用测试库）、时间/随机性、文件系统（有时）。
+
+**不要 mock**：你自己的类/模块、内部协作者、任何你控制得了的东西。
+
+边界接口的设计要便于 mock：
+
+- **依赖注入**：把外部依赖传进来，而不是在内部创建。`processPayment(order, paymentClient)` 好过内部 `new StripeClient(...)`。
+- **优先 SDK 式接口而非通用 fetcher**：每个外部操作一个具体函数（`getUser` / `getOrders` / `createOrder`），而不是一个带条件逻辑的通用 `fetch`。这样每个 mock 只返回一种确定形状，测试准备里没有条件逻辑，也更容易看出测试覆盖了哪些端点。

package/skills/tdd/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "TDD"
+  short_description: "Test-driven red-green-refactor"