476 lines
21 KiB
Markdown
476 lines
21 KiB
Markdown
---
|
|
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
|