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
--- a/commands/c1-systems.md
+++ b/commands/c1-systems.md
@@ -0,0 +1,43 @@
+---
+description: Identify C1-level systems from repositories
+argument-hint: [init-json-path]
+allowed-tools: Task, Read, Bash
+---
+
+Analyze repositories and identify C1 systems using C4 methodology.
+
+## Context
+
+- Init file: ${1:-init.json}
+- Status: !`test -f "${1:-init.json}" && echo "✅ exists" || echo "❌ missing"`
+- Validation: ${CLAUDE_PLUGIN_ROOT}/validation/scripts/
+
+## Workflow
+
+Use the Task tool to launch the **c1-abstractor** agent with the following requirements:
+
+**Input**:
+- Read init.json (repository paths and metadata)
+- Apply C4 Level 1 methodology via c4model-c1 skill
+
+**Process**:
+- Analyze each repository for system boundaries
+- Identify systems, actors, and high-level relationships
+- Create system folder structure via create-folders.sh script
+- Generate observations with evidence (file:line references)
+- Map system relations (dependencies, communication)
+
+**Output**:
+- c1-systems.json with structure:
+  - metadata (timestamp, parent reference to init.json)
+  - systems[] (id, name, type, purpose, repository_path)
+  - observations[] (category, content, evidence)
+  - relations[] (from, to, type, protocol)
+
+After agent completes:
+- Validate output: `bash ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c1-systems.py c1-systems.json`
+- Report results: systems count, next step
+
+**Next step**: /melly-c2-containers
+
+See [docs/workflow-guide.md](../../docs/workflow-guide.md) for detailed usage examples.
--- a/commands/c2-containers.md
+++ b/commands/c2-containers.md
@@ -0,0 +1,70 @@
+---
+description: Identify C2-level containers (deployable units) from systems
+argument-hint: [init-json-path]
+allowed-tools: Task, Read, Bash
+---
+
+# Identify C2 Containers
+
+Analyze systems and identify C2-level containers (deployable/runnable units) using C4 Model methodology.
+
+## Context
+
+- Init file: ${1:-init.json}
+- C1 systems file: ${2:-c1-systems.json}
+- Status: !`test -f ${1:-init.json} && test -f ${2:-c1-systems.json} && echo "✓ Files exist" || echo "✗ Missing files"`
+
+## Prerequisites
+
+Before running this command:
+1. **Run /melly-init** first to generate init.json
+2. **Run /melly-c1-systems** to generate c1-systems.json
+
+## What This Command Does
+
+1. **Validates prerequisites** - Checks init.json and c1-systems.json exist
+2. **Launches c2-abstractor agent** - Applies C4 Level 2 methodology
+3. **Identifies containers** - Deployable units (SPA, API, databases, caches, etc.)
+4. **Detects technology stacks** - Languages, frameworks, libraries, versions
+5. **Analyzes runtime environments** - Where and how containers run
+6. **Maps communication** - How containers interact (REST, gRPC, database, etc.)
+7. **Generates c2-containers.json** - Structured output with observations and relations
+8. **Validates output** - Ensures schema compliance and referential integrity
+
+## Workflow
+
+Use the Task tool to launch the **c2-abstractor** agent with:
+- Input: init.json, c1-systems.json
+- Methodology: c4model-c2 skill (automatic activation)
+- Output: c2-containers.json
+
+After agent completes:
+- Validate: `cat c2-containers.json | python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c2-containers.py`
+- Report results summary
+- Suggest next step: `/melly-c3-components` or `/melly-doc-c4model`
+
+## Next Steps
+
+After successful completion:
+- **Option 1**: Run `/melly-c3-components` to analyze component structure
+- **Option 2**: Run `/melly-doc-c4model` to generate documentation
+- **Option 3**: Manually inspect `c2-containers.json` for accuracy
+
+## Troubleshooting
+
+- **Missing init.json**: Run `/melly-init` first
+- **Missing c1-systems.json**: Run `/melly-c1-systems` first
+- **Validation fails**: Check error messages, fix issues in c2-containers.json
+- **Timestamp errors**: Ensure c2 timestamp > c1 timestamp > init timestamp
+
+## Documentation
+
+For details on C4 Level 2 methodology:
+- **Methodology**: See `plugins/c4model-c2/skills/c4model-c2/SKILL.md`
+- **Schema**: See `${CLAUDE_PLUGIN_ROOT}/validation/templates/c2-containers-template.json`
+- **Validation**: See `${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c2-containers.py`
+- **Workflow**: See `docs/c4model-methodology.md`
+
+---
+
+**C2 Level Focus**: Deployable units, technology stacks, runtime environments, communication patterns
--- a/commands/c3-components.md
+++ b/commands/c3-components.md
@@ -0,0 +1,44 @@
+---
+description: Identify C3-level components from containers
+argument-hint: [c2-containers-json-path]
+allowed-tools: Task, Read, Bash
+---
+
+Analyze containers and identify C3 components using C4 Model methodology.
+
+## Context
+
+- Input: $1 (default: c2-containers.json)
+- Status: !`test -f ${1:-c2-containers.json} && echo "✓ exists" || echo "✗ missing"`
+- Prerequisites: !`test -f init.json && test -f c1-systems.json && echo "✓ ready" || echo "✗ run /melly-init and /melly-c1-systems and /melly-c2-containers first"`
+
+## Workflow
+
+**1. Validate Prerequisites**
+
+Check that init.json, c1-systems.json, and c2-containers.json exist.
+If missing, inform user to run previous commands first.
+
+**2. Launch c3-abstractor Agent**
+
+Use Task tool to launch c3-abstractor agent:
+- Input: c2-containers.json path (${1:-c2-containers.json})
+- Agent will validate files, load c4model-c3 skill, analyze containers, identify components, and generate c3-components.json
+- Applies C3 methodology automatically
+
+**3. Validate and Report**
+
+After agent completion:
+```bash
+python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c3-components.py c3-components.json
+```
+
+Report:
+- Components identified (count and breakdown by type/layer)
+- Validation status
+- Next step: /melly-doc-c4model
+
+## Output
+
+- **c3-components.json** - Components with observations, relations, metrics
+- **Validation report** - Structure and dependency validation
--- a/commands/c4-code.md
+++ b/commands/c4-code.md
@@ -0,0 +1,44 @@
+---
+description: Identify C4-level code elements from components
+argument-hint: [c3-components-json-path]
+allowed-tools: Task, Read, Bash
+---
+
+Analyze components and identify C4 code elements using C4 Model methodology.
+
+## Context
+
+- Input: $1 (default: c3-components.json)
+- Status: !`test -f ${1:-c3-components.json} && echo "✓ exists" || echo "✗ missing"`
+- Prerequisites: !`test -f init.json && test -f c1-systems.json && test -f c2-containers.json && test -f c3-components.json && echo "✓ ready" || echo "✗ run /melly:init, /melly:c1-systems, /melly:c2-containers, and /melly:c3-components first"`
+
+## Workflow
+
+**1. Validate Prerequisites**
+
+Check that init.json, c1-systems.json, c2-containers.json, and c3-components.json exist.
+If missing, inform user to run previous commands first.
+
+**2. Launch c4-abstractor Agent**
+
+Use Task tool to launch c4-abstractor agent:
+- Input: c3-components.json path (${1:-c3-components.json})
+- Agent will validate files, load c4model-c4 skill, analyze components, identify code elements, and generate c4-code.json
+- Applies C4 methodology automatically
+
+**3. Validate and Report**
+
+After agent completion:
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c4-code.py c4-code.json
+```
+
+Report:
+- Code elements identified (count and breakdown by type/component)
+- Validation status
+- Next step: /melly:doc-c4model
+
+## Output
+
+- **c4-code.json** - Code elements with observations, relations, metrics
+- **Validation report** - Structure and relationship validation
--- a/commands/doc-c4model.md
+++ b/commands/doc-c4model.md
@@ -0,0 +1,67 @@
+---
+description: Generate C4 model markdown documentation from JSON files
+argument-hint: [level]
+allowed-tools: Task, Read, Bash
+---
+
+Generate structured markdown documentation from C4 model JSON files.
+
+## Context
+
+- Level: $1 (or "all" if not specified)
+- JSON files status: !`test -f init.json && test -f c1-systems.json && test -f c2-containers.json && test -f c3-components.json && echo "✓ All present" || echo "✗ Missing files"`
+- Last generation: !`test -f .melly-doc-metadata.json && jq -r '.last_generation' .melly-doc-metadata.json || echo "Never"`
+
+## Workflow
+
+Use the Task tool to launch the c4model-writer agent to:
+1. Detect basic-memory project root (auto-selects from ~/.basic-memory/config.json or uses fallback)
+2. Validate all required JSON files exist
+3. Apply C4 markdown templates
+4. Generate documentation to detected project location
+5. Run validation on generated files
+
+**Agent invocation:**
+```
+Level: ${1:-all}
+Force regenerate: false (incremental updates enabled)
+Output: Auto-detected project root (see agent output for location)
+```
+
+**Project Detection:**
+- Single project: Auto-selected automatically
+- Multiple projects: Uses default_project from config or BASIC_MEMORY_PROJECT_ROOT env var
+- No config: Falls back to ./knowledge-base in current directory
+
+## After Completion
+
+The agent will report:
+- Project name and root path used
+- Entities processed (new/modified/unchanged)
+- Generated file paths
+- Validation results
+
+**Validation:**
+```bash
+# Validate generated markdown (if needed)
+# Use the project root path reported by the agent
+python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-markdown.py {project-root}/systems/**/*.md
+```
+
+**Basic-Memory Indexing (Optional):**
+If you want generated files indexed in basic-memory for semantic search:
+```bash
+# One-time sync
+basic-memory sync
+
+# Or continuous watching (recommended)
+basic-memory sync --watch
+```
+
+**Next steps:**
+- Review generated documentation in the reported project root
+- Optionally sync with basic-memory for searchable knowledge
+- Run `/melly-draw-c4model` to create visualizations
+- Commit documentation to repository
+
+For detailed usage, see [docs/workflow-guide.md](../../../docs/workflow-guide.md)
--- a/commands/draw-c4model.md
+++ b/commands/draw-c4model.md
@@ -0,0 +1,71 @@
+---
+description: Generate C4 model diagrams (Mermaid + Obsidian canvas) from JSON files
+argument-hint: [level]  # c1, c2, c3, or all
+allowed-tools: Task, Read, Bash
+---
+
+Generate visual diagrams from C4 model JSON files.
+
+## Context
+
+Level: $1 (default: all)
+Available levels: c1 (systems), c2 (containers), c3 (components), all
+
+## Prerequisites
+
+Check JSON files:
+- init.json: !`test -f init.json && echo "✅ exists" || echo "❌ missing"`
+- c1-systems.json: !`test -f c1-systems.json && echo "✅ exists" || echo "❌ missing"`
+- c2-containers.json: !`test -f c2-containers.json && echo "✅ exists" || echo "❌ missing"`
+- c3-components.json: !`test -f c3-components.json && echo "✅ exists" || echo "❌ missing"`
+
+## Workflow
+
+1. **Validate Input**
+   - Level: ${1:-all}
+   - If level specified, check corresponding JSON exists
+   - If "all", check all JSON files exist
+
+2. **Launch c4model-drawer Agent**
+   - Use Task tool to invoke c4model-drawer agent
+   - Pass level parameter: ${1:-all}
+   - Agent will:
+     - Parse JSON files
+     - Generate Mermaid diagrams
+     - Create Obsidian canvas files
+     - Save to knowledge-base/systems/*/diagrams/
+
+3. **Report Results**
+   - List generated diagram files
+   - Show statistics (entities, relations)
+   - Display any errors or warnings
+
+## Output
+
+Generated files:
+- Mermaid diagrams: `knowledge-base/systems/{system}/diagrams/c{1,2,3}-*.md`
+- Canvas files: `knowledge-base/systems/{system}/diagrams/c{1,2,3}-*.canvas`
+
+## Next Steps
+
+After generation:
+- Open diagrams in Obsidian for visualization
+- Review system architecture visually
+- Share diagrams with team
+- Export to PNG/SVG if needed
+
+## Examples
+
+```bash
+# Generate all diagrams
+/melly-draw-c4model all
+
+# Generate only C1 system context
+/melly-draw-c4model c1
+
+# Generate C2 containers
+/melly-draw-c4model c2
+
+# Generate C3 components
+/melly-draw-c4model c3
+```
--- a/commands/init.md
+++ b/commands/init.md
@@ -0,0 +1,33 @@
+---
+description: Initialize C4 model exploration - scan repositories and generate init.json
+argument-hint: [repository-path]
+allowed-tools: Task, Read, Write, Bash
+---
+
+Initialize C4 model exploration by scanning repositories and generating init.json.
+
+## Context
+
+- Repository path: ${1:-.} (current directory if not specified)
+- Repository exists: !`test -d "${1:-.}" && echo "yes" || echo "no"`
+- Existing init.json: !`test -f init.json && echo "found ($(stat -c%y init.json | cut -d' ' -f1))" || echo "none"`
+
+## Workflow
+
+Use the Task tool to launch the c4model-explorer agent with:
+- Repository root path: ${1:-.}
+- Output file: init.json
+
+The agent will:
+1. Scan all repositories in the specified location
+2. Identify package manifests and technology stacks
+3. Generate init.json with metadata and structure
+
+After agent completes:
+- Validate output: `python3 ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-init.py < init.json`
+- Review init.json for accuracy
+- Suggest next step: /melly-c1-systems
+
+## Notes
+
+See [docs/workflow-guide.md](../../../docs/workflow-guide.md) for detailed usage examples.