docs: split docs/ by audience, retire an unbuilt plan - #20
Merged
Conversation
Nine `*-plan.md`, an audit and a summary sat beside the specifications a reader is meant to follow, so nothing distinguished "this is how it works" from "this is what someone intended to build". A reader could pick up a completed migration record and run its commands, which is how the dead `cmd/oneagent-release` invocations kept getting rediscovered. `docs/` now has three layers. The root keeps what is currently in force (product boundary, compliance policy, site operations) plus the user-facing `ai-agent-kit/`. `decisions/` keeps the ADRs. `internal/` takes the ten completion records, the RC testing requirements and the release evidence, with a README stating plainly that its commands may no longer run and naming the two workflows that replaced them. CLAUDE.md gains the rule for choosing between the layers, so the next document lands in the right place. `docs/ai-agent-kit-plan.md` is deleted rather than moved. It specified a seven-page wizard against a five-step one (`SetupStepper.tsx`), listed six agents absent from `agents.lock.json`, and promised project templates that do not exist. Its product-definition sections are already covered by product-boundary-baseline.md, which it deferred to in its own third line. It had no status marker, no inbound links, and had not been touched since the initial commit. The ai-agent-kit is corrected where it had drifted furthest from the product: manifest.md described `launcher`/`start.sh`/`start.command` from before the Go migration; 00-start-here told end users to build from source; 04-agent-guides still wrote guidance for six removed agents while omitting Kilo CLI, which is auto-configurable, and claimed OneAgent will not download a runtime when uv now installs a managed CPython. The kit also spoke only of PPIO although Novita ships as a second built-in provider. Two documents asserted a `credential_delivery` manifest field. ADR-008 deleted it along with the env-file scheme; credentials now go into each Agent's own config file, so both tables are rewritten to name the real locations and cite the ADR. AgentDetailPage is removed. It was never imported or routed -- `/agents/:agentId` resolves to AgentProfilePage -- yet three documents cited its single-agent activation, fast-model field, detected-config warning and backup display as delivered features. Those claims are corrected instead. One consequence is worth stating: `small_fast_model` now has no GUI entry point at all, since the remaining call sites pass an empty string; the `--small-fast-model` CLI flag still works, and per-agent-config-plan.md now says so. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
按受众给
docs/分层，并清掉一份从未实现的规划文档。参照 cc-switch 的做法：它 190 个 markdown 文件里一份内部规划文档都没有公开（我搜过*plan*/*adr*/*design*/*audit*，零命中），设计决策都在 CHANGELOG 和 release notes 里——记录「发生过什么」而不是「打算做什么」。问题
9 个
*-plan.md加 audit、summary 和规范文档并排放在docs/根下，读者无法区分「这是现状」和「这是当初的打算」。后果是具体的：那些已完成的迁移记录里带着可运行的 ```bash 命令块，调用的是早已删除的cmd/oneagent-release——这就是它反复被重新发现的原因。分三层
docs/根：当前有效的规范（产品边界、合规政策、公开站运营）+ 面向使用者的ai-agent-kit/docs/decisions/：ADR，包含已被取代的决策及其去向docs/internal/：10 份完工记录 + RC 测试要求 + 发行证据docs/internal/README.md直说这里的命令可能已失效，并指明当前的两个替代入口（ci.yml和build-artifacts.yml）。CLAUDE.md 补上选择层级的规则，让下一份文档落对位置。删除
docs/ai-agent-kit-plan.md362 行，无状态标记、零入链、自 initial commit 未动。已验证它规划的东西没落地：
SetupStepper.tsx:8-13）agents.lock.json（Kiro、Gemini CLI、Cline、Continue、Qwen Code、Kilo VS Code）templates/只有一个.env.example）产品定义部分已被
product-boundary-baseline.md覆盖——它自己第 3 行就写了以 baseline 为准。修正 ai-agent-kit 与产品的偏离
manifest.md描述的launcher/start.sh/start.command是 Go 迁移前的形态，三个都不存在00-start-here.md给终端用户的是从源码构建，改为下载发行包优先04-agent-guides.md仍为 6 个已删除 Agent 写指引，同时漏了 Kilo CLI（它是 auto 可配置的）install.go:232的UV_PYTHON_INSTALL_DIR说明 uv 会下载托管 CPythoncredential_delivery是幻影字段两份文档声称凭据交付由 manifest 的
credential_delivery声明。全仓库零命中——ADR-008刻意删除了它，凭据现在写进各 Agent 自己的配置文件。两处表格改为列出真实位置并引用 ADR。删除 AgentDetailPage
已验证从未被 import 或路由（
/agents/:agentId→AgentProfilePage），但三份文档把它的单 Agent 激活、fast model 字段、配置发现警告、备份展示当作已交付功能。文档已修正。一个后果值得单独说明：
small_fast_model现在没有任何 GUI 入口——剩下的调用点全传空字符串，所以桌面路径始终走回退。--small-fast-modelCLI 参数仍可用，per-agent-config-plan.md已写明这一点。如果这个字段需要在界面里可设，那是一个独立的功能任务。验证
go vet无输出、go test -race ./...全过、前端pnpm run build通过、pnpm run test145/145。测试数从 160 降到 145 我核对过：被删文件自身有 15 个测试，
160 − 15 = 145，逐文件 diff 确认没有其他 suite 丢测试。（中途一度以为差了 1 个，实际是我本地 main 落后于分支基线f3f1dfc，上游给ProfilesPage加了一个测试。）全部相对链接已重新校验，无死链。用全新克隆确认
frontend/dist/.keep仍被跟踪且go vet通过。未包含
README 的下载链接、截图、badge，以及
SECURITY.md/CONTRIBUTING.md/CHANGELOG.md——那是上一轮讨论里的第 1、2 条建议，本 PR 只做第 3、4 条（分层 + 移出规划）。🤖 Generated with Claude Code