Initial commit

2025-11-30 08:37:27 +08:00
commit 37774aa937
131 changed files with 31137 additions and 0 deletions
--- a/skills/ln-113-tasks-docs-creator/SKILL.md
+++ b/skills/ln-113-tasks-docs-creator/SKILL.md
@@ -0,0 +1,509 @@
+---
+name: ln-113-tasks-docs-creator
+description: Creates task management documentation (docs/tasks/README.md + kanban_board.md). Third worker in ln-110-documents-pipeline. Sets up Linear integration and task tracking rules.
+---
+
+# 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).
+
+## When to Use This Skill
+
+**This skill is a WORKER** invoked by **ln-110-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-110-documents-pipeline → ln-111-root-docs-creator → ln-112-reference-docs-creator → **ln-113-tasks-docs-creator** → ln-114-project-docs-creator → ln-115-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)
+
+---
+
+## Phase 1: Create tasks/README.md
+
+**Objective**: Create task management system documentation from template.
+
+**When to execute**: Always (first phase)
+
+**Process**:
+
+1. **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
+
+2. **Create tasks directory**:
+   - Create the `docs/tasks/` directory if it doesn't exist
+
+3. **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: `<!-- SCOPE: Task tracking system workflow and rules ONLY -->`
+     - Story-Level Test Task Pattern
+     - Kanban Board Structure (Epic Grouping Pattern)
+     - Linear Integration (MCP methods)
+     - Maintenance section
+
+4. **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)
+
+---
+
+## Phase 2: Validate Structure
+
+**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**:
+
+### 2.1 Validate SCOPE tags
+
+**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)
+
+For each file:
+1. Read first 5 lines
+2. Check for `<!-- SCOPE: ... -->` tag
+3. Expected values:
+   - tasks/README.md: `<!-- SCOPE: Task tracking system workflow and rules ONLY -->`
+   - kanban_board.md: `<!-- SCOPE: Quick navigation to active tasks in Linear -->`
+4. **If missing:**
+   - Use Edit tool to add SCOPE tag after first heading
+   - Log: `⚠ Auto-fixed: Added missing SCOPE tag to {filename}`
+
+### 2.2 Validate required sections
+
+**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`
+
+### 2.3 Validate Maintenance section
+
+**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)
+
+For each file:
+1. Search for `## Maintenance` header in last 20 lines
+2. **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}`
+
+### 2.4 Validate POSIX line endings
+
+**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)
+
+For each file:
+1. Check if file ends with single newline character
+2. **If missing:**
+   - Use Edit tool to add final newline
+   - Log: `⚠ Auto-fixed: Added POSIX newline to {filename}`
+
+### 2.5 Report validation summary
+
+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
+
+---
+
+## Phase 3: Validate Content
+
+**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**:
+
+### 3.1 Load validation spec
+
+1. Read `references/questions.md`
+2. Parse document sections and questions
+3. Extract validation heuristics for each section
+
+### 3.2 Validate kanban_board.md → Linear Configuration (Special Handling)
+
+**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):
+
+1. **Prompt user for Team Name**:
+   - Question: "What is your Linear Team Name?"
+   - Validation: Non-empty string
+   - Example: "My Project Team"
+
+2. **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"
+
+3. **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"
+
+4. **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)
+
+5. **Set initial counters** (if table exists):
+   - Set "Next Epic Number" → 1
+   - Set "Next Story Number" → 1
+
+6. **Update Last Updated date**:
+   - Replace `[YYYY-MM-DD]` → `{current_date}` in Maintenance section
+
+7. **Save updated kanban_board.md**
+
+8. **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):
+
+1. **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
+
+2. **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}$/`
+
+3. **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)
+
+4. **If validation passes**:
+   ```
+   ✓ Linear Configuration valid (Team: {name}, UUID: {uuid}, Key: {key})
+   ```
+
+### 3.3 Validate tasks/README.md sections
+
+**Parametric loop for 3 questions** (from questions.md):
+
+For each question in:
+1. "How is Linear integrated into the task management system?"
+2. "What are the task state transitions and review criteria?"
+3. "What task templates are available and how to use them?"
+
+**Validation process**:
+1. Extract validation heuristics from questions.md
+2. Read corresponding section content from tasks/README.md
+3. Check if **ANY** heuristic passes:
+   - Contains keyword X → pass
+   - Has pattern Y → pass
+   - Length > N words → pass
+4. If ANY passes → Section valid
+5. 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.4 Validate kanban_board.md → Epic Tracking
+
+**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**:
+1. Read Epic Tracking or Epics Overview section
+2. Check if ANY heuristic passes
+3. If passes → valid
+4. 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)`
+
+### 3.5 Report content validation summary
+
+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
+
+---
+
+## 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-311-task-creator, ln-312-task-replanner, ln-330-story-executor (Epic Grouping logic).
+
+---
+
+## 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
+
+### 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)
+
+---
+
+## 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
+
+---
+
+## Prerequisites
+
+**Orchestrator**: ln-110-documents-pipeline (invokes this worker in Phase 3, Step 3.3)
+
+**Standalone usage**: Can also be invoked directly for:
+- Creating only task management documentation
+- Re-validating existing task documentation
+- Setting up Linear Configuration interactively
+
+**Idempotent**: Yes - can be invoked multiple times without side effects. The skill:
+- Checks file existence before creation (preserves existing files)
+- Re-validates structure and content on each run
+- Auto-fixes structural violations (SCOPE tags, sections, Maintenance, POSIX)
+- Updates Linear Configuration if placeholders detected
+
+**Dependencies**: None (standalone worker)
+
+---
+
+## Definition of Done
+
+Before completing work, verify ALL checkpoints:
+
+### Phase 1: CREATE
+
+**✅ 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
+
+**✅ tasks/README.md:**
+- [ ] SCOPE tag present in first 5 lines OR auto-fixed
+- [ ] Required sections present (Linear Integration/Core Concepts, Task Workflow/Critical Rules, Task Templates) OR auto-fixed
+- [ ] Maintenance section present at end OR auto-fixed
+- [ ] POSIX line ending present OR auto-fixed
+- [ ] Validation summary logged
+
+**✅ kanban_board.md (if exists):**
+- [ ] SCOPE tag present OR auto-fixed
+- [ ] Required sections present (Linear Configuration, Work in Progress/Epic Tracking) OR auto-fixed
+- [ ] Maintenance section present OR auto-fixed
+- [ ] POSIX line ending present OR auto-fixed
+- [ ] Validation summary logged
+
+### 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)
+
+---
+
+## Technical Details
+
+**Standards**: Story-Level Test Task Pattern, Epic Grouping Pattern (Status → Epic → Story → Tasks), Linear MCP integration
+
+**Language**: English only
+
+---
+
+**Version:** 7.0.0 (MAJOR: Added Phase 2/3 validation. Merged CREATE+VALIDATE into unified worker. Special Linear Configuration handling with UUID/Team Key validation, user prompts for placeholders. Idempotent.)
+**Last Updated:** 2025-11-18