setup-ai-document-system

Files (9)

• SKILL.md
• bmad-integration.md
• document-system.md
• domain.md
• issue-tracker-github.md
• issue-tracker-gitlab.md
• issue-tracker-local.md
• level3-bmad-workflow.md
• triage-labels.md

SKILL.md (first lines)

# Setup AI Document System

搭建 engineering skills 依赖的每仓库配置。这个 skill 配置的是“项目内文档系统”，不是某个 agent 工具的固定入口。

- **Issue tracker** — issues 存放在哪里（默认 GitHub；也原生支持 `docs/features/<feature>/issues/` 本地 markdown）
- **Triage labels** — 五个 canonical triage roles 使用的字符串
- **Domain docs** — `CONTEXT.md`、ADRs 和 feature docs 的位置，以及读取它们的消费规则
- **Document system** — `to-prd`、`to-plan`、`to-spec`、`to-issues`、`grill-with-docs` 如何组成同一条文档链
- **Agent adapter** — `AGENTS.md`、`CLAUDE.md` 或其他工具入口如何指向 `docs/agents/*.md`
- **Optional BMad Level 3** — 复杂项目中如何把 BMad 作为展开、审计和执行层接入 AI-native 文档系统

这是 prompt-driven skill，不是确定性脚本。先探索，展示发现，和用户确认，然后再写入。

## Process

### 1. Explore

查看当前 repo，理解起始状态。读取已有内容，不要假设：

- `git remote -v` 和 `.git/config` — 这是 GitHub repo 吗？是哪一个？
- repo 根目录常见 agent adapter 文件：`AGENTS.md`、`CLAUDE.md`、`.cursor/rules/`、`.github/copilot-instructions.md` 等。它们是否存在？是否已经指向 `docs/agents/*.md`？
- repo 根目录的 `CONTEXT.md` 和 `CONTEXT-MAP.md`
- `docs/adr/` 以及任何 `src/*/docs/adr/` 目录
- `docs/AI_DOCUMENT_SYSTEM.md`
- `docs/BMAD_INTEGRATION.md` 和 `docs/LEVEL3_BMAD_WORKFLOW.md`
- `docs/features/` 和 `docs/plans/`
- `docs/agents/` — 这个 skill 之前是否已经输出过内容？
- `_bmad-output/implementation-artifacts/sprint-status.yaml` 和 BMad story files — 是否已经启用 BMad story cycle？

### 2. Present findings and ask

总结现有什么、缺什么。然后带用户逐一完成五个决策：每次只展示一个 section，拿到用户回答后再进入下一个。不要一次性倾倒全部五个。

假设用户不知道这些术语是什么意思。每个 section 先用简短说明开头（它是什么、为什么这些 skills 需要它、选择不同选项会改变什么），然后展示选项和默认值。

**Section A — Issue tracker.**

> Explainer: “issue tracker” 是这个 repo 存放执行任务的地方。`to-issues`、`triage`、`to-prd`、`to-plan`、`to-spec` 等 skills 会从中读取并写入；它们需要知道是调用外部 issue tracker CLI、在 `docs/features/<feature>/issues/` 下写 markdown 文件，还是遵循你描述的其他工作流。请选择你实际用来跟踪这个 repo 工作的位置。

默认姿态：这些 skills 是为 GitHub 设计的。如果 `git remote` 指向 GitHub，就推荐 GitHub。如果 `git remote` 指向 GitLab（`gitlab.com` 或 self-hosted host），就推荐 GitLab。否则（或用户偏好），提供：

- **GitHub** — issues 存放在 repo 的 GitHub Issues 中（使用 `gh` CLI）
- **GitLab** — issues 存放在 repo 的 GitLab Issues 中（使用 [`glab`](https://gitlab.com/gitlab-org/cli) CLI）
- **Local markdown** — PRD、Spec 和 issues 作为文件存放在本 repo 的 `docs/features/<feature>/` 下（适合个人项目或没有 remote 的 repos）
- **Other**（Jira、Linear 等）— 让用户用一段话描述工作流；skill 会把它记录为自由文本

**Section B — Triage label vocabulary.**

> Explainer: `triage` skill 处理 incoming issue 时，会把它移过一个 state machine：需要评估、等待 reporter、已准备好给 AFK agent 接手、需要人工实现，或 won't fix。为此，它需要应用与你实际配置相匹配的 labels（或 issue tracker 中的等价物）。如果你的 repo 已经使用不同 label 名（例如 `bug:triage` 而不是 `needs-triage`），在这里映射它们，避免 skill 创建重复 labels。

五个 canonical roles：

- `needs-triage` — maintainer needs to evaluate
- `needs-info` — waiting on reporter
- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
- `ready-for-human` — needs human implementation
- `wontfix` — will not be actioned

默认：每个 role 的字符串等于它的名称。询问用户是否想覆盖任何项。如果他们的 issue tracker 还没有现有 labels，默认值即可。

**Section C — Domain docs.**

> Explainer: 一些 skills（`grill-with-docs`、`to-prd`、`to-plan`、`to-spec`、`to-issues`、`improve-codebase-architecture`、`diagnose`、`tdd`）会读取 `CONTEXT.md` 来学习项目的 domain language，读取 `docs/adr/` 来了解过去的架构决策，并读取 `docs/features/<feature>/` 来理解当前功能链路。它们需要知道 repo 是一个 global context，还是多个 contexts（例如 frontend/backend 分离的 monorepo），这样才能看对位置。

确认布局：

- **Single-context** — repo 根目录一个 `CONTEXT.md` + `docs/adr/`。大多数 repos 是这样。
- **Multi-context** — 根目录 `CONTEXT-MAP.md` 指向每个 context 的 `CONTEXT.md` 文件（通常是 monorepo）。

**Section D — Project document system.**

> Explainer: `to-prd`、`to-plan`、`to-spec`、`to-issues` 和 `grill-with-docs` 应共享同一条文档链。这样 PRD 不会变成 implementation spec，Plan 不会变成任务清单，Spec 不会丢失验证命令，Issue 也不会绕开 `docs/features/<feature>/SPEC.md`。

默认使用 AI-native Markdown 结构：

- agent adapter（例如 `AGENTS.md`、`CLAUDE.md`、Cursor rules）只作为入口指针
- `CONTEXT.md` + `docs/adr/` 作为领域和架构基准
- `docs/features/<feature>/PRD.md`
- `docs/plans/<plan>.md` 或 `docs/features/<feature>/PLAN.md`（可选）
- `docs/features/<feature>/SPEC.md`
- `docs/features/<feature>/issues/`

**Section E — Optional BMad Level 3 extension.**

> Explainer: BMad 可以作为复杂项目的展开、readiness、story cycle、review 和 retro 层。AI-native `docs/` 仍是长期真相源；BMad 输出进入 `_bmad-output/`，只有晋升到 `docs/` 后才成为正式约束。启用 BMad story cycle 时，BMad stories 是执行队列，local issues 只记录 blocker、HITL、跨 story 风险、技术债、review follow-up 和 documentation fix。

确认是否启用 BMad extension：

- **Disabled** — 仅使用 AI-native 文档链。
- **Enabled, AI-native issues remain execution queue** — BMad 只用于复杂性展开、readiness、review 或 retro；实现仍走 local issues。
- **Enabled, BMad story cycle owns execution queue** — `_bmad-output/implementation-artifacts/sprint-status.yaml` 和 story files 是执行编排层；issues 只是控制面板。

### 3. Confirm and edit

向用户展示草稿：

- 要写入或更新的 agent adapter 指针（选择规则见 step 4）
- `docs/agents/issue-tracker.md`、`docs/agents/triage-labels.md`、`docs/agents/domain.md`、`docs/agents/document-system.md` 的内容

允许用户在写入前修改。

### 4. Write

**选择 agent adapter：**

- 如果 repo 已有 `AGENTS.md`、`CLAUDE.md` 或其他 agent entry file，优先更新用户实际使用的入口。
- 如果多个入口同时存在，询问用户本次更新哪个，或是否都只加入同一段简短指针。
- 如果没有入口文件，询问用户是否创建；不要替用户选择默认文件名。
- 如果用户不想写任何 adapter 文件，只写 `docs/agents/*.md`，并在完成信息中说明后续 agent 需要手动读取这些文件。

如果所选文件已经有 `## Agent skills`、`## AI-native document system` 或类似 block，就原地更新其内容，而不是追加重复 block。不要覆盖周围 section 的用户编辑。

如果 block 中已有未列入模板的自定义子章节，保留它们；只更新本 skill 管理的子章节。

Adapter block：

```markdown
## AI-native document system

From pop1414/ai-native-doc-system, MIT.

More from pop1414/ai-native-doc-system