Initial commit

2025-11-30 08:37:27 +08:00
commit 37774aa937
131 changed files with 31137 additions and 0 deletions
--- a/skills/ln-114-project-docs-creator/SKILL.md
+++ b/skills/ln-114-project-docs-creator/SKILL.md
@@ -0,0 +1,457 @@
+---
+name: ln-114-project-docs-creator
+description: Creates and validates 7 project docs (requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook). Fourth worker in ln-110-documents-pipeline.
+---
+
+# Project Documentation Creator
+
+This skill creates and validates technical project documentation following industry best practices (ISO/IEC/IEEE standards, arc42, C4 Model, ADR format).
+
+## 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 project documentation (7 docs: requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook)
+- Validating existing project documentation
+- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup)
+
+**Part of workflow**: ln-110-documents-pipeline (orchestrator) → ln-111-root-docs-creator → ln-112-reference-docs-creator → ln-113-tasks-docs-creator → **ln-114-project-docs-creator** → ln-115-presentation-creator → ln-116-test-docs-creator
+
+## How It Works
+
+The skill follows a 4-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT** → **FINALIZE**. Each phase builds on the previous, ensuring complete structure and semantic validation.
+
+---
+
+### Phase 1: Create Structure
+
+**Objective**: Establish project documentation files (3-7 files based on project type).
+
+**Process**:
+
+**1.1 Check existing files**:
+- Use Glob to scan `docs/project/*.md`
+- Check which of 7 project docs already exist:
+  - requirements.md (ALWAYS needed)
+  - architecture.md (ALWAYS needed)
+  - tech_stack.md (ALWAYS needed)
+  - api_spec.md (Backend/Full-stack only)
+  - database_schema.md (if database detected)
+  - design_guidelines.md (Frontend/Full-stack only)
+  - runbook.md (Docker-based projects)
+- Build list of MISSING files
+
+**1.2 Determine conditional templates**:
+- **api_spec.md**: Create if Backend/Full-stack project
+  - Detect: Check package.json for backend frameworks (express, fastify, nestjs) OR python/go/java runtime
+  - Skip for Frontend-only projects
+- **database_schema.md**: Create if database detected
+  - Detect: Check package.json for database libraries (pg, mongoose, mysql2, sqlite3, prisma)
+  - Skip if no database found
+- **design_guidelines.md**: Create if Frontend framework detected
+  - Detect: Check package.json for frontend frameworks (react, vue, angular, svelte, next)
+  - Skip for Backend-only projects
+
+**1.3 Create missing templates**:
+- For each missing file, use Write tool to create from `references/templates/`:
+  - `requirements_template.md` → `docs/project/requirements.md` (if missing)
+  - `architecture_template.md` → `docs/project/architecture.md` (if missing)
+  - `tech_stack_template.md` → `docs/project/tech_stack.md` (if missing)
+  - `api_spec_template.md` → `docs/project/api_spec.md` (if missing and needed)
+  - `database_schema_template.md` → `docs/project/database_schema.md` (if missing and needed)
+  - `design_guidelines_template.md` → `docs/project/design_guidelines.md` (if missing and needed)
+  - `runbook_template.md` → `docs/project/runbook.md` (if missing)
+- Track created file list (for Phase 2-3 validation)
+
+**1.4 Log summary**:
+```
+✓ Project documentation structure:
+  - Created: X new files
+  - Preserved: Y existing files
+  - Skipped: Z conditional files (not needed for this project type)
+```
+
+**Output**:
+```
+docs/project/
+├── requirements.md         (created or existing)
+├── architecture.md         (created or existing)
+├── tech_stack.md          (created or existing)
+├── api_spec.md            (created or existing, conditional)
+├── database_schema.md     (created or existing, conditional)
+├── design_guidelines.md   (created or existing, conditional)
+└── runbook.md             (created or existing, conditional)
+```
+
+---
+
+### Phase 2: Validate Structure
+
+**Objective**: Ensure project documentation complies with structural requirements and auto-fix violations.
+
+**Process**:
+
+**2.1 Check SCOPE tags** (all created files):
+- Read first 5 lines of each file created in Phase 1
+- Check for `<!-- SCOPE: ... -->` tag
+- Expected patterns:
+  - requirements.md: `<!-- SCOPE: Functional requirements ONLY (FR-XXX-NNN) -->`
+  - architecture.md: `<!-- SCOPE: arc42 architecture documentation with C4 Model -->`
+  - tech_stack.md: `<!-- SCOPE: Technology stack with versions and Docker configuration -->`
+  - api_spec.md: `<!-- SCOPE: API specification (OpenAPI 3.0 compatible) -->`
+  - database_schema.md: `<!-- SCOPE: Database schema with ER diagrams -->`
+  - design_guidelines.md: `<!-- SCOPE: UI/UX design system and guidelines -->`
+  - runbook.md: `<!-- SCOPE: Operations guide (local/testing/production) -->`
+- If missing:
+  - Use Edit tool to add SCOPE tag at line 1 (after first heading)
+  - Track violation count
+- Log: "✓ SCOPE tags: [added N/all present]"
+
+**2.2 Check required sections** (from questions.md):
+- Load `references/questions.md` using Read tool
+- For each document created in Phase 1:
+  - Extract expected sections from questions.md
+  - Check if section headers exist in document
+  - If missing:
+    - Use Edit tool to add section with placeholder
+    - Track violation count
+- Examples:
+  - requirements.md: ## Functional Requirements
+  - architecture.md: ## 1. Introduction and Goals, ## 2. Constraints, ..., ## 11. Glossary
+  - tech_stack.md: ## Frontend Technologies, ## Backend Technologies, ## Database, ## Additional Technologies
+- Log: "✓ Required sections: [added N sections across M files/all present]"
+
+**2.3 Check Maintenance section** (all created files):
+- Search for `## Maintenance` header in each file
+- If missing:
+  - Use Edit tool to add at end of file:
+    ```markdown
+    ## Maintenance
+
+    **Last Updated:** [current date]
+
+    **Update Triggers:**
+    - [Document-specific triggers]
+
+    **Verification:**
+    - [ ] All sections have content (no placeholders)
+    - [ ] Diagrams render correctly
+    - [ ] Links to other docs are valid
+    ```
+  - Track violation count
+- Log: "✓ Maintenance sections: [added N/all present]"
+
+**2.4 Check POSIX file endings** (all created files):
+- Check if each file ends with single blank line
+- If missing:
+  - Use Edit tool to add final newline
+  - Track fix count
+- Log: "✓ POSIX compliance: [fixed N files/all compliant]"
+
+**2.5 Conditional checks**:
+- **api_spec.md**: Only validate if Backend/Full-stack project detected
+  - Skip validation if Frontend-only project
+  - Log: "ℹ api_spec.md skipped (Frontend-only project)"
+- **database_schema.md**: Only validate if database detected in dependencies
+  - Check package.json for database libraries (pg, mongoose, mysql2, sqlite3)
+  - Skip if no database found
+  - Log: "ℹ database_schema.md skipped (no database detected)"
+- **design_guidelines.md**: Only validate if Frontend framework detected
+  - Check package.json for frontend frameworks (react, vue, angular, svelte)
+  - Skip if Backend-only project
+  - Log: "ℹ design_guidelines.md skipped (Backend-only project)"
+
+**2.6 Report validation**:
+- Log summary:
+  ```
+  ✅ Structure validation complete:
+    - SCOPE tags: [added N/all present]
+    - Missing sections: [added N sections across M files/all present]
+    - Maintenance sections: [added N/all present]
+    - POSIX endings: [fixed N files/all compliant]
+    - Conditional checks: [skipped K files based on project type]
+  ```
+- If violations found: "⚠️ Auto-fixed [total] structural violations"
+
+---
+
+### Phase 3: Validate Content
+
+**Objective**: Ensure each section answers its questions with meaningful content using semantic validation.
+
+**Process**:
+
+**3.1 Load validation spec**:
+- Read `references/questions.md` using Read tool
+- Parse all 27 questions with validation heuristics, auto-discovery hints, and MCP Ref hints
+- Build validation map: {document → [{question, section, heuristics, auto_discovery, mcp_ref}]}
+
+**3.2 Validate sections** (parametric loop for ~27 questions):
+
+For each question in questions.md:
+
+1. **Extract section content**:
+   - Read target document (requirements.md, architecture.md, etc.)
+   - Extract section content between headers
+   - If section missing → error (should have been added in Phase 2.2)
+
+2. **Check if content answers question**:
+   - Apply validation heuristics from questions.md
+   - Examples:
+     - "Has FR-XXX identifiers" → scan for pattern `FR-\w+-\d+`
+     - "Length > 100 words" → count words in section
+     - "Has Mermaid diagram" → check for ```mermaid code blocks
+   - If ANY heuristic passes → content valid, skip to next question
+   - If ALL fail → content invalid, continue
+
+3. **Auto-discovery** (if content invalid or has placeholders):
+   - Execute auto-discovery hints from questions.md
+   - Examples:
+     - **package.json scanning**:
+       - Read package.json
+       - Extract dependencies, devDependencies, scripts, engines, version
+       - Identify frameworks (react → Frontend, express → Backend)
+     - **src/ directory structure**:
+       - Scan src/ using Glob tool
+       - Detect architecture patterns:
+         - `src/controllers/`, `src/services/`, `src/repositories/` → Layered architecture
+         - `src/modules/`, `src/features/` → Modular architecture
+         - `src/pages/`, `src/components/` → Frontend component structure
+     - **docker-compose.yml**:
+       - Read docker-compose.yml if exists
+       - Extract services (postgres, mongo, redis, rabbitmq)
+       - Populate tech_stack.md and database_schema.md sections
+     - **.env.example**:
+       - Read .env.example if exists
+       - Extract configuration variables
+       - Populate runbook.md environment variables section
+     - **migrations/ directory**:
+       - Scan migrations/ or db/migrations/
+       - Extract table names from CREATE TABLE statements
+       - Populate database_schema.md tables section
+   - If auto-discovery successful:
+     - Use Edit tool to populate section with discovered data
+     - Track change: `sections_populated += 1`
+     - Skip MCP Ref and user questions
+   - If auto-discovery fails → continue to MCP Ref
+
+4. **MCP Ref research** (if auto-discovery fails):
+   - Execute MCP Ref hints from questions.md
+   - Examples:
+     - Framework features: `mcp__context7__resolve-library-id("React")` → `mcp__context7__get-library-docs("/facebook/react", topic="React 18 features")`
+     - Architecture patterns: `mcp__Ref__ref_search_documentation("Layered architecture vs microservices")`
+     - Library standards: `mcp__Ref__ref_search_documentation("Repository pattern best practices")`
+     - Technology comparison: `mcp__Ref__ref_search_documentation("PostgreSQL vs MongoDB comparison")`
+   - If research yields useful information:
+     - Use Edit tool to populate section with research summary
+     - Track change: `sections_researched += 1`
+     - Skip user questions
+   - If research fails → continue to user fallback
+
+5. **User question fallback** (if auto-discovery AND MCP Ref fail):
+   - Ask user the question from questions.md
+   - Examples:
+     - "What are the main functional requirements?" (if no hints found)
+     - "What are the system quality goals?" (if no constraints discovered)
+     - "What is the primary architecture pattern?" (if src/ structure ambiguous)
+   - Wait for user response
+   - Use Edit tool to populate section with user's answer
+   - Track change: `sections_user_input += 1`
+
+6. **Track validation result**:
+   - Log per question: "[Document] Section X: [valid/populated via auto-discovery/populated via MCP Ref/populated via user input]"
+
+**3.3 Priority-based validation** (optimize token usage):
+- **Critical priority** (requirements.md, architecture.md, runbook.md):
+  - Validate all sections
+  - Ask user questions if auto-discovery/MCP Ref fail
+- **High priority** (tech_stack.md, api_spec.md, database_schema.md):
+  - Validate all sections
+  - Prefer auto-discovery and MCP Ref
+  - Only ask critical user questions
+- **Medium priority** (design_guidelines.md):
+  - Validate required sections only
+  - Skip if Frontend-only and user confirms can use template defaults
+
+**3.4 Report content validation**:
+- Log summary:
+  ```
+  ✅ Content validation complete:
+    - Questions checked: 27 (or 22 for backend-only, 24 for frontend-only)
+    - Already valid: [count] sections
+    - Populated via auto-discovery: [count] sections
+    - Populated via MCP Ref: [count] sections
+    - Populated via user input: [count] sections
+    - Placeholders kept: [count] sections (optional content)
+  ```
+
+**Auto-discovery success rate example**:
+```
+Full-stack Node.js project with package.json + docker-compose.yml:
+- Auto-discovery: ~18/27 questions (67%)
+- MCP Ref: ~5/27 questions (18%)
+- User input: ~4/27 questions (15%)
+```
+
+---
+
+### Phase 4: Finalization
+
+**Objective**: Provide complete overview and next steps.
+
+**Process**:
+1. List all project files with status (3-7 files depending on project type):
+   - `docs/project/requirements.md` (ALWAYS) - created or preserved
+   - `docs/project/architecture.md` (ALWAYS) - created or preserved
+   - `docs/project/tech_stack.md` (ALWAYS) - created or preserved
+   - `docs/project/api_spec.md` (if API/Backend/Full-stack) - created or preserved
+   - `docs/project/database_schema.md` (if uses database) - created or preserved
+   - `docs/project/design_guidelines.md` (if Frontend/Full-stack) - created or preserved
+   - `docs/project/runbook.md` (if Docker-based) - created or preserved
+
+2. Report summary:
+   - "✓ Project documentation complete: Created X new files, preserved Y existing"
+   - "Validation: Structure [N fixes], Content [M updates]"
+
+**Output**: Summary message with project files status (created vs preserved)
+
+---
+
+## Complete Output Structure
+
+```
+docs/
+└── project/
+    ├── requirements.md         # Functional Requirements (FR-XXX-NNN) ONLY
+    ├── architecture.md         # arc42-based architecture with C4 Model
+    ├── tech_stack.md          # Technology stack, versions, Docker setup
+    ├── api_spec.md            # API endpoints, auth, error codes (conditional)
+    ├── database_schema.md     # ER diagrams, tables, migrations (conditional)
+    ├── design_guidelines.md   # UI/UX design system (conditional - frontend only)
+    └── runbook.md             # Operations: local/testing/production (conditional)
+```
+
+**Conditional files:**
+- `api_spec.md` - Created for API/Backend/Full-stack projects
+- `database_schema.md` - Created if project uses database (PostgreSQL, MySQL, MongoDB, etc.)
+- `design_guidelines.md` - Created for Frontend/Full-stack projects (skipped for backend-only)
+- `runbook.md` - Created for Docker-based projects
+
+---
+
+## Reference Files Used
+
+### Document Templates
+
+**Project Document Templates** (used in Phase 1 from `references/templates/`):
+- `requirements_template.md` - Functional Requirements ONLY (ISO/IEC/IEEE 29148:2018)
+- `architecture_template.md` - arc42-based architecture with C4 Model (ISO/IEC/IEEE 42010:2022)
+- `tech_stack_template.md` - Technology stack, versions, Docker configuration
+- `api_spec_template.md` - API specification (OpenAPI 3.0 compatible)
+- `database_schema_template.md` - ER diagrams, data dictionary, migrations
+- `design_guidelines_template.md` - UI/UX design system (WCAG 2.1 Level AA)
+- `runbook_template.md` - Operations guide (local/testing/production)
+
+**Validation Specification**:
+- `references/questions.md` (v1.0) - 27 questions with validation heuristics:
+  - Questions each section must answer
+  - Validation heuristics (checkable criteria)
+  - Auto-discovery hints (package.json, src/, docker-compose.yml, migrations/)
+  - MCP Ref hints (external research topics)
+
+---
+
+## Best Practices
+
+- **Idempotent Operations**: ✅ Checks file existence before creation (Phase 1), creates only missing files, preserves existing project docs
+- **Conditional Templates**: Only create templates relevant to project type (skip design_guidelines.md for backend-only, skip api_spec.md for frontend-only)
+- **Parametric Validation**: Phase 3 uses loop for 27 questions (no code duplication)
+- **Auto-discovery First**: Scan actual files before external API calls or user questions
+- **Separation of Concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT → FINALIZE
+- **Document Generation**: English only, explicit IDs (FR-XXX-001), MoSCoW prioritization, meaningful Mermaid diagrams with actual data
+- **Token Efficiency**: Reuse discovered data across multiple documents, avoid asking same questions twice
+
+---
+
+## Prerequisites
+
+**Invoked by**: ln-110-documents-pipeline orchestrator
+
+**Requires**:
+- `docs/` directory (created by ln-111-root-docs-creator)
+
+**Creates**:
+- `docs/project/` directory structure (3-7 files)
+- Validated project documentation with structure and content checks
+
+**Idempotent**: ✅ Can be invoked multiple times safely
+- Checks file existence before creation
+- Skips existing files
+- Re-validates on subsequent runs
+
+---
+
+## Definition of Done
+
+Before completing work, verify ALL checkpoints:
+
+**✅ Documents Generated:**
+- [ ] All required project documents created successfully (3-7 files depending on project type):
+  - `docs/project/requirements.md` (ALWAYS)
+  - `docs/project/architecture.md` (ALWAYS)
+  - `docs/project/tech_stack.md` (ALWAYS)
+  - `docs/project/api_spec.md` (if API/Backend/Full-stack)
+  - `docs/project/database_schema.md` (if uses database)
+  - `docs/project/design_guidelines.md` (if Frontend/Full-stack)
+  - `docs/project/runbook.md` (if Docker-based)
+- [ ] SCOPE tags included in first 3-5 lines of each document
+- [ ] Maintenance sections present in all docs
+- [ ] All placeholders replaced with actual content (no `{{PLACEHOLDER}}` remaining)
+
+**✅ Content Quality:**
+- [ ] Mermaid diagrams valid syntax (Business Context, Technical Context, C4 diagrams, ER diagrams)
+- [ ] Requirement IDs sequential and unique (FR-XXX-001 only)
+- [ ] MoSCoW prioritization applied correctly (MUST/SHOULD/COULD/WON'T)
+- [ ] Language: English only (per project standards)
+- [ ] Docker configuration present in tech_stack.md
+
+**✅ Phase Completion:**
+- [ ] Phase 1: Create Structure completed
+  - [ ] Conditional templates determined (api_spec, database_schema, design_guidelines)
+  - [ ] Missing files created (3-7 based on project type)
+  - [ ] Created file list tracked
+- [ ] Phase 2: Validate Structure completed
+  - [ ] SCOPE tags verified/added (all created files)
+  - [ ] Required sections verified/added (from questions.md)
+  - [ ] Maintenance sections verified/added (all created files)
+  - [ ] POSIX file endings verified/fixed
+  - [ ] Conditional checks performed (api_spec, database_schema, design_guidelines)
+- [ ] Phase 3: Validate Content completed
+  - [ ] questions.md loaded for semantic validation
+  - [ ] All 27 questions validated (or 22/24 for specific project types)
+  - [ ] Auto-discovery executed where applicable
+  - [ ] MCP Ref research executed where needed
+  - [ ] User fallback questions asked for critical content
+  - [ ] Content validation report generated
+- [ ] Phase 4: Finalization completed
+  - [ ] Summary displayed with file paths and status
+
+**✅ User Guidance:**
+- [ ] Summary message displayed with all file paths
+- [ ] User informed: "✓ Project documentation complete (X files created)"
+
+**Output:** Complete project documentation set in `docs/project/` (3-7 MD docs depending on project type)
+
+---
+
+## Technical Details
+
+**Standards**: ISO/IEC/IEEE 29148:2018 (Requirements), ISO/IEC/IEEE 42010:2022 (Architecture), arc42, C4 Model, MoSCoW Prioritization, OWASP Security, WCAG 2.1 Level AA
+
+**Language**: English only
+
+---
+
+**Version:** 12.0.0 (MAJOR: Merged validation into worker. Added Phase 2 structure validation + Phase 3 semantic content validation with extensive auto-discovery (package.json, src/, docker-compose.yml, migrations/) and MCP Ref research. Idempotent - can be invoked multiple times.)
+**Last Updated:** 2025-11-18