Back to Details

ln-110-project-docs-coordinator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Documentation Coordinator

项目文档统筹组件

L2 Coordinator that gathers project context once and delegates document creation to specialized L3 workers.
这是一个L2统筹组件，可一次性收集项目上下文信息，并将文档创建任务委托给专业的L3工作组件。

Purpose & Scope

目标与范围

  • Single context gathering — analyzes project once, builds Context Store
  • Project type detection — determines hasBackend, hasDatabase, hasFrontend, hasDocker
  • Delegates to 5 workers — passes Context Store to each worker
  • Aggregates results — collects status from all workers, returns summary
  • Solves the "context loss" problem by gathering data once and passing explicitly
  • 单次上下文收集 — 仅分析项目一次，构建Context Store
  • 项目类型检测 — 判断项目是否包含hasBackend、hasDatabase、hasFrontend、hasDocker
  • 委托给5个工作组件 — 将Context Store传递给每个工作组件
  • 聚合结果 — 收集所有工作组件的状态，返回汇总信息
  • 通过一次性收集数据并显式传递的方式，解决“上下文丢失”问题

Invocation (who/when)

调用方式（主体/时机）

  • ln-100-documents-pipeline: Invoked as first L2 coordinator in documentation pipeline
  • Never called directly by users
  • ln-100-documents-pipeline： 作为文档流水线中的首个L2统筹组件被调用
  • 从不直接由用户调用

Inputs

输入信息

From ln-100 (via Phase 0 Legacy Migration):
json
{
  "LEGACY_CONTENT": {
    "legacy_architecture": { "sections": [...], "diagrams": [...] },
    "legacy_requirements": { "functional": [...] },
    "legacy_principles": { "principles": [...], "anti_patterns": [...] },
    "legacy_tech_stack": { "frontend": "...", "backend": "...", "versions": {} },
    "legacy_api": { "endpoints": [...], "authentication": "..." },
    "legacy_database": { "tables": [...], "relationships": [...] },
    "legacy_runbook": { "prerequisites": [...], "install_steps": [...], "env_vars": [...] }
  }
}
LEGACY_CONTENT is passed to workers as base content. Priority: Legacy > Auto-discovery > Template defaults.
来自ln-100（通过Phase 0 Legacy Migration）：
json
{
  "LEGACY_CONTENT": {
    "legacy_architecture": { "sections": [...], "diagrams": [...] },
    "legacy_requirements": { "functional": [...] },
    "legacy_principles": { "principles": [...], "anti_patterns": [...] },
    "legacy_tech_stack": { "frontend": "...", "backend": "...", "versions": {} },
    "legacy_api": { "endpoints": [...], "authentication": "..." },
    "legacy_database": { "tables": [...], "relationships": [...] },
    "legacy_runbook": { "prerequisites": [...], "install_steps": [...], "env_vars": [...] }
  }
}
LEGACY_CONTENT会作为基础内容传递给工作组件。优先级：遗留内容 > 自动发现内容 > 模板默认值。

Architecture

架构

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 → 1 doc (if hasDocker)
└── Phase 3: Aggregate Results
ln-110-project-docs-coordinator (本组件)
├── 阶段1：上下文收集（仅执行一次）
├── 阶段2：委托给工作组件
│   ├── ln-111-root-docs-creator → 4个根文档（始终执行）
│   ├── ln-112-project-core-creator → 3个核心文档（始终执行）
│   ├── ln-113-backend-docs-creator → 2个文档（若包含hasBackend/hasDatabase）
│   ├── ln-114-frontend-docs-creator → 1个文档（若包含hasFrontend）
│   └── ln-115-devops-docs-creator → 1个文档（若包含hasDocker）
└── 阶段3：聚合结果

Workflow

工作流程

Phase 1: Context Gathering (ONE TIME)

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

1.1 Auto-Discovery (scan project files):
SourceData ExtractedContext Store Keys
package.jsonname, description, dependencies, scripts, engines, author, contributorsPROJECT_NAME, PROJECT_DESCRIPTION, DEPENDENCIES, DEV_COMMANDS, DEVOPS_CONTACTS
docker-compose.ymlservices, ports, deploy.replicas, runtime:nvidiaDOCKER_SERVICES, DEPLOYMENT_SCALE, HAS_GPU
Dockerfileruntime versionRUNTIME_VERSION
src/ structurefolders, patternsSRC_STRUCTURE, ARCHITECTURE_PATTERN
migrations/table definitionsSCHEMA_OVERVIEW
.env.exampleenvironment variablesENV_VARIABLES
tsconfig.json, .eslintrcconventionsCODE_CONVENTIONS
README.mdproject description, scaling mentionsPROJECT_DESCRIPTION (fallback), DEPLOYMENT_SCALE (fallback)
CODEOWNERSmaintainersDEVOPS_CONTACTS
git logfrequent committersDEVOPS_CONTACTS (fallback)
1.2 Detect Project Type:
FlagDetection Rule
hasBackendexpress/fastify/nestjs/fastapi/django in dependencies
hasDatabasepg/mongoose/prisma/sequelize in dependencies OR postgres/mongo in docker-compose
hasFrontendreact/vue/angular/svelte in dependencies
hasDockerDockerfile exists OR docker-compose.yml exists
1.3 User Materials Request:
  • Ask: "Do you have existing materials (requirements, designs, docs)?"
  • If provided: Extract answers for Context Store
1.4 MCP Research (for detected technologies):
  • Use Context7/Ref for best practices
  • Store in Context Store for workers
1.5 Build Context Store:
json
{
  "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,
  "flags": { "hasBackend": true, "hasDatabase": true, "hasFrontend": true, "hasDocker": true }
}
DEPLOYMENT_SCALE detection rules:
  • "single"
    (default): No deploy.replicas, no scaling keywords in README
  • "multi"
    : deploy.replicas > 1 OR load balancer mentioned
  • "auto-scaling"
    : auto-scaling keywords in README/docker-compose
  • "gpu-based"
    : runtime: nvidia in docker-compose
DEVOPS_CONTACTS fallback chain:
  1. CODEOWNERS file → extract maintainers
  2. package.json author/contributors → extract names/emails
  3. git log → top 3 frequent committers
  4. If all empty → 
    [TBD: Provide DevOps team contacts]
1.6 Merge Legacy Content (if provided by ln-100):
  • Check if 
    LEGACY_CONTENT
    was passed from ln-100 Phase 0
  • If exists, merge into Context Store: 
    contextStore.LEGACY_CONTENT = input.LEGACY_CONTENT
  • Merge priority for workers: 
    • LEGACY_CONTENT.legacy_architecture
      → used by ln-112 for architecture.md
    • LEGACY_CONTENT.legacy_requirements
      → used by ln-112 for requirements.md
    • LEGACY_CONTENT.legacy_tech_stack
      → merged with auto-discovered TECH_STACK
    • LEGACY_CONTENT.legacy_principles
      → used by ln-111 for principles.md
    • LEGACY_CONTENT.legacy_api
      → used by ln-113 for api_spec.md
    • LEGACY_CONTENT.legacy_database
      → used by ln-113 for database_schema.md
    • LEGACY_CONTENT.legacy_runbook
      → used by ln-115 for runbook.md
  • If no LEGACY_CONTENT: workers use auto-discovery + template defaults
1.1 自动发现（扫描项目文件）：
来源提取的数据上下文存储键
package.json名称、描述、依赖项、脚本、引擎、作者、贡献者PROJECT_NAME, PROJECT_DESCRIPTION, DEPENDENCIES, DEV_COMMANDS, DEVOPS_CONTACTS
docker-compose.yml服务、端口、deploy.replicas、runtime:nvidiaDOCKER_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（备选）
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 请求用户提供材料：
  • 询问：“您是否有现有材料（需求、设计、文档）？”
  • 若提供：提取信息并添加到Context Store
1.4 MCP研究（针对检测到的技术栈）：
  • 使用Context7/Ref获取最佳实践
  • 将结果存储到Context Store供工作组件使用
1.5 构建Context Store：
json
{
  "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,
  "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. 若以上均为空 → 
    [待补充：提供DevOps团队联系人信息]
1.6 合并遗留内容（若由ln-100提供）：
  • 检查ln-100的Phase 0是否传递了
    LEGACY_CONTENT
  • 若存在，将其合并到Context Store中： 
    contextStore.LEGACY_CONTENT = input.LEGACY_CONTENT
  • 工作组件使用优先级： 
    • LEGACY_CONTENT.legacy_architecture
      → 由ln-112用于生成architecture.md
    • LEGACY_CONTENT.legacy_requirements
      → 由ln-112用于生成requirements.md
    • LEGACY_CONTENT.legacy_tech_stack
      → 与自动发现的TECH_STACK合并
    • LEGACY_CONTENT.legacy_principles
      → 由ln-111用于生成principles.md
    • LEGACY_CONTENT.legacy_api
      → 由ln-113用于生成api_spec.md
    • LEGACY_CONTENT.legacy_database
      → 由ln-113用于生成database_schema.md
    • LEGACY_CONTENT.legacy_runbook
      → 由ln-115用于生成runbook.md
  • 若无LEGACY_CONTENT：工作组件使用自动发现内容 + 模板默认值

Phase 2: Delegate to Workers

阶段2：委托给工作组件

2.1 Always invoke (parallel):
  • ln-111-root-docs-creator
    with Context Store
  • ln-112-project-core-creator
    with full Context Store
2.2 Conditionally invoke:
  • ln-113-backend-docs-creator
    if hasBackend OR hasDatabase
  • ln-114-frontend-docs-creator
    if hasFrontend
  • ln-115-devops-docs-creator
    if hasDocker
Delegation Pattern:
  • Pass Context Store and flags to workers via direct Skill tool invocation
  • Wait for completion
  • Collect result (created, skipped, tbd_count, validation)
2.1 始终调用（并行执行）：
  • 向
    ln-111-root-docs-creator
    传递Context Store
  • 向
    ln-112-project-core-creator
    传递完整的Context Store
2.2 条件调用：
  • 若包含hasBackend或hasDatabase，则调用
    ln-113-backend-docs-creator
  • 若包含hasFrontend，则调用
    ln-114-frontend-docs-creator
  • 若包含hasDocker，则调用
    ln-115-devops-docs-creator
委托模式：
  • 通过直接调用Skill工具的方式，将Context Store和标识传递给工作组件
  • 等待执行完成
  • 收集结果（已创建、已跳过、待补充数量、验证信息）

Phase 3: Aggregate Results

阶段3：聚合结果

  1. Collect status from all workers
  2. Sum totals: created files, skipped files, TBD markers
  3. Report any validation warnings
  4. Return aggregated summary to ln-100
  5. Include Context Store for subsequent workers (ln-120 needs TECH_STACK)
Output:
json
{
  "workers_invoked": 5,
  "total_created": 11,
  "total_skipped": 0,
  "total_tbd": 8,
  "validation_status": "OK",
  "files": [
    "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/runbook.md"
  ],
  "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 }
  }
}
  1. 收集所有工作组件的状态
  2. 统计总数：已创建文件数、已跳过文件数、待补充标记数
  3. 报告所有验证警告
  4. 将汇总结果返回给ln-100
  5. 传递Context Store供后续工作组件使用（ln-120需要TECH_STACK信息）
输出结果：
json
{
  "workers_invoked": 5,
  "total_created": 11,
  "total_skipped": 0,
  "total_tbd": 8,
  "validation_status": "OK",
  "files": [
    "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/runbook.md"
  ],
  "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 }
  }
}

Critical Notes

重要说明

  • Context gathered ONCE — never duplicated in workers
  • Context Store passed explicitly — no implicit state
  • Workers self-validate — coordinator only aggregates
  • Idempotent — workers skip existing files
  • Parallel where possible — ln-111 and ln-112 can run in parallel
  • 仅收集一次上下文 — 工作组件中不会重复执行上下文收集
  • 显式传递Context Store — 无隐式状态
  • 工作组件自行验证 — 统筹组件仅负责聚合结果
  • 幂等性 — 工作组件会跳过已存在的文件
  • 尽可能并行执行 — ln-111和ln-112可并行运行

Documentation Standards (passed to workers)

文档规范（传递给工作组件）

  • NO_CODE Rule: Documents describe contracts, not implementations
  • Stack Adaptation: Links must match TECH_STACK (Context Store)
  • Format Priority: Tables/ASCII > Lists > Text
  • 无代码规则： 文档描述的是契约，而非实现细节
  • 技术栈适配： 链接必须与Context Store中的TECH_STACK匹配
  • 格式优先级： 表格/ASCII图 > 列表 > 纯文本

Definition of Done

完成标准

  • Context Store built with all discovered data
  • Project type flags determined
  • All applicable workers invoked
  • Results aggregated
  • Summary returned to ln-100
  • 已构建包含所有发现数据的Context Store
  • 已确定项目类型标识
  • 已调用所有适用的工作组件
  • 已聚合结果
  • 已将汇总信息返回给ln-100

Reference Files

参考文件

  • Guides: 
    references/guides/automatic_analysis_guide.md
    , 
    critical_questions.md
    , 
    troubleshooting.md
Version: 2.1.0 (Added Documentation Standards passed to workers) Last Updated: 2025-01-12
  • 指南：
    references/guides/automatic_analysis_guide.md
    , 
    critical_questions.md
    , 
    troubleshooting.md
版本： 2.1.0（新增传递给工作组件的文档规范） 最后更新时间： 2025-01-12