ln-110-project-docs-coordinator

路径： 文件路径（references/、../ln-*）相对于此技能目录。

项目文档协调器

类型： L2 协调器
类别： 1XX 文档流水线

由运行时支持的文档协调器。运行时负责上下文组装检查点、有条件的工作器分发，以及文档生成摘要汇总。

目的与范围

• 单次收集上下文 — 分析项目一次，构建 Context Store
• 检测项目类型 — 确定 hasBackend、hasDatabase、hasFrontend、hasDocker
• 委派给 5 个工作器 — 将 Context Store 传递给每个工作器
• 汇总结果 — 收集所有工作器的状态，并返回摘要
• 通过一次性收集数据并显式传递，解决“上下文丢失”问题
• 构建由 ln-100 文档质量修复循环使用的路由表

运行时契约

必须阅读： 加载 references/coordinator_runtime_contract.md、references/docs_runtime_contract.md、references/docs_generation_summary_contract.md

运行时系列：docs-runtime

标识符：

• project-docs

阶段：

1. PHASE_0_CONFIG
2. PHASE_1_CONTEXT_ASSEMBLY
3. PHASE_2_DETECTION
4. PHASE_3_DELEGATE
5. PHASE_4_AGGREGATE
6. PHASE_5_SELF_CHECK

工作器摘要契约：

• ln-111..115 可能会收到 summaryArtifactPath
• 每个工作器都会写入或返回 docs-generation 摘要封装
• ln-110 使用工作器摘要，而非工作器的自由文本

调用（调用方／时机）

• ln-100-documents-pipeline： 在文档流水线中作为第一个 L2 协调器调用
• 绝不由用户直接调用

输入

来自 ln-100（可选的源清理阶段）：

{
  "SOURCE_DOC_NOTES": {
    "architecture_notes": { "sections": [...], "diagrams": [...] },
    "requirements_notes": { "functional": [...] },
    "principles_notes": { "principles": [...], "anti_patterns": [...] },
    "tech_stack_notes": { "frontend": "...", "backend": "...", "versions": {} },
    "api_notes": { "endpoints": [...], "authentication": "..." },
    "database_notes": { "tables": [...], "relationships": [...] },
    "runbook_notes": { "prerequisites": [...], "install_steps": [...], "env_vars": [...] },
    "infrastructure_notes": { "servers": [...], "domains": [...], "ports": {} }
  }
}

SOURCE_DOC_NOTES 会在工作器分发前丰富标准上下文存储。工作器只使用规范化的上下文字段；没有针对旧版内容的专用覆盖分支。

必须阅读： 加载 references/docs_quality_contract.md。

架构

ln-110-project-docs-coordinator (this skill)
├── Phase 1: Context Gathering (ONE TIME)
├── Phase 2: Delegate to Workers
│   ├── ln-111-root-docs-creator → 4 root docs (ALWAYS)
│   ├── ln-112-project-core-creator → 3 core docs (ALWAYS)
│   ├── ln-113-backend-docs-creator → 2 docs (if hasBackend/hasDatabase)
│   ├── ln-114-frontend-docs-creator → 1 doc (if hasFrontend)
│   └── ln-115-devops-docs-creator → 2 docs (1 always + 1 if hasDocker)
└── Phase 3: Aggregate Results

工作流

阶段 1：收集上下文（仅一次）

1.1 自动发现（扫描项目文件）：

来源	提取的数据	上下文存储键
package.json	名称、描述、依赖项、脚本、引擎、作者、贡献者	PROJECT_NAME、PROJECT_DESCRIPTION、DEPENDENCIES、DEV_COMMANDS、DEVOPS_CONTACTS
docker-compose.yml	服务、端口、deploy.replicas、runtime:nvidia	DOCKER_SERVICES、DEPLOYMENT_SCALE、HAS_GPU
Dockerfile	运行时版本	RUNTIME_VERSION
src/ 结构	文件夹、模式	SRC_STRUCTURE、ARCHITECTURE_PATTERN
migrations/	表定义	SCHEMA_OVERVIEW
.env.example	环境变量	ENV_VARIABLES
tsconfig.json、.eslintrc	规范	CODE_CONVENTIONS
README.md	项目描述、扩缩容相关说明	PROJECT_DESCRIPTION（备用）、DEPLOYMENT_SCALE（备用）
CODEOWNERS	维护者	DEVOPS_CONTACTS
git log	常提交代码的人员	DEVOPS_CONTACTS（备用）
~/.ssh/config、部署目标	SSH 别名、主机名、IP	SERVER_INVENTORY
docker-compose VIRTUAL_HOST 变量	域名路由	DOMAIN_DNS
.env.example 注册表 URL、.npmrc	制品仓库	ARTIFACT_REPOSITORY
docker-compose deploy.resources	资源限制	HOST_REQUIREMENTS

1.2 检测项目类型：

标志	检测规则
hasBackend	依赖项中包含 express/fastify/nestjs/fastapi/django
hasDatabase	依赖项中包含 pg/mongoose/prisma/sequelize，或 docker-compose 中包含 postgres/mongo
hasFrontend	依赖项中包含 react/vue/angular/svelte
hasDocker	Dockerfile 或 docker-compose.yml 存在

1.3 请求用户提供材料：

• 询问：“您是否有现有材料（需求、设计、文档）？”
• 如果有：提取答案并存入上下文存储

1.4 MCP 研究（针对检测到的技术）：

• 使用 Context7/Ref 获取最佳实践
• 存入上下文存储，供工作器使用

1.5 构建上下文存储：

{
  "PROJECT_NAME": "my-project",
  "PROJECT_DESCRIPTION": "...",
  "TECH_STACK": { "frontend": "React 18", "backend": "Express 4.18", "database": "PostgreSQL 15" },
  "DEPENDENCIES": [...],
  "SRC_STRUCTURE": { "controllers": [...], "services": [...] },
  "ENV_VARIABLES": ["DATABASE_URL", "JWT_SECRET"],
  "DEV_COMMANDS": { "dev": "npm run dev", "test": "npm test" },
  "DOCKER_SERVICES": ["app", "db"],
  "DEPLOYMENT_SCALE": "single",
  "DEVOPS_CONTACTS": [],
  "HAS_GPU": false,
  "SERVER_INVENTORY": [],
  "DOMAIN_DNS": [],
  "ARTIFACT_REPOSITORY": {},
  "HOST_REQUIREMENTS": {},
  "flags": { "hasBackend": true, "hasDatabase": true, "hasFrontend": true, "hasDocker": true }
}

DEPLOYMENT_SCALE 检测规则：

• "single"（默认）：没有 deploy.replicas，且 README 中没有扩缩容关键词
• "multi"：deploy.replicas > 1，或提及负载均衡器
• "auto-scaling"：README/docker-compose 中包含自动扩缩容关键词
• "gpu-based"：docker-compose 中包含 runtime: nvidia

DEVOPS_CONTACTS 备用链：

1. CODEOWNERS 文件 → 提取维护者
2. package.json 作者/贡献者 → 提取姓名/电子邮件
3. git log → 最常提交代码的前 3 人
4. 如果以上都为空 → [TBD: Provide DevOps team contacts]

1.6 合并规范化的源文档备注（如果 ln-100 提供）：

• 检查是否已从 ln-100 清理阶段传入 SOURCE_DOC_NOTES
• 如果存在，将补充事实合并到标准上下文存储中：

  contextStore.SOURCE_DOC_NOTES = input.SOURCE_DOC_NOTES
  

• 丰富上下文的目的：
  • 架构备注可强化架构证据
  • 需求备注可强化需求证据
  • 技术栈备注可说明版本和选择理由
  • 原则、API、数据库、运行手册和基础设施备注可提供补充事实信息
• 工作器始终基于规范化上下文和当前项目源生成内容
• 如果不存在 SOURCE_DOC_NOTES：依赖直接自动发现和当前规范文档

阶段 2：委派给工作者

**强制要求：**必须调用所有适用的工作者。工作者通过 Agent 工具并行运行，以隔离上下文。

2.1 始终调用（并行）：

• 使用 Context Store 调用 ln-111-root-docs-creator
• 使用完整 Context Store 调用 ln-112-project-core-creator
• 使用 Context Store 调用 ln-115-devops-docs-creator（始终创建 infrastructure.md；是否创建 runbook.md 由内部根据 hasDocker 条件决定）

2.2 按条件调用：

• 如果 hasBackend OR hasDatabase，则调用 ln-113-backend-docs-creator
• 如果 hasFrontend，则调用 ln-114-frontend-docs-creator

调用（通过 Agent 工具并行）：

Agent(description: "{doc_type} docs via {worker}",
     prompt: "Invoke Skill(skill: \"{worker}\") with context below.\n\nCONTEXT: {contextStore}",
     subagent_type: "general-purpose")

委派规则：

• 通过 Agent+Skill 模式将 Context Store 和标志传递给工作者
• 等待所有 Agent 执行完成
• 收集规范化结果（created_files、skipped_files、quality_inputs、validation_status）

阶段 3：汇总结果

1. 收集所有工作者的状态
2. 汇总文件总数：已创建、已跳过
3. 报告任何验证警告
4. 将汇总结果返回给 ln-100
5. 包含 Context Store，供后续工作者使用（ln-120 需要 TECH_STACK）
6. 将所有工作者的 quality_inputs.owners 合并到一张修复路由表中

输出：

{
  "workers_invoked": 5,
  "total_created": 11,
  "total_skipped": 0,
  "validation_status": "passed",
  "created_files": [
    "AGENTS.md",
    "CLAUDE.md",
    "docs/README.md",
    "docs/documentation_standards.md",
    "docs/principles.md",
    "docs/project/requirements.md",
    "docs/project/architecture.md",
    "docs/project/tech_stack.md",
    "docs/project/api_spec.md",
    "docs/project/database_schema.md",
    "docs/project/design_guidelines.md",
    "docs/project/infrastructure.md",
    "docs/project/runbook.md"
  ],
  "quality_inputs": {
    "doc_paths": ["AGENTS.md", "CLAUDE.md", "docs/README.md", "docs/project/architecture.md"],
    "owners": {
      "AGENTS.md": "ln-111-root-docs-creator",
      "CLAUDE.md": "ln-111-root-docs-creator",
      "docs/project/architecture.md": "ln-112-project-core-creator"
    }
  },
  "context_store": {
    "PROJECT_NAME": "...",
    "TECH_STACK": { "frontend": "React 18", "backend": "Express 4.18", "database": "PostgreSQL 15" },
    "DEPENDENCIES": [...],
    "flags": { "hasBackend": true, "hasDatabase": true, "hasFrontend": true, "hasDocker": true }
  }
}

重要说明

• 上下文仅收集一次——绝不在工作者中重复收集
• 明确传递 Context Store——不依赖隐式状态
• 工作者自行验证——协调器只负责汇总
• 幂等——工作者会跳过已存在的文件
• 尽可能并行——ln-111 和 ln-112 可以并行运行
• 必须提供修复路由表——每个已创建的文档路径都必须映射到一个负责的创建者

工作者调用（强制要求）

**宿主技能调用：**必须委派调用 Skill(skill: "...", args: "...")。

• Claude：严格按所示方式调用 Skill 工具。
• Codex：如果没有 Skill 工具，则在可用技能中查找指定技能，读取其 SKILL.md，将 args 视为 $ARGUMENTS，执行该技能工作流，然后携带执行结果/产物返回此处。
• 不要内联工作者逻辑，也不要在未执行目标技能的情况下将工作者标记为已完成。

阶段	工作者	上下文	条件
2	ln-111-root-docs-creator	Agent（并行）——根目录文档	始终
2	ln-112-project-core-creator	Agent（并行）——项目核心文档	始终
2	ln-115-devops-docs-creator	Agent（并行）——基础设施 + 运维手册	始终
2	ln-113-backend-docs-creator	Agent（并行）——API 规范 + DB 架构	hasBackend OR hasDatabase
2	ln-114-frontend-docs-creator	Agent（并行）——设计指南	hasFrontend

**所有工作者：**通过带有 Skill 的 Agent 工具调用——工作者会获取 Context Store。

TodoWrite 格式（强制要求）

- Build Context Store (pending)
- Invoke ln-111-root-docs-creator (pending)
- Invoke ln-112-project-core-creator (pending)
- Invoke ln-115-devops-docs-creator (pending)
- Invoke ln-113-backend-docs-creator [conditional] (pending)
- Invoke ln-114-frontend-docs-creator [conditional] (pending)
- Aggregate results (pending)

反模式：

• ❌ 直接创建文档文件，而不是调用工作者
• ❌ 未通过 Agent+Skill 调用就将工作者步骤标记为已完成
• ❌ 未检查标志就跳过条件工作者

文档规范（传递给工作者）

• **NO_CODE 规则：**文档描述契约，而非实现
• **技术栈适配：**链接必须符合 TECH_STACK（Context Store）
• **格式优先级：**表格/ASCII > 列表 > 文本

完成定义

• 已构建包含所有发现数据的 Context Store
• 已确定项目类型标志
• 已调用所有适用的工作者
• 已汇总结果
• **已验证时效性：**所有文档事实均与当前代码一致（路径、函数、API、配置均存在且准确）
• 已将摘要返回给 ln-100

阶段 4：元分析

可选参考：仅当用户要求运行后元分析或采用协议格式的运行回顾时，才加载 references/meta_analysis_protocol.md。

技能类型：planning-coordinator。收到请求时，在所有阶段完成后运行。使用 planning-coordinator 格式在聊天中输出。

参考文件

• 指南：references/guides/automatic_analysis_guide.md、critical_questions.md、troubleshooting.md

---

**版本：**2.1.0 **最后更新：**2025-01-12