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

444
skills/ln-111-root-docs-creator/SKILL.md Normal file
View File

@@ -0,0 +1,444 @@
---
name: ln-111-root-docs-creator
description: Creates root documentation (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md). First worker in ln-110-documents-pipeline. Establishes documentation structure and standards.
---
# Root Documentation Creator
This skill creates the root documentation entry points for a project: CLAUDE.md (project root), docs/README.md (documentation hub with general standards), docs/documentation_standards.md (60 universal documentation requirements), and docs/principles.md (11 development principles).
## 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 root documentation files (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md)
- Setting up documentation structure for existing project
- 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**: Create all 4 root documentation files.
**Process**:
**1.1 Create CLAUDE.md**:
- Check if CLAUDE.md exists in project root
- If exists:
- Read first 50 lines
- Check for link to `docs/README.md`
- If missing:
- Use Edit tool to add Documentation section:
```markdown
## Documentation
Project documentation: [docs/README.md](docs/README.md)
```
- Log: "✓ Added docs link to existing CLAUDE.md"
- If present:
- Log: "✓ CLAUDE.md already has docs link"
- If NOT exists:
- Ask user: "Project name?"
- Ask user: "Brief project description (1-2 sentences)?"
- Copy template: `references/claude_md_template.md` → `CLAUDE.md`
- Replace placeholders:
- `{{PROJECT_NAME}}` — user input
- `{{PROJECT_DESCRIPTION}}` — user input
- `{{DATE}}` — current date (YYYY-MM-DD)
- Log: "✓ Created CLAUDE.md"
**1.2 Create docs/README.md**:
- Check if docs/README.md exists
- If exists:
- Skip creation
- Log: "✓ docs/README.md already exists"
- If NOT exists:
- Create docs/ directory if missing
- Copy template: `references/docs_root_readme_template.md` → `docs/README.md`
- Ask user: "Documentation status? (Draft/Active)"
- Replace placeholders:
- `{{VERSION}}` — "1.0.0"
- `{{DATE}}` — current date (YYYY-MM-DD)
- `{{STATUS}}` — user input
- Log: "✓ Created docs/README.md"
**1.3 Create docs/documentation_standards.md**:
- Check if docs/documentation_standards.md exists
- If exists:
- Skip creation
- Log: "✓ docs/documentation_standards.md already exists"
- If NOT exists:
- Copy template: `references/documentation_standards_template.md` → `docs/documentation_standards.md`
- Replace placeholders:
- `{{DATE}}` — current date (YYYY-MM-DD)
- `{{PROJECT_NAME}}` — from 1.1 (if collected)
- Log: "✓ Created docs/documentation_standards.md"
**1.4 Create docs/principles.md**:
- Check if docs/principles.md exists
- If exists:
- Skip creation
- Log: "✓ docs/principles.md already exists"
- If NOT exists:
- Copy template: `references/principles_template.md` → `docs/principles.md`
- Replace placeholders:
- `{{DATE}}` — current date (YYYY-MM-DD)
- Log: "✓ Created docs/principles.md"
**1.5 Output**:
```
CLAUDE.md # Created or updated with docs link
docs/
├── README.md # Created or existing
├── documentation_standards.md # Created or existing
└── principles.md # Created or existing
```
---
### Phase 2: Validate Structure
**Objective**: Ensure all 4 files comply with structural requirements and auto-fix violations.
**Process**:
**2.1 Check SCOPE tags**:
- Read first 10 lines of CLAUDE.md
- Check for `> **SCOPE:**` or `<!-- SCOPE: ... -->` tag
- If missing:
- Use Edit tool to add SCOPE tag after first heading:
```markdown
> **SCOPE:** Entry point with project overview and navigation ONLY.
```
- Track violation: `scope_tag_added_claude = True`
- Read first 10 lines of docs/README.md
- Check for `<!-- SCOPE: ... -->` tag
- If missing:
- Use Edit tool to add SCOPE tag after version info:
```markdown
<!-- SCOPE: Root documentation hub with general standards and navigation ONLY. -->
```
- Track violation: `scope_tag_added_docs_readme = True`
- Read first 10 lines of docs/principles.md
- Check for `> **SCOPE:**` or `<!-- SCOPE: ... -->` tag
- If missing:
- Use Edit tool to add SCOPE tag
- Track violation: `scope_tag_added_principles = True`
**2.2 Check required sections (parametric loop)**:
Define file parameters:
```
files = [
{
"path": "CLAUDE.md",
"sections": ["Documentation", "Documentation Maintenance Rules", "Maintenance"]
},
{
"path": "docs/README.md",
"sections": ["General Documentation Standards", "Writing Guidelines", "Maintenance"]
},
{
"path": "docs/documentation_standards.md",
"sections": ["Quick Reference", "Maintenance"]
},
{
"path": "docs/principles.md",
"sections": ["Decision-Making Framework", "Verification Checklist", "Maintenance"]
}
]
```
For each file in files:
1. Read file content
2. For each required 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[file] += 1`
**2.3 Check Maintenance sections**:
- For each file in [CLAUDE.md, docs/README.md, docs/documentation_standards.md, docs/principles.md]:
- Search for `## Maintenance` header
- If missing:
- Use Edit tool to add at end of file:
```markdown
## Maintenance
**Update Triggers:**
- [To be defined]
**Verification:**
- [ ] All links resolve to existing files
- [ ] All placeholders replaced with content
**Last Updated:** [current date]
```
- Track violation: `maintenance_added[file] = True`
**2.4 Check POSIX file endings**:
- For each file:
- Check if file ends with single blank line
- If missing:
- Use Edit tool to add final newline
- Track fix: `posix_fixed[file] = True`
**2.5 Report validation**:
- Log summary:
```
✅ Structure validation complete:
- SCOPE tags: [count] files fixed
- Missing sections: [count] sections added across [count] files
- Maintenance sections: [count] files fixed
- POSIX endings: [count] files fixed
```
- If violations found: "⚠️ Auto-fixed [total] structural violations"
---
### Phase 3: Validate Content
**Objective**: Ensure each file answers its questions with meaningful content.
**Process**:
**3.1 Load validation spec**:
- Read `references/questions.md`
- Parse questions and validation heuristics for all 4 files
**3.2 Validate files (parametric loop)**:
Define file parameters:
```
files = [
{
"path": "CLAUDE.md",
"question": "Where is project documentation located and how to navigate it?",
"heuristics": [
"Contains link: [docs/README.md](docs/README.md)",
"Has SCOPE tag in first 10 lines",
"Contains 'Documentation Navigation Rules' section",
"Length > 80 words"
],
"auto_discovery": ["Check package.json for name/description"]
},
{
"path": "docs/README.md",
"question": "What is the documentation structure and what are general standards?",
"heuristics": [
"Contains SCOPE tag",
"Has 'General Documentation Standards' section",
"Has 'Writing Guidelines' section",
"Mentions SCOPE Tags, Maintenance Sections, Sequential Numbering",
"Length > 100 words"
],
"auto_discovery": ["Scan docs/ structure for subdirectories"]
},
{
"path": "docs/documentation_standards.md",
"question": "What are the comprehensive documentation requirements?",
"heuristics": [
"Contains 'Quick Reference' section with table",
"Has 12+ main sections (##)",
"File size > 300 lines",
"Mentions ISO/IEC/IEEE, DIATAXIS, arc42"
],
"auto_discovery": []
},
{
"path": "docs/principles.md",
"question": "What are the development principles and decision framework?",
"heuristics": [
"Contains SCOPE tag",
"Lists 11 principles",
"Has 'Decision-Making Framework' section",
"Has 'Verification Checklist' section",
"File size > 300 lines"
],
"auto_discovery": []
}
]
```
For each file in files:
1. **Read file content**:
- Extract full file content
2. **Check if content answers question**:
- Apply validation heuristics
- If ANY heuristic passes → content valid, skip to next file
- If ALL fail → content invalid, continue
3. **Auto-discovery** (if content invalid or placeholder present):
- **CLAUDE.md**:
- Check package.json for "name" and "description"
- If found, suggest to user: "Would you like to use '{name}' and '{description}' from package.json?"
- **docs/README.md**:
- Scan docs/ directory for subdirectories (project/, reference/, tasks/)
- Generate navigation links dynamically
- **docs/documentation_standards.md**, **docs/principles.md**:
- Use template as-is (universal standards)
- No auto-discovery needed
4. **Skip external API calls**:
- Templates already complete with universal standards
- No MCP Ref needed
**3.3 Report content validation**:
- Log summary:
```
✅ Content validation complete:
- Files checked: 4
- Already valid: [count]
- Auto-discovery applied: [count]
- Template content used: [count]
```
---
## Complete Output Structure
```
project_root/
├── CLAUDE.md # ← Project entry point with link to docs/
└── docs/
├── README.md # ← Root documentation hub (general standards)
├── documentation_standards.md # ← Documentation requirements (60 universal requirements)
└── principles.md # ← Development principles (11 principles + Decision Framework + Verification Checklist)
```
**Note**: Other documentation (project/, reference/, tasks/, presentation/) created by other workers in ln-110-documents-pipeline workflow.
---
## Reference Files Used
### Templates
**CLAUDE.md Template**:
- `references/claude_md_template.md` - Minimal CLAUDE.md with documentation link
**Root README Template**:
- `references/docs_root_readme_template.md` (v1.1.0) - Root documentation hub with:
- Overview (documentation system organization)
- General Documentation Standards (SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions)
- Writing Guidelines (Progressive Disclosure Pattern)
- Maintenance section (Update Triggers, Verification, Last Updated)
**Documentation Standards Template**:
- `references/documentation_standards_template.md` (v1.0.0) - Documentation requirements with:
- Quick Reference (60 universal requirements in 12 categories)
- Claude Code Integration (#26-30)
- AI-Friendly Writing Style (#31-36)
- Markdown Best Practices (#37-42)
- Code Examples Quality (#43-47)
- DIATAXIS Framework (#48-52)
- Project Files (#53-58)
- Visual Documentation (#67-71)
- Conventional Commits & Changelog (#72-75)
- Security & Compliance (#76-79)
- Performance & Optimization (#80-82)
- Project-Specific Customization Guide
- References (industry sources)
- Maintenance section
**Development Principles Template**:
- `references/principles_template.md` (v1.0.0) - Development principles with:
- 11 Core Principles (Standards First, YAGNI, KISS, DRY, Consumer-First Design, Task Granularity, Value-Based Testing, No Legacy Code, Token Efficiency, Documentation-as-Code, Security by Design)
- Decision-Making Framework (7 steps: Security → Standards → Correctness → Simplicity → Necessity → Maintainability → Performance)
- Trade-offs (when principles conflict)
- Anti-Patterns to Avoid
- Verification Checklist (11 items)
- Maintenance section
**Validation Specification**:
- `references/questions.md` (v1.0) - Question-driven validation:
- Questions each file 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**: Phases 2-3 use loops for 4 files (no code duplication)
- **Auto-discovery first**: Check package.json and docs/ structure before asking user
- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation)
- **Separation of concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT
- **CLAUDE.md**: Keep minimal - only project name, description, and docs link
- **docs/README.md**: General standards only - NO project-specific content
- **SCOPE Tags**: Include in first 3-10 lines of all documentation files
---
## Prerequisites
**Invoked by**: ln-110-documents-pipeline orchestrator
**Requires**: None (first worker in chain)
**Creates**:
- CLAUDE.md (project entry point)
- docs/README.md (documentation hub)
- docs/documentation_standards.md (60 requirements)
- docs/principles.md (11 principles + Decision Framework)
- Validated structure and content
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Structure Created:**
- [ ] CLAUDE.md exists in project root
- [ ] docs/ directory exists
- [ ] docs/README.md exists
- [ ] docs/documentation_standards.md exists
- [ ] docs/principles.md exists
**✅ Structure Validated:**
- [ ] SCOPE tags present in CLAUDE.md, docs/README.md, docs/principles.md
- [ ] Required sections present in all 4 files
- [ ] Maintenance sections present in all 4 files
- [ ] POSIX file endings compliant
**✅ Content Validated:**
- [ ] All files checked against questions.md
- [ ] CLAUDE.md has docs link
- [ ] docs/README.md has General Standards + Writing Guidelines
- [ ] docs/documentation_standards.md has Quick Reference + 12 sections
- [ ] docs/principles.md has 11 principles + Decision Framework + Verification Checklist
**✅ Reporting:**
- [ ] Phase 1 logged: creation summary
- [ ] Phase 2 logged: structural fixes (if any)
- [ ] Phase 3 logged: content validation (if any)
---
## Technical Details
**Standards**:
- ISO/IEC/IEEE 29148:2018 (Documentation standards)
- Progressive Disclosure Pattern (token efficiency)
**Language**: English only
---
**Version:** 10.0.0 (MAJOR: Applied ln-112 pattern - 4 phases → 3 phases, added questions.md for semantic validation, parametric validation loop, removed workflow coupling. No functionality change, pure architectural refactoring for consistency with ln-112 PoC.)
**Last Updated:** 2025-11-18

109
skills/ln-111-root-docs-creator/diagram.html Normal file
View File

@@ -0,0 +1,109 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-111-root-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-111-root-docs-creator</h1>
<p class="subtitle">Root Documentation Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create root documentation entry points (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md)</li>
<li><strong>Worker for:</strong> ln-110-documents-pipeline orchestrator</li>
<li><strong>Phases:</strong> 3 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Semantic Content Validation)</li>
<li><strong>Validation:</strong> Phase 2/3 validation with questions.md (22 questions for 4 documents)</li>
<li><strong>Idempotent:</strong> Can be run multiple times safely</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-decision"></div>
<span>Conditional Check</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: Root Docs Creation]) --> Phase1{CLAUDE.md exists?}
Phase1 -->|Yes| CheckLink{Has docs/README.md<br/>link?}
Phase1 -->|No| AskProject[Ask: Project name<br/>and description]
CheckLink -->|Yes| Phase2Start[Phase 2: Create docs/README.md]
CheckLink -->|No| AddLink[Add docs link<br/>to CLAUDE.md]
AskProject --> CreateClaude[Create CLAUDE.md<br/>from template]
CreateClaude --> CreateStandards[Create documentation_standards.md<br/>60 universal requirements]
CreateStandards --> CreatePrinciples[Create principles.md<br/>11 development principles]
CreatePrinciples --> Phase2Start
AddLink --> Phase2Start
Phase2Start --> CreateDir[Create docs/<br/>directory]
CreateDir --> CreateReadme[Create docs/README.md<br/>from template]
CreateReadme --> ReplaceVars[Replace placeholders:<br/>VERSION, DATE, STATUS]
ReplaceVars --> Phase2Validate[Phase 2: Structure Validation<br/>SCOPE tags, Maintenance sections]
Phase2Validate --> Phase3Validate[Phase 3: Semantic Content Validation<br/>questions.md Q1-Q22]
Phase3Validate --> Notify[Notify: Root structure<br/>established + validated]
Notify --> End([End: ✓ 4 docs created + validated])
%% Styling
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
classDef success fill:#B3E5FC,stroke:#0277BD,stroke-width:2px
class AskProject,CreateClaude,CreateStandards,CreatePrinciples,AddLink,CreateDir,CreateReadme,ReplaceVars,Phase2Validate,Phase3Validate,Notify action
class Phase1,CheckLink decision
class End success
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>First Worker:</strong> Establishes documentation structure and standards</li>
<li><strong>Idempotent:</strong> Skips if CLAUDE.md already has docs link</li>
<li><strong>Template-Based:</strong> Uses claude_md_template.md, docs_root_readme_template.md, documentation_standards_template.md, principles_template.md</li>
<li><strong>General Standards:</strong> docs/README.md contains SCOPE Tags, Maintenance Sections, Writing Guidelines</li>
<li><strong>Semantic Validation:</strong> Parametric validation loop with questions.md (Q1-Q22)</li>
</ul>
</div>
<footer>
<p>Generated for ln-111-root-docs-creator skill | Version 10.0.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>

128
skills/ln-111-root-docs-creator/references/claude_md_template.md Normal file
View File

@@ -0,0 +1,128 @@
# {{PROJECT_NAME}}
{{PROJECT_DESCRIPTION}}
> **SCOPE:** Entry point with project overview and navigation ONLY. Contains project summary, documentation rules, and links to detailed docs. DO NOT add: business logic (→ Architecture.md + ADRs), principles (→ principles.md), API specs (→ api_spec.md), patterns (→ guides/).
## ⚠️ Critical Rules for AI Agents
**Read this table BEFORE starting any work.**
| Category | Rule | When to Apply | Rationale |
|----------|------|---------------|-----------|
| **Standards Hierarchy** | Industry Standards → Security → Principles | All work | ISO/IEC/IEEE, RFC, OWASP override YAGNI/KISS |
| **Documentation** | Read README before folder work | Before creating/editing files | Understand structure and conventions |
| **Documentation Navigation** | Read SCOPE tag first in each document | Before reading any doc | DAG structure - understand boundaries |
| **Testing** | Read tests/README.md before tests | Before test work | Story-Level Test Task Pattern |
| **Research** | Search MCP Ref before proposing changes | Before code changes | Official docs prevent reinventing wheel |
| **Task Management** | Linear MCP only, NO gh command | All task operations | See docs/tasks/README.md |
| **Skills** | Use built-in skills proactively | Documentation/Planning/Execution | Skills automate workflows |
| **Language** | English for all content, Russian for chat | All project content | Code/docs/tasks/commits in English only |
**Key Principles:**
- **Standards First**: Industry standards (ISO, RFC, OWASP, WCAG 2.1 AA) override development principles
- **Token Efficiency**: Progressive Disclosure Pattern (tables > paragraphs), no duplication
- **Quality**: Risk-Based Testing (2-5 E2E, 3-8 Integration, 5-15 Unit per Story)
- **No Legacy Code**: Remove backward compatibility shims immediately
---
## Documentation Navigation Rules
**Graph Structure:** All documentation organized as Directed Acyclic Graph (DAG) with CLAUDE.md as entry point.
**Reading Order:**
1. **Read SCOPE first** - Every document starts with `> **SCOPE:**` tag defining its boundaries
2. **Follow links down** - Navigate from parent to child documents through links
3. **Respect boundaries** - SCOPE tells you what IS and what IS NOT in each document
**Example Navigation:**
```
CLAUDE.md (SCOPE: Entry point, project overview)
→ Read SCOPE: "Contains project summary, NOT implementation details"
→ Need principles? Follow link → docs/principles.md
→ Read SCOPE: "Contains development principles, NOT architecture"
→ Need architecture? Follow link → docs/Architecture.md
```
---
## Documentation
Project documentation: [docs/README.md](docs/README.md)
Documentation standards: [docs/documentation_standards.md](docs/documentation_standards.md)
Development principles: [docs/principles.md](docs/principles.md)
## Development Commands
| Task | Windows | Bash |
|------|---------|------|
| **Install Dependencies** | `[Add your command]` | `[Add your command]` |
| **Run Tests** | `[Add your command]` | `[Add your command]` |
| **Start Dev Server** | `[Add your command]` | `[Add your command]` |
| **Build** | `[Add your command]` | `[Add your command]` |
| **Lint/Format** | `[Add your command]` | `[Add your command]` |
> [!NOTE]
> Update this table with project-specific commands during project setup
---
## Documentation Maintenance Rules
### For AI Agents (Claude Code)
**Principles:**
1. **Single Source of Truth:** Each fact exists in ONE place only - link, don't duplicate
2. **Graph Structure:** All docs reachable from `CLAUDE.md` → `docs/README.md` (DAG, no cycles)
3. **SCOPE Tag Required:** Every document MUST start with `> **SCOPE:**` tag defining boundaries (what IS and what IS NOT in document)
4. **DRY (Don't Repeat Yourself):** Reference existing docs instead of copying content
5. **Update Immediately:** When code changes, update related docs while context is fresh
6. **Context-Optimized:** Keep `CLAUDE.md` concise (≤100 lines recommended) - detailed info in `docs/`
7. **English Only:** ALL project content (code, comments, documentation, tasks, commit messages, variable names) MUST be in English
For document responsibilities and scope, see [docs/README.md](docs/README.md).
**Avoiding Duplication:**
**BAD:**
- Same architecture description in 3 files
- Development commands duplicated in multiple docs
- Full specs repeated across multiple guides
**GOOD:**
- `CLAUDE.md`: "See [docs/project/architecture.md](docs/project/architecture.md) for component structure (C4 diagrams)"
- Guides reference each other: "See [guide_name.md](./guide_name.md)"
- One canonical source per concept with links from other docs
**Best Practices (Claude Code 2025):**
- Use subagents for complex doc updates to avoid context pollution
- Update docs immediately after feature completion (context is fresh)
- Use `/clear` after big doc refactors to start fresh
- Keep `CLAUDE.md` as the always-loaded entry point with links to detailed docs
---
## Maintenance
**Update Triggers:**
- When changing project navigation (new/renamed docs)
- When updating critical rules for agents
- When modifying development commands
- When adding/removing key principles
- When documentation structure changes
**Verification:**
- [ ] All links resolve to existing files
- [ ] SCOPE tag clearly defines document boundaries
- [ ] Critical rules align with project requirements
- [ ] Command examples match actual project setup
- [ ] No duplicated content across documents
- [ ] Documentation Standards link correct
---
**Last Updated:** {{DATE}}

224
skills/ln-111-root-docs-creator/references/docs_root_readme_template.md Normal file
View File

@@ -0,0 +1,224 @@
# Documentation System
**Version:** {{VERSION}}
**Last Updated:** {{DATE}}
**Status:** {{STATUS}}
<!-- SCOPE: Root documentation hub with general standards and navigation ONLY. Contains documentation structure overview, SCOPE tags rules, maintenance conventions, sequential numbering, placeholder conventions. NO content duplication - all details in subdirectory READMEs. -->
<!-- DO NOT add here: Project-specific details → project/README.md, Reference documentation → reference/README.md, Task management rules → tasks/README.md, Implementation code → Task descriptions -->
---
## Overview
This documentation system provides comprehensive technical and operational documentation following industry standards (ISO/IEC/IEEE 29148, arc42, C4 Model, Michael Nygard's ADR format).
**Documentation is organized into three main areas:**
- **Project Documentation** - Requirements, architecture, technical specifications
- **Reference Documentation** - Architecture decisions (ADRs), reusable patterns (Guides), API references (Manuals)
- **Task Management** - Linear workflow, task tracking rules, kanban board
---
## General Documentation Standards
All documentation in this system follows these conventions:
### SCOPE Tags
Every document contains HTML comment tags defining its boundaries:
```html
<!-- SCOPE: What this document CONTAINS -->
<!-- DO NOT add here: What belongs elsewhere → where to find it -->
```
**Purpose**: Prevent content duplication, maintain single source of truth, redirect to correct location.
**Example**:
```html
<!-- SCOPE: Project requirements ONLY. Functional requirements ONLY. -->
<!-- DO NOT add here: Architecture details → architecture.md, Implementation → Task descriptions -->
```
### Maintenance Sections
All documents contain a **Maintenance** section with:
| Field | Description | Example |
|-------|-------------|---------|
| **Update Triggers** | When to update the document | "When changing acceptance criteria (Non-Functional Requirements are forbidden here)" |
| **Verification** | How to verify document is current | "Check all FR-XXX IDs referenced in tests exist" |
| **Last Updated** | Date of last modification | "2025-11-15" |
### Sequential Numbering
**Rule**: Phases/Sections/Steps use sequential integers: 1, 2, 3, 4 (NOT 1, 1.5, 2).
**Exceptions**:
| Case | Format | Example | When Valid |
|------|--------|---------|------------|
| **Conditional Branching** | Letter suffixes | Phase 4a (CREATE), Phase 4b (REPLAN), Phase 5 | Mutually exclusive paths (EITHER A OR B) |
| **Loop Internals** | Steps inside Phase | Phase 3: Loop → Step 1 → Step 2 → Repeat | Cyclic workflows with repeated sub-steps |
**Important**: When inserting new items, renumber all subsequent items.
### Placeholder Conventions
Documents use placeholders for registry updates:
| Placeholder | Location | Purpose | Updated By |
|-------------|----------|---------|------------|
| `{{ADR_LIST}}` | reference/README.md | ADR registry | ln-322-adr-creator |
| `{{GUIDE_LIST}}` | reference/README.md | Guide registry | ln-321-guide-creator |
| `{{MANUAL_LIST}}` | reference/README.md | Manual registry | ln-323-manual-creator |
**Usage**: Skills automatically add new entries BEFORE the placeholder using Edit tool.
### Writing Guidelines (Progressive Disclosure Pattern)
All documentation follows token-efficient formatting rules:
| Content Type | Format | Rationale |
|--------------|--------|-----------|
| **Skill descriptions** | < 200 chars in SKILL.md frontmatter | Clarity, focused scope |
| **Workflows** | Reference table with link to SKILL.md | Avoid duplication (DRY) |
| **Examples** | Table rows (verdict + rationale) | 60-80% more compact than paragraphs |
| **Lists** | Bullet points with inline details | Progressive disclosure |
| **References** | One-line format (source - topics - insight) | Scannable, no verbose paragraphs |
| **Comparisons** | Table with columns | Visual clarity, easy scanning |
| **Step-by-step processes** | Inline arrow notation (Step 1 → Step 2 → Step 3) | Compact flow representation |
**Verbose content is justified for:**
- ❌ Anti-patterns (educational value - prevents mistakes)
- 🎓 Complex architectural explanations (orchestrator patterns, state machines)
- ⚠️ Critical rules with rationale (INVEST criteria, task sizing)
**Compression targets:**
- Main documentation files: < 500 lines (optimal: 300-400 lines)
- README hubs: < 200 lines
- Individual guides: < 800 lines (optimal: 400-600 lines)
### Documentation Standards
**Full documentation requirements:** See [documentation_standards.md](documentation_standards.md)
Key highlights:
- **Claude Code Integration** - CLAUDE.md ≤100 lines, @-sourcing, sessionStart hooks
- **AI-Friendly Writing** - Second person, active voice, max 25 words/sentence
- **Code Examples** - All examples runnable, realistic names, show expected output
- **DIATAXIS Framework** - Organize docs into Tutorial/How-to/Reference/Explanation
- **Security** - Never commit secrets, use .env.example templates
- **Conventional Commits** - Structured commit messages for auto-changelog
**Total:** 60 requirements in 12 categories. See documentation_standards.md for complete details.
---
## Documentation Structure
### 1. [Project Documentation](project/README.md)
Core project documentation created by ln-114-project-docs-creator skill:
- **[README.md](project/README.md)** - Project documentation hub
- **[requirements.md](project/requirements.md)** - Functional requirements (FR-XXX-NNN) with MoSCoW prioritization
- **[architecture.md](project/architecture.md)** - System architecture (C4 Model, arc42)
- **[technical_specification.md](project/technical_specification.md)** - Implementation details
**Purpose**: Define WHAT we build and WHY.
**Created by**: ln-114-project-docs-creator
---
### 2. [Reference Documentation](reference/README.md)
Reusable knowledge base and architecture decisions:
- **[ADRs](reference/adrs/)** - Architecture Decision Records (format: `adr-NNN-slug.md`)
- **[Guides](reference/guides/)** - Project patterns and best practices (format: `NN-pattern-name.md`)
- **[Manuals](reference/manuals/)** - Package API references (format: `package-version.md`)
**Purpose**: Document HOW we build (patterns, decisions, APIs).
**Created by**: ln-322-adr-creator, ln-321-guide-creator, ln-323-manual-creator
---
### 3. [Task Management System](tasks/README.md)
Linear integration and workflow rules:
- **[README.md](tasks/README.md)** - Task lifecycle, Linear integration rules, workflow skills
- **[kanban_board.md](tasks/kanban_board.md)** - Live navigation to active tasks
**Purpose**: Define HOW we track and manage work.
**Created by**: ln-111-docs-creator (Phase 2, Phase 9-10)
---
## Standards Compliance
This documentation system follows:
| Standard | Application | Reference |
|----------|-------------|-----------|
| **ISO/IEC/IEEE 29148:2018** | Requirements Engineering | [requirements.md](project/requirements.md) |
| **ISO/IEC/IEEE 42010:2022** | Architecture Description | [architecture.md](project/architecture.md) |
| **arc42 Template** | Software architecture documentation | [architecture.md](project/architecture.md) |
| **C4 Model** | Software architecture visualization | [architecture.md](project/architecture.md) |
| **Michael Nygard's ADR Format** | Architecture Decision Records | [reference/adrs/](reference/adrs/) |
| **MoSCoW Prioritization** | Requirements prioritization | [requirements.md](project/requirements.md) |
---
## Contributing to Documentation
When updating documentation:
1. **Check SCOPE tags** at top of document to ensure changes belong there
2. **Update Maintenance > Last Updated** date in the modified document
3. **Update registry** if adding new documents:
- ADRs, Guides, Manuals → automatically updated by skills
- Project docs → update [project/README.md](project/README.md) manually
4. **Follow sequential numbering** rules (no decimals unless conditional branching)
5. **Add placeholders** if creating new document types
6. **Verify links** after structural changes
---
## Quick Navigation
| Area | Key Documents | Skills |
|------|---------------|--------|
| **Standards** | [documentation_standards.md](documentation_standards.md) | ln-111-root-docs-creator, ln-121-structure-validator |
| **Project** | [requirements.md](project/requirements.md), [architecture.md](project/architecture.md), [technical_specification.md](project/technical_specification.md) | ln-114-project-docs-creator, ln-122-content-updater |
| **Reference** | [ADRs](reference/adrs/), [Guides](reference/guides/), [Manuals](reference/manuals/) | ln-322-adr-creator, ln-321-guide-creator, ln-323-manual-creator |
| **Tasks** | [kanban_board.md](tasks/kanban_board.md), [README.md](tasks/README.md) | ln-210-epic-coordinator, ln-220-story-coordinator, ln-310-story-decomposer |
---
## Maintenance
**Update Triggers**:
- When adding new documentation areas (new subdirectories)
- When changing general documentation standards (SCOPE, Maintenance, Sequential Numbering)
- When changing writing guidelines or documentation formatting standards
- When adding new placeholder conventions
- When updating compliance standards
**Verification**:
- All links to subdirectory READMEs are valid
- SCOPE tags accurately reflect document boundaries
- Placeholder conventions documented for all registries
- Standards Compliance table references correct documents
**Last Updated**: {{DATE}}
---
**Template Version:** 1.1.0
**Template Last Updated:** 2025-11-16

160
skills/ln-111-root-docs-creator/references/documentation_standards_template.md Normal file
View File

@@ -0,0 +1,160 @@
# Documentation Standards
**Comprehensive Requirements for Claude Code Skills Documentation (2024-2025)**
**Last Updated:** {{DATE}}
<!-- SCOPE: 82 universal documentation requirements for Claude Code skills. Based on industry standards (ISO/IEC/IEEE, DIATAXIS, RFC), Claude Code best practices, and AI-friendly documentation research. NO project-specific details (→ project/requirements.md), NO skill-specific workflows (→ SKILL.md). -->
---
## Quick Reference (82 Requirements)
**Legend:** 🔴 Critical | 🟡 Important | 🟢 Desired | ⚠️ Conditional | ✅ Already implemented
| Category | Count | 🔴 | 🟡 | 🟢 | ⚠️ | ✅ | Validator |
|----------|-------|-----|-----|-----|-----|-----|-----------|
| **Core Documentation** | 25 | 8 | 12 | 5 | 0 | 0 | ln-121, ln-122 |
| **Claude Code Integration** | 5 | 1 | 2 | 2 | 0 | 0 | ln-121 v2.1.0+ |
| **AI-Friendly Writing** | 6 | 0 | 5 | 1 | 0 | 0 | ln-121 warning |
| **Markdown Best Practices** | 6 | 0 | 4 | 2 | 0 | 0 | ln-121 v2.1.0+ |
| **Code Examples Quality** | 5 | 1 | 2 | 2 | 0 | 0 | Manual + CI |
| **DIATAXIS Framework** | 5 | 0 | 1 | 2 | 0 | 2 | Manual |
| **Project Files** | 6 | 1 | 3 | 2 | 0 | 0 | Manual |
| **Quality Checks** | 5 | 0 | 4 | 1 | 0 | 0 | markdownlint, Vale |
| **Front Matter (SSG)** | 3 | 0 | 0 | 2 | 1 | 0 | Conditional |
| **Visual Documentation** | 5 | 0 | 0 | 4 | 0 | 1 | Manual |
| **Conventional Commits** | 4 | 0 | 1 | 1 | 0 | 2 | commitlint |
| **Security & Compliance** | 4 | 1 | 3 | 0 | 0 | 0 | Manual |
| **Performance** | 3 | 0 | 1 | 2 | 0 | 0 | Manual |
**Total:** 82 requirements | 🔴 12 Critical | 🟡 38 Important | 🟢 24 Desired | ⚠️ 1 Conditional | ✅ 5 Implemented
---
## Key Requirements by Priority
### Critical (Must Have)
| Requirement | Rationale | Validator |
|------------|-----------|-----------|
| CLAUDE.md ≤100 lines | Claude Code performance optimization | ln-121 v2.1.0+ |
| All code examples runnable | Prevent documentation drift | Manual + CI |
| LICENSE file exists | Legal compliance | Manual |
| Never commit secrets | Security breach prevention | Manual |
### Important (Should Have)
**Claude Code Integration:**
- @-sourcing support in CLAUDE.md (DRY pattern)
- Explicitly specify `setting_sources=["project"]`
**AI-Friendly Writing:**
- Use second person ("you" vs "users")
- Active voice instead of passive
- Short sentences (max 25 words)
- Prohibited phrases ("please note", "simply", "just", "easily")
- Don't assume prior knowledge
**Markdown Best Practices:**
- Header depth ≤ h3 (rarely h4)
- Descriptive links (not "click here")
- Callouts/Admonitions for important info
- Files end with single blank line (POSIX)
**Code Examples Quality:**
- Test documentation examples in CI/CD
- Include setup context (directory, prerequisites)
**Project Files:**
- CONTRIBUTING.md (contribution process)
- SECURITY.md (vulnerability reporting)
- .gitignore for docs (exclude generated files)
**Quality Checks:**
- markdownlint-cli2 (.markdownlint.jsonc)
- Vale.sh (.vale.ini for editorial checks)
- Build verification (prevent broken deployments)
- Link checking (dead link detection)
**Security & Compliance:**
- GitHub Secrets for CI/CD
- .env.example instead of .env
- Vulnerability reporting process (SECURITY.md)
**Performance:**
- Optimize CLAUDE.md size (-30 to -40% tokens via @-sourcing)
### Desired (Nice to Have)
**Documentation Structure:** DIATAXIS framework (Tutorial/How-to/Reference/Explanation sections), How-to guides ✅, Reference docs ✅
**Visual Elements:** Mermaid diagrams ✅, workflow diagrams, sequence diagrams, light/dark theme support, centralized image storage
**Version Control:** Conventional Commits format, auto-generate CHANGELOG, Keep a Changelog ✅, Semantic versioning ✅
**Code Quality:** Realistic variable names (not foo/bar), show expected output, code blocks in step lists
**Project Files:** CODE_OF_CONDUCT.md, README badges, vocabulary files for terminology
**Advanced Features:** SessionStart hooks, subagents in .claude/agents/*.md, Front Matter for SSG (Hugo/Docusaurus) ⚠️, lazy loading, caching strategy
**Writing Style:** Avoid first-person pronouns, Title case for h1/Sentence case for h2+
---
## Standards Compliance
| Standard | Reference |
|----------|-----------|
| **ISO/IEC/IEEE 29148:2018** | Requirements Engineering |
| **ISO/IEC/IEEE 42010:2022** | Architecture Description |
| **DIATAXIS Framework** | diataxis.fr - Documentation structure |
| **RFC 2119, WCAG 2.1 AA** | Requirement keywords, Accessibility |
| **OWASP Top 10** | Security requirements |
| **Conventional Commits** | conventionalcommits.org |
| **Keep a Changelog** | Changelog format |
| **Semantic Versioning** | Major.Minor.Patch |
**Sources:** Claude Code docs, Clever Cloud guide, DIATAXIS framework, Matter style guide
---
## Verification Checklist
Before submitting documentation:
- [ ] **CLAUDE.md ≤100 lines** - Concise and focused
- [ ] **All code examples runnable** - No placeholders, tested
- [ ] **LICENSE file exists** - Legal compliance
- [ ] **No secrets committed** - API keys in .env only
- [ ] **Header depth ≤ h3, files end with blank line** - Markdown standards
- [ ] **Active voice, second person, short sentences** - AI-friendly writing
- [ ] **SCOPE tag in docs/**, Maintenance section** - Core requirements
- [ ] **Descriptive links, callouts for important info** - Best practices
---
## Maintenance
**Update Triggers:**
- When Claude Code releases new best practices
- When industry standards evolve (ISO/IEC/IEEE updates)
- When new validation tools become available
- When ln-121-structure-validator or ln-122-content-updater add new checks
- Annual review (Q1 each year)
**Verification:**
- [ ] All 82 requirements documented with rationale
- [ ] Priority levels assigned (Critical/Important/Desired)
- [ ] Validators identified for automated checks
- [ ] Standards compliance table complete
- [ ] References link to authoritative sources
- [ ] Verification checklist covers all critical requirements
**Last Updated:** {{DATE}}
---
**Template Version:** 2.0.0 (MAJOR: Progressive Disclosure - reduced from 390→160 lines (-59%), removed detailed sections 1-12 and Implementation Roadmap, converted to compact table format, added SCOPE tag)
**Template Last Updated:** {{DATE}}

110
skills/ln-111-root-docs-creator/references/principles_template.md Normal file
View File

@@ -0,0 +1,110 @@
# Development Principles
**Last Updated:** {{DATE}}
<!-- SCOPE: Universal development principles for THIS project ONLY. Contains 8 core principles with rationale, Decision Framework, and Verification Checklist. NO implementation details (→ Architecture.md), NO project-specific requirements (→ Requirements.md), NO testing philosophy (→ docs/reference/guides/testing-strategy.md). -->
---
## Core Principles
| # | Name | Type | Principle | Approach/Rules |
|---|------|------|-----------|----------------|
| **1** | **Standards First** | code+docs | Industry standards (ISO/RFC/OWASP/WCAG) override development principles | **Hierarchy:** Industry Standards → Security Standards → Accessibility Standards → Dev Principles (YAGNI/KISS/DRY within standard boundaries) |
| **2** | **YAGNI (You Aren't Gonna Need It)** | code+docs | Don't build features "just in case". Build what's needed NOW | **Avoid:** Generic frameworks for one use case, caching without bottleneck, extensibility points without requirements |
| **3** | **KISS (Keep It Simple)** | code+docs | Simplest solution that solves the problem. No unnecessary complexity | **Approach:** Start with naive solution → Add complexity ONLY when proven necessary → Each abstraction layer must justify existence |
| **4** | **DRY (Don't Repeat Yourself)** | code+docs | Each piece of knowledge exists in ONE place. Link, don't duplicate | **Code:** Extract repeated logic, constants defined once. **Docs:** Single Source of Truth, reference via links, update immediately |
| **5** | **Consumer-First Design** | code | Design APIs/functions/workflows from consumer's perspective | **Design:** 1. Define interface/API FIRST (what consumers need) → 2. Implement internals SECOND (how it works) → 3. Never expose internal complexity to consumers. **Note:** This is for API/interface DESIGN, not task execution order (see Foundation-First Execution in workflow) |
| **6** | **No Legacy Code** | code | Remove backward compatibility shims immediately after migration | **Rules:** Deprecated features deleted in NEXT release (not "someday"), NO commented-out code (use git history), NO `if legacy_mode:` branches |
| **7** | **Documentation-as-Code** | docs | Documentation lives WITH code, updated WITH code changes | **Rules:** Documentation in same commit as code, NO separate "docs update" tasks, Outdated docs = bug (same severity as code bug) |
| **8** | **Security by Design** | code | Security integrated from design phase, not bolted on later | **Practices:** Never commit secrets → env vars/secret managers, Validate at boundaries → Pydantic models, Least Privilege → minimum permissions, Fail Securely → don't leak info in errors, Defense in Depth → multiple security layers |
---
## Decision-Making Framework
When making technical decisions, evaluate against these principles **in order**:
1. **Security:** Is it secure by design? (OWASP, NIST standards)
2. **Standards Compliance:** Does it follow industry standards? (ISO, RFC, W3C)
3. **Correctness:** Does it solve the problem correctly?
4. **Simplicity (KISS):** Is it the simplest solution that works?
5. **Necessity (YAGNI):** Do we actually need this now?
6. **Maintainability:** Can future developers understand and modify it?
7. **Performance:** Is it fast enough? (Optimize only if proven bottleneck)
### Trade-offs
When principles conflict, use the Decision-Making Framework hierarchy:
| Conflict | Lower Priority | Higher Priority | Resolution |
|----------|---------------|-----------------|------------|
| **Simplicity vs Security** | KISS | Security by Design | Choose secure solution, even if more complex |
| **YAGNI vs Standards** | YAGNI | Standards First | Implement standard now (e.g., OAuth 2.0), not "simple custom auth" |
| **Flexibility vs Constraints** | Flexibility | YAGNI | Choose constraints (clear boundaries), not open-ended "for future" |
---
## Anti-Patterns to Avoid
### God Objects
- ❌ One class/module that does everything
- ✅ Small, focused classes with single responsibility
### Premature Optimization
- ❌ Caching before measuring actual bottlenecks
- ✅ Measure first (profiling, metrics), optimize proven bottlenecks
### Over-Engineering
- ❌ Complex abstractions "for future flexibility"
- ✅ Simple solution now, refactor if complexity justified later
### Magic Numbers/Strings
- ❌ `if status == 200:` hardcoded everywhere
- ✅ `if status == HTTPStatus.OK:` or `STATUS_OK = 200` as constant
### Leaky Abstractions
- ❌ Service layer exposes database models to API layer
- ✅ Service layer returns DTOs/Pydantic schemas, hides ORM details
---
## Verification Checklist
Before submitting code, verify compliance with principles:
- [ ] **Standards First:** Follows industry standards (ISO, RFC, OWASP, WCAG 2.1 AA)
- [ ] **YAGNI:** Only building what's needed now (no speculative features)
- [ ] **KISS:** Solution is as simple as possible, not simpler
- [ ] **DRY:** No duplicated logic or documentation
- [ ] **Consumer-First Design:** API/interface designed from consumer perspective
- [ ] **No Legacy Code:** No deprecated code, no commented-out code
- [ ] **Documentation-as-Code:** Docs updated in same commit as code
- [ ] **Security by Design:** No secrets committed, input validated, least privilege
---
## Maintenance
**Update Triggers:**
- When adding new principles
- When changing decision framework hierarchy
- When industry standards evolve (ISO, RFC, OWASP updates)
- When trade-off examples change
- Annual review (Q1 each year)
**Verification:**
- [ ] All 8 principles documented
- [ ] Decision Framework clear (7 steps)
- [ ] Trade-offs explained (3 conflicts)
- [ ] Anti-patterns listed (5 patterns)
- [ ] Verification Checklist complete (8 items)
- [ ] Links to external resources valid
- [ ] Table format demonstrates principles clearly
**Last Updated:** {{DATE}}
---
**Template Version:** 3.0.0 (MAJOR: Removed domain-specific principles (Task Granularity→ln-113, Value-Based Testing→ln-116, Token Efficiency→documentation_standards.md), converted to table format (8 universal principles only), removed all detailed sections with examples for Progressive Disclosure)
**Template Last Updated:** {{DATE}}

475
skills/ln-111-root-docs-creator/references/questions.md Normal file
View File

@@ -0,0 +1,475 @@
# Root Documentation Questions
**Purpose:** Define what each root documentation file should answer. Each section maps explicitly to document sections for validation.
**Format:** Document → Rules → Questions (with target sections) → Validation Heuristics → Auto-Discovery
---
## Table of Contents
| Document | Questions | Auto-Discovery | Priority | Line |
|----------|-----------|----------------|----------|------|
| [CLAUDE.md](#claudemd) | 6 | Medium | Critical | L30 |
| [docs/README.md](#docsreadmemd) | 7 | Low | High | L170 |
| [docs/documentation_standards.md](#docsdocumentation_standardsmd) | 3 | None | Medium | L318 |
| [docs/principles.md](#docsprinciplesmd) | 6 | None | High | L381 |
**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
- **Medium:** 3+ questions need auto-discovery
---
<!-- DOCUMENT_START: CLAUDE.md -->
## CLAUDE.md
**File:** CLAUDE.md (project root)
**Target Sections:** ⚠️ Critical Rules for AI Agents, Documentation Navigation Rules, Documentation, Development Commands, Documentation Maintenance Rules, Maintenance
**Rules for this document:**
- Recommended length: ≤100 lines (guideline from Claude Code docs)
- Must have SCOPE tag in first 10 lines
- Must link to docs/README.md
- Entry point for all documentation (DAG root)
---
<!-- QUESTION_START: 1 -->
### Question 1: Where is project documentation located?
**Expected Answer:** Links to docs/README.md, documentation_standards.md, principles.md
**Target Section:** ## Documentation
**Validation Heuristics:**
- ✅ Has section "## Documentation" with links to docs/README.md, documentation_standards.md, principles.md
**Auto-Discovery:**
- None needed (standard structure)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: What are critical rules for AI agents?
**Expected Answer:** Table of critical rules organized by category (Standards Hierarchy, Documentation, Testing, Research, Task Management, Skills, Language) with When to Apply and Rationale columns
**Target Section:** ## ⚠️ Critical Rules for AI Agents
**Validation Heuristics:**
- ✅ Has section "## ⚠️ Critical Rules for AI Agents" with table (Category, Rule, When to Apply, Rationale), 7+ rows, "Key Principles" subsection, mentions Standards First, Token Efficiency, Quality, No Legacy Code
**Auto-Discovery:**
- None needed (universal rules)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: How to navigate documentation (DAG structure)?
**Expected Answer:** SCOPE tags explanation + reading order + graph structure with examples
**Target Section:** ## Documentation Navigation Rules
**Validation Heuristics:**
- ✅ Has section "## Documentation Navigation Rules" with SCOPE tag explanation, reading order (numbered list), example navigation, >40 words
**Auto-Discovery:**
- None needed (universal best practice)
<!-- QUESTION_END: 3 -->
---
<!-- QUESTION_START: 4 -->
### Question 4: What are documentation maintenance rules?
**Expected Answer:** DRY principles, Single Source of Truth, update triggers, English-only policy
**Target Section:** ## Documentation Maintenance Rules
**Validation Heuristics:**
- ✅ Has section "## Documentation Maintenance Rules" with "Single Source of Truth"/"DRY", "English Only" rule, "Principles"/"Avoiding Duplication" subsections, >60 words
**Auto-Discovery:**
- None needed (universal standards)
<!-- QUESTION_END: 4 -->
---
<!-- QUESTION_START: 5 -->
### Question 5: When should CLAUDE.md be updated?
**Expected Answer:** Update triggers + verification checklist
**Target Section:** ## Maintenance
**Validation Heuristics:**
- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections, "Last Updated" field
**Auto-Discovery:**
- None needed (standard maintenance section)
<!-- QUESTION_END: 5 -->
---
<!-- QUESTION_START: 6 -->
### Question 6: What are the project development commands?
**Expected Answer:** Table with development commands organized by task (Install Dependencies, Run Tests, Start Dev Server, Build, Lint/Format) for both Windows and Bash
**Target Section:** ## Development Commands
**Validation Heuristics:**
- ✅ Has section "## Development Commands" with table (Task, Windows, Bash), 5+ rows, note about updating commands, placeholder/actual commands
**Auto-Discovery:**
- Scan package.json → "scripts" field (for Node.js projects)
- Scan pyproject.toml → [tool.poetry.scripts] or [project.scripts] (for Python projects)
- Scan Makefile → targets (for Make-based projects)
- Scan composer.json → "scripts" field (for PHP projects)
**Notes:**
- If no commands found, use placeholder: `[Add your command]`
- Auto-discovery hints can suggest common commands based on detected project type
<!-- QUESTION_END: 6 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tag in first 10 lines
- ✅ Total length > 80 words (meaningful content)
**Auto-Discovery Hints:**
- Scan package.json → "name", "description" fields (for project name/description)
- Check existing CLAUDE.md for project name
<!-- DOCUMENT_END: CLAUDE.md -->
---
<!-- DOCUMENT_START: docs/README.md -->
## docs/README.md
**File:** docs/README.md (documentation hub)
**Target Sections:** Overview, General Documentation Standards, Writing Guidelines, Standards Compliance, Contributing to Documentation, Quick Navigation, Maintenance
**Rules for this document:**
- Must have SCOPE tag in first 10 lines (HTML comment)
- Hub file - navigation to subdirectories (project/, reference/, tasks/)
- General standards only - NO project-specific content
---
<!-- QUESTION_START: 1 -->
### Question 1: What is the documentation structure?
**Expected Answer:** Overview of documentation areas (Project, Reference, Task Management)
**Target Section:** ## Overview
**Validation Heuristics:**
- ✅ Has section "## Overview" mentioning Project Documentation (project/), Reference Documentation (reference/), Task Management (tasks/), >30 words
**Auto-Discovery:**
- Scan docs/ directory for subdirectories (project/, reference/, tasks/)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: What are general documentation standards?
**Expected Answer:** SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions
**Target Section:** ## General Documentation Standards
**Validation Heuristics:**
- ✅ Has section "## General Documentation Standards" with subsections (SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions), >100 words
**Auto-Discovery:**
- None needed (universal standards)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: What are writing guidelines?
**Expected Answer:** Progressive Disclosure Pattern, token efficiency, table-first format
**Target Section:** ## Writing Guidelines
**Validation Heuristics:**
- ✅ Has section "## Writing Guidelines" mentioning Progressive Disclosure/token efficiency, table/list with format guidelines, >50 words
**Auto-Discovery:**
- None needed (universal best practice)
<!-- QUESTION_END: 3 -->
---
<!-- QUESTION_START: 4 -->
### Question 4: When should docs/README.md be updated?
**Expected Answer:** Update triggers + verification checklist
**Target Section:** ## Maintenance
**Validation Heuristics:**
- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections
**Auto-Discovery:**
- None needed (standard maintenance section)
<!-- QUESTION_END: 4 -->
---
<!-- QUESTION_START: 5 -->
### Question 5: What are the standards this documentation complies with?
**Expected Answer:** Standards Compliance table with Standard, Application, and Reference columns
**Target Section:** ## Standards Compliance
**Validation Heuristics:**
- ✅ Has section "## Standards Compliance" with table (Standard, Application, Reference), 5+ standards (ISO/IEC/IEEE 29148:2018, ISO/IEC/IEEE 42010:2022, arc42, C4 Model, ADR Format, MoSCoW), document path links
**Auto-Discovery:**
- None needed (universal standards)
<!-- QUESTION_END: 5 -->
---
<!-- QUESTION_START: 6 -->
### Question 6: How to contribute to documentation?
**Expected Answer:** Numbered list of contribution steps (Check SCOPE tags, Update Last Updated date, Update registry, Follow sequential numbering, Add placeholders, Verify links)
**Target Section:** ## Contributing to Documentation
**Validation Heuristics:**
- ✅ Has section "## Contributing to Documentation" with 6+ steps mentioning SCOPE tags, Last Updated, registry, sequential numbering, link verification, >40 words
**Auto-Discovery:**
- None needed (universal contribution guidelines)
<!-- QUESTION_END: 6 -->
---
<!-- QUESTION_START: 7 -->
### Question 7: How to quickly navigate to key documentation areas?
**Expected Answer:** Quick Navigation table with Area, Key Documents, and Skills columns
**Target Section:** ## Quick Navigation
**Validation Heuristics:**
- ✅ Has section "## Quick Navigation" with table (Area, Key Documents, Skills), 4 rows (Standards, Project, Reference, Tasks), document/skill name links
**Auto-Discovery:**
- Scan docs/ directory structure (project/, reference/, tasks/)
- Detect skill references from kanban_board.md (if exists)
<!-- QUESTION_END: 7 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tag (HTML comment) in first 10 lines
- ✅ Total length > 100 words
<!-- DOCUMENT_END: docs/README.md -->
---
<!-- DOCUMENT_START: docs/documentation_standards.md -->
## docs/documentation_standards.md
**File:** docs/documentation_standards.md (60 universal requirements)
**Target Sections:** Quick Reference, 12 main sections (Claude Code Integration through References), Maintenance
**Rules for this document:**
- 60+ universal documentation requirements
- 12 main sections covering industry standards
- References to ISO/IEC/IEEE, DIATAXIS, arc42
---
<!-- QUESTION_START: 1 -->
### Question 1: What are the comprehensive documentation requirements?
**Expected Answer:** Quick Reference table with 60+ requirements in 12 categories
**Target Section:** ## Quick Reference
**Validation Heuristics:**
- ✅ Has section "## Quick Reference" with table (Requirement, Description, Priority, Reference), 60+ rows across categories (Claude Code Integration, AI-Friendly Writing, Markdown, Code Examples, DIATAXIS)
**Auto-Discovery:**
- None needed (universal standards, use template as-is)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: What are the detailed requirements for each category?
**Expected Answer:** 12 main sections with detailed explanations
**Target Sections:** 12 sections (## Claude Code Integration, ## AI-Friendly Writing Style, etc.)
**Validation Heuristics:**
- ✅ Has 12+ main sections with subsections, mentions ISO/IEC/IEEE/DIATAXIS/arc42 standards, >300 lines
**Auto-Discovery:**
- None needed (universal standards)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: When should documentation standards be updated?
**Expected Answer:** Update triggers + verification checklist
**Target Section:** ## Maintenance
**Validation Heuristics:**
- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections
**Auto-Discovery:**
- None needed (standard maintenance section)
<!-- QUESTION_END: 3 -->
---
**Overall File Validation:**
- ✅ File size > 300 lines
- ✅ Mentions ISO/IEC/IEEE 29148:2018
- ✅ Mentions DIATAXIS framework
- ✅ Mentions arc42
**MCP Ref Hints:**
- Research: "DIATAXIS framework documentation" (if user wants customization)
- Research: "ISO/IEC/IEEE 29148:2018" (if user wants compliance details)
<!-- DOCUMENT_END: docs/documentation_standards.md -->
---
<!-- DOCUMENT_START: docs/principles.md -->
## docs/principles.md
**File:** docs/principles.md (8 development principles + Decision Framework)
**Target Sections:** Core Principles table, Decision-Making Framework, Trade-offs (subsection), Anti-Patterns, Verification Checklist, Maintenance
**Rules for this document:**
- Must have SCOPE tag in first 10 lines
- 8 core principles (Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design)
- Decision-Making Framework (7 steps)
- Verification Checklist (8 items)
---
<!-- QUESTION_START: 1 -->
### Question 1: What are the core development principles?
**Expected Answer:** 8 principles in table format (4 columns: Name, Type, Principle, Approach/Rules)
**Target Section:** ## Core Principles
**Validation Heuristics:**
- ✅ Has section "## Core Principles" with 8-row table (Name, Type, Principle, Approach/Rules): Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design, no subsections
**Auto-Discovery:**
- None needed (universal principles)
**Notes:**
- Task Granularity → Moved to ln-113-tasks-docs-creator (task management specific)
- Value-Based Testing → Moved to ln-116-test-docs-creator (testing specific)
- Token Efficiency → Referenced in documentation_standards.md (already detailed in #80-85)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: How to make decisions when principles conflict?
**Expected Answer:** Decision-Making Framework with priority order (Security → Standards → Correctness → ...)
**Target Section:** ## Decision-Making Framework
**Validation Heuristics:**
- ✅ Has section "## Decision-Making Framework" with 7 steps (Security, Standards, Correctness, Simplicity, Necessity, Maintainability, Performance), >30 words
**Auto-Discovery:**
- None needed (universal framework)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: How to resolve conflicts when principles contradict?
**Expected Answer:** Trade-offs table with Conflict, Lower Priority, Higher Priority, and Resolution columns
**Target Section:** ### Trade-offs (subsection under Decision-Making Framework)
**Validation Heuristics:**
- ✅ Has subsection "### Trade-offs" under Decision-Making Framework with table (Conflict, Lower Priority, Higher Priority, Resolution), 3+ conflicts using framework hierarchy
**Auto-Discovery:**
- None needed (universal trade-offs)
<!-- QUESTION_END: 3 -->
---
<!-- QUESTION_START: 4 -->
### Question 4: What are common anti-patterns to avoid?
**Expected Answer:** List of anti-patterns across principles
**Target Section:** ## Anti-Patterns to Avoid
**Validation Heuristics:**
- ✅ Has section "## Anti-Patterns to Avoid" with 5+ anti-patterns, >20 words
**Auto-Discovery:**
- None needed (universal anti-patterns)
<!-- QUESTION_END: 4 -->
---
<!-- QUESTION_START: 5 -->
### Question 5: How to verify principles compliance?
**Expected Answer:** Verification checklist with 8 items
**Target Section:** ## Verification Checklist
**Validation Heuristics:**
- ✅ Has section "## Verification Checklist" with 8-item checklist (- [ ] format) covering all 8 core principles
**Auto-Discovery:**
- None needed (universal checklist)
<!-- QUESTION_END: 5 -->
---
<!-- QUESTION_START: 6 -->
### Question 6: When should principles be updated?
**Expected Answer:** Update triggers + verification
**Target Section:** ## Maintenance
**Validation Heuristics:**
- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections
**Auto-Discovery:**
- None needed (standard maintenance section)
<!-- QUESTION_END: 6 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tag in first 10 lines
- ✅ File size > 100 lines (reduced from 300+ due to table format + removed domain-specific principles)
- ✅ All 8 core principles present (Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design)
**MCP Ref Hints:**
- Research: "YAGNI principle examples" (if user wants deeper explanation)
- Research: "DRY principle best practices" (if user wants industry context)
<!-- DOCUMENT_END: docs/principles.md -->
---
**Version:** 4.0.0 (MAJOR: Added Table of Contents and programmatic markers for context management)
**Last Updated:** 2025-11-18