Initial commit

2025-11-30 08:37:27 +08:00
commit 37774aa937
131 changed files with 31137 additions and 0 deletions
--- a/skills/ln-111-root-docs-creator/references/docs_root_readme_template.md
+++ b/skills/ln-111-root-docs-creator/references/docs_root_readme_template.md
@@ -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