diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 833b7fc..0f059bf 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,8 +9,8 @@ { "name": "specode", "source": "./plugins/specode", - "version": "6.0.0", - "description": "Lightweight spec-driven workflow: orchestrates superpowers skills per phase, lands 4 fixed docs (requirements/design/tasks/implementation-log). **v6.0.0 BREAKING**: 固定产物 3→4 — design.md 重定义为**传统设计文档**(背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略,散文无 checkbox);新增 tasks.md 承载可执行计划(writing-plans 格式 + Interfaces 契约块,引擎中立,task-swarm/superpowers/自执行统一消费,pipeline.yml 改从 tasks.md 推导);流水线变为 requirements→design→tasks→执行方式 selector→执行→验收,brainstorming 一次跨 requirements+design 双产物落盘(后置 relocate 检查两份);continue 改「加载即停」— 只读文档+汇报进度简报后停下等指令,绝不自动续跑;design-unchecked 更名 plan-unchecked(tasks.md 优先,design.md 含 checkbox 按 5.x legacy 兜底,旧名保留 alias)。5.x 存量 spec 由 continue 推断表 legacy 行兜底识别,不中断。 **v5.2.0**: 新增 Tier-0 RagKit gate — 检测到 ragkit 插件 + 已建索引(chunks.json)时,requirements/design 的经验检索走 `ragkit:query` 多路召回(模型自主提炼检索词、可多轮多角度、≤5 点封顶),未安装零成本跳过,zero-import。 **v5.1.3**: `list-specs` 让 intake 阶段（目录已建、requirements 未写）的 spec 可见 — 列出含任一固定产物的子目录 + 空子目录(intake)，隐藏目录与无关内容目录仍排除；全库文档陈旧内容清理(README/CONTRIBUTING/SKILL 残留措辞)。 **v5.0.1**: distill skill 加 `user-invocable:false`(隐藏裸 `/distill` + 消除 `/specode:distill` 重复);distill 收敛为纯 md-only(移除 `--format yml|both` + codemap 死路径);清理全部 `.ai-memory`/codemap 文档残留 + requirements 模板删 recall 段。**v5.0.0 BREAKING**: 命令去 `specode-` 前缀 — `/specode:spec` / `/specode:continue` / `/specode:list` / `/specode:distill`(原 `/specode:specode-*`);内核 skill 加 `user-invocable:false` 隐藏裸 `/specode`。**v4.0.0 BREAKING**: 彻底拔出记忆注入工程 — 砍 P3-1 codemap recall / P3-2 rule-check / acceptance auto-distill prompt。保留 project-level CLAUDE.md scan。distill v4 完全重写为手动 md-only Obsidian wiki organizer, 默认写 `/Volumes/External HD/Obsidian/Notes/11-KnowledgeBase//`。如需 v3 行为 checkout `backup/specode-v3.4.0-task-swarm-v0.9.2`。", + "version": "6.1.0", + "description": "Lightweight spec-driven workflow: orchestrates superpowers skills per phase, lands 4 fixed docs (requirements/design/tasks/implementation-log). **v6.1.0**: 新增独立 intake skill(skills/intake/,同 distill,user-invocable:false)接管 requirements phase — 项目分析(agent-docs 扫描+经验检索+读真实代码)+基于分析的澄清+写 requirements.md(保留 spec_id/created_at/project_root frontmatter 契约);修正 6.0.0 的brainstorming 双产物错位 — brainstorming 从此只产 design.md(单产物),requirements 由 intake 产;检索主节点移到 intake 项目分析步、design 降为条件性 top-up;弊端修复 — writing-plans 结尾的执行方式提问改为「忽略而非抑制」;SKILL 轻量化 215→171 行(verb 表/autonomous-mode 细节下沉到 refs,零行为变化)。 **v6.0.0 BREAKING**: 固定产物 3→4 — design.md 重定义为**传统设计文档**(背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略,散文无 checkbox);新增 tasks.md 承载可执行计划(writing-plans 格式 + Interfaces 契约块,引擎中立,task-swarm/superpowers/自执行统一消费,pipeline.yml 改从 tasks.md 推导);流水线变为 requirements→design→tasks→执行方式 selector→执行→验收,brainstorming 一次跨 requirements+design 双产物落盘(后置 relocate 检查两份);continue 改「加载即停」— 只读文档+汇报进度简报后停下等指令,绝不自动续跑;design-unchecked 更名 plan-unchecked(tasks.md 优先,design.md 含 checkbox 按 5.x legacy 兜底,旧名保留 alias)。5.x 存量 spec 由 continue 推断表 legacy 行兜底识别,不中断。 **v5.2.0**: 新增 Tier-0 RagKit gate — 检测到 ragkit 插件 + 已建索引(chunks.json)时,requirements/design 的经验检索走 `ragkit:query` 多路召回(模型自主提炼检索词、可多轮多角度、≤5 点封顶),未安装零成本跳过,zero-import。 **v5.1.3**: `list-specs` 让 intake 阶段（目录已建、requirements 未写）的 spec 可见 — 列出含任一固定产物的子目录 + 空子目录(intake)，隐藏目录与无关内容目录仍排除；全库文档陈旧内容清理(README/CONTRIBUTING/SKILL 残留措辞)。 **v5.0.1**: distill skill 加 `user-invocable:false`(隐藏裸 `/distill` + 消除 `/specode:distill` 重复);distill 收敛为纯 md-only(移除 `--format yml|both` + codemap 死路径);清理全部 `.ai-memory`/codemap 文档残留 + requirements 模板删 recall 段。**v5.0.0 BREAKING**: 命令去 `specode-` 前缀 — `/specode:spec` / `/specode:continue` / `/specode:list` / `/specode:distill`(原 `/specode:specode-*`);内核 skill 加 `user-invocable:false` 隐藏裸 `/specode`。**v4.0.0 BREAKING**: 彻底拔出记忆注入工程 — 砍 P3-1 codemap recall / P3-2 rule-check / acceptance auto-distill prompt。保留 project-level CLAUDE.md scan。distill v4 完全重写为手动 md-only Obsidian wiki organizer, 默认写 `/Volumes/External HD/Obsidian/Notes/11-KnowledgeBase//`。如需 v3 行为 checkout `backup/specode-v3.4.0-task-swarm-v0.9.2`。", "homepage": "https://github.com/qxbyte/pluginhub", "repository": "https://github.com/qxbyte/pluginhub", "license": "MIT", diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c04f47..ed9bed1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,14 @@ ## Unreleased +## 6.1.0 (2026-07-05) — specode + +- **新增独立 `intake` skill**（`skills/intake/`，同 `distill` 平级）接管 requirements phase：项目分析（agent-docs 扫描 + 经验检索 + 读真实代码）+ 基于分析的澄清 + 写 `requirements.md`（保留 `spec_id` / `created_at` / `project_root` frontmatter 契约，`project_root` 仍经 `write-project-root` 单写入口）。 +- **修正 6.0.0 brainstorming 双产物错位**：brainstorming 从此只产 `design.md`（单产物），requirements 由 intake 产；requirements phase 不再有 superpowers/native 分叉。 +- **检索节点收敛**：主节点 = intake 项目分析步；design = 条件性 top-up（继承 intake 指针）；tasks / 执行零注入不变。 +- **弊端修复**：writing-plans 结尾的执行方式提问改为「忽略而非抑制」（无参数可关，只能消化）。 +- **SKILL 轻量化**：`skills/specode/SKILL.md` 215 → 171 行，verb 表 / autonomous-mode 细节下沉到 references（零行为变化）。 + ## 6.0.0 (2026-07-03) — specode **BREAKING**：固定产物 3 → 4，修正 5.x 的两级错位（brainstorming 的设计产出被当成 requirements、writing-plans 的计划被当成 design）。 diff --git a/README.md b/README.md index 0bf38b4..e2845cf 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ any plugin it hosts. More plugins will land here over time. | Plugin | Version | What it does | | --- | --- | --- | -| **specode** | 6.0.0 | A lightweight spec-driven **workflow** — orchestration shell that delegates each phase to [superpowers](https://github.com/obra/superpowers) skills (first-class native fallback) and lands 4 fixed docs per spec. **v6.0.0 BREAKING**: fixed docs 3 → 4 — `design.md` redefined as a **traditional design doc** (背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略, prose only, no checkboxes); new `tasks.md` carries the executable plan (writing-plans format + `**Interfaces:**` contract blocks), engine-neutral — task-swarm (pipeline.yml now derived from it) / superpowers / specode self-execute all consume the same file; pipeline becomes requirements → design → tasks → 执行方式 selector → execute → acceptance, with brainstorming spanning requirements+design in one dual-artifact call; `/specode:continue` becomes **load-and-stop** — reads docs, reports a progress brief, then waits for the user's instruction (never auto-resumes); `design-unchecked` renamed `plan-unchecked` (tasks.md first, 5.x legacy design.md fallback, old name kept as alias); 5.x specs keep working via the legacy inference row. **v5.2.0**: Tier-0 RagKit gate tightened — probe changed from `test -d .ragkit` to `test -f .ragkit/chunks.json` (eliminates false-positive when only config.json exists after `backend set`); Tier-0 採纳条目 capped at Tier-2 discipline (≤5/phase, reasoned override allowed). **v5.1.3**: `list-specs` now surfaces intake-phase specs (dir created, requirements not yet written) — lists subdirs containing any fixed doc plus empty subdirs, hidden dirs still excluded; repo-wide stale-docs cleanup. **v5.1.2**: distill polish — `ensure-gitignore` skips in a non-git project with no existing `.gitignore` (no stray file); new `knowledge.py copy-to` verb (one-step dual-landing: copy cases/navigation + rebuild the dest's MEMORY) now used by distill Step 5; navigation `来源` keeps the origin slug (reusing specs listed in body). **v5.1.1**: validation-driven fixes — distill runs `design-unchecked` before sedimenting (warns if the spec isn't fully executed, so knowledge points don't reference unbuilt code); dedup navigation points against MEMORY before writing; retrieval emphasizes semantic relevance over tag-overlap. **v5.1.0**: reintroduces experience retrieval/injection on a new "pointers-not-facts" footing — new stdlib `knowledge.py` (ensure-gitignore/memory-rebuild/memory-validate); distill now emits **atomic case/navigation knowledge-points** to the project's `/knowledge-base/` (cases/ + navigation/ + a MEMORY index, gitignored), optionally copied to Obsidian; new `references/retrieval.md` two-tier gated retrieval wired into the requirements/design phases (inject pointers not facts, default reads only the small index, ≤5 docs on hit); acceptance re-hooks the distill prompt via the existing `auto_distill` default. **v5.0.1**: the `distill` skill is now `user-invocable: false` (hides the bare `/distill` + the duplicate `/specode:distill`, leaving one clean command entry); distill is now **md-only** (dropped the dead `--format yml|both` + `codemap knowledge write` path); purged all remaining `.ai-memory`/codemap doc references and removed the obsolete recall section from the requirements template. **v5.0.0 BREAKING**: commands dropped the redundant `specode-` prefix — `/specode:spec` / `/specode:continue` / `/specode:list` / `/specode:distill` (were `/specode:specode-*`); the `distill` skill dir + name were renamed to `distill`; the `specode` orchestration skill is now `user-invocable: false` so the bare `/specode` no longer shows in the slash menu (still auto-activates via its commands). Preserved AI-EDS-era features: project-level `CLAUDE.md` / `AGENT.md` filesystem scan injected as `## 项目级约束` section (痛点 #14 方案 D), SessionStart cache-vs-marketplace drift hint (M8), autonomous-mode defaults — 5 schema keys + 5 `SPECODE_*` env vars + `read-defaults` / `write-default` / `reset-default` verbs (M1+M9). **v4.0.0 BREAKING**: removed memory-injection pipeline — P3-1 `codemap recall` injection / P3-2 rule-acknowledgement post-check / acceptance auto-distill prompt all dropped; round 1/2 baseline showed the recall round-trip did not net save token. `distill` skill v4 rewritten as a **manual-only Obsidian organizer** — `/specode:distill ` writes md (default) to `/Volumes/External HD/Obsidian/Notes/11-KnowledgeBase//`, no `.ai-memory/` writes. To restore v3 behaviour: `git checkout backup/specode-v3.4.0-task-swarm-v0.9.2`. | +| **specode** | 6.1.0 | A lightweight spec-driven **workflow** — orchestration shell that delegates each phase to [superpowers](https://github.com/obra/superpowers) skills (first-class native fallback) and lands 4 fixed docs per spec. **v6.1.0**: new standalone `specode:intake` skill (peer to `distill`) owns the requirements phase — project analysis (agent-docs scan + experience retrieval + reading located real code) + analysis-driven clarification + writes `requirements.md` preserving the `spec_id`/`created_at`/`project_root` frontmatter contract; fixes the 6.0.0 brainstorming dual-artifact mismatch (brainstorming now produces `design.md` only); retrieval's primary node moves to intake with design as a conditional top-up; writing-plans' execution-mode question is now ignored (not "suppressed"); SKILL.md lightened 215→171 lines (verb table + autonomous-mode detail sunk to references) and dead v3/codemap-term noise dropped from distill. **v6.0.0 BREAKING**: fixed docs 3 → 4 — `design.md` redefined as a **traditional design doc** (背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略, prose only, no checkboxes); new `tasks.md` carries the executable plan (writing-plans format + `**Interfaces:**` contract blocks), engine-neutral — task-swarm (pipeline.yml now derived from it) / superpowers / specode self-execute all consume the same file; pipeline becomes requirements → design → tasks → 执行方式 selector → execute → acceptance, with brainstorming spanning requirements+design in one dual-artifact call; `/specode:continue` becomes **load-and-stop** — reads docs, reports a progress brief, then waits for the user's instruction (never auto-resumes); `design-unchecked` renamed `plan-unchecked` (tasks.md first, 5.x legacy design.md fallback, old name kept as alias); 5.x specs keep working via the legacy inference row. **v5.2.0**: Tier-0 RagKit gate tightened — probe changed from `test -d .ragkit` to `test -f .ragkit/chunks.json` (eliminates false-positive when only config.json exists after `backend set`); Tier-0 採纳条目 capped at Tier-2 discipline (≤5/phase, reasoned override allowed). **v5.1.3**: `list-specs` now surfaces intake-phase specs (dir created, requirements not yet written) — lists subdirs containing any fixed doc plus empty subdirs, hidden dirs still excluded; repo-wide stale-docs cleanup. **v5.1.2**: distill polish — `ensure-gitignore` skips in a non-git project with no existing `.gitignore` (no stray file); new `knowledge.py copy-to` verb (one-step dual-landing: copy cases/navigation + rebuild the dest's MEMORY) now used by distill Step 5; navigation `来源` keeps the origin slug (reusing specs listed in body). **v5.1.1**: validation-driven fixes — distill runs `design-unchecked` before sedimenting (warns if the spec isn't fully executed, so knowledge points don't reference unbuilt code); dedup navigation points against MEMORY before writing; retrieval emphasizes semantic relevance over tag-overlap. **v5.1.0**: reintroduces experience retrieval/injection on a new "pointers-not-facts" footing — new stdlib `knowledge.py` (ensure-gitignore/memory-rebuild/memory-validate); distill now emits **atomic case/navigation knowledge-points** to the project's `/knowledge-base/` (cases/ + navigation/ + a MEMORY index, gitignored), optionally copied to Obsidian; new `references/retrieval.md` two-tier gated retrieval wired into the requirements/design phases (inject pointers not facts, default reads only the small index, ≤5 docs on hit); acceptance re-hooks the distill prompt via the existing `auto_distill` default. **v5.0.1**: the `distill` skill is now `user-invocable: false` (hides the bare `/distill` + the duplicate `/specode:distill`, leaving one clean command entry); distill is now **md-only** (dropped the dead `--format yml|both` + `codemap knowledge write` path); purged all remaining `.ai-memory`/codemap doc references and removed the obsolete recall section from the requirements template. **v5.0.0 BREAKING**: commands dropped the redundant `specode-` prefix — `/specode:spec` / `/specode:continue` / `/specode:list` / `/specode:distill` (were `/specode:specode-*`); the `distill` skill dir + name were renamed to `distill`; the `specode` orchestration skill is now `user-invocable: false` so the bare `/specode` no longer shows in the slash menu (still auto-activates via its commands). Preserved AI-EDS-era features: project-level `CLAUDE.md` / `AGENT.md` filesystem scan injected as `## 项目级约束` section (痛点 #14 方案 D), SessionStart cache-vs-marketplace drift hint (M8), autonomous-mode defaults — 5 schema keys + 5 `SPECODE_*` env vars + `read-defaults` / `write-default` / `reset-default` verbs (M1+M9). **v4.0.0 BREAKING**: removed memory-injection pipeline — P3-1 `codemap recall` injection / P3-2 rule-acknowledgement post-check / acceptance auto-distill prompt all dropped; round 1/2 baseline showed the recall round-trip did not net save token. `distill` skill v4 rewritten as a **manual-only Obsidian organizer** — `/specode:distill ` writes md (default) to `/Volumes/External HD/Obsidian/Notes/11-KnowledgeBase//`, no `.ai-memory/` writes. To restore v3 behaviour: `git checkout backup/specode-v3.4.0-task-swarm-v0.9.2`. | | **task-swarm** | 0.10.1 | Multi-agent **orchestration** driven by a `pipeline.yml`: semantic task groups with cross-group concurrency, fork coders, per-group reviewer + validator loops. **v0.10.1**: the `task-swarm` orchestration skill is now `user-invocable: false` so the bare `/task-swarm` no longer shows in the slash menu (the `/task-swarm:swarm` command is unchanged). Preserved AI-EDS-era features: frontmatter-first `project_root` + registry-based run lookup (0.7.x), `## 项目级约束（必读）` section + `_PROJECT_AGENT_DOCS.md` inbox sentinel (0.7.3 + 0.7.4), lifecycle group with `init` dedupe (`--on-existing {error/resume/abort-old/force-new}` flag) + `run.pipeline_end_validator` (0.8.0 + 0.8.1), M2 `run-loop` auto-driver (0.8.1), task.md `## 开发纪律 (范式参考)` section listing superpowers skill names as paradigm identifiers (0.9.0–0.9.2). **v0.10.0 BREAKING**: removed `_ingest_lessons.py` + `cmd_resolve` auto-ingest + `--no-ingest` flag — `cmd_resolve` no longer writes `/.ai-memory/knowledge/cases\|pitfalls/*.yml`. To restore v0.9.x behaviour: `git checkout backup/specode-v3.4.0-task-swarm-v0.9.2`. See [`plugins/task-swarm/`](./plugins/task-swarm). | | **obsidian-wiki** | 2.0.1 | Maintain an Obsidian LLM-Wiki with three skills: deterministic structure layer (`wiki-struct`: Home tree / READMEs / partition pages), content curation (`wiki-curate`: ingest / curate / lint), unified orchestrator (`wiki-orchestrate`). Generic code + per-vault config in the home-dir registry `~/.config/obsidian-wiki/` (falls back to `/.wiki/config.json`). **v2.0.0 BREAKING**: the spec-distill skill was extracted into specode's `/specode:distill`. See [`plugins/obsidian-wiki/`](./plugins/obsidian-wiki). | | **ragkit** | 0.1.0 | Standalone knowledge-base **RAG** — vector + lexical + metadata three-channel recall, RRF-fused, returns pointer cards. Optional downstream consumer of specode `distill` output; zero heavy deps (stdlib + numpy for lexical mode). See [`plugins/ragkit/`](./plugins/ragkit). | @@ -192,12 +192,16 @@ back to cwd) and asks you to confirm it once per spec. On the **first ever** run it also asks once for your document management directory and remembers it. The agent then walks the pipeline: -1. **requirements** — clarify + write `requirements.md` (via - `superpowers:brainstorming`, or a native `AskUserQuestion` wizard). +1. **requirements** — the `specode:intake` skill (specode's own, always) + runs project analysis (agent-docs scan + experience retrieval + + reading the located real code) → analysis-driven clarification → + writes `requirements.md` with the frontmatter contract (`spec_id` / + `created_at` / `project_root`). This is also the **primary node for + ragkit/experience retrieval**. 2. **design** — produce a traditional design doc `design.md` (architecture / modules / interfaces / data flow / error handling / - test strategy; brainstorming's design output lands here, or native - authoring). + test strategy) via `superpowers:brainstorming` (design only) or native + authoring. 3. **tasks** — produce the executable plan `tasks.md` (via `superpowers:writing-plans`, or native Task breakdown). Engine-neutral: every execution path consumes this one file. @@ -268,7 +272,9 @@ plugins/specode/ selectors.md 执行方式 selector verbatim examples obsidian.md specsRoot path resolution + conventions superpowers-wiring.md phase ↔ superpowers skill mapping - retrieval.md two-tier gated experience retrieval spec + retrieval.md experience retrieval spec (intake primary node) + skills/intake/ + SKILL.md requirements phase engine (analysis + clarify + write) skills/distill/ SKILL.md /specode:distill behavior (case/navigation points) references/ breakdown heuristics + doc templates diff --git a/README.zh-CN.md b/README.zh-CN.md index c1a84ce..3ca8cc8 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -18,7 +18,7 @@ | 插件 | 版本 | 做什么 | | --- | --- | --- | -| **specode** | 6.0.0 | 轻量**规格驱动工作流**——编排外壳，每个阶段委托给 [superpowers](https://github.com/obra/superpowers) 技能（一等公民原生降级），每条规格固定产出 4 份文档。**v6.0.0 BREAKING**：固定产物 3→4——`design.md` 重定义为**传统设计文档**（背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略，散文无 checkbox）；新增 `tasks.md` 承载可执行计划（writing-plans 格式 + `**Interfaces:**` 契约块），引擎中立——task-swarm（pipeline.yml 改从它推导）/ superpowers / specode 自执行统一消费同一份文件；流水线变为 requirements → design → tasks → 执行方式 selector → 执行 → 验收，brainstorming 一次跨 requirements+design 双产物落盘；`/specode:continue` 改**加载即停**——只读文档 + 汇报进度简报后停下等指令，绝不自动续跑；`design-unchecked` 更名 `plan-unchecked`（tasks.md 优先，5.x legacy design.md 兜底，旧名保留 alias）；5.x 存量 spec 经 legacy 推断行兜底不中断。**v5.2.0**：Tier-0 RagKit gate 收紧——探针从 `test -d .ragkit` 改为 `test -f .ragkit/chunks.json`（消除 `backend set` 只写 config.json 时的假阳性）；Tier-0 采纳条目封顶 Tier-2 同等纪律（≤5 点/phase，复杂需求可标注理由突破）。 **v5.1.3**：`list-specs` 让 intake 阶段（目录已建、requirements 未写）的 spec 可见——列出含任一固定产物的子目录 + 空子目录，隐藏目录仍排除；全库文档陈旧内容清理。 **v5.1.2**：distill 打磨——非 git 且无 .gitignore 时 `ensure-gitignore` 跳过(不建 stray);新增 `copy-to` 一步 dual-landing(复制 + 重建 dest MEMORY),distill Step5 改用;navigation `来源` 单值保留 origin。 **v5.1.1**：试跑验证修复——distill 沉淀前 `design-unchecked` 检查是否执行完(未完告警,防指向未落地代码);写 navigation 前比对 MEMORY 去重;retrieval 强调语义相关而非 tag 命中。 **v5.1.0**：以全新「定位用·非事实用」路线重新引入经验检索注入——新增 stdlib `knowledge.py`(ensure-gitignore/memory-rebuild/memory-validate);distill 改产**原子 case/navigation 知识点**到项目 `/knowledge-base/`(cases/+navigation/+MEMORY 索引,不入仓),可选复制到 Obsidian;新增 `references/retrieval.md` 两级 gated 检索接入 requirements/design 阶段(注入指针非事实、默认只读小索引、命中才读≤5点);acceptance 末尾按 `auto_distill` 重新挂回 distill 提示。 **v5.0.1**：`distill` skill 改为 `user-invocable: false`（隐藏裸 `/distill` 与重复的 `/specode:distill`，只留命令一条）；distill 收敛为纯 **md-only**（移除已死的 `--format yml|both` 与 `codemap knowledge write` 路径）；清理全部 `.ai-memory`/codemap 文档残留，并从 requirements 模板删除已废弃的 recall 段。**v5.0.0 BREAKING**：命令去掉冗余 `specode-` 前缀——`/specode:spec` / `/specode:continue` / `/specode:list` / `/specode:distill`（原 `/specode:specode-*`）；`distill` skill 目录与 `name` 同改为 `distill`；编排内核 skill `specode` 改为 `user-invocable: false`，斜杠菜单不再显示裸 `/specode`（仍经命令自动激活）。AI-EDS 时代保留至 v4.0.0 的能力：项目级 `CLAUDE.md` / `AGENT.md` filesystem 扫描注入「## 项目级约束」段（痛点 #14 方案 D）、SessionStart cache 与 marketplace drift 提示（M8）、autonomous-mode defaults（5 schema key + 5 个 `SPECODE_*` env var + `read-defaults` / `write-default` / `reset-default` verb，M1+M9）。**v4.0.0 BREAKING**：拔除记忆注入工程——P3-1 `codemap recall` 注入 / P3-2 rule-acknowledgement post-check / acceptance 后自动 distill 全部砍掉；round 1/2 baseline 实验证明 recall 注入未 net 节省 token。`distill` skill v4 完全重写为**仅手动**Obsidian 整理器——`/specode:distill ` 默认 md-only 写到 `/Volumes/External HD/Obsidian/Notes/11-KnowledgeBase//`，不再写 `.ai-memory/`。如需 v3 行为：`git checkout backup/specode-v3.4.0-task-swarm-v0.9.2`。 | +| **specode** | 6.1.0 | 轻量**规格驱动工作流**——编排外壳，每个阶段委托给 [superpowers](https://github.com/obra/superpowers) 技能（一等公民原生降级），每条规格固定产出 4 份文档。**v6.1.0**：新增独立 `specode:intake` skill（与 `distill` 平级）接管 requirements phase——项目分析（agent-docs 扫描 + 经验检索 + 读定位到的真实代码）+ 基于分析的澄清 + 写 `requirements.md`（保留 `spec_id`/`created_at`/`project_root` frontmatter 契约）；修正 6.0.0 brainstorming 双产物错位（brainstorming 从此只产 `design.md`）；检索主节点移到 intake、design 降为条件性 top-up；writing-plans 执行方式提问改为「忽略而非抑制」；SKILL.md 轻量化 215→171 行（verb 表 + autonomous-mode 细节下沉到 references），并清理 distill 里的 v3/codemap 死术语噪声。**v6.0.0 BREAKING**：固定产物 3→4——`design.md` 重定义为**传统设计文档**（背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略，散文无 checkbox）；新增 `tasks.md` 承载可执行计划（writing-plans 格式 + `**Interfaces:**` 契约块），引擎中立——task-swarm（pipeline.yml 改从它推导）/ superpowers / specode 自执行统一消费同一份文件；流水线变为 requirements → design → tasks → 执行方式 selector → 执行 → 验收，brainstorming 一次跨 requirements+design 双产物落盘；`/specode:continue` 改**加载即停**——只读文档 + 汇报进度简报后停下等指令，绝不自动续跑；`design-unchecked` 更名 `plan-unchecked`（tasks.md 优先，5.x legacy design.md 兜底，旧名保留 alias）；5.x 存量 spec 经 legacy 推断行兜底不中断。**v5.2.0**：Tier-0 RagKit gate 收紧——探针从 `test -d .ragkit` 改为 `test -f .ragkit/chunks.json`（消除 `backend set` 只写 config.json 时的假阳性）；Tier-0 采纳条目封顶 Tier-2 同等纪律（≤5 点/phase，复杂需求可标注理由突破）。 **v5.1.3**：`list-specs` 让 intake 阶段（目录已建、requirements 未写）的 spec 可见——列出含任一固定产物的子目录 + 空子目录，隐藏目录仍排除；全库文档陈旧内容清理。 **v5.1.2**：distill 打磨——非 git 且无 .gitignore 时 `ensure-gitignore` 跳过(不建 stray);新增 `copy-to` 一步 dual-landing(复制 + 重建 dest MEMORY),distill Step5 改用;navigation `来源` 单值保留 origin。 **v5.1.1**：试跑验证修复——distill 沉淀前 `design-unchecked` 检查是否执行完(未完告警,防指向未落地代码);写 navigation 前比对 MEMORY 去重;retrieval 强调语义相关而非 tag 命中。 **v5.1.0**：以全新「定位用·非事实用」路线重新引入经验检索注入——新增 stdlib `knowledge.py`(ensure-gitignore/memory-rebuild/memory-validate);distill 改产**原子 case/navigation 知识点**到项目 `/knowledge-base/`(cases/+navigation/+MEMORY 索引,不入仓),可选复制到 Obsidian;新增 `references/retrieval.md` 两级 gated 检索接入 requirements/design 阶段(注入指针非事实、默认只读小索引、命中才读≤5点);acceptance 末尾按 `auto_distill` 重新挂回 distill 提示。 **v5.0.1**：`distill` skill 改为 `user-invocable: false`（隐藏裸 `/distill` 与重复的 `/specode:distill`，只留命令一条）；distill 收敛为纯 **md-only**（移除已死的 `--format yml|both` 与 `codemap knowledge write` 路径）；清理全部 `.ai-memory`/codemap 文档残留，并从 requirements 模板删除已废弃的 recall 段。**v5.0.0 BREAKING**：命令去掉冗余 `specode-` 前缀——`/specode:spec` / `/specode:continue` / `/specode:list` / `/specode:distill`（原 `/specode:specode-*`）；`distill` skill 目录与 `name` 同改为 `distill`；编排内核 skill `specode` 改为 `user-invocable: false`，斜杠菜单不再显示裸 `/specode`（仍经命令自动激活）。AI-EDS 时代保留至 v4.0.0 的能力：项目级 `CLAUDE.md` / `AGENT.md` filesystem 扫描注入「## 项目级约束」段（痛点 #14 方案 D）、SessionStart cache 与 marketplace drift 提示（M8）、autonomous-mode defaults（5 schema key + 5 个 `SPECODE_*` env var + `read-defaults` / `write-default` / `reset-default` verb，M1+M9）。**v4.0.0 BREAKING**：拔除记忆注入工程——P3-1 `codemap recall` 注入 / P3-2 rule-acknowledgement post-check / acceptance 后自动 distill 全部砍掉；round 1/2 baseline 实验证明 recall 注入未 net 节省 token。`distill` skill v4 完全重写为**仅手动**Obsidian 整理器——`/specode:distill ` 默认 md-only 写到 `/Volumes/External HD/Obsidian/Notes/11-KnowledgeBase//`，不再写 `.ai-memory/`。如需 v3 行为：`git checkout backup/specode-v3.4.0-task-swarm-v0.9.2`。 | | **task-swarm** | 0.10.1 | 由 `pipeline.yml` 驱动的**多 agent 编排**：语义任务组 + 跨组并发、fork coder、按组 reviewer + validator 循环。**v0.10.1**：编排内核 skill `task-swarm` 改为 `user-invocable: false`，斜杠菜单不再显示裸 `/task-swarm`（命令 `/task-swarm:swarm` 不变）。AI-EDS 时代保留至 v0.10.0 的能力：frontmatter-first `project_root` + registry-based run 查找（0.7.x）、coder/reviewer/validator `task.md` 中「## 项目级约束（必读）」段 + `_PROJECT_AGENT_DOCS.md` inbox sentinel（0.7.3+0.7.4）、lifecycle group + `init` dedupe（`--on-existing` flag）+ `run.pipeline_end_validator`（0.8.0+0.8.1）、M2 `run-loop` 自动驱动器（0.8.1）、task.md 「## 开发纪律 (范式参考)」段列出 superpowers skill 名作为范式标识（0.9.0–0.9.2）。**v0.10.0 BREAKING**：拔除记忆注入工程——删 `_ingest_lessons.py` + `cmd_resolve` 自动 ingest + `--no-ingest` flag，`cmd_resolve` 不再写 `/.ai-memory/knowledge/cases\|pitfalls/*.yml`。如需 v0.9.x 行为：`git checkout backup/specode-v3.4.0-task-swarm-v0.9.2`。详见 [`plugins/task-swarm/`](./plugins/task-swarm)。 | | **obsidian-wiki** | 2.0.1 | 维护 Obsidian LLM-Wiki 的三个 skill：确定性结构层（`wiki-struct`：Home 树 / README / 分区页）、内容策展（`wiki-curate`：ingest / curate / lint）、统一编排器（`wiki-orchestrate`）。通用代码 + 家目录注册表 `~/.config/obsidian-wiki/` 按库配置（回退库内 `.wiki/config.json`）。**v2.0.0 BREAKING**：spec-distill 已剥离并迁入 specode 的 `/specode:distill`。详见 [`plugins/obsidian-wiki/`](./plugins/obsidian-wiki)。 | | **ragkit** | 0.1.0 | 独立知识库 **RAG**——向量 + 词汇 + 元数据三路召回，RRF 融合，返回定位卡片。specode `distill` 产出的 `knowledge-base/` 可直接消费；零重型依赖（词汇路仅需 stdlib + numpy）。详见 [`plugins/ragkit/`](./plugins/ragkit)。 | @@ -120,8 +120,8 @@ specode 共有四条命令。 先 `cd` 到你的项目目录——specode 以 cwd 推导项目根默认值（`git rev-parse --show-toplevel`，无 git 则 cwd），并在每条 spec 开始时让你确认一次。**首次运行**时还会询问一次文档管理目录并记住它。之后代理依次走完流水线： -1. **需求阶段** — 澄清 + 写 `requirements.md`（通过 `superpowers:brainstorming`，或原生 `AskUserQuestion` 向导）。 -2. **设计阶段** — 生成传统设计文档 `design.md`（架构 / 模块划分 / 接口设计 / 数据流 / 错误处理 / 测试策略；brainstorming 的设计产出落在这里，或原生撰写）。 +1. **需求阶段** — 由 `specode:intake` skill（specode 自己的，永远走它）执行：项目分析（agent-docs 扫描 + 经验检索 + 读定位到的真实代码）→ 基于分析的澄清 → 写 `requirements.md`（含 `spec_id` / `created_at` / `project_root` frontmatter 契约）。这里也是 **ragkit / 经验检索的主节点**。 +2. **设计阶段** — 生成传统设计文档 `design.md`（架构 / 模块划分 / 接口设计 / 数据流 / 错误处理 / 测试策略），通过 `superpowers:brainstorming`（只产 design）或原生撰写。 3. **计划阶段（tasks）** — 生成可执行计划 `tasks.md`（通过 `superpowers:writing-plans`，或原生任务分解）。引擎中立：所有执行路径消费同一份文件。 4. **执行方式选择器** — 从自适应 4 个选项中选择执行路径（详见上方亮点）。 5. **执行阶段** — 以 TDD 方式跑完计划，追加写入 `implementation-log.md`。 @@ -175,7 +175,9 @@ plugins/specode/ selectors.md 执行方式选择器逐字示例 obsidian.md specsRoot 路径解析 + 惯例 superpowers-wiring.md 阶段 ↔ superpowers 技能映射 - retrieval.md 两级 gated 经验检索规格 + retrieval.md 经验检索规格（intake 为主节点） + skills/intake/ + SKILL.md 需求阶段引擎（项目分析 + 澄清 + 写需求） skills/distill/ SKILL.md /specode:distill 行为（case/navigation 知识点） references/ 拆分启发式 + 文档模板 diff --git a/plugins/specode/.claude-plugin/plugin.json b/plugins/specode/.claude-plugin/plugin.json index 8571ea3..ea2a56d 100644 --- a/plugins/specode/.claude-plugin/plugin.json +++ b/plugins/specode/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "specode", - "version": "6.0.0", - "description": "Lightweight spec-driven workflow: orchestrates superpowers skills per phase, lands 4 fixed docs (requirements/design/tasks/implementation-log). **v6.0.0 BREAKING**: 固定产物 3→4 — design.md 重定义为**传统设计文档**(背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略,散文无 checkbox);新增 tasks.md 承载可执行计划(writing-plans 格式 + Interfaces 契约块,引擎中立,task-swarm/superpowers/自执行统一消费,pipeline.yml 改从 tasks.md 推导);流水线变为 requirements→design→tasks→执行方式 selector→执行→验收,brainstorming 一次跨 requirements+design 双产物落盘(后置 relocate 检查两份);continue 改「加载即停」— 只读文档+汇报进度简报后停下等指令,绝不自动续跑;design-unchecked 更名 plan-unchecked(tasks.md 优先,design.md 含 checkbox 按 5.x legacy 兜底,旧名保留 alias)。5.x 存量 spec 由 continue 推断表 legacy 行兜底识别,不中断。 **v5.2.0**: Tier-0 RagKit gate tightened — probe changed from `test -d .ragkit` to `test -f .ragkit/chunks.json` (eliminates false-positive when only config.json exists after `backend set`); Tier-0 采纳条目 capped at Tier-2 discipline (≤5/phase, reasoned override allowed). **v5.1.3**: `list-specs` 让 intake 阶段（目录已建、requirements 未写）的 spec 可见 — 列出含任一固定产物的子目录 + 空子目录(intake)，隐藏目录与无关内容目录仍排除；全库文档陈旧内容清理(README/CONTRIBUTING/SKILL 残留措辞)。 **v5.1.2**: distill 打磨 — ensure-gitignore 在非 git 且无既有 .gitignore 时跳过(不建 stray);新增 knowledge.py copy-to(一步 dual-landing:复制 cases/navigation + 重建 dest MEMORY),distill Step5 改用它;navigation 来源 单值保留 origin、复用 spec 写正文。 **v5.1.1**: 试跑验证修复 — distill 沉淀前用 design-unchecked 检查 spec 是否执行完(未完则告警,防知识点指向未落地代码);写 navigation 点前先比对 MEMORY 去重;retrieval 强调语义相关而非 tag 命中;F2(非 git project_root)评估为 by design 不修。 **v5.1.0**: 重新引入「经验检索注入」走全新「定位用·非事实用」路线 — 新增 stdlib knowledge.py(ensure-gitignore/memory-rebuild/memory-validate);distill 改产**原子 case/navigation 知识点**到项目 /knowledge-base/(cases/+navigation/+MEMORY 索引,不入仓),可选复制到 Obsidian;新增 references/retrieval.md 两级 gated 检索接入 requirements/design phase(注入指针非事实、默认只读小索引、命中才读≤5点);acceptance 末尾按 auto_distill 重挂 distill 提示。 **v5.0.1**: distill skill 加 `user-invocable:false`(隐藏裸 `/distill` + 消除 `/specode:distill` 重复项,只留命令一条);distill 收敛为纯 **md-only**(移除 `--format yml|both` + `codemap knowledge write` 死路径);清理全部 `.ai-memory`/codemap 文档残留,并从 requirements 模板删除已废弃的「已知约束/历史坑」recall 段。**v5.0.0 BREAKING**: 命令去 `specode-` 前缀 — `/specode:spec` / `/specode:continue` / `/specode:list` / `/specode:distill`(原 `/specode:specode-*`);distill skill 目录与名同改为 `distill`;编排内核 skill `specode` 加 `user-invocable:false`,斜杠菜单不再显示裸 `/specode`(仍经命令/自然语言自动激活)。**v4.0.0 BREAKING**: 彻底拔出记忆注入工程 — 砍掉 specode 主流程的 (1) P3-1 codemap recall 注入 `## 已知约束 / 历史坑` 段, (2) P3-2 rule-acknowledgement post-check, (3) acceptance 后自动 AskUser 触发 distill。round 1/2 baseline 实验证明 recall 注入未 net 节省 token。保留 project-level CLAUDE.md / AGENT.md filesystem scan (不涉及 .ai-memory)。distill skill v4 完全重写: 仅手动触发 `/specode:distill `, 默认 md-only, 默认写 `/Volumes/External HD/Obsidian/Notes/11-KnowledgeBase//` (--target-dir 可覆盖), 不再调 codemap recall, 不再默认写 .ai-memory yml。如需 v3 记忆注入行为, checkout `backup/specode-v3.4.0-task-swarm-v0.9.2`。", + "version": "6.1.0", + "description": "Lightweight spec-driven workflow: orchestrates superpowers skills per phase, lands 4 fixed docs (requirements/design/tasks/implementation-log). **v6.1.0**: 新增独立 intake skill(skills/intake/,同 distill,user-invocable:false)接管 requirements phase — 项目分析(agent-docs 扫描+经验检索+读真实代码)+基于分析的澄清+写 requirements.md(保留 spec_id/created_at/project_root frontmatter 契约);修正 6.0.0 的brainstorming 双产物错位 — brainstorming 从此只产 design.md(单产物),requirements 由 intake 产;检索主节点移到 intake 项目分析步、design 降为条件性 top-up;弊端修复 — writing-plans 结尾的执行方式提问改为「忽略而非抑制」;SKILL 轻量化 215→171 行(verb 表/autonomous-mode 细节下沉到 refs,零行为变化)。 **v6.0.0 BREAKING**: 固定产物 3→4 — design.md 重定义为**传统设计文档**(背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略,散文无 checkbox);新增 tasks.md 承载可执行计划(writing-plans 格式 + Interfaces 契约块,引擎中立,task-swarm/superpowers/自执行统一消费,pipeline.yml 改从 tasks.md 推导);流水线变为 requirements→design→tasks→执行方式 selector→执行→验收,brainstorming 一次跨 requirements+design 双产物落盘(后置 relocate 检查两份);continue 改「加载即停」— 只读文档+汇报进度简报后停下等指令,绝不自动续跑;design-unchecked 更名 plan-unchecked(tasks.md 优先,design.md 含 checkbox 按 5.x legacy 兜底,旧名保留 alias)。5.x 存量 spec 由 continue 推断表 legacy 行兜底识别,不中断。 **v5.2.0**: Tier-0 RagKit gate tightened — probe changed from `test -d .ragkit` to `test -f .ragkit/chunks.json` (eliminates false-positive when only config.json exists after `backend set`); Tier-0 采纳条目 capped at Tier-2 discipline (≤5/phase, reasoned override allowed). **v5.1.3**: `list-specs` 让 intake 阶段（目录已建、requirements 未写）的 spec 可见 — 列出含任一固定产物的子目录 + 空子目录(intake)，隐藏目录与无关内容目录仍排除；全库文档陈旧内容清理(README/CONTRIBUTING/SKILL 残留措辞)。 **v5.1.2**: distill 打磨 — ensure-gitignore 在非 git 且无既有 .gitignore 时跳过(不建 stray);新增 knowledge.py copy-to(一步 dual-landing:复制 cases/navigation + 重建 dest MEMORY),distill Step5 改用它;navigation 来源 单值保留 origin、复用 spec 写正文。 **v5.1.1**: 试跑验证修复 — distill 沉淀前用 design-unchecked 检查 spec 是否执行完(未完则告警,防知识点指向未落地代码);写 navigation 点前先比对 MEMORY 去重;retrieval 强调语义相关而非 tag 命中;F2(非 git project_root)评估为 by design 不修。 **v5.1.0**: 重新引入「经验检索注入」走全新「定位用·非事实用」路线 — 新增 stdlib knowledge.py(ensure-gitignore/memory-rebuild/memory-validate);distill 改产**原子 case/navigation 知识点**到项目 /knowledge-base/(cases/+navigation/+MEMORY 索引,不入仓),可选复制到 Obsidian;新增 references/retrieval.md 两级 gated 检索接入 requirements/design phase(注入指针非事实、默认只读小索引、命中才读≤5点);acceptance 末尾按 auto_distill 重挂 distill 提示。 **v5.0.1**: distill skill 加 `user-invocable:false`(隐藏裸 `/distill` + 消除 `/specode:distill` 重复项,只留命令一条);distill 收敛为纯 **md-only**(移除 `--format yml|both` + `codemap knowledge write` 死路径);清理全部 `.ai-memory`/codemap 文档残留,并从 requirements 模板删除已废弃的「已知约束/历史坑」recall 段。**v5.0.0 BREAKING**: 命令去 `specode-` 前缀 — `/specode:spec` / `/specode:continue` / `/specode:list` / `/specode:distill`(原 `/specode:specode-*`);distill skill 目录与名同改为 `distill`;编排内核 skill `specode` 加 `user-invocable:false`,斜杠菜单不再显示裸 `/specode`(仍经命令/自然语言自动激活)。**v4.0.0 BREAKING**: 彻底拔出记忆注入工程 — 砍掉 specode 主流程的 (1) P3-1 codemap recall 注入 `## 已知约束 / 历史坑` 段, (2) P3-2 rule-acknowledgement post-check, (3) acceptance 后自动 AskUser 触发 distill。round 1/2 baseline 实验证明 recall 注入未 net 节省 token。保留 project-level CLAUDE.md / AGENT.md filesystem scan (不涉及 .ai-memory)。distill skill v4 完全重写: 仅手动触发 `/specode:distill `, 默认 md-only, 默认写 `/Volumes/External HD/Obsidian/Notes/11-KnowledgeBase//` (--target-dir 可覆盖), 不再调 codemap recall, 不再默认写 .ai-memory yml。如需 v3 记忆注入行为, checkout `backup/specode-v3.4.0-task-swarm-v0.9.2`。", "author": { "name": "xueqiang", "email": "xueqiang361@gmail.com" diff --git a/plugins/specode/CHANGELOG.md b/plugins/specode/CHANGELOG.md index 0cbadf4..c4e3b17 100644 --- a/plugins/specode/CHANGELOG.md +++ b/plugins/specode/CHANGELOG.md @@ -4,7 +4,14 @@ specode 是 spec-driven 轻量工作流插件：requirements → design → task ## Unreleased -## 6.0.0 (2026-07-03) +## 6.1.0 (2026-07-05) + +- **新增独立 intake skill**（`skills/intake/`，与 `distill` 平级，`user-invocable: false`，由编排 SKILL 经 Skill 工具按名 `specode:intake` 调用）接管 **requirements phase**：项目分析（agent-docs 扫描 + 经验检索 + 读定位到的真实代码）→ 基于分析的澄清（brainstorming 级，非固定问卷）→ 写 `requirements.md`。**保留 frontmatter 契约不动**：`spec_id` / `created_at` / `project_root`（后者仍经 `write-project-root` 单一写入口）。 +- **修正 6.0.0 的 brainstorming 双产物错位**：brainstorming 从此**只产 design.md（单产物）**，requirements 由 intake 产。requirements phase 不再分「superpowers 在/不在」——永远走 intake，消掉一个 fork。relocate 后置检查回到单文件。 +- **检索节点收敛**：主节点移到 intake 的项目分析步；**design 降为条件性 top-up**（默认继承 intake 指针，仅新领域才补查）；tasks / 执行零注入不变。 +- **弊端修复**：writing-plans 结尾硬编码的「Subagent vs Inline」执行方式提问无参数可关——SKILL 措辞从「抑制」改为**「忽略、不据此执行，继续走 specode selector」**（诚实：只能消化不能抑制）。 +- **SKILL 轻量化（零行为变化）**：`skills/specode/SKILL.md` 215 → 171 行——完整 `resolve_root.py` verb 表下沉到 `references/obsidian.md`；autonomous-mode mapping + 决策伪代码抽到新 `references/autonomous-mode.md`；resolver why-prose 精简；v4.0.0 移除说明压成一行；重复三处的 Absence-fallback 矩阵 slim 成指针。 +- **清理 v3/codemap 死术语噪声（零行为变化）**：功能层无残留（codemap / `.ai-memory` 活代码路径在 4.0.0/5.0.1 已干净移除）；但 `distill` skill 反复对着已不存在的工具声明「无 codemap knowledge write / 不调 codemap recall / 不读 .ai-memory」约 5 处——收敛为中性的活约束（md-only / 不消费旧 KB 当事实 / 不喂下游），历史细节留 CHANGELOG，仅保留一条 checkout-backup 逃生指针。 - **BREAKING**: 固定产物 3 → 4 —— `design.md` 重定义为**传统设计文档**（背景与目标/架构概览/模块划分/接口设计/数据流/错误处理/测试策略，散文无 checkbox）；新增 `tasks.md` 承载可执行计划（writing-plans 格式 + `**Interfaces:**` 契约块，引擎中立，task-swarm / superpowers / 自执行统一消费）。流水线变为 requirements → design → tasks → 执行方式 selector → 执行 → 验收；brainstorming 一次跨 requirements+design 双产物落盘（后置 relocate 检查两份）。 - **BREAKING**: continue 改「加载即停」——`/specode:continue ` 只读文档 + 汇报进度简报（阶段/文档状态/checkbox x/N）后停下等用户指令，不再自动续跑；用户说「继续」才从推断阶段续跑，提出需求变更则先消化进文档再问。 diff --git a/plugins/specode/commands/distill.md b/plugins/specode/commands/distill.md index 93bc8e1..1042a71 100644 --- a/plugins/specode/commands/distill.md +++ b/plugins/specode/commands/distill.md @@ -17,7 +17,7 @@ description: 手动把一个已完成（或进行中）的 spec 沉淀为项目 - **主写域 = `/knowledge-base/`**（`cases/` + `navigation/` + `MEMORY.md`）；Obsidian 是**可选副本**，不是默认主产物 - spec 目录**只读**：绝不修改 `//` 下任何文件 -- **md-only**：无 yml、无 `codemap knowledge write`、无 `.ai-memory`、无任何静默注入 +- **md-only**：只产 markdown，无 yml、无任何静默注入 - `--target-dir` / 用户输入路径**直写不拼接**；`/Volumes/` 下需先校验挂载 - `knowledge-base/` 不提交项目仓库（落盘时 `ensure-gitignore` 保证） - `project_root` 经 `resolve_root.py read-project-root --spec ...` 读取，**不从 cwd 反推** diff --git a/plugins/specode/commands/spec.md b/plugins/specode/commands/spec.md index 90c4f67..940b092 100644 --- a/plugins/specode/commands/spec.md +++ b/plugins/specode/commands/spec.md @@ -20,4 +20,4 @@ After activation, follow the orchestration logic in specode SKILL.md (each phase - default: `resolve_root.py resolve-project-root` (returns `git rev-parse --show-toplevel` of cwd, falling back to cwd) → present it via `AskUserQuestion` **once** for the user to confirm/override. - persist: after requirements.md exists, `resolve_root.py write-project-root --spec / --root ` writes it into the requirements.md YAML frontmatter (validates absolute path / dir exists / `/Volumes` mounted). This frontmatter field is the **only** place project_root lives. - read (any later phase / skill): `resolve_root.py read-project-root --spec /` — the single read entry. Never read cwd/workdir instead. -4. Follow SKILL.md §pipeline: requirements (brainstorming/native) → design (brainstorming dual-artifact/native, 传统设计文档) → tasks (writing-plans/native) → "execution mode" selector → execution → acceptance. Four fixed artifacts land under `//`. +4. Follow SKILL.md §pipeline: requirements (**`specode:intake` skill** — project analysis + clarification + writes requirements.md with the frontmatter contract) → design (brainstorming design-only/native, 传统设计文档) → tasks (writing-plans/native) → "execution mode" selector → execution → acceptance. Four fixed artifacts land under `//`. diff --git a/plugins/specode/scripts/spec_hooks.py b/plugins/specode/scripts/spec_hooks.py index bab36e4..04a515f 100644 --- a/plugins/specode/scripts/spec_hooks.py +++ b/plugins/specode/scripts/spec_hooks.py @@ -21,10 +21,11 @@ "specode（spec-mode 轻量工作流）可用。仅在用户输入 `/specode:spec <需求>`、" "`/specode:continue `、`/specode:list` 或显式要求用 spec 模式时激活；" "否则按普通对话处理。激活后遵循 " - "specode SKILL.md：① 在 requirements/design/tasks/执行/验收各 phase 优先调对应 superpowers " - "skill（缺席则 specode-native 降级）；② 4 份固定产物 requirements.md / design.md / " - "tasks.md / implementation-log.md 永远以固定文件名落在 //；③ tasks 完成后用 " - "AskUserQuestion 呈现「执行方式」selector（task-swarm / superpowers / specode 自执行）。" + "specode SKILL.md：① requirements 由 specode:intake skill 产（项目分析+澄清+写需求）；" + "design/tasks/执行/验收各 phase 优先调对应 superpowers skill（缺席则 specode-native 降级）；" + "② 4 份固定产物 requirements.md / design.md / tasks.md / implementation-log.md 永远以固定文件名" + "落在 //；③ tasks 完成后用 AskUserQuestion 呈现「执行方式」selector" + "（task-swarm / superpowers / specode 自执行）。" ) diff --git a/plugins/specode/skills/distill/SKILL.md b/plugins/specode/skills/distill/SKILL.md index e544606..b47a116 100644 --- a/plugins/specode/skills/distill/SKILL.md +++ b/plugins/specode/skills/distill/SKILL.md @@ -6,9 +6,9 @@ description: > markdown knowledge points. Default output: md-only, written to the project's own `/knowledge-base/` (cases/ + navigation/ + MEMORY.md); optionally copied to an Obsidian vault. Trigger ONLY via - `/specode:distill ` — never auto-run by the main specode flow. No - codemap recall, no .ai-memory yml, no auto-injection. Pure "atomic - locate-pointer 沉淀器 for the current project". + `/specode:distill ` — never auto-run by the main specode flow. + Md-only, no auto-injection. Pure "atomic locate-pointer 沉淀器 for the + current project". --- # distill — project knowledge-base 沉淀器（原子双轨） @@ -32,18 +32,10 @@ distill 是一个**手动、按需**触发的沉淀器：把一个完成（或 **当前 agent 上下文**，提炼成若干**原子知识点**（一需求扇出 N 份独立文档）， 落到该 spec 所属项目的 `knowledge-base/`，并维护一份轻量索引 `MEMORY.md`。 -**md-only** —— 无 yml、无 `codemap knowledge write`、无 `.ai-memory`、无任何 -静默注入。历史沿革（仍然成立的事实）： - -- v1-v3 的 distill 曾是「记忆 ingest 管线」，写 dual yml + md 到 - `/.ai-memory/knowledge/` 供 `codemap recall` 在后续 spec 自动 - 注入。Round 1/2 基线实验证明 recall 往返**并不净省 token**，4.0.0 整体拔除。 -- yml / `codemap knowledge write` 路径在 5.0.1 移除（其唯一消费者 `codemap - recall` 早在 4.0.0 已删，yml 无物可喂）。 -- 当前形态（本次重写）：从「Obsidian-primary 5 类组织器」改为「项目 - `knowledge-base/` primary 的原子双轨（case + navigation）定位沉淀器 + 可选 - Obsidian 副本」。要 v3 的自动注入行为，checkout - `backup/specode-v3.4.0-task-swarm-v0.9.2`。 +**md-only**（只产 markdown，无任何静默注入）。当前形态 = 项目 +`knowledge-base/` primary 的原子双轨（case + navigation）定位沉淀器 + 可选 +Obsidian 副本。（v1-v3 的自动注入 / yml 形态已在 4.0.0 / 5.0.1 完全移除；要旧 +行为 checkout `backup/specode-v3.4.0-task-swarm-v0.9.2`。历史细节见 CHANGELOG。） --- @@ -140,15 +132,14 @@ spec `requirements.md` frontmatter 的 `project_root`），**不从 cwd 反推** 「继续沉淀 / 中止」；用户选中止则结束，不写任何文档。 （5.x legacy spec 的计划在 design.md 里，`plan-unchecked` 自动兜底识别，无需分支处理。） -### Step 2 — 读全 spec + 回顾 agent 上下文（NO recall） +### Step 2 — 读全 spec + 回顾 agent 上下文（不消费旧 KB） `Read` `//` 下每个 `.md`（requirements / design / tasks / implementation-log 等），并回顾本轮 agent 上下文里反复用到的「找文件 / 调用链 / 配置映射」导航经验，留作 Step 3。 -> **NO recall**：**不**读任何旧 KB（`knowledge-base/` / `MEMORY.md`）当事实 -> 输入。distill 只**产出**指针，从不把历史 KB 当真相消费。不调用任何 -> `codemap recall`，不读 `.ai-memory/`。 +> **不消费旧 KB 当事实**：**不**读任何旧 KB（`knowledge-base/` / `MEMORY.md`） +> 当事实输入。distill 只**产出**指针，从不把历史 KB 当真相消费。 > （例外：Step 4 写 navigation 点前可 `Read` `MEMORY.md` **仅用于去重比对**—— > 这是索引维护，不是把历史 KB 当事实喂给新内容，与本不变量不冲突。） @@ -214,8 +205,8 @@ sh "$R/scripts/run.sh" "$R/scripts/knowledge.py" memory-rebuild --kb //requirements.md（含 project_root frontmatter 契约）+ 交给 design 阶段的定位指针。不是用户直接触发的命令。 +--- + +# intake — specode 需求 intake 引擎 + +## §0 你是谁 / 何时被调用 + +- specode 编排壳在 **requirements phase** 通过 `Skill` 工具按名调用你（`specode:intake`）；此时 `` 已解析、`//` 目录已建、slug 已定。 +- 你是 requirements 的**唯一生产者**——specode 不再分「superpowers 在/不在」两条 requirements 路径。superpowers 的 `brainstorming` 从此**只做 design**（产 design.md），不再兼职写需求。 +- 你相对旧「native 2-4 问问卷」的价值全在 **§3 项目分析** + **§4 基于分析的澄清**：先读真实项目建立事实基线，再问有依据的问题——这才是 specode 版的"驱动生成能力"，不是空泛问卷。 +- 你的产物： + 1. `//requirements.md`（散文需求 + 硬 frontmatter 契约，见 §1）； + 2. 一段交给 design 阶段的「**参考定位（非事实来源）**」定位指针（§5，临时上下文，不持久化为事实）。 + +## §1 硬约束 🔒（绝不可动） + +1. **frontmatter 契约（最高优先级，用户明确要求保留）**：`requirements.md` 顶部 YAML **必须**含三个字段——`spec_id` / `created_at` / `project_root`。其中 **`project_root` 是下游 distill / task-swarm / retrieval 的单一事实源**，**只能**经 `resolve_root.py write-project-root` 单一验证写入口落盘（它校验绝对路径 / 目录存在 / `/Volumes` 挂载），**绝不手写该字段**。你换的是"谁生成 requirements 的正文内容"，**绝不破坏这套契约元素**。 +2. **散文需求**：`requirements.md` 是自然语言 spec（背景 / 范围 in-out / `- [ ] AC-N` / 开放问题），**无形式化子句、无 checkbox**——计划在 tasks.md、设计在 design.md，别越界。Bug 修复用 Current / Expected 散文写在这里，不单独建 `bugfix.md`。 +3. **用户可见输出中文**；技术名 / 路径 / 代码标识符 / frontmatter 键名保持英文原样。 +4. **不回贴全文**（见 §6 报告纪律）。 + +## §2 run.sh resolver 前缀（每次 CLI 调用） + +所有 `resolve_root.py` 调用**必须**走 `run.sh` 包装器 + 绝对 plugin-root。skill 驱动的 Bash 里 `$CLAUDE_PLUGIN_ROOT` 不一定有值，必须 `find` 兜底。shell 状态不跨 Bash 调用保留，所以**每次**都带这段自包含 resolver 前缀： + +```bash +R="${CLAUDE_PLUGIN_ROOT:-$CODEBUDDY_PLUGIN_ROOT}"; [ -f "$R/scripts/run.sh" ] || R="$(find "$HOME/.claude/plugins/cache" "$HOME/.codebuddy/plugins/cache" -path '*/specode/*/scripts/run.sh' 2>/dev/null | sort -V | tail -1)"; R="${R%/scripts/run.sh}" +sh "$R/scripts/run.sh" "$R/scripts/resolve_root.py" +``` + +## §3 autonomous-mode 感知（每个 AskUserQuestion 站点适用） + +本 skill 有两处会 `AskUserQuestion`（§Step1 project_root 确认、§Step3 澄清）。每处**先**按 autonomous-mode 规则判定是否跳过——完整规则（gate→key→env mapping + 决策伪代码）见 `skills/specode/references/autonomous-mode.md`。要点：`interactive == false` 且该 gate 的 key `source ∈ {env, file}` 时跳过提问用 default，否则原样 `AskUserQuestion`。本 skill 的两处 gate：project_root 确认 → key `project_root_default`；澄清 → 无独立 key，仅受 `interactive` 主开关约束（非交互则基于已有信息尽力起草、把不确定项写进「开放问题」而非阻塞）。 + +## §4 流程（5 步，质量在 Step 2–3） + +### Step 1 — project_root 确认（必做，autonomous-aware） + +1. 取默认：`resolve_root.py resolve-project-root`（返回 cwd 的 `git rev-parse --show-toplevel`，无 git 则 cwd）。 +2. 按 §3 决定：`AskUserQuestion` 一次（默认值预选，让用户确认或覆盖）/ 或 autonomous 直接用 default。 +3. **持有确认的绝对路径**——Step 2（约束扫描 + 检索）用它、Step 4 经 `write-project-root` 落盘。此刻 requirements.md frontmatter 尚未写，直接用持有的绝对路径，**不要** `read-project-root`。 + +### Step 2 — 项目分析（intake 高于问卷的关键，先读真实项目再问） + +不是"问用户要什么"就完事——**先读真实项目建立事实基线**： + +- **a. 项目级约束扫描**（filesystem-only）：扫下列存在的文件并以 **path-only**（不拷内容）注入 requirements 草稿的 `## 项目级约束（CLAUDE.md / AGENT.md）` 段。扫描序（去重、仅存在的）：(1) `/CLAUDE.md|AGENTS.md|AGENT.md|CODEBUDDY.md`；(2) `` 直接父目录下同 4 文件（覆盖 monorepo workspace 根）；(3) 用户描述中点名的子目录。段模板： + + ```markdown + ## 项目级约束（CLAUDE.md / AGENT.md） + + > 主 agent 的 system prompt 已自动加载下列文件；这里列出来是为了 design / 执行阶段 / 下游 task-swarm subagent 都能看见这条约束链路。**优先级高于本 spec 的其他描述**：冲突时以下列文件为准。 + + - `` + - `` + ``` + + 为何 path-only：主 agent 上下文已有完整内容，复制一遍只是冗余 + 陈旧风险；task-swarm 渲染 task.md 时按同样规则把路径塞进 subagent prompt。一个文件都没扫到（典型 fresh 项目）→ **整段省略**（不写「无」之类占位）。 + +- **b. 经验检索定位**（`/knowledge-base/MEMORY.md` 存在时）——**这是 ragkit / 经验检索的主节点**。按 `skills/specode/references/retrieval.md` 跑：先试 Tier-0 Gate（`ragkit:query` 可用且 `knowledge-base/.ragkit/chunks.json` 存在时多路召回），否则两级 gated（Tier-1 读 MEMORY 小索引比对当前需求页面/字段/域，命中才 Tier-2 读 ≤5 点全文）。产出「**参考定位（非事实来源）**」指针（文件路径 + 调用链）。`MEMORY.md` 不存在 → **静默跳过**（不报错、不写空段）。**顶层不变量**：指针只定位真实代码，**真实代码是唯一事实**；不把 KB 内容当当前代码的真相。 + +- **c. 读真实代码**：对 b 定位到的关键文件**实际打开读**（不只拿路径）——理解现有结构 / 命名 / 模式，作为需求分析与范围界定的事实基线。 + +- **d. fresh 项目**（无 knowledge-base、无 agent docs）→ b/c 静默跳过，靠 Step 3 澄清 + 用户描述建立理解。 + +### Step 3 — 澄清（brainstorming 级，非固定问卷） + +在 Step 2 的项目分析之上做**逐条澄清**（一次一个问题、优先多选），围绕 **purpose / scope（in / out）/ constraints / success criteria**。关键：**由 Step 2 的分析驱动**——问的是「基于现有的 `X` 代码/模式，这个需求该怎样接入 / 边界在哪」这类**有依据的问题**，不是空泛问卷。 + +- autonomous-aware（§3）：非交互则基于已有信息尽力起草，把不确定项写进「开放问题」，不阻塞。 +- **何时停**：intent / scope / AC 足够清晰、开放问题已列出即可——不要过度追问（YAGNI）。 + +### Step 4 — 写 requirements.md + +按 `assets/templates/requirements.md` 结构写正文：`## 背景 / 为什么` · `## 范围`（包含 / 不包含）· `## 验收标准`（`- [ ] AC-N`，可观察可验证）· `## 开放问题`（+ Step 2a 的 `## 项目级约束` 段，若有）。落 `//requirements.md`。 + +然后落 **frontmatter（§1 硬约束）**： + +1. 写 `spec_id: ` / `created_at: YYYY-MM-DD`（可随正文一起写进顶部 YAML）。 +2. **`project_root` 只经单一写入口落盘**： + ```bash + sh "$R/scripts/run.sh" "$R/scripts/resolve_root.py" write-project-root --spec / --root + ``` + 它校验并把 `project_root` 写进 requirements.md frontmatter。**绝不手写该字段。** + +### Step 5 — 交接给 design + +把 Step 2b 的「参考定位（非事实来源）」指针作为**临时上下文**交回 specode 编排（供 design 阶段用：specode 调 `brainstorming` 时把这段作为 context 传入，或 native design 直接沿用）。**不持久化为 requirements.md 的事实结论**（retrieval.md 顶层不变量）。design 默认继承这些指针、仅在开辟 intake 未覆盖的新领域时才补查（design 的检索是**条件性 top-up**，非强制）。 + +交接后**结束本 skill**，把控制权还给 specode 编排（它接着进入 design phase）。 + +## §5 报告纪律 + +不回贴 requirements.md 全文。报告只含：文件路径（一行）+ 3-8 条要点/关键澄清 + 开放问题（若有）+ 下一步（进入 design）。唯一例外是用户明确要求看全文。 + +## §6 References + +- `skills/specode/references/retrieval.md` — 经验检索规格（Step 2b 的引擎；intake 是其**主节点**）。 +- `assets/templates/requirements.md` — 需求模板（Step 4 结构 + frontmatter 契约）。 +- `skills/specode/references/autonomous-mode.md` — §3 判定的完整规则来源（gate→key→env + 伪代码）。 diff --git a/plugins/specode/skills/specode/SKILL.md b/plugins/specode/skills/specode/SKILL.md index 9b49f2f..934037c 100644 --- a/plugins/specode/skills/specode/SKILL.md +++ b/plugins/specode/skills/specode/SKILL.md @@ -34,55 +34,18 @@ Bug fixes do not get a separate `bugfix.md` — write Current / Expected directl **Every time specode starts, first call `resolve_root.py get-root` via run.sh to read specsRoot.** Only when the config is missing (typically first use) ask the user via `AskUserQuestion`, then immediately `set-root` to write it back to config. Afterwards all sessions use it silently and automatically, never prompting again. -All specode CLIs **must** be invoked through the `run.sh` wrapper with an **absolute** plugin-root path. Resolve that root robustly: prefer the host env var `$CLAUDE_PLUGIN_ROOT` (CodeBuddy: `$CODEBUDDY_PLUGIN_ROOT`), but **never assume it is set**. The host only inline-substitutes / exports `${CLAUDE_PLUGIN_ROOT}` for hooks and MCP/LSP subprocesses, and only the bare token — a CLI call emitted from *this skill body* with the `${VAR:-fallback}` form is neither substituted nor run in an env that carries the variable, so it expands **empty** and you get `sh: /scripts/run.sh: No such file or directory`. Always fall back to globbing the plugin cache, and never call a bare `python3