abcnuts/organize-github-repos

Organize GitHub Repos

Overview

This skill provides comprehensive tools for verifying and maintaining alignment between Supabase (Maverick Town) databases and connected GitHub repositories. It prevents data loss by detecting miscommunications, validating synchronization states, and providing auto-healing capabilities when discrepancies are found.

When to Use This Skill

Use this skill when:

• Auditing repository states - Verify that GitHub repos match Supabase records
• Detecting misalignments - Find discrepancies between Supabase and GitHub
• Preventing data loss - Ensure synchronization before critical operations
• Recovering from errors - Identify and fix broken connections
• Onboarding new repos - Validate proper setup of new GitHub repositories
• Troubleshooting sync issues - Debug why data isn't flowing correctly

Core Capabilities

1. Repository State Verification

Purpose: Compare Supabase records with actual GitHub repository states

Process:

1. Query Supabase for all registered repositories
2. Use GitHub MCP to fetch actual repository data
3. Compare metadata (name, URL, visibility, default branch, etc.)
4. Generate discrepancy report

MCP Tools Used:

• supabase MCP: Query repository tables
• github MCP (via gh CLI): Fetch repository details

Example Command:

manus-mcp-cli tool call supabase_query --server supabase --input '{
  "query": "SELECT * FROM repositories WHERE active = true"
}'

2. Data Integrity Checks

Purpose: Ensure critical data fields are populated and valid

Checks:

• Repository URLs are accessible
• Webhook configurations are present
• API tokens are valid and not expired
• Database foreign keys are intact
• Timestamps are reasonable (not in future, not too old)

Auto-Healing Actions:

• Refresh expired tokens
• Recreate missing webhooks
• Update stale metadata
• Fix broken foreign key relationships

3. RAG-Based Historical Analysis

Purpose: Store and query historical repository states to detect patterns

Implementation:

• Store snapshots of repository states in vector database
• Query historical data to find when misalignments occurred
• Identify recurring issues or patterns
• Provide context-aware recommendations

Storage Location: /home/ubuntu/skills/organize-github-repos/rag-data/

Example Queries:

• "When did repo X last sync successfully?"
• "What repos have had sync failures in the past week?"
• "Show me all repos that were deleted from GitHub but still in Supabase"

4. Alignment Report Generation

Purpose: Create comprehensive reports of current alignment status

Report Sections:

1. Executive Summary - Overall health score, critical issues
2. Repository Inventory - All repos in Supabase vs GitHub
3. Discrepancies - Detailed list of misalignments
4. Recommendations - Prioritized action items
5. Historical Trends - Changes over time

Output Formats:

• Markdown (human-readable)
• JSON (machine-readable)
• CSV (for spreadsheet analysis)

Workflow

Quick Start: Full Audit

# 1. Fetch all repositories from Supabase
manus-mcp-cli tool call supabase_query --server supabase --input '{
  "query": "SELECT id, name, github_url, last_sync FROM repositories"
}'

# 2. For each repo, verify GitHub state
gh repo view <owner>/<repo> --json name,url,visibility,defaultBranchRef

# 3. Compare and generate report
python3 /home/ubuntu/skills/organize-github-repos/scripts/verify_alignment.py

# 4. Review discrepancies
cat /tmp/alignment-report.md

Workflow Decision Tree

Start Here: What do you need to do?

1. "I want to verify everything is aligned" → Run Full Audit (see Quick Start above)

2. "I suspect a specific repo is out of sync" → Run Single Repository Check:

   python3 scripts/check_single_repo.py <repo-name>
   

3. "I need to find all broken connections" → Run Connection Health Check:

   python3 scripts/health_check.py --mode=connections
   

4. "I want to see historical sync patterns" → Query RAG Database:

   python3 scripts/query_history.py "show sync failures last 7 days"
   

5. "I need to fix misalignments automatically" → Run Auto-Heal:

   python3 scripts/auto_heal.py --dry-run  # Preview changes
   python3 scripts/auto_heal.py --execute  # Apply fixes
   

Scripts

scripts/verify_alignment.py

Purpose: Main verification script that compares Supabase and GitHub states

Usage:

python3 scripts/verify_alignment.py [--output-format=markdown|json|csv]

What it does:

1. Queries Supabase for all repositories
2. Fetches corresponding GitHub data via MCP
3. Compares fields and identifies discrepancies
4. Generates alignment report

scripts/check_single_repo.py

Purpose: Focused check on a single repository

Usage:

python3 scripts/check_single_repo.py <repo-name> [--fix]

What it does:

1. Looks up repo in Supabase
2. Fetches GitHub state
3. Shows detailed comparison
4. Optionally applies fixes if --fix flag is used

scripts/health_check.py

Purpose: System-wide health check for connections and integrations

Usage:

python3 scripts/health_check.py [--mode=all|connections|webhooks|tokens]

What it does:

1. Tests Supabase connection
2. Validates GitHub MCP availability
3. Checks webhook endpoints
4. Verifies API token validity

scripts/query_history.py

Purpose: Query RAG database for historical patterns

Usage:

python3 scripts/query_history.py "<natural language query>"

Examples:

python3 scripts/query_history.py "repos with sync failures last week"
python3 scripts/query_history.py "when did repo X last update"
python3 scripts/query_history.py "show all deleted repos"

scripts/auto_heal.py

Purpose: Automatically fix detected misalignments

Usage:

python3 scripts/auto_heal.py [--dry-run] [--execute] [--repo=<name>]

What it does:

1. Runs verification to find issues
2. Applies fixes based on predefined rules
3. Logs all changes for audit trail
4. Supports dry-run mode for safety

Auto-Healing Rules:

• Update stale metadata from GitHub
• Recreate missing webhooks
• Refresh expired tokens (if refresh token available)
• Remove Supabase entries for deleted GitHub repos (with confirmation)
• Fix broken foreign key relationships

References

references/supabase_schema.md

Documentation of the Maverick Town Supabase schema, including:

• repositories table structure
• sync_logs table structure
• Foreign key relationships
• Expected data types and constraints

references/github_api_reference.md

GitHub API endpoints and MCP tool mappings:

• Repository metadata endpoints
• Webhook management
• Authentication patterns
• Rate limiting considerations

references/common_issues.md

Catalog of known misalignment patterns and solutions:

• Webhook delivery failures
• Token expiration issues
• Repository rename handling
• Organization transfer scenarios

RAG Data Storage

Location: /home/ubuntu/skills/organize-github-repos/rag-data/

Structure:

rag-data/
├── snapshots/           # Historical repository state snapshots
│   └── YYYY-MM-DD/
│       └── repo-name.json
├── discrepancies/       # Logged misalignments
│   └── YYYY-MM-DD.jsonl
└── resolutions/         # Applied fixes and outcomes
    └── YYYY-MM-DD.jsonl

Snapshot Format:

{
  "timestamp": "2026-02-10T12:00:00Z",
  "repo_name": "example-repo",
  "supabase_state": { ... },
  "github_state": { ... },
  "discrepancies": [ ... ]
}

Best Practices

1. Run audits regularly - Schedule weekly full audits to catch drift early
2. Use dry-run first - Always preview auto-heal changes before executing
3. Review discrepancy reports - Don't blindly auto-fix; understand root causes
4. Monitor RAG data growth - Archive old snapshots to prevent storage bloat
5. Validate after fixes - Re-run verification after auto-healing to confirm success
6. Document manual interventions - Log any manual fixes in resolutions/ for future reference

Troubleshooting

"MCP connection failed"

• Verify Supabase MCP server is configured: manus-mcp-cli tool list --server supabase
• Check GitHub CLI is authenticated: gh auth status

"No discrepancies found but I know there are issues"

• Check if verification script has correct field mappings
• Review Supabase schema in references/supabase_schema.md
• Ensure GitHub MCP is returning complete data

"Auto-heal made incorrect changes"

• Review rag-data/resolutions/ to see what was changed
• Restore from Supabase backup if needed
• Adjust auto-healing rules in scripts/auto_heal.py

"RAG queries returning no results"

• Verify snapshots are being created: ls rag-data/snapshots/
• Check snapshot format matches expected structure
• Ensure query syntax is correct (see examples above)

Future Enhancements

• Real-time monitoring - Webhook-based live sync status
• Predictive alerts - ML-based detection of potential issues before they occur
• Multi-org support - Handle multiple GitHub organizations
• Slack notifications - Alert on critical misalignments
• Web dashboard - Visual interface for alignment status