levnikolaevich/ln-130-tasks-docs-creator

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

Type: L2 Worker Category: 1XX Documentation Pipeline

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

Purpose

Create and validate task management documentation (docs/tasks/). Generates README.md with workflow rules and kanban_board.md with Linear integration, including interactive setup for team UUID/Key configuration.

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)

Workflow

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

MANDATORY READ: Load shared/references/docs_quality_contract.md, shared/references/docs_quality_rules.json, and shared/references/markdown_read_protocol.md.

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). Raw placeholders are allowed only during setup for docs/tasks/README.md and docs/tasks/kanban_board.md; published output must not leak unresolved markers into any other document.

---

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:

   • MANDATORY READ: Load references/tasks_readme_template.md
   • Copy template → docs/tasks/README.md
   • Replace placeholders:
     • {{DATE}} → current date (YYYY-MM-DD)
   • Template contains:
     • Full shared header contract (SCOPE, DOC_KIND, DOC_ROLE, READ_WHEN, SKIP_WHEN, PRIMARY_SOURCES)
     • Story-Level Test Task Pattern
     • Kanban Board Structure (Epic Grouping Pattern)
     • Linear Integration (MCP methods)
     • Quick Navigation, Agent Entry, and Maintenance sections

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 the opening block
2. Check for <!-- SCOPE: ... --> tag and metadata markers
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

MANDATORY READ: Load references/questions.md for validation specs (section names, heuristics, special handling rules).

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 the section with minimal concrete guidance or an explicit empty-state note
    • 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:

     ## 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

MANDATORY READ: Load references/questions.md — parse sections and extract validation heuristics.

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-301-task-creator, ln-302-task-replanner, ln-400-story-executor (Epic Grouping logic).

---

Reference Files

• references/tasks_readme_template.md — Task management system rules template
• references/kanban_board_template.md — Linear integration + kanban template
• references/questions.md — Validation questions, heuristics, special handling rules

---

Critical Rules

• Idempotent: Checks file existence before creation; preserves existing files; safe to re-run
• Linear UUID validation: Team UUID must match /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/; Team Key must match /^[A-Z]{2,4}$/
• Shared docs-quality contract: Follow shared/references/docs_quality_contract.md and shared/references/docs_quality_rules.json for placeholder policy, SCOPE/Maintenance requirements, and allowed setup exceptions
• Placeholder detection: If [TEAM_NAME], [TEAM_UUID], or [TEAM_KEY] found in kanban_board.md, enter interactive setup mode and prompt user; do not leave unresolved markers outside the allowlisted task docs
• Shared opening contract required: Both README.md and kanban_board.md must include SCOPE, metadata markers, Quick Navigation, Agent Entry, and Maintenance
• Story-Level Test Task Pattern: Tests consolidated in final Story task, not scattered across implementation tasks

Return Contract

Return a normalized summary so ln-100 can run a centralized docs-quality gate without re-parsing worker prose:

{
  "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"
}

Runtime Summary Artifact

MANDATORY READ: Load shared/references/docs_generation_summary_contract.md

Accept optional summaryArtifactPath.

Summary kind:

• docs-generation

Required payload semantics:

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

Write the summary to the provided artifact path or return the same envelope in structured output.

Definition of Done

• [ ] Phase 1: tasks/README.md created from template (or preserved if exists); setup placeholders contained only within allowlisted task docs
• [ ] Phase 2: Structure valid — SCOPE tags, required sections, Maintenance, POSIX endings (auto-fixed if needed)
• [ ] Phase 3: Content valid — heuristics pass per questions.md, Linear Configuration set up (if placeholders found)
• [ ] Return contract emitted with created_files, skipped_files, quality_inputs, and validation_status
• [ ] Summary message displayed with auto-fix count and Linear Configuration status

---

Version: 7.1.0 Last Updated: 2025-01-12