/repo-value-analysis

name: repo-value-analysis
description: "Analyze external repositories for adoptable ideas and patterns."
user-invocable: false
argument-hint: "<repo-url-or-path>"
agent: research-coordinator-engineer
allowed-tools:
  - Agent
  - Read
  - Write
  - Bash
  - Grep
  - Glob
routing:
  triggers:
    - repo value analysis
    - does repo add value
    - analyze repo for ideas
    - what can we learn from
    - compare against repo
    - read every file in repo
  pairs_with:
    - workflow
  complexity: Complex
  category: analysis

Repo Competitive Analysis Pipeline

Overview

This skill conducts systematic 6-phase analysis of external repositories to assess their value for adoption. You dispatch parallel subagents to read and catalog every file in an external repo, inventory your own toolkit in parallel, identify genuine capability gaps, audit those gaps against your actual codebase, and produce a reality-grounded comparison report with adoption recommendations.

The pipeline enforces **full file reading** (not sampling), **parallel execution** (up to 8 agent zones simultaneously), and **mandatory audit** (every recommendation verified before reporting). Optional flags allow local analysis (`--local`), zone focus (`--zone`), and quick comparison (`--quick` skips audit).

---

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | errors, error handling | `error-handling.md` | Loads detailed guidance from `error-handling.md`. | | Phase 2 DEEP-READ: zone agent dispatch | `phase2-agent-template.md` | Loads detailed guidance from `phase2-agent-template.md`. | | Phase 3 INVENTORY: cataloging our system | `phase3-inventory-template.md` | Loads detailed guidance from `phase3-inventory-template.md`. | | Phase 5 AUDIT: verifying HIGH/MEDIUM recommendations | `phase5-audit-template.md` | Loads detailed guidance from `phase5-audit-template.md`. | | Phase 6 REPORT: final report structure | `phase6-report-template.md` | Loads detailed guidance from `phase6-report-template.md`. |

Instructions

Input Parsing

Before starting Phase 1, parse the user's input:

• **GitHub URL**: Extract repo name from URL (e.g., `https://github.com/org/repo` -> `repo`)
• **Local path**: Validate the path exists and contains files
• **Bare repo name**: Assume `https://github.com/{name}` if it looks like `org/repo`

Set `REPO_NAME` and `REPO_PATH` variables for use throughout the pipeline.

Phase 1: CLONE

**Goal**: Obtain the repository and categorize its contents into zones for parallel deep-read.

**Step 1: Clone the repository**

git clone --depth 1 <url> /tmp/<REPO_NAME>

If `--local` flag was provided, skip cloning and use the provided path instead. This allows re-analysis of already-cloned repos without redundant network calls.

**Step 2: Count and categorize files**

Survey the repository structure:

• Count total files (excluding `.git/`)
• List top-level directories with file counts

This gives you a baseline for zone complexity and helps identify sub-repo patterns.

**Step 3: Define analysis zones**

Categorize files into zones based on directory names and file patterns. Zones organize the repo into digestible chunks:

| Zone | Typical directories/patterns | Purpose | |------|------------------------------|---------| | skills | `skills/`, `commands/`, `prompts/`, `templates/` | Reusable skill/prompt definitions | | agents | `agents/`, `personas/`, `roles/` | Agent configurations | | hooks | `hooks/`, `middleware/`, `interceptors/` | Event-driven automation | | docs | `docs/`, `*.md` (non-config), `adr/`, `guides/` | Documentation and decisions | | tests | `tests/`, `*_test.*`, `*.spec.*`, `__tests__/` | Test suites | | config | Config files, CI/CD, `*.yaml`, `*.toml`, `*.json` (root) | Configuration | | code | `scripts/`, `src/`, `lib/`, `pkg/`, `*.py`, `*.go`, `*.ts` | Source code | | other | Everything else | Uncategorized files |

**Step 4: Cap zones for parallel feasibility**

If any zone exceeds ~100 files, split it into sub-zones by subdirectory. Each sub-zone gets its own agent in Phase 2. Cap at ~100 files per agent because:

• Agents MUST read **every file** in their zone, not sample or skim (sampling introduces bias and misses distinguishing components)
• ~100 files is feasible for a single agent within budget and timeout
• Larger zones are split, so no single agent is overwhelmed

Log the split decisions in the analysis notes for transparency.

**Gate**: Repository cloned (or local path validated). All files categorized into zones. Zone file counts recorded. No zone exceeds ~100 files (split if needed). Proceed only when gate passes.

Phase 2: DEEP-READ (Parallel)

**Goal**: Read every file in every zone of the external repository to extract techniques, patterns, and potential capability gaps.

Dispatch 1 Agent per analysis zone (background). Each agent receives the zone name and file list, instructions to read EVERY file (not sample, not skim) to avoid sampling bias, and a structured output template.

See `references/phase2-agent-template.md` for the full agent instructions template and parallel dispatch rules.

**Gate**: All zone agents have completed (or timed out after 5 minutes each). At least 75% of agents returned results (tolerance for individual agent failure). Zone finding files exist in `/tmp/`. Proceed only when gate passes.

Phase 3: INVENTORY (Parallel with Phase 2)

**Goal**: Catalog our own toolkit simultaneously with Phase 2 deep-read for faster wall-clock time.

Dispatch 1 Agent (in background, concurrent with Phase 2 zone agents) to inventory our system. Running this in parallel is safe because inventory is a read-only catalog of our codebase.

See `references/phase3-inventory-template.md` for the full agent instructions and parallel-execution rationale.

**Gate**: Self-inventory agent completed (or timed out after 5 minutes). `/tmp/self-inventory.md` exists and contains counts for all 4 component types. Proceed only when