ln-130-tasks-docs-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tasks Documentation Creator

任务管理文档生成工具

This skill creates task management documentation: docs/tasks/README.md (task management system rules) and docs/tasks/kanban_board.md (Linear integration with Epic Story Counters).

本工具用于创建任务管理文档：docs/tasks/README.md（任务管理系统规则）和docs/tasks/kanban_board.md（集成Epic故事计数器的Linear看板）。

When to Use This Skill

适用场景

This skill is a L2 WORKER invoked by ln-100-documents-pipeline orchestrator OR used standalone.

Use this skill when:

Creating task management documentation (docs/tasks/)
Setting up Linear integration and kanban board
Validating existing task documentation structure and content
Configuring Linear team settings (Team Name, UUID, Key)

Part of workflow: ln-100-documents-pipeline → ln-110-project-docs-coordinator → ln-120-reference-docs-creator → ln-130-tasks-docs-creator → ln-140-test-docs-creator (optional) → ln-150-presentation-creator

本工具是L2 WORKER，可由ln-100-documents-pipeline编排器调用，也可独立使用。

在以下场景中使用本工具：

创建任务管理文档（docs/tasks/目录下）
配置Linear集成与Kanban看板
验证现有任务文档的结构与内容
配置Linear团队设置（团队名称、UUID、Key）

工作流位置：ln-100-documents-pipeline → ln-110-project-docs-coordinator → ln-120-reference-docs-creator → ln-130-tasks-docs-creator → ln-140-test-docs-creator（可选）→ ln-150-presentation-creator

How It Works

工作原理

The skill follows a 3-phase workflow: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT.

Phase 1: CREATE - Create tasks/README.md from template with SCOPE tags, workflow rules, Linear integration Phase 2: VALIDATE STRUCTURE - Auto-fix structural violations (SCOPE tags, sections, Maintenance, POSIX) Phase 3: VALIDATE CONTENT - Validate semantic content + special Linear Configuration handling (placeholder detection, UUID/Team Key validation, interactive user prompts)

本工具遵循三阶段工作流：创建 → 结构验证 → 内容验证。

阶段1：创建 - 基于模板创建tasks/README.md，包含SCOPE标签、工作流规则、Linear集成配置 阶段2：结构验证 - 自动修复结构违规问题（SCOPE标签、章节、维护部分、POSIX换行） 阶段3：内容验证 - 验证语义内容，针对Linear配置进行特殊处理（占位符检测、UUID/Team Key验证、交互式用户提示）

Phase 1: Create tasks/README.md

阶段1：创建tasks/README.md

Objective: Create task management system documentation from template.

When to execute: Always (first phase)

Process:

Check if tasks/README.md exists:
- Use Glob tool:
```
pattern: "docs/tasks/README.md"
```
- If file exists:
  - Skip creation
  - Log:
```
✓ docs/tasks/README.md already exists (preserved)
```
  - Proceed to Phase 2
- If NOT exists:
  - Continue to step 2
Create tasks directory:
- Create the
```
docs/tasks/
```
  directory if it doesn't exist
Create tasks/README.md from template:
- Copy template:
```
references/tasks_readme_template.md
```
  (v2.0.0) →
```
docs/tasks/README.md
```
- Replace placeholders:
  - ```
  {{DATE}}
```
  → current date (YYYY-MM-DD)
- Template contains:
  - SCOPE tags:
```

```
  - Story-Level Test Task Pattern
  - Kanban Board Structure (Epic Grouping Pattern)
  - Linear Integration (MCP methods)
  - Maintenance section

Notify user:

If created:

✓ Created docs/tasks/README.md with task management rules

If skipped:

✓ docs/tasks/README.md already exists (preserved)

Output: docs/tasks/README.md (created or existing)

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

执行时机：始终作为第一阶段执行

流程：

检查tasks/README.md是否存在：
- 使用Glob工具：
```
pattern: "docs/tasks/README.md"
```
- 若文件已存在：
  - 跳过创建步骤
  - 日志记录：
```
✓ docs/tasks/README.md已存在（保留原文件）
```
  - 进入阶段2
- 若文件不存在：
  - 继续执行步骤2
创建tasks目录：
- 若
```
docs/tasks/
```
  目录不存在则创建
基于模板创建tasks/README.md：
- 复制模板：
```
references/tasks_readme_template.md
```
  （v2.0.0）→
```
docs/tasks/README.md
```
- 替换占位符：
  - ```
  {{DATE}}
```
  → 当前日期（YYYY-MM-DD）
- 模板包含：
  - SCOPE标签：
```

```
  - 故事级测试任务模式
  - Kanban看板结构（Epic分组模式）
  - Linear集成（MCP方法）
  - 维护章节

通知用户：

若文件创建成功：

✓ 已创建docs/tasks/README.md，包含任务管理规则

若文件已存在：

✓ docs/tasks/README.md已存在（保留原文件）

输出：docs/tasks/README.md（新建或已存在的文件）

Phase 2: Validate Structure

阶段2：结构验证

Objective: Ensure tasks/README.md and kanban_board.md comply with structural requirements. Auto-fix violations.

When to execute: After Phase 1 completes (files exist or created)

Process:

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

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

流程：

2.1 Validate SCOPE tags

2.1 验证SCOPE标签

Files to check: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)

For each file:

Read first 5 lines
Check for
```

```
tag

Expected values:

tasks/README.md:

<!-- SCOPE: Task tracking system workflow and rules ONLY -->

kanban_board.md:

<!-- SCOPE: Quick navigation to active tasks in Linear -->

If missing:
- Use Edit tool to add SCOPE tag after first heading
- Log:
```
⚠ Auto-fixed: Added missing SCOPE tag to {filename}
```

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

对每个文件执行以下操作：

读取前5行内容
检查是否包含
```

```
标签

预期值：

tasks/README.md：

<!-- SCOPE: Task tracking system workflow and rules ONLY -->

kanban_board.md：

<!-- SCOPE: Quick navigation to active tasks in Linear -->

若缺失：
- 使用编辑工具在第一个标题后添加SCOPE标签
- 日志记录：
```
⚠ 自动修复：为{filename}添加缺失的SCOPE标签
```

2.2 Validate required sections

2.2 验证必填章节

Load validation spec:

Read
```
references/questions.md
```
Extract section names from questions

For tasks/README.md:

Required sections (from questions.md):
- "Linear Integration" OR "Core Concepts" (Linear MCP methods)
- "Task Workflow" OR "Critical Rules" (state transitions)
- "Task Templates" (template references)
For each section:
- Check if section header exists (case-insensitive)
- If missing:
  - Use Edit tool to add section with placeholder content
  - Log:
```
⚠ Auto-fixed: Added missing section '{section}' to tasks/README.md
```

For kanban_board.md (if exists):

Required sections:
- "Linear Configuration" (Team Name, UUID, Key)
- "Work in Progress" OR "Epic Tracking" (Kanban sections)
For each section:
- Check if section header exists
- If missing:
  - Use Edit tool to add section with placeholder
  - Log:
```
⚠ Auto-fixed: Added missing section '{section}' to kanban_board.md
```

加载验证规范：

读取
```
references/questions.md
```
从问题中提取章节名称

针对tasks/README.md：

必填章节（来自questions.md）：
- "Linear Integration" 或 "Core Concepts"（Linear MCP方法）
- "Task Workflow" 或 "Critical Rules"（状态流转规则）
- "Task Templates"（模板引用）
对每个章节：
- 检查章节标题是否存在（不区分大小写）
- 若缺失：
  - 使用编辑工具添加带占位符内容的章节
  - 日志记录：
```
⚠ 自动修复：为tasks/README.md添加缺失章节'{section}'
```

针对kanban_board.md（若存在）：

必填章节：
- "Linear Configuration"（团队名称、UUID、Key）
- "Work in Progress" 或 "Epic Tracking"（Kanban看板章节）
对每个章节：
- 检查章节标题是否存在
- 若缺失：
  - 使用编辑工具添加带占位符的章节
  - 日志记录：
```
⚠ 自动修复：为kanban_board.md添加缺失章节'{section}'
```

2.3 Validate Maintenance section

2.3 验证维护章节

Files to check: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)

For each file:

Search for
```
## Maintenance
```
header in last 20 lines

If missing:

Use Edit tool to add at end of file:

markdown

## Maintenance

**Update Triggers:**
- When Linear workflow changes
- When task templates are added/modified
- When label taxonomy changes

**Last Updated:** {current_date}

Log:

⚠ Auto-fixed: Added Maintenance section to {filename}

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

对每个文件执行以下操作：

检查最后20行是否包含
```
## Maintenance
```
标题

若缺失：

使用编辑工具在文件末尾添加：

markdown

## Maintenance

**Update Triggers:**
- When Linear workflow changes
- When task templates are added/modified
- When label taxonomy changes

**Last Updated:** {current_date}

日志记录：

⚠ 自动修复：为{filename}添加Maintenance章节

2.4 Validate POSIX line endings

2.4 验证POSIX换行符

Files to check: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)

For each file:

Check if file ends with single newline character

If missing:

Use Edit tool to add final newline

Log:

⚠ Auto-fixed: Added POSIX newline to {filename}

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

对每个文件执行以下操作：

检查文件是否以单个换行符结尾
若缺失：
- 使用编辑工具添加末尾换行符
- 日志记录：
```
⚠ 自动修复：为{filename}添加POSIX换行符
```

2.5 Report validation summary

2.5 结构验证总结

Log summary:

✓ 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]

If violations found:

⚠ Auto-fixed {total} structural violations

Output: Structurally valid task management documentation

日志输出总结：

✓ 结构验证完成：
  tasks/README.md:
    - SCOPE标签：[已添加/已存在]
    - 必填章节：[数量]个章节[已添加/已存在]
    - Maintenance章节：[已添加/已存在]
    - POSIX换行：[已修复/合规]
  kanban_board.md:
    - SCOPE标签：[已添加/已存在/跳过 - 文件不存在]
    - 必填章节：[数量]个章节[已添加/已存在/跳过]
    - Maintenance章节：[已添加/已存在/跳过]
    - POSIX换行：[已修复/合规/跳过]

若发现违规：

⚠ 自动修复{total}处结构违规

输出：结构合规的任务管理文档

Phase 3: Validate Content

阶段3：内容验证

Objective: Ensure each section answers its validation questions with meaningful content. Special handling for Linear Configuration (placeholder detection, user prompts, UUID/Team Key validation).

When to execute: After Phase 2 completes (structure valid, auto-fixes applied)

Process:

目标：确保每个章节的内容能有效回应对应的验证问题。针对Linear配置进行特殊处理（占位符检测、用户提示、UUID/Team Key验证）。

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

流程：

3.1 Load validation spec

3.1 加载验证规范

Read
```
references/questions.md
```
Parse document sections and questions
Extract validation heuristics for each section

读取
```
references/questions.md
```
解析文档章节及对应问题
提取每个章节的验证规则

3.2 Validate kanban_board.md → Linear Configuration (Special Handling)

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

Question: "What is the Linear team configuration?"

Step 3.2.1: Check if kanban_board.md exists:

Use Glob tool:
```
pattern: "docs/tasks/kanban_board.md"
```

If NOT exists:

Log:

ℹ kanban_board.md not found - skipping Linear Configuration validation

Skip to Step 3.3

If exists:
- Continue to Step 3.2.2

Step 3.2.2: Read Linear Configuration section:

Read
```
docs/tasks/kanban_board.md
```
Locate
```
## Linear Configuration
```
section
Extract Team Name, Team UUID, Team Key values

Step 3.2.3: Placeholder Detection:

Check for placeholders:

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

Interactive Setup Mode (if placeholders detected):

Prompt user for Team Name:
- Question: "What is your Linear Team Name?"
- Validation: Non-empty string
- Example: "My Project Team"
Prompt user for Team UUID:
- Question: "What is your Linear Team UUID?"
- Format:
```
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
- Validation Regex:
```
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
```
- If invalid:
  - Show error: "Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase hex)"
  - Re-prompt user
- Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Prompt user for Team Key:
- Question: "What is your Linear Team Key (2-4 uppercase letters)?"
- Format: 2-4 uppercase letters
- Validation Regex:
```
/^[A-Z]{2,4}$/
```
- If invalid:
  - Show error: "Invalid Team Key format. Expected: 2-4 uppercase letters (e.g., PROJ, WEB, API)"
  - Re-prompt user
- Example: "PROJ"

Replace placeholders:

Use Edit tool to replace in 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}

(if placeholder exists)

Set initial counters (if table exists):
- Set "Next Epic Number" → 1
- Set "Next Story Number" → 1
Update Last Updated date:
- Replace
```
[YYYY-MM-DD]
```
  →
```
{current_date}
```
  in Maintenance section
Save updated kanban_board.md

Log success:

✓ 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

Validation Mode (if real values present, no placeholders):

Extract existing values:
- Extract Team UUID from line matching:
```
Team UUID: {value}
```
  or in table
- Extract Team Key from line matching:
```
Team Key: {value}
```
  or in table

Validate formats:

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}$/
```

If validation fails:

⚠ 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.

Mark as invalid but continue (don't block)

If validation passes:

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

问题："What is the Linear team configuration?"

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

使用Glob工具：
```
pattern: "docs/tasks/kanban_board.md"
```

若文件不存在：

日志记录：

ℹ 未找到kanban_board.md - 跳过Linear配置验证

跳至步骤3.3

若文件存在：
- 继续执行步骤3.2.2

步骤3.2.2：读取Linear配置章节：

读取
```
docs/tasks/kanban_board.md
```
定位
```
## Linear Configuration
```
章节
提取团队名称、团队UUID、团队Key的值

步骤3.2.3：占位符检测：

检查是否存在以下占位符：

匹配模式：[TEAM_NAME], [TEAM_UUID], [TEAM_KEY]
若存在任意占位符 → 进入交互式配置模式
若无占位符 → 进入验证模式

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

提示用户输入团队名称：
- 问题："你的Linear团队名称是什么？"
- 验证规则：非空字符串
- 示例："My Project Team"
提示用户输入团队UUID：
- 问题："你的Linear团队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"
提示用户输入团队Key：
- 问题："你的Linear团队Key是什么（2-4个大写字母）？"
- 格式：2-4个大写字母
- 验证正则：
```
/^[A-Z]{2,4}$/
```
- 若格式无效：
  - 显示错误："Team Key格式无效。预期格式：2-4个大写字母（例如：PROJ, WEB, API）"
  - 重新提示用户
- 示例："PROJ"

替换占位符：

使用编辑工具在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}

（若存在该占位符）

初始化计数器（若存在表格）：
- 将"Next Epic Number"设置为1
- 将"Next Story Number"设置为1
更新最后修改日期：
- 将Maintenance章节中的
```
[YYYY-MM-DD]
```
  替换为
```
{current_date}
```
保存更新后的kanban_board.md

记录成功日志：

✓ Linear配置已更新：
  - Team Name: {user_team_name}
  - Team UUID: {user_team_uuid}
  - Team Key: {user_team_key}
  - Next Epic Number: 1
  - Next Story Number: 1

验证模式（存在真实值，无占位符时）：

提取现有值：
- 从匹配
```
Team UUID: {value}
```
  的行或表格中提取团队UUID
- 从匹配
```
Team Key: {value}
```
  的行或表格中提取团队Key

验证格式：

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}$/
```

若验证失败：

⚠ Linear配置中检测到格式无效：
  - Team UUID: {uuid}（预期格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）
  - Team Key: {key}（预期格式：2-4个大写字母）

请手动修复或重新运行工具以替换为正确值。

标记为无效但继续执行（不阻断流程）

若验证通过：

✓ Linear配置验证通过（团队：{name}, UUID: {uuid}, Key: {key}）

3.3 Validate tasks/README.md sections

3.3 验证tasks/README.md章节

Parametric loop for 3 questions (from questions.md):

For each question in:

"How is Linear integrated into the task management system?"
"What are the task state transitions and review criteria?"
"What task templates are available and how to use them?"

Validation process:

Extract validation heuristics from questions.md
Read corresponding section content from tasks/README.md
Check if ANY heuristic passes:
- Contains keyword X → pass
- Has pattern Y → pass
- Length > N words → pass
If ANY passes → Section valid

If NONE passes → Log warning:

⚠ Section may be incomplete: {section_name}

Example validation (Question 1: Linear Integration):

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

No auto-discovery needed (workflow is standardized in template)

针对3个问题的循环验证（来自questions.md）：

针对以下每个问题：

"How is Linear integrated into the task management system?"
"What are the task state transitions and review criteria?"
"What task templates are available and how to use them?"

验证流程：

从questions.md中提取对应章节的验证规则
读取tasks/README.md中对应章节的内容
检查是否满足任意一条规则：
- 包含关键词X → 通过
- 符合模式Y → 通过
- 字数超过N → 通过
若满足任意一条 → 章节内容合规

若均不满足 → 记录警告：

⚠ 章节内容可能不完整：{section_name}

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

验证规则：
- 包含"Linear"或"MCP" → 通过
- 提及团队ID或UUID → 通过
- 包含工作流状态（Backlog, Todo, In Progress） → 通过
- 字数超过100 → 通过

内容检查：
- ✓ 包含"Linear" → 通过
→ 章节内容合规

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

3.4 Validate kanban_board.md → Epic Tracking

3.4 验证kanban_board.md → Epic跟踪

Question: "Are Epics being tracked in the board?"

If kanban_board.md exists:

Validation heuristics:

- 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

Action:

Read Epic Tracking or Epics Overview section
Check if ANY heuristic passes
If passes → valid

If none pass → log warning:

⚠ Epic Tracking section may be incomplete

If kanban_board.md does NOT exist:

Skip validation

Log:

ℹ Epic Tracking validation skipped (kanban_board.md not found)

问题："Are Epics being tracked in the board?"

若kanban_board.md存在：

验证规则：

- 包含"Epic"或"Epics Overview"章节标题 → 通过
- 包含列名为Epic, Name, Status, Progress的表格 → 通过
- 或包含占位符："No active epics" → 通过
- 字数超过20 → 通过

操作流程：

读取Epic Tracking或Epics Overview章节内容
检查是否满足任意一条规则
若满足 → 内容合规

若均不满足 → 记录警告：

⚠ Epic跟踪章节内容可能不完整

若kanban_board.md不存在：

跳过验证

日志记录：

ℹ 跳过Epic跟踪验证（未找到kanban_board.md）

3.5 Report content validation summary

3.5 内容验证总结

Log summary:

✓ 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)

Output: Validated and potentially updated task management documentation with Linear configuration

日志输出总结：

✓ 内容验证完成：
  tasks/README.md:
    - ✓ Linear Integration: 合规（包含"Linear", "MCP", 工作流状态）
    - ✓ Task Workflow: 合规（包含状态流转规则）
    - ✓ Task Templates: 合规（包含模板引用）
  kanban_board.md:
    - ✓ Linear Configuration: {status}（团队：{name}, UUID: {uuid}, Key: {key}）
    - ✓ Epic Tracking: 合规（存在表格或占位符）

输出：已验证并可能更新的任务管理文档，包含配置完成的Linear集成

Complete Output Structure

最终输出结构

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

Note: Kanban board updated by ln-301-task-creator, ln-302-task-replanner, ln-400-story-executor (Epic Grouping logic).

docs/
└── tasks/
    ├── README.md                     # 任务管理系统规则
    └── kanban_board.md               # Linear集成看板（可选，手动创建或由其他工具生成）

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

Reference Files Used

参考文件

Templates

模板文件

Tasks README Template:

```
references/tasks_readme_template.md
```
(v2.0.0) - Task management system rules with:
- SCOPE tags (task management ONLY)
- Story-Level Test Task Pattern (tests in final Story task, NOT scattered)
- Kanban Board Structure (Epic Grouping Pattern with Status → Epic → Story → Tasks hierarchy)
- Linear Integration (MCP methods: create_project, create_issue, update_issue, list_issues)
- Maintenance section (Update Triggers, Verification, Last Updated)

Kanban Board Template:

```
references/kanban_board_template.md
```
(v3.0.0) - Linear integration template with:
- Linear Configuration table (Team Name, UUID, Key, Workspace URL)
- Epic Story Counters table (Next Epic Number, Story counters per Epic)
- Kanban sections: Backlog, Todo (✅ APPROVED), In Progress, To Review, To Rework, Done (Last 5 tasks), Postponed
- Epic Grouping Pattern format (Epic header → 📖 Story → Task with indentation)
- Placeholders for Epic/Story/Task entries

任务README模板：

```
references/tasks_readme_template.md
```
（v2.0.0）- 任务管理系统规则模板，包含：
- SCOPE标签（仅用于任务管理）
- 故事级测试任务模式（测试用例整合在最终故事任务中，不分散在实现任务里）
- Kanban看板结构（Epic分组模式，层级为Status → Epic → Story → Tasks）
- Linear集成（MCP方法：create_project, create_issue, update_issue, list_issues）
- Maintenance章节（更新触发条件、验证方式、最后修改日期）

Kanban看板模板：

```
references/kanban_board_template.md
```
（v3.0.0）- Linear集成模板，包含：
- Linear配置表格（团队名称、UUID、Key、工作区URL）
- Epic故事计数器表格（Next Epic Number、各Epic对应的故事计数器）
- Kanban章节：Backlog, Todo（✅ APPROVED）, In Progress, To Review, To Rework, Done（最近5个任务）, Postponed
- Epic分组模式格式（Epic标题 → 📖 Story → 缩进的任务）
- Epic/Story/Task条目的占位符

Validation Specification

验证规范

questions.md:

```
references/questions.md
```
(v1.0) - Validation questions for task management documentation:
- 5 sections (3 for tasks/README.md, 2 for kanban_board.md)
- Question format: Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints
- Special handling section for Linear Configuration (placeholder detection, UUID/Team Key validation)

questions.md：

```
references/questions.md
```
（v1.0）- 任务管理文档验证问题，包含：
- 5个章节（3个对应tasks/README.md，2个对应kanban_board.md）
- 问题格式：问题 → 预期内容 → 验证规则 → 自动发现提示 → MCP参考提示
- Linear配置特殊处理章节（占位符检测、UUID/Team Key验证）

Best Practices

最佳实践

Story-Level Test Task Pattern: Tests consolidated in final Story task, NOT scattered across implementation tasks
Epic Grouping Pattern: Epic context always visible, 0/2/4 space indentation (Epic → Story → Tasks)
Linear MCP: All task operations use Linear MCP methods (create_project, create_issue, update_issue)
SCOPE Tags: Include in first 3-5 lines of all documentation files
Idempotent: Can be invoked multiple times - checks file existence, preserves existing files, re-validates on each run

故事级测试任务模式：测试用例整合在最终故事任务中，不分散在实现任务里
Epic分组模式：始终显示Epic上下文，使用0/2/4空格缩进（Epic → Story → Tasks）
Linear MCP：所有任务操作均使用Linear MCP方法（create_project, create_issue, update_issue）
SCOPE标签：所有文档文件的前3-5行需包含SCOPE标签
幂等性：可多次调用 - 检查文件是否存在、保留现有文件、每次调用时重新验证

Documentation Standards

文档标准

NO_CODE Rule: Task docs describe workflows, not implementations
Stack Adaptation: References must match project stack
Format Priority: Tables (states, transitions) > Lists > Text

NO_CODE规则：任务文档仅描述工作流，不涉及实现细节
栈适配：参考内容需匹配项目技术栈
格式优先级：表格（状态、流转）> 列表 > 文本

Prerequisites

前置条件

Orchestrator: ln-110-documents-pipeline (invokes this worker in Phase 3, Step 3.3)

Standalone usage: Creating task docs, re-validating, setting up Linear Configuration

Idempotent: Yes - checks file existence, re-validates, auto-fixes, updates Linear Configuration if placeholders detected

编排器：ln-110-documents-pipeline（在阶段3步骤3.3中调用本工具）

独立使用场景：创建任务文档、重新验证文档、配置Linear集成

幂等性：是 - 检查文件是否存在、重新验证、自动修复、若检测到占位符则更新Linear配置

完成标准：

在完成工作前，需验证所有检查点：

Definition of Done

阶段1：创建

Before completing work, verify ALL checkpoints:

✅ tasks/README.md：

```
docs/tasks/
```
目录已创建（若之前不存在）
```
docs/tasks/README.md
```
已从模板创建（若之前不存在）或已保留原文件（若已存在）
所有
```
{{DATE}}
```
占位符已替换为当前日期
模板包含SCOPE标签、故事级测试任务模式、Kanban看板结构、Linear集成、Maintenance章节
已通知用户：文件已创建或已保留

Phase 1: CREATE

阶段2：结构验证

✅ tasks/README.md:

```
docs/tasks/
```
directory created (if didn't exist)
```
docs/tasks/README.md
```
created from template (if didn't exist) OR preserved (if existed)
All
```
{{DATE}}
```
placeholders replaced with current date
Template contains SCOPE tags, Story-Level Test Task Pattern, Kanban Board Structure, Linear Integration, Maintenance section
User notified: created OR preserved

Phase 2: VALIDATE STRUCTURE

阶段3：内容验证

✅ tasks/README.md：

Linear Integration章节验证通过（包含"Linear"或"MCP"或团队ID或工作流状态或字数>100）
Task Workflow章节验证通过（包含工作流状态或评审标准或字数>60）
Task Templates章节验证通过（包含"template"或Epic/Story/Task或链接或字数>40）
已记录内容验证总结

✅ kanban_board.md（若存在）：

Linear Configuration章节验证通过：
- 若检测到占位符([TEAM_NAME], [TEAM_UUID], [TEAM_KEY])：
  - 已提示用户输入团队名称（非空验证）
  - 已提示用户输入团队UUID（正则验证：
```
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
```
    ）
  - 已提示用户输入团队Key（正则验证：
```
/^[A-Z]{2,4}$/
```
    ）
  - 已用用户输入替换占位符
  - Next Epic Number已设置为1
  - Next Story Number已设置为1
  - 最后修改日期已更新
- 若存在真实值：
  - 团队UUID格式已验证
  - 团队Key格式已验证
  - 已记录验证结果（合规或带警告的无效）
Epic Tracking章节验证通过（包含"Epic"标题或表格或占位符或字数>20）
已记录内容验证总结

✅ 整体检查：

已显示总结信息："✓ 任务管理文档验证完成（三阶段流程结束）"
已告知用户所有自动修复操作
已告知用户Linear配置状态（若适用）

输出：docs/tasks/README.md + 可选的kanban_board.md（已验证、自动修复、若检测到占位符则已配置Linear集成）

版本：7.1.0（新增Documentation Standards章节） 最后更新：2025-01-12

Phase 3: VALIDATE CONTENT

—

✅ tasks/README.md:

Linear Integration section validated (contains "Linear" OR "MCP" OR team ID OR workflow states OR length > 100 words)
Task Workflow section validated (contains workflow states OR review criteria OR length > 60 words)
Task Templates section validated (contains "template" OR Epic/Story/Task OR links OR length > 40 words)
Validation summary logged

✅ kanban_board.md (if exists):

Linear Configuration section validated:
- If placeholders detected ([TEAM_NAME], [TEAM_UUID], [TEAM_KEY]):
  - User prompted for Team Name (non-empty validation)
  - User prompted for Team UUID (regex validation:
```
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
```
    )
  - User prompted for Team Key (regex validation:
```
/^[A-Z]{2,4}$/
```
    )
  - Placeholders replaced with user input
  - Next Epic Number set to 1
  - Next Story Number set to 1
  - Last Updated date updated
- If real values present:
  - Team UUID format validated
  - Team Key format validated
  - Validation result logged (valid OR invalid with warning)
Epic Tracking section validated (has "Epic" header OR table OR placeholder OR length > 20 words)
Validation summary logged

✅ Overall:

Summary message displayed: "✓ Task management documentation validated (3-phase complete)"
User informed about any auto-fixes applied
User informed about Linear Configuration status (if applicable)

Output: docs/tasks/README.md + optionally kanban_board.md (validated, auto-fixed where needed, Linear Configuration set up if placeholders found)

Version: 7.1.0 (Added Documentation Standards section) Last Updated: 2025-01-12

—