458 lines
20 KiB
Markdown
458 lines
20 KiB
Markdown
---
|
||
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
|