@trespies-source/dojo-genesis-plugin 1.0.0

package/skills/repo-context-sync/scripts/diff_tracker.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3.11
+"""
+diff_tracker.py - Track and summarize changes since last sync
+Usage: python3.11 diff_tracker.py <repo_path> [last_commit_hash]
+Example: python3.11 diff_tracker.py /home/ubuntu/repos/dojo-genesis abc123
+"""
+
+import sys
+import subprocess
+from pathlib import Path
+from datetime import datetime
+
+def run_git_command(repo_path, command):
+    """Run a git command in the repo directory"""
+    try:
+        result = subprocess.run(
+            command,
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Git command failed: {e.stderr}", file=sys.stderr)
+        sys.exit(1)
+
+def get_current_commit(repo_path):
+    """Get the current commit hash"""
+    return run_git_command(repo_path, ["git", "rev-parse", "HEAD"])
+
+def get_commit_info(repo_path, commit_hash):
+    """Get commit information"""
+    try:
+        info = run_git_command(repo_path, [
+            "git", "show", "--no-patch", "--format=%H%n%an%n%ae%n%at%n%s",
+            commit_hash
+        ])
+        lines = info.split('\n')
+        return {
+            'hash': lines[0],
+            'author': lines[1],
+            'email': lines[2],
+            'timestamp': int(lines[3]),
+            'message': lines[4] if len(lines) > 4 else ''
+        }
+    except:
+        return None
+
+def get_diff_summary(repo_path, from_commit, to_commit):
+    """Get summary of changes between commits"""
+    # Get list of changed files
+    files_output = run_git_command(repo_path, [
+        "git", "diff", "--name-status", f"{from_commit}..{to_commit}"
+    ])
+    
+    changes = {
+        'added': [],
+        'modified': [],
+        'deleted': [],
+        'renamed': []
+    }
+    
+    for line in files_output.split('\n'):
+        if not line:
+            continue
+        parts = line.split('\t')
+        status = parts[0]
+        filename = parts[1] if len(parts) > 1 else ''
+        
+        if status == 'A':
+            changes['added'].append(filename)
+        elif status == 'M':
+            changes['modified'].append(filename)
+        elif status == 'D':
+            changes['deleted'].append(filename)
+        elif status.startswith('R'):
+            changes['renamed'].append(filename)
+    
+    return changes
+
+def get_commit_log(repo_path, from_commit, to_commit):
+    """Get commit log between two commits"""
+    log_output = run_git_command(repo_path, [
+        "git", "log", "--oneline", f"{from_commit}..{to_commit}"
+    ])
+    return log_output.split('\n') if log_output else []
+
+def generate_markdown_summary(repo_path, from_commit, to_commit, changes, commits):
+    """Generate a markdown summary of changes"""
+    repo_name = Path(repo_path).name
+    current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    
+    from_info = get_commit_info(repo_path, from_commit)
+    to_info = get_commit_info(repo_path, to_commit)
+    
+    md = f"""# Diff Summary: {repo_name}
+
+**Generated:** {current_time}
+**From Commit:** `{from_commit[:7]}` ({from_info['message'] if from_info else 'Unknown'})
+**To Commit:** `{to_commit[:7]}` ({to_info['message'] if to_info else 'Unknown'})
+
+## Summary
+
+- **Added:** {len(changes['added'])} files
+- **Modified:** {len(changes['modified'])} files
+- **Deleted:** {len(changes['deleted'])} files
+- **Renamed:** {len(changes['renamed'])} files
+- **Total Commits:** {len(commits)}
+
+## Commits
+
+"""
+    
+    for commit in commits:
+        md += f"- `{commit}`\n"
+    
+    if changes['added']:
+        md += "\n## Added Files\n\n"
+        for f in changes['added']:
+            md += f"- `{f}`\n"
+    
+    if changes['modified']:
+        md += "\n## Modified Files\n\n"
+        for f in changes['modified']:
+            md += f"- `{f}`\n"
+    
+    if changes['deleted']:
+        md += "\n## Deleted Files\n\n"
+        for f in changes['deleted']:
+            md += f"- `{f}`\n"
+    
+    if changes['renamed']:
+        md += "\n## Renamed Files\n\n"
+        for f in changes['renamed']:
+            md += f"- `{f}`\n"
+    
+    return md
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python3.11 diff_tracker.py <repo_path> [last_commit_hash]")
+        print("Example: python3.11 diff_tracker.py /home/ubuntu/repos/dojo-genesis abc123")
+        sys.exit(1)
+    
+    repo_path = sys.argv[1]
+    
+    if not Path(repo_path).is_dir():
+        print(f"❌ Error: {repo_path} is not a directory", file=sys.stderr)
+        sys.exit(1)
+    
+    if not (Path(repo_path) / ".git").is_dir():
+        print(f"❌ Error: {repo_path} is not a git repository", file=sys.stderr)
+        sys.exit(1)
+    
+    # Get current commit
+    current_commit = get_current_commit(repo_path)
+    
+    # Determine from_commit
+    if len(sys.argv) >= 3:
+        from_commit = sys.argv[2]
+    else:
+        # Default to 10 commits back
+        try:
+            from_commit = run_git_command(repo_path, ["git", "rev-parse", "HEAD~10"])
+        except:
+            # If repo has less than 10 commits, use first commit
+            from_commit = run_git_command(repo_path, ["git", "rev-list", "--max-parents=0", "HEAD"])
+    
+    print(f"📊 Analyzing changes from {from_commit[:7]} to {current_commit[:7]}")
+    
+    # Get diff summary
+    changes = get_diff_summary(repo_path, from_commit, current_commit)
+    commits = get_commit_log(repo_path, from_commit, current_commit)
+    
+    # Generate markdown
+    markdown = generate_markdown_summary(repo_path, from_commit, current_commit, changes, commits)
+    
+    print(markdown)
+    
+    # Also save to file
+    output_file = Path(repo_path) / ".diff_summary.md"
+    output_file.write_text(markdown)
+    print(f"\n✅ Summary saved to: {output_file}")
+
+if __name__ == "__main__":
+    main()

package/skills/repo-context-sync/scripts/smart_clone.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# smart_clone.sh - Efficient sparse checkout of relevant directories from a GitHub repo
+# Usage: smart_clone.sh <repo_url> <local_path> [dir1] [dir2] ...
+# Example: smart_clone.sh https://github.com/user/repo /home/ubuntu/repos/repo /00_Roadmap/ /02_Specs/
+
+set -e
+
+if [ "$#" -lt 2 ]; then
+    echo "Usage: $0 <repo_url> <local_path> [dir1] [dir2] ..."
+    echo "Example: $0 https://github.com/user/repo /home/ubuntu/repos/repo /00_Roadmap/ /02_Specs/"
+    exit 1
+fi
+
+REPO_URL="$1"
+LOCAL_PATH="$2"
+shift 2
+DIRS=("$@")
+
+echo "🔍 Smart Clone: $REPO_URL"
+echo "📁 Target: $LOCAL_PATH"
+
+# Check if directory already exists
+if [ -d "$LOCAL_PATH/.git" ]; then
+    echo "✅ Repo already cloned. Fetching latest changes..."
+    cd "$LOCAL_PATH"
+    git fetch origin
+    git pull origin main || git pull origin master
+    echo "✅ Updated successfully"
+    exit 0
+fi
+
+# Create parent directory if needed
+mkdir -p "$(dirname "$LOCAL_PATH")"
+
+# Clone with sparse checkout
+echo "📥 Cloning with sparse checkout..."
+git clone --filter=blob:none --sparse "$REPO_URL" "$LOCAL_PATH"
+cd "$LOCAL_PATH"
+
+# If specific directories provided, configure sparse checkout
+if [ ${#DIRS[@]} -gt 0 ]; then
+    echo "🎯 Configuring sparse checkout for:"
+    for dir in "${DIRS[@]}"; do
+        echo "   - $dir"
+        git sparse-checkout add "$dir"
+    done
+else
+    echo "📦 No specific directories provided, checking out full repo"
+    git sparse-checkout disable
+fi
+
+echo "✅ Clone complete: $LOCAL_PATH"

package/skills/repo-context-sync/templates/context_summary.md

@@ -0,0 +1,58 @@
+# Repo Context Summary: {repo_name}
+
+**Generated:** {timestamp}
+**Path:** `{repo_path}`
+**Branch:** `{branch}`
+**Commit:** `{commit_hash}` - {commit_message}
+**Remote:** {remote_url}
+
+## Overview
+
+{brief_description}
+
+## File Structure
+
+```
+{tree_view}
+```
+
+## Detected Patterns
+
+**Languages:** {languages}
+**Frameworks:** {frameworks}
+**File Hierarchy Pattern:** {hierarchy_pattern}
+
+## Recent Changes (since {last_sync})
+
+{diff_summary}
+
+### Commits
+{commit_list}
+
+### Modified Files
+{modified_files}
+
+### Added Files
+{added_files}
+
+### Deleted Files
+{deleted_files}
+
+## Key Patterns Extracted
+
+### Naming Conventions
+{naming_patterns}
+
+### Import Structure
+{import_patterns}
+
+### Architecture Notes
+{architecture_notes}
+
+## Relevant Files for Current Task
+
+{file_list_with_summaries}
+
+---
+
+*This summary was generated by the repo-context-sync skill to ground AI reasoning in actual codebase state.*

package/skills/repo-status/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: repo-status
+description: Generate comprehensive living status documents for software repositories combining filesystem exploration, semantic clustering, file importance ranking, and health assessment. Use when understanding codebases, auditing repos, creating system maps, assessing health, or onboarding to projects. Trigger phrases: 'give me a complete repo overview', 'understand this codebase', 'what does this repo do', 'create a system map', 'audit this repository', 'build a mental model'.
+---
+
+> **OpenClaw Integration:** This skill is invoked by the Dojo Genesis plugin via `/dojo run repo-status`.
+> The agent receives project context automatically via the `before_agent_start` hook.
+> Use `dojo_get_context` for full state, `dojo_save_artifact` to persist outputs,
+> and `dojo_update_state` to record phase transitions and decisions.
+
+# Repo Status Skill
+
+**Version:** 1.0
+**Created:** 2026-02-08
+**Author:** Cruz + Manus (Cowork)
+**Origin:** Codified from a live repo-context-sync + strategic-scout + status-writing session on Dojo Genesis.
+**Lineage:** status-writing + file-management + health-audit, distilled into a single repeatable workflow.
+
+---
+
+## I. The Philosophy: See the Whole Before Touching a Part
+
+Most codebases are explored piecemeal — someone reads a file, then another, then another, building a fragmentary picture that drifts as the project evolves. This skill takes the opposite approach: **see the whole system first, as a living organism**, then record what you see in a structured artifact that any future agent or human can use as a starting point.
+
+The output is a `.status.md` file — a comprehensive, versioned snapshot that bridges three perspectives:
+
+- **Status Writer**: Emoji-driven health indicators, workstream tracking, blockers, next steps. The "heartbeat" view.
+- **File Management**: Annotated directory tree with per-folder status. The "anatomy" view.
+- **Health Supervisor**: Critical/security/sustainability assessment. The "checkup" view.
+
+A single document. One place to look. Updated over time like a living record.
+
+---
+
+## II. When to Use This Skill
+
+- **Onboarding to a new project:** Before writing a single line, run this skill to build your mental model.
+- **Periodic health check:** Monthly or per-release, re-run to track drift and detect decay.
+- **Before a major refactor:** Understand what exists before deciding what to change.
+- **When handing off context:** Give another agent or team member a single file that tells them everything.
+- **When a project feels "big" or "messy":** Structure reduces anxiety. This skill imposes structure on chaos.
+
+---
+
+## III. The Workflow
+
+This is a 5-phase process. Each phase builds on the previous one.
+
+### Phase 1: Grounding (Read Before You Judge)
+
+**Objective:** Understand what the project *is* before evaluating how well it works.
+
+1. **List the root directory.** Get the top-level shape.
+2. **Read core documents.** In priority order:
+   - `README.md` (what it is, how to run it)
+   - `STATUS.md` or equivalent (where it is right now)
+   - `CHANGELOG.md` or release notes (where it's been)
+   - `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml` (tech stack, deps)
+   - `ARCHITECTURE.md`, `PHILOSOPHY.md` if they exist (intent, design)
+3. **Identify the tech stack.** Language(s), framework(s), database(s), infra.
+4. **Note the project's self-stated purpose.** This becomes Section 1 of the output.
+
+*Time budget: ~10% of total effort. Resist the urge to explore deeply here.*
+
+### Phase 2: Deep Inventory (Parallel Exploration)
+
+**Objective:** Build a complete picture of everything in the repository.
+
+Launch parallel exploration across the major layers. For most projects, these are:
+
+| Layer | What to Inventory |
+|-------|-------------------|
+| **Frontend** | Components, routes, state management, styling, tests, LOC estimates |
+| **Backend** | Packages, handlers, services, models, LOC estimates |
+| **Data** | Migrations, schemas, seed data, vector stores |
+| **Knowledge** | Docs, skills, prompts, thinking artifacts, compressions |
+| **Infra** | CI/CD, Docker, scripts, deployment configs |
+| **Tests** | Unit, integration, e2e, coverage estimates |
+
+For each layer, collect:
+- File count
+- Approximate LOC (use `wc -l` or `cloc` if available)
+- Package/module count
+- Status (active, legacy, deprecated, empty)
+
+*Time budget: ~30% of total effort. Parallelize aggressively.*
+
+### Phase 3: Semantic Clustering
+
+**Objective:** Group everything by *what the system does*, not where files happen to live.
+
+This is the distinctive step. Instead of just listing directories, map every feature to an **action verb** — a cluster that describes a behavioral capability of the system.
+
+Read `references/semantic-clusters.md` for the full cluster framework and examples.
+
+**The process:**
+
+1. Review the inventory from Phase 2.
+2. For each significant component, ask: "What verb describes what this does?"
+3. Assign it to a cluster. Create new clusters if needed.
+4. For each cluster, build a component table: `Component | Location | Status | LOC`
+5. Write a health assessment per cluster.
+6. Identify cross-cluster components (things that serve multiple verbs).
+7. Identify orphans (components that don't fit any cluster) — these may signal architectural confusion.
+
+*Time budget: ~25% of total effort. This is where the insight lives.*
+
+### Phase 4: Write the .status.md
+
+**Objective:** Assemble everything into a single, structured document.
+
+Read `references/status-template.md` for the complete output template.
+
+The document has 10 sections:
+
+1. **Vision & Purpose** — One sentence + core principles (from Phase 1)
+2. **Current State** — Emoji table of major areas (from Phase 2)
+3. **Directory Structure** — Annotated tree with per-folder status (from Phase 2)
+4. **Semantic Clusters** — One subsection per verb, with component tables (from Phase 3)
+5. **File Importance Ranking** — 4 tiers (Critical, Important, Supporting, Knowledge)
+6. **Health Assessment** — Critical issues, security, sustainability (health-audit framework)
+7. **Active Workstreams** — What's being worked on right now
+8. **Blockers & Dependencies** — What's preventing progress
+9. **Next Steps** — Immediate actionable items
+10. **Aggregate Statistics** — Summary numbers table
+
+Save to `.status.md` at the project root (dot-prefixed to stay out of the way but discoverable).
+
+*Time budget: ~25% of total effort.*
+
+### Phase 5: Verification
+
+**Objective:** Catch errors, fill gaps, and harden the document.
+
+1. **Cross-check statistics programmatically.** Run `find` and `wc -l` to verify LOC claims. Check file counts against actual filesystem.
+2. **Identify unmapped components.** Walk the component directories and confirm every significant directory appears in at least one semantic cluster.
+3. **Validate status emojis.** Ensure every area marked "complete" actually has evidence of completeness.
+4. **Apply corrections.** Update the `.status.md` with any discrepancies found.
+5. **Note confidence level.** If you couldn't verify something, say so.
+
+*Time budget: ~10% of total effort. This step prevents the document from being fiction.*
+
+---
+
+## IV. The Semantic Cluster Framework
+
+The clusters are action verbs that describe what a system *does*. For the full reference with starter verbs and mapping guidance, read:
+
+```
+references/semantic-clusters.md
+```
+
+**Starter set (adapt to your project):**
+
+| Verb | Meaning | Example Components |
+|------|---------|-------------------|
+| CONVERSE | Chat, messaging, streaming | Chat UI, SSE handlers, message models |
+| REASON | Thinking, planning, deciding | Agent, intent classifier, orchestration |
+| REMEMBER | Storage, recall, learning | Memory system, embeddings, seeds |
+| OBSERVE | Monitoring, tracing, metrics | Trace logger, event bus, cost tracker |
+| LEARN | Adaptation, feedback, calibration | Calibration engine, preference system |
+| ACT | Tool execution, side effects | Tool registry, tool implementations |
+| PROTECT | Auth, security, boundaries | Middleware, secure storage, auth context |
+| CONNECT | External integrations | Plugins, APIs, bots, webhooks |
+| PRESENT | UI, rendering, layout | Shell, sidebars, panels, components |
+| PERSIST | Database, migrations, storage | DB manager, migrations, schemas |
+| BUILD | CI/CD, testing, deployment | Workflows, Docker, scripts, tests |
+| THINK | Meta-cognition, knowledge | Skills, prompts, documentation |
+| ORCHESTRATE | Multi-step coordination | DAG engine, task decomposition |
+
+Not every project will use all 13. Some projects may need verbs not on this list. The framework is a starting point, not a constraint.
+
+---
+
+## V. File Importance Ranking
+
+Rank files into 4 tiers based on runtime criticality and development importance:
+
+| Tier | Criteria | Typical Count |
+|------|----------|---------------|
+| **Tier 1: Critical** | System won't function without these. Core agent, main state, primary API endpoint, database manager. | 10 files |
+| **Tier 2: Important** | Core features break without these. Supporting services, secondary state, routing. | 10 files |
+| **Tier 3: Supporting** | System degrades gracefully without these. Integrations, utilities, background tasks. | 20-30 files |
+| **Tier 4: Knowledge** | Essential for development, not runtime. Docs, specs, skills, prompts. | Variable |
+
+For each file in Tiers 1-2, include `Rank | File | Why` — a one-line justification.
+
+---
+
+## VI. Health Assessment Framework
+
+Borrowed directly from the health-audit skill. For each category, use a table with `Area | Status | Notes`.
+
+| Category | What to Check |
+|----------|--------------|
+| **Critical Issues** | Can it build? Critical dependency vulnerabilities? Main branch broken? |
+| **Security** | Secrets hardcoded? Auth implemented? RLS policies set? Encryption at rest? |
+| **Sustainability** | Test coverage adequate? CI/CD automated? Technical debt managed? Docs current? Manual processes documented? |
+
+Be honest. Use emoji status indicators: ✅ good, ⚠️ concern, ❌ blocked.
+
+---
+
+## VII. Best Practices
+
+- **Dot-prefix the output file.** `.status.md` stays discoverable but doesn't clutter the root alongside README and STATUS.
+- **Separate from STATUS.md.** The lightweight `STATUS.md` (per status-writing skill) is the human-facing dashboard. `.status.md` is the comprehensive agent-facing audit. They complement each other.
+- **Update incrementally.** After the first generation, subsequent runs should diff against the existing `.status.md` and update rather than regenerate from scratch.
+- **Statistics drift is normal.** LOC counts change every commit. The goal is "accurate enough to be useful" — within 10% is fine.
+- **Semantic clusters are the crown jewel.** The directory tree tells you *where* things are. The clusters tell you *what* things do. Prioritize cluster quality over tree completeness.
+- **Parallelize Phase 2.** The deep inventory is the slowest phase. Use subagents or parallel exploration to cut time.
+- **Verification is not optional.** A beautiful document full of wrong numbers is worse than no document. Always verify.
+
+---
+
+## VIII. Quality Checklist
+
+Before delivering the `.status.md`, confirm:
+
+- [ ] Vision statement is present and accurate
+- [ ] Every major directory appears in the annotated tree
+- [ ] Every significant component maps to at least one semantic cluster
+- [ ] No orphan directories (unmapped components) remain unexplained
+- [ ] File importance ranking has at least 10 Tier 1-2 files
+- [ ] Health assessment covers critical, security, and sustainability
+- [ ] Aggregate statistics are programmatically verified (within 10%)
+- [ ] Active workstreams reflect actual current work
+- [ ] Next steps are concrete and actionable
+- [ ] The document reads coherently from top to bottom
+---
+
+## OpenClaw Tool Integration
+
+When running inside the Dojo Genesis plugin:
+
+1. **Start** by calling `dojo_get_context` to retrieve full project state, history, and artifacts
+2. **During** the skill, follow the workflow steps documented above
+3. **Save** outputs using `dojo_save_artifact` with the `artifacts` output directory
+4. **Update** project state by calling `dojo_update_state` to record skill completion and any phase transitions
+

package/skills/repo-status/claw.json

@@ -0,0 +1,12 @@
+{
+  "name": "dojo-genesis-plugin-repo-status",
+  "version": "1.0.0",
+  "description": "Generate comprehensive repo status documents",
+  "author": "dojo-genesis",
+  "license": "MIT",
+  "permissions": [],
+  "entry": "SKILL.md",
+  "tags": ["dojo-genesis", "orchestration", "system", "health"],
+  "models": ["claude-*", "gpt-*", "gemini-*"],
+  "minOpenClawVersion": "2026.1.0"
+}