zhongwei/gh-levnikolaevich-claude-code-skills-full-development-workflow-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:37:27 +08:00
commit 37774aa937
131 changed files with 31137 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
skills/ln-112-reference-docs-creator/SKILL.md Normal file
View File

@@ -0,0 +1,325 @@
---
name: ln-112-reference-docs-creator
description: Creates reference documentation structure (docs/reference/ with README, adrs/, guides/, manuals/ directories). Second worker in ln-110-documents-pipeline.
---
# Reference Documentation Creator
This skill creates the reference documentation structure: docs/reference/README.md (hub with registries for ADRs/Guides/Manuals) and empty subdirectories for storing reference materials.
## When to Use This Skill
**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator.
This skill should be used directly when:
- Creating only reference documentation structure (docs/reference/)
- Setting up directories for ADRs, guides, and manuals
- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup)
## How It Works
The skill follows a 3-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Each phase builds on the previous, ensuring complete structure and semantic validation.
---
### Phase 1: Create Structure
**Objective**: Establish reference documentation directories and README hub.
**Process**:
**1.1 Check & create directories**:
- Check if `docs/reference/adrs/` exists → create if missing
- Check if `docs/reference/guides/` exists → create if missing
- Check if `docs/reference/manuals/` exists → create if missing
- Log for each: "✓ Created docs/reference/[name]/" or "✓ docs/reference/[name]/ already exists"
**1.2 Check & create README**:
- Check if `docs/reference/README.md` exists
- If exists:
- Skip creation
- Log: "✓ docs/reference/README.md already exists, proceeding to validation"
- If NOT exists:
- Copy template: `ln-112-reference-docs-creator/references/reference_readme_template.md` → `docs/reference/README.md`
- Replace placeholders:
- `{{VERSION}}` — "1.0.0"
- `{{DATE}}` — current date (YYYY-MM-DD)
- `{{ADR_LIST}}` — kept as placeholder (filled in Phase 3)
- `{{GUIDE_LIST}}` — kept as placeholder (filled in Phase 3)
- `{{MANUAL_LIST}}` — kept as placeholder (filled in Phase 3)
- Log: "✓ Created docs/reference/README.md from template"
**1.3 Output**:
```
docs/reference/
├── README.md # Created or existing
├── adrs/ # Empty, ready for ADRs
├── guides/ # Empty, ready for guides
└── manuals/ # Empty, ready for manuals
```
---
### Phase 2: Validate Structure
**Objective**: Ensure reference/README.md complies with structural requirements and auto-fix violations.
**Process**:
**2.1 Check SCOPE tag**:
- Read `docs/reference/README.md` (first 5 lines)
- Check for `<!-- SCOPE: ... -->` tag
- Expected: `<!-- SCOPE: Reference documentation hub (ADRs, Guides, Manuals) with links to subdirectories -->`
- If missing:
- Use Edit tool to add SCOPE tag at line 1 (after first heading)
- Track violation: `scope_tag_added = True`
**2.2 Check required sections**:
- Load expected sections from `references/questions.md`
- Required sections:
- "Architecture Decision Records (ADRs)"
- "Project Guides"
- "Package Manuals"
- For each section:
- Check if `## [Section Name]` header exists
- If missing:
- Use Edit tool to add section with placeholder:
```markdown
## [Section Name]
{{PLACEHOLDER}}
```
- Track violation: `missing_sections += 1`
**2.3 Check Maintenance section**:
- Search for `## Maintenance` header
- If missing:
- Use Edit tool to add at end of file:
```markdown
## Maintenance
**Last Updated:** [current date]
**Update Triggers:**
- New ADRs added to adrs/ directory
- New guides added to guides/ directory
- New manuals added to manuals/ directory
**Verification:**
- [ ] All ADR links in registry are valid
- [ ] All guide links in registry are valid
- [ ] All manual links in registry are valid
- [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files
```
- Track violation: `maintenance_added = True`
**2.4 Check POSIX file endings**:
- Check if file ends with single blank line
- If missing:
- Use Edit tool to add final newline
- Track fix: `posix_fixed = True`
**2.5 Report validation**:
- Log summary:
```
✅ Structure validation complete:
- SCOPE tag: [added/present]
- Missing sections: [count] sections added
- Maintenance section: [added/present]
- POSIX endings: [fixed/compliant]
```
- If violations found: "⚠️ Auto-fixed [total] structural violations"
---
### Phase 3: Validate Content
**Objective**: Ensure each section answers its questions with meaningful content and populate registries from auto-discovery.
**Process**:
**3.1 Load validation spec**:
- Read `references/questions.md`
- Parse questions and validation heuristics for all 3 sections
**3.2 Validate sections (parametric loop)**:
Define section parameters:
```
sections = [
{
"name": "Architecture Decision Records (ADRs)",
"question": "Where are architecture decisions documented?",
"directory": "docs/reference/adrs/",
"placeholder": "{{ADR_LIST}}",
"glob_pattern": "docs/reference/adrs/*.md",
"heuristics": [
"Contains link: [ADRs](adrs/) or [adrs](adrs/)",
"Mentions 'Architecture Decision Record' or 'ADR'",
"Has placeholder {{ADR_LIST}} or actual list",
"Length > 30 words"
]
},
{
"name": "Project Guides",
"question": "Where are reusable project patterns documented?",
"directory": "docs/reference/guides/",
"placeholder": "{{GUIDE_LIST}}",
"glob_pattern": "docs/reference/guides/*.md",
"heuristics": [
"Contains link: [Guides](guides/) or [guides](guides/)",
"Has placeholder {{GUIDE_LIST}} or actual list",
"Length > 20 words"
]
},
{
"name": "Package Manuals",
"question": "Where are third-party package references documented?",
"directory": "docs/reference/manuals/",
"placeholder": "{{MANUAL_LIST}}",
"glob_pattern": "docs/reference/manuals/*.md",
"heuristics": [
"Contains link: [Manuals](manuals/) or [manuals](manuals/)",
"Has placeholder {{MANUAL_LIST}} or actual list",
"Length > 20 words"
]
}
]
```
For each section in sections:
1. **Read section content**:
- Extract section from reference/README.md
2. **Check if content answers question**:
- Apply validation heuristics
- If ANY heuristic passes → content valid, skip to next section
- If ALL fail → content invalid, continue
3. **Auto-discovery** (if content invalid or placeholder present):
- Scan directory using Glob tool (section.glob_pattern)
- If files found:
- Extract filenames
- Generate dynamic list:
```markdown
- [ADR-001: Frontend Framework](adrs/adr-001-frontend-framework.md)
- [02-Repository Pattern](guides/02-repository-pattern.md)
- [Axios 1.6](manuals/axios-1.6.md)
```
- Use Edit tool to replace placeholder with generated list
- Track change: `sections_populated += 1`
- If NO files:
- Keep placeholder as-is
- Track: `placeholders_kept += 1`
4. **Skip external API calls**:
- Do NOT use MCP Ref search (template already has format examples)
**3.3 Report content validation**:
- Log summary:
```
✅ Content validation complete:
- Sections checked: 3
- Populated from auto-discovery: [count]
- Placeholders kept (no files): [count]
- Already valid: [count]
```
---
## Complete Output Structure
```
docs/
└── reference/
├── README.md # Reference hub with registries
├── adrs/ # Empty or with ADR files
├── guides/ # Empty or with guide files
└── manuals/ # Empty or with manual files
```
---
## Reference Files Used
### Templates
**Reference README Template**:
- `references/reference_readme_template.md` (v2.0.0) - Reference hub with:
- SCOPE tags (reference documentation ONLY)
- Three registry sections with placeholders
- Maintenance section
**Validation Specification**:
- `references/questions.md` (v1.0) - Question-driven validation:
- Questions each section must answer
- Validation heuristics
- Auto-discovery hints
---
## Best Practices
- **No premature validation**: Phase 1 creates structure, Phase 2 validates it (no duplicate checks)
- **Parametric validation**: Phase 3 uses loop for 3 sections (no code duplication)
- **Auto-discovery first**: Scan actual files before external API calls
- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation)
- **Separation of concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT
---
## Prerequisites
**Invoked by**: ln-110-documents-pipeline orchestrator
**Requires**:
- `docs/` directory (created by ln-111-root-docs-creator)
**Creates**:
- `docs/reference/` directory structure with README hub
- Validated structure and content (auto-discovery from existing files)
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Structure Created:**
- [ ] `docs/reference/` directory exists
- [ ] `docs/reference/adrs/` directory exists
- [ ] `docs/reference/guides/` directory exists
- [ ] `docs/reference/manuals/` directory exists
- [ ] `docs/reference/README.md` exists (created or existing)
**✅ Structure Validated:**
- [ ] SCOPE tag present in first 5 lines
- [ ] Three registry sections present (ADRs, Guides, Manuals)
- [ ] Maintenance section present at end
- [ ] POSIX file endings compliant
**✅ Content Validated:**
- [ ] All sections checked against questions.md
- [ ] Placeholders populated from auto-discovery OR kept if no files
- [ ] No validation heuristic failures
**✅ Reporting:**
- [ ] Phase 1 logged: creation summary
- [ ] Phase 2 logged: structural fixes (if any)
- [ ] Phase 3 logged: content updates (if any)
---
## Technical Details
**Standards**:
- Michael Nygard's ADR Format (7 sections)
- ISO/IEC/IEEE 29148:2018 (Documentation standards)
**Language**: English only
---
**Version:** 7.1.0 (MINOR: Workflow optimization - merged Phase 1+2 CREATE, removed redundant Phase 2 Step 3 verification, removed Phase 3.4 project-specific standards check, parametrized Phase 4 content validation. No functionality change, pure refactoring for clarity and efficiency.)
**Last Updated:** 2025-11-18

98
skills/ln-112-reference-docs-creator/diagram.html Normal file
View File

@@ -0,0 +1,98 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-112-reference-docs-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>📚 ln-112-reference-docs-creator</h1>
<p class="subtitle">Reference Documentation Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create reference documentation structure (adrs/, guides/, manuals/) + README hub</li>
<li><strong>Worker for:</strong> ln-110-documents-pipeline orchestrator</li>
<li><strong>Phases:</strong> 4 phases (Phase 1+2 CREATE merged → Phase 3 Structure Validation → Phase 4 Content Validation)</li>
<li><strong>Optimization:</strong> Merged Phase 1+2 CREATE, removed redundant verifications, parametrized validation</li>
<li><strong>Output:</strong> Empty structure with registries ready for content creation</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Creation Action</span>
</div>
<div class="legend-item">
<div class="legend-color color-validation"></div>
<span>Validation</span>
</div>
<div class="legend-item">
<div class="legend-color color-success"></div>
<span>Success State</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Reference Docs Creation]) --> Phase1[Phase 1+2: Create Structure merged<br/>Create dirs + README + ADR template]
Phase1 --> CreateAll[Create subdirectories adrs/, guides/, manuals/<br/>+ README.md + _template.md]
CreateAll --> ReplaceVars[Replace placeholders:<br/>DATE, registries]
ReplaceVars --> Phase3[Phase 3: Structure Validation<br/>Verify dirs, SCOPE tags, registries]
Phase3 --> Phase4[Phase 4: Content Validation<br/>Parametric validation with questions.md]
Phase4 --> Notify[Notify: Reference structure<br/>created + validated]
Notify --> End([End: ✓ Reference structure ready])
%% Styling
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef success fill:#B3E5FC,stroke:#0277BD,stroke-width:2px
class Phase1,CreateAll,ReplaceVars action
class Phase3,Phase4 validation
class Notify action
class End success
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>Second Worker:</strong> Creates reference documentation structure after root docs</li>
<li><strong>Structure Only:</strong> Creates directories and registries, NOT content</li>
<li><strong>ADR Template:</strong> Copies Michael Nygard's 7-section ADR template</li>
<li><strong>Validation:</strong> Parametric content validation (Phase 4) with project-specific standards removal</li>
</ul>
</div>
<footer>
<p>Generated for ln-112-reference-docs-creator skill | Version 7.1.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

119
skills/ln-112-reference-docs-creator/references/questions.md Normal file
View File

@@ -0,0 +1,119 @@
# Reference Documentation Questions
**Purpose:** Define what each section of reference documentation should answer.
**Format:** Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints
---
## Table of Contents
| Document | Questions | Auto-Discovery | Priority | Line |
|----------|-----------|----------------|----------|------|
| [docs/reference/README.md](#docsreferencereadmemd) | 3 | High | High | L23 |
**Priority Legend:**
- **Critical:** Must answer all questions
- **High:** Strongly recommended
- **Medium:** Optional (can use template defaults)
**Auto-Discovery Legend:**
- **None:** No auto-discovery needed (use template as-is)
- **Low:** 1-2 questions need auto-discovery
- **High:** All questions need auto-discovery
---
<!-- DOCUMENT_START: docs/reference/README.md -->
## docs/reference/README.md
**File:** docs/reference/README.md (reference documentation hub)
**Target Sections:** Architecture Decision Records (ADRs), Project Guides, Package Manuals
**Rules for this document:**
- Hub file for reference documentation subdirectories
- Must link to adrs/, guides/, manuals/ directories
- Auto-discovery of existing files in each directory
---
<!-- QUESTION_START: 1 -->
### Question 1: Where are architecture decisions documented?
**Expected Answer:** Link to adrs/ directory, ADR format description (Nygard template), list of existing ADRs or placeholder
**Target Section:** ## Architecture Decision Records (ADRs)
**Validation Heuristics:**
- ✅ Contains link: `[ADRs](adrs/)` or `[adrs](adrs/)`
- ✅ Mentions "Architecture Decision Record" or "ADR"
- ✅ Has placeholder `{{ADR_LIST}}` or actual ADR list
- ✅ Length > 30 words
**Auto-Discovery:**
- Scan `docs/reference/adrs/` for *.md files
- Generate list dynamically from filenames
- Example: `adr-001-frontend-framework.md` → "ADR-001: Use React+Next.js"
**MCP Ref Hints:**
- Research: "Michael Nygard ADR format" (if no ADRs exist and need to explain format)
- Extract: ADR template structure (Context, Decision, Status, Consequences)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: Where are reusable project patterns documented?
**Expected Answer:** Link to guides/ directory, description of guide purpose (reusable patterns, how-tos), list of existing guides or placeholder
**Target Section:** ## Project Guides
**Validation Heuristics:**
- ✅ Contains link: `[Guides](guides/)` or `[guides](guides/)`
- ✅ Mentions "patterns" or "guides" or "how-to"
- ✅ Has placeholder `{{GUIDE_LIST}}` or actual guide list
- ✅ Length > 20 words
**Auto-Discovery:**
- Scan `docs/reference/guides/` for *.md files
- Generate list dynamically from filenames
- Example: `authentication-flow.md` → "Authentication Flow Guide"
**MCP Ref Hints:**
- N/A (guides are project-specific)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: Where are third-party package references documented?
**Expected Answer:** Link to manuals/ directory, description of manual purpose (package API references, version-specific), list of existing manuals or placeholder
**Target Section:** ## Package Manuals
**Validation Heuristics:**
- ✅ Contains link: `[Manuals](manuals/)` or `[manuals](manuals/)`
- ✅ Mentions "packages" or "API reference" or "manuals"
- ✅ Has placeholder `{{MANUAL_LIST}}` or actual manual list
- ✅ Length > 20 words
**Auto-Discovery:**
- Scan `docs/reference/manuals/` for *.md files
- Generate list dynamically from filenames
- Example: `axios-1.6.md` → "Axios 1.6 API Manual"
**MCP Ref Hints:**
- N/A (manuals are package-specific, created by ln-323-manual-creator)
<!-- QUESTION_END: 3 -->
---
**Overall File Validation:**
- ✅ Has links to all 3 subdirectories (adrs/, guides/, manuals/)
- ✅ Total length > 60 words
<!-- DOCUMENT_END: docs/reference/README.md -->
---
**Version:** 2.0.0 (MAJOR: Added Table of Contents and programmatic markers for context management)
**Last Updated:** 2025-11-18

63
skills/ln-112-reference-docs-creator/references/reference_readme_template.md Normal file
View File

@@ -0,0 +1,63 @@
# Reference Documentation
**Version:** {{VERSION}}
**Last Updated:** {{DATE}}
<!-- SCOPE: Reference documentation hub (ADRs, Guides, Manuals) with links to subdirectories -->
<!-- DO NOT add here: ADR/Guide/Manual content → specific files, Project details → project/README.md -->
---
## Overview
This directory contains reusable knowledge base and architecture decisions:
- **Architecture Decision Records (ADRs)** - Key technical decisions
- **Project Guides** - Reusable patterns and best practices
- **Package Manuals** - API reference for external libraries
---
## Architecture Decision Records (ADRs)
<!-- Example: [ADR-001: Use React+Next.js](adrs/adr-001-frontend-framework.md) | Accepted | 2024-10-15 -->
{{ADR_LIST}}
---
## Project Guides
<!-- Example: [01-Repository Pattern](guides/01-repository-pattern.md) | 2024-11-10 -->
{{GUIDE_LIST}}
---
## Package Manuals
<!-- Example: [Axios 1.6](manuals/axios-1.6.md) | 2024-10-20 -->
{{MANUAL_LIST}}
---
## Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- New ADRs added to adrs/ directory
- New guides added to guides/ directory
- New manuals added to manuals/ directory
**Verification:**
- [ ] All ADR links in registry are valid
- [ ] All guide links in registry are valid
- [ ] All manual links in registry are valid
- [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files
---
**Template Version:** 2.0.0
**Template Last Updated:** {{DATE}}