claude_memory 0.2.0 → 0.3.0

data/.claude/skills/study-repo/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: study-repo
+description: Deep analysis of an external repository's architecture, patterns, and design decisions. Generates comprehensive influence document and updates improvements.md with prioritized recommendations.
+agent: general-purpose
+allowed-tools: Read, Grep, Glob, Bash
+disable-model-invocation: false
+argument-hint: [repo-path] [--focus=aspect]
+---
+
+# Repository Study Skill
+
+Deep analysis of external repositories to identify patterns, architecture decisions, and opportunities for adoption in ClaudeMemory.
+
+## Prerequisites
+
+Before running this skill, clone the repository you want to study:
+
+```bash
+# For public repos
+git clone https://github.com/user/project /tmp/study-repos/project-name
+
+# For private repos (requires gh CLI)
+gh repo clone user/project /tmp/study-repos/project-name
+
+# Use --depth 1 for speed (recommended)
+git clone --depth 1 https://github.com/user/project /tmp/study-repos/project-name
+```
+
+Then invoke: `/study-repo /tmp/study-repos/project-name`
+
+**Optional Focus Mode**: Narrow analysis to specific aspect
+```bash
+/study-repo /tmp/study-repos/project-name --focus="MCP implementation"
+/study-repo /tmp/study-repos/project-name --focus="testing strategy"
+```
+
+See `.claude/skills/study-repo/focus-examples.md` for more examples.
+
+## Analysis Phases
+
+Follow these phases systematically to ensure comprehensive coverage:
+
+### Phase 1: Repository Context (10 minutes)
+
+**Goal**: Understand project purpose, maturity, and ecosystem
+
+**Tasks**:
+1. Read README.md, CHANGELOG.md, LICENSE
+2. Examine gemspec/package.json for dependencies and metadata
+3. Check GitHub metadata (stars, issues, PRs, contributors)
+4. Review CI configuration (.github/workflows/, .gitlab-ci.yml)
+5. Check documentation structure (docs/, wiki)
+
+**Output**: Executive Summary section with:
+- Project purpose (1-2 sentences)
+- Key innovation (what makes it unique)
+- Technology stack table
+- Production readiness assessment
+
+### Phase 2: Architecture Mapping (15 minutes)
+
+**Goal**: Map high-level structure and module organization
+
+**Tasks**:
+1. Run `tree -L 3 -d` to understand directory structure
+2. Identify entry points (bin/, exe/, main files)
+3. Map core modules and their responsibilities
+4. Identify data model (database schema, structs, classes)
+5. Document dependencies between modules
+
+**Output**: Architecture Overview section with:
+- Data model description
+- Design patterns identified
+- Module organization diagram (text-based)
+- Comparison table vs ClaudeMemory
+
+### Phase 3: Pattern Recognition (20 minutes)
+
+**Goal**: Identify key design patterns and conventions
+
+**Tasks**:
+1. Search for common patterns:
+   - Dependency injection
+   - Command pattern
+   - Repository pattern
+   - Factory pattern
+   - Observer pattern
+2. Review naming conventions
+3. Check error handling approaches
+4. Examine configuration management
+5. Identify testing patterns
+
+**Output**: Key Components Deep-Dive with:
+- Component purpose
+- Code examples with file:line references
+- Design decision rationale
+
+### Phase 4: Code Quality Assessment (15 minutes)
+
+**Goal**: Evaluate testing, documentation, and performance
+
+**Tasks**:
+1. Analyze test coverage and structure
+2. Review documentation quality
+3. Check for performance optimizations
+4. Examine logging and observability
+5. Look for code quality tools (linters, formatters)
+
+**Output**: Comparative Analysis section with:
+- What they do well (with evidence)
+- What we do well (our advantages)
+- Trade-offs table
+
+### Phase 5: Comparative Analysis (15 minutes)
+
+**Goal**: Compare their approach with ClaudeMemory's
+
+**Tasks**:
+1. For each major component, compare:
+   - Their implementation
+   - Our implementation
+   - Pros/cons of each approach
+2. Identify areas where they excel
+3. Identify areas where we excel
+4. Document fundamental architectural differences
+
+**Output**: Enhanced Comparative Analysis with:
+- Side-by-side comparison
+- Trade-off analysis
+- Context for adoption decisions
+
+### Phase 6: Adoption Opportunities (20 minutes)
+
+**Goal**: Extract actionable recommendations with priorities
+
+**Tasks**:
+1. List all potential adoptions
+2. For each, assess:
+   - Value (quantified benefit)
+   - Effort (implementation complexity)
+   - Risk (compatibility, maintenance)
+   - Fit (alignment with our architecture)
+3. Prioritize as High ⭐ / Medium / Low
+4. Identify features to avoid
+5. Propose implementation phases
+
+**Output**: Adoption Opportunities section with:
+- High Priority ⭐ items (adopt soon)
+- Medium Priority items (consider)
+- Low Priority items (defer)
+- Features to Avoid (with reasoning)
+- Implementation Recommendations (phased plan)
+
+## Output Format
+
+Generate a comprehensive influence document following this structure (see `.claude/skills/study-repo/analysis-template.md` for full template):
+
+```markdown
+# [Project Name] Analysis
+
+*Analysis Date: YYYY-MM-DD*
+*Repository: GitHub URL*
+*Version/Commit: tag or SHA*
+
+---
+
+## Executive Summary
+[Project purpose, key innovation, tech stack, maturity]
+
+## Architecture Overview
+[Data model, design patterns, module organization, comparison table]
+
+## Key Components Deep-Dive
+[Component 1, Component 2, etc. with code examples and file:line references]
+
+## Comparative Analysis
+[What they do well, what we do well, trade-offs]
+
+## Adoption Opportunities
+
+### High Priority ⭐
+#### 1. [Feature]
+- **Value**: [Benefit]
+- **Evidence**: [file:line proof]
+- **Implementation**: [Approach]
+- **Effort**: [Estimate]
+- **Trade-off**: [Costs]
+- **Recommendation**: ADOPT / CONSIDER / DEFER
+
+[Medium and Low sections follow]
+
+### Features to Avoid
+[With reasoning]
+
+## Implementation Recommendations
+[Phase 1, Phase 2, etc.]
+
+## Architecture Decisions
+[What to preserve, adopt, reject]
+
+## Key Takeaways
+[Main learnings and next steps]
+```
+
+**Critical Requirements**:
+- All claims must include file:line references
+- Code examples for key patterns
+- Priority markers (⭐) on High Priority items
+- Comparison table vs ClaudeMemory
+- Quantified benefits where possible
+- Clear ADOPT/CONSIDER/DEFER recommendations
+
+## Integration with improvements.md
+
+After creating the influence document, update `docs/improvements.md`:
+
+1. **Extract High Priority items** (⭐ marked) from influence doc
+2. **Format as new section**:
+   ```markdown
+   ## [Project Name] Study (YYYY-MM-DD)
+
+   Source: docs/influence/[project-name].md
+
+   ### High Priority Recommendations
+
+   - [ ] **[Feature 1]**: [Brief description]
+     - Value: [Quantified benefit]
+     - Evidence: [file:line from their repo]
+     - Effort: [Estimate]
+
+   - [ ] **[Feature 2]**: [...]
+   ```
+3. **Append to improvements.md** preserving existing structure
+4. **Update "Last updated" timestamp** at top of file
+
+## Success Criteria
+
+The analysis is complete when all of these are verified:
+
+- ✅ `docs/influence/<project_name>.md` created with all sections
+- ✅ Executive Summary includes project metadata and tech stack
+- ✅ Architecture Overview has comparison table vs ClaudeMemory
+- ✅ Key Components include code examples with file:line references
+- ✅ All major claims have evidence citations
+- ✅ Adoption Opportunities use ⭐ for High Priority items
+- ✅ Each opportunity has Value/Evidence/Implementation/Effort/Trade-off
+- ✅ Clear ADOPT/CONSIDER/DEFER recommendations given
+- ✅ Implementation Recommendations organized in phases
+- ✅ Trade-offs section discusses costs and risks
+- ✅ `docs/improvements.md` updated with new dated section
+- ✅ High priority items extracted and formatted as tasks
+- ✅ Existing improvements.md structure preserved
+- ✅ Console summary shows key findings
+
+## Focus Mode
+
+When `--focus` flag is provided, narrow the analysis:
+
+1. **Parse focus topic** from arguments
+2. **Filter files** to only relevant ones:
+   - For "testing": test/, spec/, .github/workflows/
+   - For "MCP": mcp/, server/, tools/
+   - For "database": schema, migrations, queries
+   - For "CLI": bin/, exe/, commands/
+3. **Narrow exploration** to focused aspect
+4. **Target recommendations** to focused area
+5. **Faster execution** with reduced scope
+
+See `.claude/skills/study-repo/focus-examples.md` for detailed examples.
+
+## Error Handling
+
+Handle common error cases gracefully:
+
+- **Invalid path**: Display clear error with example usage
+- **Empty directory**: Warn about missing files
+- **No README**: Note absence but continue analysis
+- **Large repo**: Suggest using `--focus` flag
+- **Permission issues**: Check file permissions and suggest fixes
+
+## Execution Steps
+
+1. **Parse arguments**: Extract repo path and optional focus
+2. **Validate path**: Check directory exists and is readable
+3. **Detect project name**: Extract from path or .git/config
+4. **Run analysis phases**: Follow Phase 1-6 systematically
+5. **Generate influence doc**: Use template with collected data
+6. **Update improvements.md**: Extract and append High Priority items
+7. **Display summary**: Show key findings and output locations
+8. **Exit with success**: Return 0 if complete
+
+## Integration with /improve
+
+The recommendations added to `docs/improvements.md` can be implemented using `/improve`:
+
+```bash
+# Study external project
+/study-repo /tmp/study-repos/some-project
+
+# Review recommendations
+cat docs/influence/some-project.md
+
+# Implement selected improvements
+/improve
+```
+
+This creates a complete workflow: `/study-repo` → recommendations → `/improve` → implementation

data/.claude/skills/study-repo/analysis-template.md

@@ -0,0 +1,323 @@
+# [Project Name] Analysis
+
+*Analysis Date: [YYYY-MM-DD]*
+*Repository: [GitHub URL]*
+*Version/Commit: [tag or SHA]*
+
+---
+
+## Executive Summary
+
+### Project Purpose
+[1-2 sentence description of what this project does and why it exists]
+
+### Key Innovation
+[What makes this project unique or interesting? What novel approach does it take?]
+
+### Technology Stack
+- **Language**: [Primary language(s) and version]
+- **Framework**: [Key frameworks used]
+- **Dependencies**: [Major libraries/gems]
+- **Database**: [If applicable]
+- **Special Tools**: [Unique tooling, build systems, etc.]
+
+### Production Readiness
+- **Maturity**: [Alpha / Beta / Stable / Production-grade]
+- **Test Coverage**: [Percentage if available, or qualitative assessment]
+- **Documentation**: [Quality and completeness]
+- **Community**: [GitHub stars, contributors, maintenance activity]
+- **Known Issues**: [Critical bugs or limitations]
+
+---
+
+## Architecture Overview
+
+### Data Model
+[How data is structured and stored. Schema, entities, relationships.]
+
+```ruby
+# Example from [file:line]
+class Example
+  # ...
+end
+```
+
+### Design Patterns
+[Key architectural patterns identified:]
+- **Pattern 1**: [Description and usage]
+- **Pattern 2**: [Description and usage]
+
+### Module Organization
+```
+project/
+├── core/           # [Purpose]
+├── adapters/       # [Purpose]
+├── infrastructure/ # [Purpose]
+└── application/    # [Purpose]
+```
+
+[Explain component relationships and boundaries]
+
+### Comparison with ClaudeMemory
+
+| Aspect | [Project] | ClaudeMemory | Notes |
+|--------|-----------|--------------|-------|
+| **Data Model** | [Their approach] | [Our approach] | [Key differences] |
+| **Storage** | [Their tech] | [Our tech] | [Trade-offs] |
+| **Search** | [Their method] | [Our method] | [Performance implications] |
+| **CLI Design** | [Their pattern] | [Our pattern] | [Usability comparison] |
+| **Testing** | [Their strategy] | [Our strategy] | [Coverage comparison] |
+| **Error Handling** | [Their approach] | [Our approach] | [Robustness comparison] |
+
+---
+
+## Key Components Deep-Dive
+
+### Component 1: [Name]
+
+**Purpose**: [What this component does and why it exists]
+
+**Location**: `path/to/component/`
+
+**Implementation**:
+```[language]
+# From [file:line]
+class ComponentExample
+  def key_method
+    # Critical logic
+  end
+end
+```
+
+**Design Decisions**:
+- [Why implemented this way]
+- [What alternatives were rejected]
+- [Trade-offs made]
+
+**Dependencies**: [What it depends on]
+
+**Testing**: [How it's tested]
+
+---
+
+### Component 2: [Name]
+
+**Purpose**: [...]
+
+**Location**: `path/to/component/`
+
+**Implementation**:
+```[language]
+# From [file:line]
+```
+
+**Design Decisions**: [...]
+
+---
+
+### Component 3: [Name]
+
+[Repeat structure for each major component]
+
+---
+
+## Comparative Analysis
+
+### What They Do Well
+
+#### 1. [Feature/Approach]
+- **Description**: [What they do]
+- **Evidence**: [file:line references]
+- **Why It Works**: [Analysis of benefits]
+- **Metrics**: [Quantifiable improvements if available]
+
+#### 2. [Feature/Approach]
+[Repeat structure]
+
+---
+
+### What We Do Well
+
+#### 1. [Feature/Approach]
+- **Description**: [What we do]
+- **Evidence**: [file references from our codebase]
+- **Our Advantage**: [Why our approach is strong]
+- **Context**: [When our approach excels]
+
+#### 2. [Feature/Approach]
+[Repeat structure]
+
+---
+
+### Trade-offs
+
+| Approach | Pros | Cons | Best For |
+|----------|------|------|----------|
+| **Their approach to X** | [Benefits] | [Costs] | [Use cases] |
+| **Our approach to X** | [Benefits] | [Costs] | [Use cases] |
+
+---
+
+## Adoption Opportunities
+
+### High Priority ⭐
+
+#### 1. [Feature Name]
+- **Value**: [Quantified benefit - e.g., "50% faster queries", "eliminates N+1 issues"]
+- **Evidence**: [Proof from their codebase with file:line references]
+- **Implementation**: [High-level approach to adopt in our codebase]
+- **Effort**: [Rough estimate in developer-days]
+- **Trade-off**: [What we give up or risk]
+- **Recommendation**: **ADOPT** / CONSIDER / DEFER
+- **Integration Points**: [Which of our files/modules would change]
+
+#### 2. [Feature Name]
+[Same structure]
+
+---
+
+### Medium Priority
+
+#### 1. [Feature Name]
+- **Value**: [Benefit]
+- **Evidence**: [file:line]
+- **Implementation**: [Approach]
+- **Effort**: [Estimate]
+- **Trade-off**: [Costs]
+- **Recommendation**: ADOPT / **CONSIDER** / DEFER
+- **Integration Points**: [...]
+
+---
+
+### Low Priority
+
+#### 1. [Feature Name]
+- **Value**: [Minor benefit]
+- **Evidence**: [file:line]
+- **Implementation**: [Approach]
+- **Effort**: [Estimate]
+- **Trade-off**: [Costs]
+- **Recommendation**: ADOPT / CONSIDER / **DEFER**
+- **Reason to Defer**: [Why not now]
+
+---
+
+### Features to Avoid
+
+#### 1. [Feature Name]
+- **What It Is**: [Description]
+- **Why Avoid**: [Clear reasoning - complexity, maintenance burden, poor fit]
+- **Our Alternative**: [What we have or should do instead]
+- **Evidence**: [Issues, complexity metrics, or design conflicts]
+
+#### 2. [Feature Name]
+[Same structure]
+
+---
+
+## Implementation Recommendations
+
+### Phase 1: [Name] (Timeframe: [e.g., 1-2 weeks])
+
+**Goals**: [What this phase accomplishes]
+
+**Tasks**:
+- [ ] [Task 1 - specific and measurable]
+- [ ] [Task 2]
+- [ ] [Task 3]
+
+**Success Criteria**:
+- [How to verify phase completion]
+- [Metrics or tests to validate]
+
+**Risks**: [What could go wrong]
+
+---
+
+### Phase 2: [Name] (Timeframe: [e.g., 2-3 weeks])
+
+**Goals**: [...]
+
+**Tasks**:
+- [ ] [Task 1]
+- [ ] [Task 2]
+
+**Success Criteria**: [...]
+
+**Risks**: [...]
+
+**Dependencies**: [What from Phase 1 must complete first]
+
+---
+
+### Phase 3: [Name] (Timeframe: [...])
+
+[Continue for additional phases]
+
+---
+
+## Architecture Decisions
+
+### What to Preserve
+
+These aspects of our architecture should be maintained:
+
+- **[Our Feature]**: [Why keep it - benefits, stability, fit]
+- **[Our Pattern]**: [Why preserve - maintainability, clarity]
+
+### What to Adopt
+
+These aspects of their architecture should be integrated:
+
+- **[Their Feature]**: [Why adopt - clear benefits outweigh costs]
+- **[Their Pattern]**: [Why take - proven approach, better fit]
+
+### What to Reject
+
+These aspects of their architecture don't fit our needs:
+
+- **[Their Feature]**: [Why reject - complexity, poor fit, better alternatives]
+- **[Their Pattern]**: [Why avoid - maintenance burden, unclear benefits]
+
+---
+
+## Key Takeaways
+
+### Main Learnings
+1. [Primary insight from analysis]
+2. [Secondary insight]
+3. [Pattern or approach worth remembering]
+
+### Recommended Adoption Order
+1. **First**: [Feature] - [Why start here]
+2. **Second**: [Feature] - [Why next]
+3. **Third**: [Feature] - [Why later]
+
+### Expected Impact
+- **Performance**: [Quantified if possible]
+- **Maintainability**: [Qualitative assessment]
+- **Feature Completeness**: [What new capabilities we gain]
+- **Developer Experience**: [How it improves our workflow]
+
+### Next Actions
+- [ ] Review findings with team
+- [ ] Prioritize recommendations
+- [ ] Update `docs/improvements.md`
+- [ ] Begin Phase 1 implementation
+- [ ] Schedule follow-up review after adoption
+
+---
+
+## References
+
+- **Repository**: [GitHub URL]
+- **Documentation**: [Docs URL]
+- **Related Issues**: [Relevant issue links]
+- **Discussions**: [Community discussions if relevant]
+- **Similar Projects**: [Related projects for context]
+
+---
+
+*Analysis completed: [DATE]*
+*Analyst: Claude Code*
+*Review Status: [Draft / Under Review / Approved]*