ln-130-tasks-docs-creator

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

类型： L2 Worker 类别： 1XX 文档流水线

任务文档创建器

此技能用于创建任务管理文档：docs/tasks/README.md（任务管理系统规则）和 docs/tasks/kanban_board.md（配置了 Epic Story Counters 的跟踪器集成）。

目的

创建并验证任务管理文档（docs/tasks/）。生成包含工作流规则的 README.md，以及与跟踪器集成的 kanban_board.md；后者会适配已配置的提供方（linear/github/file），并包含针对提供方的交互式配置。

何时使用此技能

此技能是一个 L2 WORKER，由编排器 ln-100-documents-pipeline 调用，也可独立使用。

在以下情况下使用此技能：

• 创建任务管理文档（docs/tasks/）
• 设置跟踪器集成和看板
• 验证现有任务文档的结构和内容
• 配置针对提供方的跟踪器设置（linear：Team Name/UUID/Key；github：repository/project_number；file：无）

工作流组成部分：ln-100-documents-pipeline → ln-110-project-docs-coordinator → ln-120-reference-docs-creator → ln-130-tasks-docs-creator → ln-140-test-docs-creator（可选）

工作流

此技能遵循 3 阶段工作流：创建 → 验证结构 → 验证内容。

必须阅读： 加载 references/docs_quality_contract.md 和 references/markdown_read_protocol.md。 可选规则目录：仅在需要确切的规则 ID、路径矩阵或允许的占位符例外时，才加载 references/docs_quality_rules.json。

阶段 1：创建 - 根据模板创建 tasks/README.md，包含 SCOPE 标签、工作流规则和已配置的跟踪器集成 阶段 2：验证结构 - 自动修复结构违规（SCOPE 标签、章节、Maintenance、POSIX） 阶段 3：验证内容 - 验证语义内容，以及针对提供方的 Tracker Configuration 处理（占位符检测、提供方特定字段验证、交互式用户提示）。仅在设置期间，docs/tasks/README.md 和 docs/tasks/kanban_board.md 才允许包含原始占位符；已发布的输出不得在任何其他文档中泄露尚未解决的标记。

---

阶段 1：创建 tasks/README.md

目标：根据模板创建任务管理系统文档。

执行时机：始终执行（第一阶段）

流程：

1. 检查 tasks/README.md 是否存在：

   • 使用 Glob 工具：pattern: "docs/tasks/README.md"
   • 如果文件存在：
     • 跳过创建
     • 记录：✓ docs/tasks/README.md already exists (preserved)
     • 继续阶段 2
   • 如果文件不存在：
     • 继续第 2 步

2. 创建 tasks 目录：

   • 如果 docs/tasks/ 目录不存在，则创建该目录

3. 根据模板创建 tasks/README.md：

   • 必须阅读： 加载 references/templates/tasks_readme_template.md
   • 将模板复制到 docs/tasks/README.md
   • 替换占位符：
     • {{DATE}} → 当前日期（YYYY-MM-DD）
   • 模板包含：
     • 完整的共享标头约定（SCOPE、DOC_KIND、DOC_ROLE、READ_WHEN、SKIP_WHEN、PRIMARY_SOURCES）
     • Story 级测试任务模式
     • 看板结构（Epic 分组模式）
     • Linear 集成（MCP 方法）
     • Quick Navigation、Agent Entry 和 Maintenance 章节

4. 通知用户：

   • 如果已创建：✓ Created docs/tasks/README.md with task management rules
   • 如果跳过：✓ docs/tasks/README.md already exists (preserved)

输出：docs/tasks/README.md（已创建或已存在）

---

阶段 2：验证结构

目标：确保 tasks/README.md 和 kanban_board.md 符合结构要求。自动修复违规。

执行时机：阶段 1 完成后（文件已存在或已创建）

流程：

2.1 验证 SCOPE 标签

检查文件：docs/tasks/README.md、docs/tasks/kanban_board.md（如果存在）

对每个文件：

1. 阅读开头部分
2. 检查是否存在 `` 标签和元数据标记
3. 预期值：
   • tasks/README.md：``
   • kanban_board.md：``
4. 如果缺失：
   • 使用 Edit 工具，在第一个标题后添加 SCOPE 标签
   • 记录：⚠ Auto-fixed: Added missing SCOPE tag to {filename}

2.2 验证必需章节

必须阅读： 加载 references/questions.md，了解验证规范（章节名称、启发式规则、特殊处理规则）。

对于 tasks/README.md：

• 必需章节（来自 questions.md）：
  • “Linear Integration”或“Core Concepts”（Linear MCP 方法）
  • “Task Workflow”或“Critical Rules”（状态转换）
  • “Task Templates”（模板引用）
• 对于每个章节：
  • 检查章节标题是否存在（不区分大小写）
  • 如果缺失：
    • 使用 Edit 工具添加该章节，并提供最简明的具体指南或明确的空状态说明
    • 记录：⚠ Auto-fixed: Added missing section '{section}' to tasks/README.md

对于 kanban_board.md（如果存在）：

• 必需章节：
  • “Linear Configuration”（团队名称、UUID、Key）
  • “Work in Progress”或“Epic Tracking”（看板章节）
• 对于每个章节：
  • 检查章节标题是否存在
  • 如果缺失：
    • 使用 Edit 工具添加该章节，并添加占位内容
    • 记录：⚠ Auto-fixed: Added missing section '{section}' to kanban_board.md

2.3 验证 Maintenance 章节

检查文件：docs/tasks/README.md、docs/tasks/kanban_board.md（如果存在）

对每个文件：

1. 检查最后 20 行中是否有 ## Maintenance 标题
2. 如果缺失：
   • 使用 Edit 工具添加到文件末尾：

     ## Maintenance
     
     **Update Triggers:**
     - When Linear workflow changes
     - When task templates are added/modified
     - When label taxonomy changes
     
     **Last Updated:** {current_date}
     

   • 记录：⚠ Auto-fixed: Added Maintenance section to {filename}

2.4 验证 POSIX 换行符

检查文件：docs/tasks/README.md、docs/tasks/kanban_board.md（如果存在）

对每个文件：

1. 检查文件是否以单个换行符结尾
2. 如果缺失：
   • 使用 Edit 工具添加末尾换行符
   • 记录：⚠ Auto-fixed: Added POSIX newline to {filename}

2.5 报告验证摘要

记录摘要：

✓ Structure validation completed:
  tasks/README.md:
    - SCOPE tag: [added/present]
    - Required sections: [count] sections [added/present]
    - Maintenance section: [added/present]
    - POSIX endings: [fixed/compliant]
  kanban_board.md:
    - SCOPE tag: [added/present/skipped - file not exists]
    - Required sections: [count] sections [added/present/skipped]
    - Maintenance section: [added/present/skipped]
    - POSIX endings: [fixed/compliant/skipped]

如果发现违规项：⚠ Auto-fixed {total} structural violations

输出：结构有效的任务管理文档

---

阶段 3：验证内容

目标：确保每个章节都以有意义的内容回答其验证问题。针对 Linear Configuration 进行特殊处理（占位内容检测、用户提示、UUID/Team Key 验证）。

执行时机：阶段 2 完成后（结构有效，自动修复已应用）

流程：

3.1 加载验证规范

必须阅读： 加载 references/questions.md，解析章节并提取验证启发式规则。

3.2 验证 kanban_board.md → Linear 配置（特殊处理）

问题：“Linear 团队配置是什么？”

步骤 3.2.1：检查 kanban_board.md 是否存在：

• 使用 Glob 工具：pattern: "docs/tasks/kanban_board.md"
• 如果不存在：
  • 记录：ℹ kanban_board.md not found - skipping Linear Configuration validation
  • 跳转到步骤 3.3
• 如果存在：
  • 继续执行步骤 3.2.2

步骤 3.2.2：读取 Linear Configuration 部分：

• 读取 docs/tasks/kanban_board.md
• 定位 ## Linear Configuration 部分
• 提取 Team Name、Team UUID 和 Team Key 的值

步骤 3.2.3：检测占位符：

检查是否存在占位符：

Pattern: [TEAM_NAME], [TEAM_UUID], [TEAM_KEY]
If ANY placeholder present → Interactive Setup Mode
If NO placeholders present → Validation Mode

交互式设置模式（检测到占位符时）：

1. 提示用户输入 Team Name：

   • 问题：“您的 Linear Team Name 是什么？”
   • 验证：非空字符串
   • 示例：“My Project Team”

2. 提示用户输入 Team UUID：

   • 问题：“您的 Linear Team UUID 是什么？”
   • 格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   • 验证正则表达式：/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
   • 如果无效：
     • 显示错误：“UUID 格式无效。预期格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx（小写十六进制）”
     • 重新提示用户输入
   • 示例：“a1b2c3d4-e5f6-7890-abcd-ef1234567890”

3. 提示用户输入 Team Key：

   • 问题：“您的 Linear Team Key 是什么（2-4 个大写字母）？”
   • 格式：2-4 个大写字母
   • 验证正则表达式：/^[A-Z]{2,4}$/
   • 如果无效：
     • 显示错误：“Team Key 格式无效。预期格式：2-4 个大写字母（例如 PROJ、WEB、API）”
     • 重新提示用户输入
   • 示例：“PROJ”

4. 替换占位符：

   • 使用 Edit 工具在 kanban_board.md 中替换：
     • [TEAM_NAME] → {user_team_name}
     • [TEAM_UUID] → {user_team_uuid}
     • [TEAM_KEY] → {user_team_key}
     • [WORKSPACE_URL] → https://linear.app/{workspace_slug}（如果存在该占位符）

5. 设置初始计数器（如果存在表格）：

   • 将“Next Epic Number”设为 1
   • 将“Next Story Number”设为 1

6. 更新 Last Updated 日期：

   • 在 Maintenance 部分中，将 [YYYY-MM-DD] 替换为 {current_date}

7. 保存更新后的 kanban_board.md

8. 记录成功信息：

   ✓ Linear configuration updated:
     - Team Name: {user_team_name}
     - Team UUID: {user_team_uuid}
     - Team Key: {user_team_key}
     - Next Epic Number: 1
     - Next Story Number: 1
   

验证模式（存在实际值、没有占位符时）：

1. 提取现有值：

   • 从符合以下格式的行或表格中提取 Team UUID：Team UUID: {value}
   • 从符合以下格式的行或表格中提取 Team Key：Team Key: {value}

2. 验证格式：

   • UUID：/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
   • Team Key：/^[A-Z]{2,4}$/

3. 如果验证失败：

   ⚠ Invalid format detected in Linear Configuration:
     - Team UUID: {uuid} (expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
     - Team Key: {key} (expected: 2-4 uppercase letters)
   
   Fix manually or re-run skill to replace with correct values.
   

   • 标记为无效，但继续执行（不要阻止流程）

4. 如果验证通过：

   ✓ Linear Configuration valid (Team: {name}, UUID: {uuid}, Key: {key})
   

3.3 验证 tasks/README.md 各部分

针对 3 个问题的参数化循环（来自 questions.md）：

对以下每个问题：

1. “Linear 如何集成到任务管理系统中？”
2. “任务状态如何转换，审核标准是什么？”
3. “有哪些任务模板，如何使用？”

验证流程：

1. 从 questions.md 中提取验证启发式规则
2. 从 tasks/README.md 中读取相应部分的内容
3. 检查是否有任意一条启发式规则通过：
   • 包含关键词 X → 通过
   • 符合模式 Y → 通过
   • 长度 > N 个词 → 通过
4. 如果任意一条通过 → 部分有效
5. 如果没有一条通过 → 记录警告：⚠ Section may be incomplete: {section_name}

验证示例（问题 1：Linear 集成）：

Heuristics:
- Contains "Linear" or "MCP" → pass
- Mentions team ID or UUID → pass
- Has workflow states (Backlog, Todo, In Progress) → pass
- Length > 100 words → pass

Check content:
- ✓ Contains "Linear" → PASS
→ Section valid

无需自动发现（工作流已在模板中标准化）

3.4 验证 kanban_board.md → Epic 跟踪

问题：“看板中是否正在跟踪 Epic？”

如果 kanban_board.md 存在：

验证启发式规则：

- Has "Epic" or "Epics Overview" section header → pass
- Has table with columns: Epic, Name, Status, Progress → pass
- OR has placeholder: "No active epics" → pass
- Length > 20 words → pass

操作：

1. 阅读 Epic 跟踪或 Epic 概览部分
2. 检查是否有任意一条启发式规则通过
3. 如果通过 → 有效
4. 如果没有一条通过 → 记录警告：⚠ Epic Tracking section may be incomplete

如果 kanban_board.md 不存在：

• 跳过验证
• 记录：ℹ Epic Tracking validation skipped (kanban_board.md not found)

3.5 报告内容验证摘要

记录摘要：

✓ Content validation completed:
  tasks/README.md:
    - ✓ Linear Integration: valid (contains "Linear", "MCP", workflow states)
    - ✓ Task Workflow: valid (contains state transitions)
    - ✓ Task Templates: valid (contains template references)
  kanban_board.md:
    - ✓ Linear Configuration: {status} (Team: {name}, UUID: {uuid}, Key: {key})
    - ✓ Epic Tracking: valid (table present or placeholder)

输出：已验证且可能已更新的任务管理文档，其中包含 Linear 配置

---

完整输出结构

docs/
└── tasks/
    ├── README.md                     # Task management system rules
    └── kanban_board.md               # Linear integration (optional, created manually or by other skills)

注意：看板由 ln-301-task-creator、ln-302-task-replanner、ln-400-story-executor（Epic 分组逻辑）更新。

---

参考文件

• references/templates/tasks_readme_template.md — 任务管理系统规则模板
• references/templates/kanban_board_template.md — Linear 集成与看板模板
• references/questions.md — 验证问题、启发式规则、特殊处理规则

---

关键规则

• 幂等： 创建前检查文件是否存在；保留现有文件；可安全地重复运行
• Linear UUID 验证： Team UUID 必须匹配 /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/；Team Key 必须匹配 /^[A-Z]{2,4}$/
• 共享文档质量契约： 遵循 references/docs_quality_contract.md 和 references/docs_quality_rules.json 中关于占位符策略、SCOPE/Maintenance 要求以及允许的设置例外的规定
• 占位符检测： 如果在 kanban_board.md 中发现 [TEAM_NAME]、[TEAM_UUID] 或 [TEAM_KEY]，则进入交互式设置模式并提示用户；除允许列表中的任务文档外，不得留下未解决的标记
• 必需的共享开篇契约： README.md 和 kanban_board.md 都必须包含 SCOPE、元数据标记、Quick Navigation、Agent Entry 和 Maintenance
• Story 级测试任务模式： 测试集中在最终的 Story 任务中，而不是分散在各个实现任务中

返回契约

返回规范化摘要，以便 ln-100 无需重新解析工作进程的文本即可运行集中式文档质量门禁：

{
  "created_files": [
    "docs/tasks/README.md",
    "docs/tasks/kanban_board.md"
  ],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": [
      "docs/tasks/README.md",
      "docs/tasks/kanban_board.md"
    ],
    "owners": {
      "docs/tasks/README.md": "ln-130-tasks-docs-creator",
      "docs/tasks/kanban_board.md": "ln-130-tasks-docs-creator"
    }
  },
  "validation_status": "passed|passed_with_fixes|skipped"
}

运行时摘要产物

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

接受可选的 summaryArtifactPath。

摘要类型：

• docs-generation

必需的负载语义：

• worker = "ln-130"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

将摘要写入提供的产物路径，或在结构化输出中返回相同的封装内容。

完成定义

• 阶段 1：根据模板创建 tasks/README.md（如果已存在则保留）；设置占位符仅出现在允许列表中的任务文档内
• 阶段 2：结构有效 — SCOPE 标签、必需章节、Maintenance、POSIX 行尾（如有需要则自动修复）
• 阶段 3：内容有效 — questions.md 中的启发式规则通过；设置 Tracker Configuration（如果发现占位符）
• 已输出返回契约，其中包含 created_files、skipped_files、quality_inputs 和 validation_status
• 显示摘要消息，其中包含自动修复次数和 Tracker Configuration 状态

---

版本： 7.1.0 最后更新： 2025-01-12