repo-ingest

name	repo-ingest
version	1.1.0
description	Use when updating agent coordination skills from external repositories - extracts architectural patterns from source repos and proposes skill updates with provenance tracking; prevents cargo culting and stale patterns
triggers	["repo-ingest","learn from repo","update from smith","ingest repository","self update","pattern extraction","upstream sync"]

Repo Ingest — Pattern Extraction and Skill Evolution

Extract architectural patterns from external repositories and propose updates to marketplace skills. This is a research analyst that proposes PRs, not a translator that blindly copies.

The skill reads source repositories, produces structured pattern briefs, compares against current skill implementations, and generates proposed updates as branches — never direct edits to the marketplace.

When to Use This Skill

• A repository has interesting coordination, handoff, or agent patterns worth adopting
• Smith or another upstream has released updates you want to incorporate
• You want to systematically improve marketplace skills based on real-world implementations
• Periodic review of source repos for new patterns (monthly recommended)

When NOT to Use This Skill

• Copying code from a repo — this extracts PATTERNS, not code
• One-off manual skill edits — just edit the skill directly
• Repos with no relevance to agent coordination or development patterns
• Without understanding what the source repo does — read first, ingest second

Source Registry

Track which repos have been ingested and when. Lives at:

{marketplace-root}/repo-ingest/sources.json

{
  "sources": [
    {
      "name": "smith",
      "url": "https://github.com/callmeradical/smith",
      "description": "Distributed autonomous development runtime — handoff protocol, loop state machines, agent coordination via etcd",
      "last_ingested": "2026-04-11T00:00:00Z",
      "last_sha": "abc123",
      "patterns_extracted": ["handoff-protocol", "journal-separation", "completion-saga", "lease-locks"],
      "skills_influenced": ["handoff", "pickup", "signal"]
    }
  ]
}

The 5 Steps (MANDATORY)

Step 1: Identify Source and Scope (REQUIRED)

Determine what repo(s) to ingest and what you're looking for.

Single repo:

/repo-ingest https://github.com/callmeradical/smith

Multiple repos:

/repo-ingest https://github.com/callmeradical/smith https://github.com/org/other-repo

With focus area:

/repo-ingest https://github.com/callmeradical/smith --focus "handoff protocol changes"

For each repo:

1. Clone or fetch latest if already cloned: git clone --depth 1 {url} /tmp/repo-ingest/{name}
2. Check sources.json for prior ingestion — note last_sha to identify what's new
3. If re-ingesting: git log {last_sha}..HEAD --oneline to see what changed

Gate: You know which repos to analyze and what's changed since last ingestion.

Step 2: Explore and Extract Patterns (REQUIRED)

For each repository, systematically explore the architecture. You're looking for transferable patterns, not code to copy.

Exploration checklist:

• README and top-level docs — understand what the project does
• Architecture docs — design decisions and their rationale
• Key data structures — how state is modeled
• Coordination mechanisms — how agents/components communicate
• Error handling — how failures are recovered
• State machines — lifecycle transitions and guards

For each pattern you identify, extract:

### Pattern: {Name}

**Problem it solves:** {One sentence}
**How they solved it:** {Their approach — 2-3 sentences}
**Constraints that drove this choice:** {Why THIS solution — what alternatives they rejected}
**What's transferable:** {What applies to our filesystem-based, Claude Code context}
**What's NOT transferable:** {What's specific to their infrastructure — e.g., etcd, Kubernetes}
**Relevance to our skills:** {Which marketplace skills would benefit}

Do NOT extract patterns that are:

• Specific to their infrastructure (etcd, K8s, gRPC) without a filesystem analog
• Already implemented in our skills with no meaningful difference
• Trivial or obvious (e.g., "use git for version control")

Gate: You have a structured pattern brief with at least one transferable pattern per repo.

Step 3: Compare Against Current Skills (REQUIRED)

For each extracted pattern, read the current marketplace skill it would affect:

# Read current skill
cat {marketplace-root}/{skill-name}/SKILL.md

Produce a comparison:

### Pattern: {Name} → Skill: {skill-name}

**Current approach:** {How the skill handles this now}
**Source approach:** {How the source repo handles it}
**Gap:** {What's missing or different}
**Risk of adoption:** {What could break — low/medium/high}
**Recommendation:** ADOPT / ADAPT / SKIP
- ADOPT: Take the pattern as-is, it's strictly better
- ADAPT: The idea is good but needs modification for our context
- SKIP: Not worth the change — our approach is fine or theirs doesn't fit

Gate: Every pattern has a recommendation with rationale. No ADOPT without understanding WHY it's better.

Step 4: Generate Proposals (REQUIRED)

For patterns marked ADOPT or ADAPT, generate concrete skill update proposals.

Create a branch for the updates:

git checkout -b repo-ingest/{source-name}-{date}

For each proposed change, write:

1. The diff — actual edits to the SKILL.md file(s)
2. Provenance comment — add to the skill's changelog:

   **v{next}** ({date})
   - {Description of change}
   - Source: {repo-name} ({sha}) — {pattern-name}
   

3. Pattern brief file — save to repo-ingest/briefs/{source-name}-{date}.md:

   ---
   source: {repo-url}
   sha: {sha}
   ingested: {ISO-8601}
   patterns: [{pattern-names}]
   skills_affected: [{skill-names}]
   ---
   
   # Pattern Brief: {source-name}
   
   ## Extracted Patterns
   {All pattern extractions from Step 2}
   
   ## Comparisons
   {All comparisons from Step 3}
   
   ## Applied Changes
   - {Pattern} → {Skill}: {What changed}
   

Do NOT:

• Edit skills directly on main — always use a branch
• Apply SKIP patterns
• Remove existing functionality without clear rationale
• Change skill behavior without updating the version number

Gate: All changes are on a branch, every change has provenance, brief is saved.

Step 5: Update Registry and Report (REQUIRED)

1. Update sources.json with new ingestion data:

   {
     "last_ingested": "{now}",
     "last_sha": "{current-sha-of-source}",
     "patterns_extracted": ["{pattern-names}"],
     "skills_influenced": ["{skill-names}"]
   }
   

2. Report to the user:

   ## Repo Ingest Report — {date}
   
   ### Sources Analyzed
   - {repo}: {N} patterns extracted, {M} applicable
   
   ### Proposed Changes
   | Pattern | Skill | Action | Risk |
   |---------|-------|--------|------|
   | {name}  | {skill} | ADOPT/ADAPT | low/med/high |
   
   ### Branch
   `repo-ingest/{source-name}-{date}` — ready for review
   
   ### Pattern Brief
   Saved to `repo-ingest/briefs/{source-name}-{date}.md`
   

3. Do NOT auto-merge. Present the branch for human review. The user decides what ships.

Gate: sources.json updated, report presented, branch ready for review.

Red Flags - STOP

If you catch yourself:

• ❌ Copying code instead of extracting patterns — this is pattern analysis, not code migration
• ❌ Recommending ADOPT without explaining why it's better than current — justify every change
• ❌ Editing skills directly on main — always branch
• ❌ Ignoring constraint differences — etcd patterns don't map 1:1 to filesystem
• ❌ Extracting patterns you don't understand — if you can't explain the tradeoff, you can't recommend adoption
• ❌ Ingesting without checking sources.json — you might re-extract patterns already adopted

STOP. This skill is a research analyst, not a copy machine.

Verification Checklist

Before reporting results:

• Source repo cloned and explored systematically
• Patterns extracted with problem/approach/constraints/transferable structure
• Each pattern compared against current skill implementation
• Recommendations justified (ADOPT/ADAPT/SKIP with rationale)
• Changes on a branch, not main
• Every change has provenance (source repo, SHA, pattern name)
• Pattern brief saved to repo-ingest/briefs/
• sources.json updated
• Report presented to user for review

Best Practices

1. Extract the WHY, not just the WHAT — Smith uses lease-based locks because it's distributed. We use timestamp-based locks because we're local. The pattern is "prevent concurrent mutation" — the mechanism differs.
2. Provenance is non-negotiable — every change must trace back to a source repo, SHA, and pattern name. Without provenance, you can't debug why a skill changed.
3. Re-ingest periodically — source repos evolve. Run this monthly or when you know an upstream has significant changes.
4. One branch per ingestion — don't mix patterns from different repos in one branch. Makes review cleaner.
5. SKIP is a valid recommendation — not every pattern needs adoption. "Our approach is fine" is a legitimate conclusion.
6. Brief files are permanent — they document the intellectual lineage of your skills. Don't delete them.

Supporting Files

sources.json

Registry of all source repositories. Lives at repo-ingest/sources.json. Created on first ingestion.

briefs/

Pattern brief files from each ingestion. One file per source per ingestion date. Format: {source-name}-{YYYY-MM-DD}.md.

Related Skills

• /handoff — One of the skills repo-ingest can update. Smith's handoff protocol is the first source pattern.
• /pickup — Another target skill. Smith's loop startup protocol informed this design.
• /signal — Another target skill. Smith's journal system informed the signal types.
• /coordinate — The switchboard architecture. Patterns from Agent-MCP, GitAgent, A2A, and ACP informed the distributed coordination design.

After Using This Skill

MANDATORY NEXT STEPS:

• Review the proposed branch before merging
• Check that pattern briefs accurately represent what was extracted

OPTIONAL NEXT STEPS:

• Share the pattern brief with collaborators for feedback
• Schedule the next ingestion (monthly cadence recommended)
• Add new source repos to sources.json for future ingestion

Changelog

v1.1.0 (2026-04-11)

• Added coordinate/switchboard as target skill for pattern extraction
• Registered additional source repos: Agent-MCP, GitAgent, A2A, ACP
• Source: landscape research on multi-agent coordination protocols

v1.0.0 (2026-04-11)

• Initial skill creation
• Five-step extraction pipeline: identify → explore → compare → propose → report
• Source registry with provenance tracking
• Pattern brief format with problem/approach/constraints structure
• Branch-based proposals, never direct main edits
• Smith as first registered source