---
name: ln-110-documents-pipeline
description: Orchestrates complete doc system via 6 workers (ln-111→ln-116). Each worker self-validates. Phase 4: global cleanup. Idempotent.
---

# Documentation Pipeline (Orchestrator)

This skill orchestrates the creation of a complete documentation system by invoking 6 specialized documentation workers in sequence. Each worker handles one domain (root/reference/tasks/project/presentation/test) and validates its own output, eliminating Worker→Worker coupling.

## When to Use This Skill

This skill should be used when:
- Start a new IT project and need complete documentation system at once
- Use automated workflow instead of manually invoking 6 workers
- Create entire documentation structure (CLAUDE.md → docs/ → presentation/) in one go
- Prefer orchestrated CREATE path over manual skill chaining
- Need automatic global cleanup (deduplication, orphaned files, consolidation)

**Alternative**: If you prefer granular control, invoke workers manually:
1. [ln-111-root-docs-creator](../ln-111-root-docs-creator/SKILL.md) - CLAUDE.md + docs/README.md + documentation_standards.md + principles.md
2. [ln-112-reference-docs-creator](../ln-112-reference-docs-creator/SKILL.md) - reference/ structure
3. [ln-113-tasks-docs-creator](../ln-113-tasks-docs-creator/SKILL.md) - tasks/README.md + kanban
4. [ln-114-project-docs-creator](../ln-114-project-docs-creator/SKILL.md) - project docs
5. [ln-115-presentation-creator](../ln-115-presentation-creator/SKILL.md) - HTML presentation
6. [ln-116-test-docs-creator](../ln-116-test-docs-creator/SKILL.md) - tests/README.md (optional)

**Note**: Each worker now validates its own output in Phase 2/3. Orchestrator handles global operations only.

## How It Works

The skill follows a 5-phase orchestration workflow: User confirmation → Invoke 6 workers sequentially → Global cleanup → Summary. Phase 3 (validation) is intentionally skipped - each worker validates its own output.

### Phase 1: User Confirmation

**Objective**: Check existing files, explain workflow, and get user approval.

**Process**:

1. **Pre-flight Check** (scan existing documentation):
   - Use Glob tool to check all potential files:
     - **Root docs** (4 files): `CLAUDE.md`, `docs/README.md`, `docs/documentation_standards.md`, `docs/principles.md`
     - **Reference structure** (4 items): `docs/reference/README.md`, `docs/reference/adrs/`, `docs/reference/guides/`, `docs/reference/manuals/`
     - **Tasks docs** (2 files): `docs/tasks/README.md`, `docs/tasks/kanban_board.md`
     - **Project docs** (up to 7 files): `docs/project/requirements.md`, `architecture.md`, `tech_stack.md`, `api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md`
     - **Presentation** (3 items): `docs/presentation/README.md`, `presentation_final.html`, `assets/` directory
     - **Test docs** (2 files): `docs/reference/guides/testing-strategy.md`, `tests/README.md`
   - Count existing vs missing files
   - Show user summary:
     ```
     📊 Documentation Status:
     ✓ Found: X existing files
     ✗ Missing: Y files

     ⚠️ Pipeline will create ONLY missing files.
     ✅ Existing files will be preserved (no overwrites).
     ```

2. Show user what will be created:
   - Root documentation (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md via ln-111-root-docs-creator)
   - Reference structure (docs/reference/ via ln-112-reference-docs-creator)
   - Task management docs (docs/tasks/ via ln-113-tasks-docs-creator)
   - Project documentation (docs/project/ via ln-114-project-docs-creator)
   - HTML presentation (docs/presentation/ via ln-115-presentation-creator)
   - Test documentation (tests/ via ln-116-test-docs-creator - optional)
   - Estimated time: 15-20 minutes with interactive dialog

3. Ask: "Proceed with creating missing files? (yes/no)"

4. Ask: "Include test documentation (tests/README.md)? (yes/no)"

**Output**: File scan summary + user approval + test docs preference

---

### Phase 2: Invoke Workers Sequentially

**Objective**: Create complete documentation system by invoking 6 workers in order.

**Process** (AUTOMATIC invocations with Skill tool):

**2.1 Create Root Documentation**:
- **Invocation**: `Skill(skill: "ln-111-root-docs-creator")` → AUTOMATIC
- **Output**: `CLAUDE.md` + `docs/README.md` (root hub with general standards) + `docs/documentation_standards.md` (60 universal requirements) + `docs/principles.md` (11 development principles)
- **Validation**: ln-111 validates output in Phase 2/3 (SCOPE tags, Maintenance sections)
- **Verify**: All four files exist before continuing

**2.2 Create Reference Structure**:
- **Invocation**: `Skill(skill: "ln-112-reference-docs-creator")` → AUTOMATIC
- **Output**: `docs/reference/README.md` + `adrs/`, `guides/`, `manuals/` directories + ADR template
- **Validation**: ln-112 validates output in Phase 2/3
- **Verify**: Reference hub exists before continuing

**2.3 Create Task Management Docs**:
- **Invocation**: `Skill(skill: "ln-113-tasks-docs-creator")` → AUTOMATIC
- **Output**: `docs/tasks/README.md` + optionally `kanban_board.md` (if user provides Linear config)
- **Validation**: ln-113 validates output in Phase 2/3
- **Verify**: Tasks README exists before continuing

**2.4 Create Project Documentation**:
- **Invocation**: `Skill(skill: "ln-114-project-docs-creator")` → AUTOMATIC (requires user interaction for 23 technical questions)
- **Output**: `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional: `api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md` (3-7 documents based on project type)
- **Validation**: ln-114 validates output in Phase 2/3
- **Verify**: All required project docs exist before continuing

**2.5 Create HTML Presentation**:
- **Invocation**: `Skill(skill: "ln-115-presentation-creator")` → AUTOMATIC
- **Output**: `docs/presentation/README.md` + `presentation_final.html` + `assets/`
- **Validation**: ln-115 validates output in Phase 2/3
- **Verify**: Presentation files exist before continuing

**2.6 Create Test Documentation (Optional)**:
- **Condition**: If user approved test docs in Phase 1
- **Invocation**: `Skill(skill: "ln-116-test-docs-creator")` → AUTOMATIC
- **Output**: `tests/README.md` (test documentation with Story-Level Test Task Pattern)
- **Validation**: ln-116 validates output in Phase 2/3
- **Skip**: If "no" → can run ln-116-test-docs-creator later manually

**Output**: Complete documentation system with all 6 workers completed and validated

---

### Phase 4: Global Cleanup and Consolidation

**Objective**: Remove duplicates, orphaned files, consolidate knowledge across ALL documentation.

**Trigger**: Only after ALL workers complete Phase 2/3 validation.

**Process**:

**4.1 Scan for duplicate content**

1. **Read all .md files in docs/**
   - Use Glob tool: `pattern: "docs/**/*.md"`
   - Store list of all documentation files

2. **Identify duplicate sections:**
   - For each file:
     - Read file content
     - Extract section headers (##, ###)
     - Extract section content (text between headers)
   - Compare sections across files:
     - If 2+ sections have:
       - Same heading (case-insensitive)
       - >80% content similarity (simple word overlap check)
     - Mark as duplicate

3. **Determine canonical version:**
   - Rules for canonical location:
     - "Development Principles" → principles.md (always canonical)
     - "Testing Strategy" → testing-strategy.md (always canonical)
     - "Linear Configuration" → tasks/kanban_board.md (always canonical)
     - For other duplicates: Keep in FIRST file encountered (alphabetical order)

4. **Remove duplicates:**
   - For each duplicate section:
     - Use Edit tool to delete from non-canonical files
     - Use Edit tool to add link to canonical location:
       ```markdown
       See [Development Principles](../principles.md#development-principles) for details.
       ```
   - Track count of removed duplicates

5. **Log results:**
   - "✓ Removed {count} duplicate sections"
   - List: "{section_name} removed from {file} (canonical: {canonical_file})"

**4.2 Scan for orphaned files**

1. **List all .md files in docs/**
   - Use Glob tool: `pattern: "docs/**/*.md"`

2. **Check against expected structure:**
   - Expected files (created by workers):
     - docs/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 (conditional)
     - docs/project/database_schema.md (conditional)
     - docs/project/design_guidelines.md (conditional)
     - docs/project/runbook.md (conditional)
     - docs/reference/README.md
     - docs/reference/adrs/*.md (user-created)
     - docs/reference/guides/*.md (user-created)
     - docs/reference/manuals/*.md (user-created)
     - docs/tasks/README.md
     - docs/tasks/kanban_board.md
     - docs/testing-strategy.md
     - tests/README.md
   - Any file NOT in this list = orphaned

3. **Move orphaned files to archive:**
   - Create `.archive/YYYY-MM-DD/` directory (current date)
   - For each orphaned file:
     - Use Bash tool: `mv {file_path} .archive/YYYY-MM-DD/`
     - Log: "Archived {file_name} (not in expected structure)"
   - Track count

4. **Log results:**
   - "✓ Archived {count} orphaned files to .archive/{date}/"
   - List archived files

**4.3 Consolidate knowledge**

1. **Identify scattered information:**
   - Known patterns:
     - Linear config scattered: kanban_board.md + tasks/README.md
     - Development principles scattered: principles.md + architecture.md + CLAUDE.md
     - Testing info scattered: testing-strategy.md + tests/README.md + architecture.md

2. **For each scattered concept:**
   - Determine Single Source of Truth (SSoT):
     - Linear config → kanban_board.md
     - Development principles → principles.md
     - Testing strategy → testing-strategy.md

3. **Update non-SSoT files:**
   - Use Edit tool to replace duplicate content with link:
     ```markdown
     See [Linear Configuration](../tasks/kanban_board.md#linear-configuration) for team ID and settings.
     ```
   - Track consolidation count

4. **Log results:**
   - "✓ Consolidated {count} scattered concepts"
   - List: "{concept} consolidated to {SSoT_file}"

**4.4 Cross-link validation**

1. **Scan all .md files for internal links:**
   - For each file:
     - Read content
     - Extract all markdown links: `[text](path)`
     - Filter internal links (relative paths, not http://)

2. **Verify link targets exist:**
   - For each link:
     - Resolve relative path
     - Check if target file exists (Glob tool)
     - If missing: Mark as broken

3. **Fix broken links:**
   - For each broken link:
     - If target was archived: Update link to archive path
     - If target never existed: Remove link (convert to plain text)
   - Track fix count

4. **Add missing critical links:**
   - **CLAUDE.md → docs/README.md:**
     - Read CLAUDE.md
     - Check for link to docs/README.md
     - If missing: Add in "Documentation Hub" section
   - **docs/README.md → section READMEs:**
     - Check for links to project/, reference/, tasks/, tests/ READMEs
     - If missing: Add
   - Track added links count

5. **Log results:**
   - "✓ Fixed {count} broken links"
   - "✓ Added {count} missing critical links"
   - List changes

**4.5 Final report**

```
✅ Global Cleanup Complete:

Structure:
- Removed {N} duplicate sections (canonical: principles.md)
- Archived {N} orphaned files to .archive/YYYY-MM-DD/
  - list of archived files
- Consolidated {N} scattered concepts

Links:
- Fixed {N} broken links
- Added {N} missing critical links:
  - list of added links
```

**Output**: All documentation cleaned up, duplicates removed, orphaned files archived, knowledge consolidated, cross-links validated

---

### Phase 5: Summary and Next Steps

**Objective**: Provide complete overview of created system.

**Process**:
1. List all created files with sizes:
   - `CLAUDE.md` (project entry point)
   - `docs/README.md` (root documentation hub)
   - `docs/documentation_standards.md` (60 universal requirements)
   - `docs/principles.md` (11 development principles)
   - `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional documents (3-7 total)
   - `docs/reference/README.md` (reference hub with empty adrs/, guides/, manuals/ directories)
   - `docs/tasks/README.md` + optionally `kanban_board.md`
   - `docs/presentation/README.md` + `presentation_final.html`
   - `tests/README.md` (if created)

2. Show documentation system features:
   - ✅ SCOPE tags (document boundaries defined)
   - ✅ Maintenance sections (update triggers + verification)
   - ✅ README hub (central navigation)
   - ✅ DAG structure (Directed Acyclic Graph navigation)
   - ✅ Living documentation ready
   - ✅ Deduplicated content (canonical sources only)
   - ✅ Validated cross-links (no broken links)

3. Recommend next steps:
   - "Review generated documentation (CLAUDE.md → docs/)"
   - "Open docs/presentation/presentation_final.html in browser"
   - "Run ln-210-epic-coordinator to decompose scope into Epics"
   - "Share documentation with technical stakeholders"

**Output**: Summary message with file list and recommendations

---

## Complete Output Structure

```
project_root/
├── CLAUDE.md                         # ← Project entry point (link to docs/)
├── docs/
│   ├── README.md                     # ← Root documentation hub (general standards)
│   ├── documentation_standards.md    # ← 60 universal requirements (Claude Code + industry standards)
│   ├── principles.md                 # ← 11 development principles (Standards First, YAGNI, KISS, DRY, etc.)
│   ├── project/
│   │   ├── requirements.md           # ← Functional Requirements (NO NFR per project policy)
│   │   ├── architecture.md           # ← arc42-based architecture with C4 Model
│   │   ├── tech_stack.md             # ← Technology versions, Docker config
│   │   ├── api_spec.md               # ← API endpoints (conditional)
│   │   ├── database_schema.md        # ← Database schema (conditional)
│   │   ├── design_guidelines.md      # ← UI/UX system (conditional)
│   │   └── runbook.md                # ← Operations guide (conditional)
│   ├── reference/
│   │   ├── README.md                 # ← Reference documentation hub (registries)
│   │   ├── adrs/                     # ← Empty, ready for ADRs
│   │   ├── guides/                   # ← Empty, ready for guides
│   │   └── manuals/                  # ← Empty, ready for manuals
│   ├── tasks/
│   │   ├── README.md                 # ← Task management system rules
│   │   └── kanban_board.md           # ← Linear integration (optional)
│   └── presentation/
│       ├── README.md                 # ← Navigation hub for presentation
│       ├── presentation_final.html   # ← Final standalone HTML (~130-180 KB)
│       └── assets/                   # ← Modular HTML structure
└── tests/
    └── README.md                     # ← Test documentation (optional)
```

---

## Integration with Project Workflow

**Recommended workflow for new projects:**

1. **ln-110-documents-pipeline** (this skill) - Create complete documentation system
2. **ln-210-epic-coordinator** - Decompose scope into Epics (Linear Projects)
3. **ln-220-story-coordinator** - Create User Stories for each Epic (automatic decomposition + replan)
4. **ln-310-story-decomposer** - Break down Stories into implementation tasks (automatic decomposition + replan)
5. **ln-320-story-validator** - Verify Stories before development
6. **ln-330-story-executor** - Orchestrate Story implementation
7. **ln-340-story-quality-gate** - Review completed Stories

---

## Advantages of Orchestrator Approach

**Benefits:**
- ✅ Single command creates complete system
- ✅ No need to remember skill sequence
- ✅ Automated skill chaining
- ✅ Consistent output every time
- ✅ Time-saving (one invocation vs 2-3 manual invocations)
- ✅ **Idempotent**: Safe to run multiple times - preserves existing files, creates only missing ones
- ✅ **Pre-flight check**: Shows file scan summary before execution
- ✅ **Global cleanup**: Automatic deduplication, orphaned files archival, knowledge consolidation
- ✅ **Validated cross-links**: No broken links in documentation

**Trade-offs:**
- ⚠️ Less granular control (can't skip ln-111-docs-creator phases)
- ⚠️ Longer execution time (15-20 minutes)
- ⚠️ Global cleanup runs even if only one file was created

**When to use manual approach instead:**
- Need only HTML rebuild → use [ln-115-presentation-creator](../ln-115-presentation-creator/SKILL.md)
- Need one specific ADR → use [ln-322-adr-creator](../ln-322-adr-creator/SKILL.md)

---

## Error Handling

If any invoked skill fails:
1. Notify user which skill failed
2. Show error message from failed skill
3. Recommend manual invocation for debugging
4. List already completed steps (partial progress)

---

## Technical Implementation Notes

**Skill Invocation:**
- Uses **Skill tool** with command parameter
- Waits for each skill to complete before proceeding
- Verifies output files exist before moving to next phase

**File Verification:**
- Uses **Glob** tool to check docs/project/ structure
- Lists file sizes for user confirmation
- Warns if expected files missing

**Global Cleanup:**
- Uses **Glob** tool to find all .md files
- Uses **Read** tool to analyze content
- Uses **Edit** tool to remove duplicates and add links
- Uses **Bash** tool to archive orphaned files

**Standards Compliance:**
- All output follows same standards as underlying skills
- ISO/IEC/IEEE 29148:2018 (Requirements)
- ISO/IEC/IEEE 42010:2022 (Architecture)
- arc42 + C4 Model + Michael Nygard's ADR Format

---

## Definition of Done

Before completing work, verify ALL checkpoints:

**✅ User Confirmation (Phase 1):**
- [ ] Workflow explained to user (6 workers: ln-111 → ln-112 → ln-113 → ln-114 → ln-115 → ln-116)
- [ ] User approved: "Proceed with complete documentation system creation? (yes/no)"
- [ ] Test docs preference captured: "Include test documentation? (yes/no)"

**✅ Workers Invoked Sequentially (Phase 2):**
- [ ] ln-111-root-docs-creator invoked → Output verified: `CLAUDE.md` + `docs/README.md` + `docs/documentation_standards.md` + `docs/principles.md`
- [ ] ln-112-reference-docs-creator invoked → Output verified: `docs/reference/README.md` + directories (adrs/, guides/, manuals/)
- [ ] ln-113-tasks-docs-creator invoked → Output verified: `docs/tasks/README.md` + optionally `kanban_board.md`
- [ ] ln-114-project-docs-creator invoked → Output verified: `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional documents (3-7 files)
- [ ] ln-115-presentation-creator invoked → Output verified: `docs/presentation/README.md` + `presentation_final.html` + `assets/`
- [ ] ln-116-test-docs-creator invoked (if enabled) → Output verified: `tests/README.md`
- [ ] Each worker validated its own output (SCOPE tags, Maintenance sections, POSIX compliance)

**✅ File Verification Complete:**
- [ ] All expected files exist (Glob tool used to verify structure)
- [ ] File sizes listed for user confirmation
- [ ] Warning displayed if expected files missing

**✅ Global Cleanup Complete (Phase 4):**
- [ ] 4.1: Duplicate sections identified and removed (>80% similarity)
- [ ] 4.1: Links added to canonical locations (principles.md, testing-strategy.md, kanban_board.md)
- [ ] 4.2: Orphaned files archived to `.archive/YYYY-MM-DD/`
- [ ] 4.3: Scattered concepts consolidated to Single Source of Truth (SSoT)
- [ ] 4.4: Internal links validated (broken links fixed, critical links added)
- [ ] 4.5: Final report generated (counts, lists, actions)

**✅ Summary Displayed (Phase 5):**
- [ ] All created files listed with sizes
- [ ] Documentation system features highlighted (SCOPE tags, Maintenance sections, README hubs, DAG structure, deduplicated content, validated links)
- [ ] Next steps recommended (ln-210-epic-coordinator)

**✅ Error Handling (if applicable):**
- [ ] If any worker failed: User notified which worker failed, error message shown, manual invocation recommended, partial progress listed

**Output:** Complete documentation system (CLAUDE.md + docs/ with README.md, documentation_standards.md, principles.md + presentation/ + optionally tests/) with global cleanup (no duplicates, no orphaned files, consolidated knowledge, validated cross-links)

---

**Version:** 6.0.0 (MAJOR: Removed Phase 3 validation - delegated to workers Phase 2/3. Added Phase 4 Global Cleanup: deduplication, orphaned files, consolidation, cross-link validation. Orchestrator now coordinates workers (Phase 2) + global operations (Phase 4). All workers are idempotent.)
**Last Updated:** 2025-11-18