Initial commit

2025-11-29 18:17:07 +08:00
commit c0cd55ad8d
55 changed files with 15836 additions and 0 deletions
--- a/commands/analyze-lib-docs.md
+++ b/commands/analyze-lib-docs.md
@@ -0,0 +1,274 @@
+---
+description: Analyze library documentation and extract metadata for semantic search
+argument-hint: [library-name] [docs-path]
+allowed-tools: Task, Read, Write, Bash, Glob, Grep
+---
+
+# Library Documentation Analysis
+
+Analyze markdown-based library documentation and extract observations and relations for semantic search.
+
+## Arguments
+
+- `$1` - **Library name** (required): Name of the library (e.g., laravel, react, django)
+- `$2` - **Documentation path** (optional): Path to library docs
+  - Default: `knowledge-base/libraries/$1/`
+  - Supports absolute or relative paths
+
+## Workflow
+
+<!-- markdownlint-disable MD029 -->
+
+### Phase 1: Validation
+
+1. **Validate arguments**:
+   - Library name is required
+   - If no path provided, use default: `knowledge-base/libraries/$1/`
+   - Verify documentation path exists
+   - Check for markdown files in path
+
+2. **Verify dependencies**:
+   - basic-memory MCP server is available
+   - Validation scripts exist in plugin
+
+### Phase 2: Analysis
+
+3. **Invoke lib-doc-analyzer agent**:
+
+   Explicitly invoke the lib-doc-analyzer agent to perform the analysis:
+
+   ```
+   Use the lib-doc-analyzer agent to analyze the $1 library documentation.
+   
+   Agent context:
+   - Library name: $1
+   - Documentation path: $2 (or knowledge-base/libraries/$1/ if not specified)
+   - Task: Analyze all markdown files and extract observations and relations
+   - Skill: Use the lib-doc-methodology skill for guidance
+   ```
+
+   **Alternative invocation patterns:**
+
+   ```
+   Have the lib-doc-analyzer agent process the library documentation at $2.
+   Extract metadata from $1 documentation using the lib-doc-analyzer agent.
+   Ask lib-doc-analyzer to analyze library docs for $1 at $2.
+   ```
+
+   **What the agent will do:**
+   - Automatically follow the 5-phase workflow defined in its system prompt
+   - Use the lib-doc-methodology skill for extraction rules
+   - Generate enhanced markdown files with frontmatter
+   - Create lib-docs-$1.json metadata file
+   - Run validation scripts to verify quality
+
+
+4. **Agent performs 5-phase workflow**:
+   - Discovery: Find all markdown files
+   - Parsing: Extract structure (headings, code, links)
+   - Analysis: Extract observations and relations
+   - Generation: Create enhanced markdown files
+   - Validation: Verify content preservation
+
+### Phase 3: Validation
+
+5. **Run validation scripts**:
+   ```bash
+   # Validate metadata JSON
+   python3 plugins/melly-writer-lib/scripts/validate-lib-docs.py lib-docs-$1.json
+   
+   # Verify content preservation
+   python3 plugins/melly-writer-lib/scripts/validate-content.py $2
+   ```
+
+6. **Check validation results**:
+   - Exit code 0: Success
+   - Exit code 1: Warnings (continue with caution)
+   - Exit code 2: Blocking errors (stop workflow)
+
+### Phase 4: Integration
+
+7. **Store in basic-memory**:
+   - Create knowledge entities for each enhanced markdown file
+   - Include metadata (observations, relations) in entity
+   - Generate permalinks for cross-referencing
+
+8. **Generate metadata file**:
+   - Create `lib-docs-$1.json` with complete metadata
+   - Include library info, entities, relationships, statistics
+   - Store in documentation path
+
+### Phase 5: Reporting
+
+9. **Generate summary report**:
+   ```
+   ✅ Library Documentation Analysis Complete
+   
+   Library: [Library Name Version]
+   Path: [Documentation Path]
+   ---
+   📊 Statistics:
+     Files processed: [count]
+     Observations: [count]
+     Relations: [count]
+     Total chunks: [count]
+     Avg chunk size: [words]
+   
+   📁 Output:
+     Enhanced files: [path]/**/*.md
+     Metadata: lib-docs-[name].json
+     basic-memory entities: [count] created
+   
+   ✅ Validation:
+     Content preservation: [passed/total] passed
+     Metadata quality: Valid
+   
+   💡 Next Steps:
+     1. Search: "What is [concept] in [library]?"
+     2. Build context: "Show me [library] [topic] concepts"
+     3. Navigate: Open enhanced markdown files in Obsidian
+   ```
+
+## Examples
+
+```bash
+# Analyze Laravel documentation (default path)
+/melly-analyze-lib-docs laravel
+
+# Analyze React documentation (default path)
+/melly-analyze-lib-docs react
+
+# Analyze Django with custom path
+/melly-analyze-lib-docs django /path/to/django-docs
+
+# Analyze Laravel 11.x with explicit path
+/melly-analyze-lib-docs laravel-11 knowledge-base/libraries/laravel-11/
+```
+
+## Error Handling
+
+### Missing library name:
+```
+❌ Error: Library name is required
+Usage: /melly-analyze-lib-docs [library-name] [docs-path]
+Example: /melly-analyze-lib-docs laravel
+```
+
+### Documentation path not found:
+```
+❌ Error: Documentation path not found
+Path: knowledge-base/libraries/[name]/
+Please ensure the documentation exists or provide a custom path.
+```
+
+### No markdown files found:
+```
+❌ Error: No markdown files found in documentation path
+Path: [path]
+Expected: At least one .md file in the directory
+```
+
+### Validation failure:
+```
+❌ Validation Error: Content preservation failed
+File: [filename]
+Issue: Enhanced content differs from original
+Action: Review agent output and try again
+```
+
+### basic-memory unavailable:
+```
+⚠️  Warning: basic-memory MCP server not available
+Analysis will continue, but entities won't be stored for semantic search.
+Metadata will still be generated in lib-docs-[name].json
+```
+
+## Output Structure
+
+### Enhanced Markdown Files
+Each original markdown file is enhanced with:
+- **Frontmatter**: Library metadata (name, version, url, file info)
+- **Metadata Section**: Observations and relations extracted from content
+- **Separator**: `---` to separate metadata from original content
+- **Original Content**: 100% preserved, byte-for-byte identical
+
+### Metadata JSON File
+`lib-docs-[library-name].json` contains:
+- **library**: Library information (name, version, url, stats)
+- **entities**: Array of enhanced files with metadata
+- **relationships**: Cross-file relations discovered
+- **analyzed_at**: Timestamp of analysis
+
+### basic-memory Entities
+Each enhanced markdown file becomes a searchable entity:
+- **Content**: Original markdown content
+- **Metadata**: Observations and relations
+- **Permalink**: Stable reference for cross-linking
+
+## Best Practices
+
+1. **Organize documentation**:
+   - Use standard path: `knowledge-base/libraries/[name]/`
+   - Keep original structure (don't flatten)
+   - Preserve version information
+
+2. **Incremental updates**:
+   - Re-analyze when docs are updated
+   - Metadata will be regenerated
+   - basic-memory entities will be updated
+
+3. **Quality validation**:
+   - Always review validation output
+   - Check content preservation results
+   - Verify observations are extracted, not fabricated
+
+4. **Semantic search**:
+   - Use natural language queries
+   - Reference concepts by name
+   - Build context from multiple entities
+
+5. **Integration with C4 model**:
+   - Library docs inform C2 (Container) analysis
+   - Technical decisions reference library capabilities
+   - Architectural patterns link to library features
+
+## Troubleshooting
+
+### Agent doesn't activate
+**Cause**: lib-doc-analyzer agent not found
+**Solution**: Ensure agent exists in `plugins/melly-writer-lib/agents/`
+
+### Skill not used
+**Cause**: lib-doc-methodology skill not loaded
+**Solution**: Check `plugins/melly-writer-lib/skills/lib-doc-methodology/SKILL.md` exists
+
+### Validation scripts fail
+**Cause**: Python version incompatibility or missing dependencies
+**Solution**:
+- Ensure Python 3.8+ is installed: `python3 --version`
+- Make scripts executable: `chmod +x plugins/melly-writer-lib/scripts/*.py`
+- Install required packages (see plugin README.md)
+
+### basic-memory errors
+**Cause**: MCP server configuration issue
+**Solution**: Verify basic-memory in `~/.claude/settings.json`
+
+## Dependencies
+
+- **Agent**: lib-doc-analyzer
+- **Skill**: lib-doc-methodology
+- **Scripts**: validate-lib-docs.py, validate-content.py
+- **MCP Server**: basic-memory (optional but recommended)
+- **Python**: 3.8+ with required packages
+
+## Related Commands
+
+- `/melly-init` - Initialize C4 model exploration
+- `/melly-c2-containers` - Analyze C2 containers (uses library knowledge)
+- `/melly-doc-c4model` - Generate C4 documentation (references library docs)
+
+---
+
+**Version**: 1.0.0
+**Plugin**: melly-writer-lib
+**Category**: knowledge-extraction