zhongwei/gh-levnikolaevich-claude-code-skills-full-development-workflow-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-levnikolaevich-claude-co…/skills/ln-114-project-docs-creator/SKILL.md
Zhongwei Li 37774aa937 Initial commit
2025-11-30 08:37:27 +08:00

20 KiB
Raw Permalink Blame History

name, description
name description
ln-114-project-docs-creator 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: 
      ## 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

Reference in New Issue View Git Blame Copy Permalink