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/claude_md_template.md
+++ b/skills/ln-111-root-docs-creator/references/claude_md_template.md
@@ -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}}
--- 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
--- a/skills/ln-111-root-docs-creator/references/documentation_standards_template.md
+++ b/skills/ln-111-root-docs-creator/references/documentation_standards_template.md
@@ -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}}
--- a/skills/ln-111-root-docs-creator/references/principles_template.md
+++ b/skills/ln-111-root-docs-creator/references/principles_template.md
@@ -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}}
--- a/skills/ln-111-root-docs-creator/references/questions.md
+++ b/skills/ln-111-root-docs-creator/references/questions.md
@@ -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