claude-integrator

A Claude Code / Codex skill that scans an examples/ directory of vendored open-source repos, scores each candidate on fit / cost / risk / value with hard license gates, and scaffolds an OpenSpec change proposal so an integrator agent can absorb the upstream into a host project.

The skill produces analysis only. It does not create branches, copy code, run installers, or hit the network. The integrator decides which drafts to act on.

What it does

For every directory under examples/<name>/ in the host repo:

1. Discover — read git remote, license (LICENSE / COPYING), top manifest (package.json / Cargo.toml / pyproject.toml / go.mod), README lead, and primary language.
2. Classify — full-app, library, plugin, headless-cli, vendored-upstream, or unknown.
3. Score — fit, cost, risk, value, each low | med | high, with a one-line justification per axis.
4. License gate — PolyForm-Noncommercial-1.0.0, BUSL-1.1, SSPL-1.0, AGPL-3.0, GPL-3.0, and unverified custom licenses auto-bump risk to high and forbid vendor-as-submodule / extract-module.
5. Recommend — exactly one of vendor-as-submodule | extract-module | npm-dep | keep-as-reference | skip | already-integrated.
6. Draft OpenSpec — for each accepted target, scaffold openspec/changes/integrate-<name>/{proposal,tasks,context}.md from the templates in this repo.

Repo layout

claude-integrator/
├── SKILL.md                         # the skill body (procedural workflow)
├── references/
│   └── integration-rubric.md        # scoring rubric + license-gate matrix
├── scripts/
│   ├── scan-examples.py             # deterministic, read-only scanner (Python 3.10+)
│   └── draft-openspec.py            # idempotent OpenSpec drafter
└── templates/
    ├── proposal.md                  # OpenSpec proposal stub
    ├── tasks.md                     # OpenSpec tasks stub
    └── context.md                   # OpenSpec context stub

Install

Option A — drop-in for a recodee-style repo

# from the root of the host repo
mkdir -p .agents/skills/integrate-examples
git clone https://github.com/recodeee/claude-integrator.git \
  .agents/skills/integrate-examples

If the host's .agents/ is gitignored, force-add the skill directory:

git add -f .agents/skills/integrate-examples

Option B — install at the user level (Claude Code)

mkdir -p ~/.claude/skills
git clone https://github.com/recodeee/claude-integrator.git \
  ~/.claude/skills/integrate-examples

Option C — vendor it

git submodule add https://github.com/recodeee/claude-integrator.git \
  vendor/claude-integrator

Activation

The skill is triggered manually with /integrate-examples (Claude Code slash command surface).

If the host repo uses a skill-rules.json-style activation hook, add this entry so prompts mentioning examples/, integrate, vendor, or open source suggest the skill:

"integrate-examples": {
  "type": "workflow",
  "enforcement": "suggest",
  "priority": "medium",
  "description": "Scan examples/ for vendored open-source repos, score each on fit/cost/risk/value, and draft an OpenSpec change so the integrator can absorb them into the host app",
  "promptTriggers": {
    "keywords": [
      "examples/",
      "integrate examples",
      "vendor",
      "open source",
      "open-source",
      "absorb upstream"
    ],
    "intentPatterns": [
      "(integrate|absorb|merge|adopt).*(examples?/|open[- ]source|upstream|third[- ]party)"
    ]
  }
}

Usage

# 1. Scan
python3 scripts/scan-examples.py --root ./examples --out /tmp/integ.json

# 2. Render the per-repo report (the skill body shows the table format).

# 3. Draft an OpenSpec change for an accepted target
python3 scripts/draft-openspec.py \
  --report /tmp/integ.json \
  --slug integrate-codexmonitor

# 4. Validate (if the host uses OpenSpec)
openspec validate --specs

scan-examples.py is read-only, deterministic, and emits sorted JSON — reruns with the same inputs produce a byte-identical file. draft-openspec.py refuses to overwrite an existing change directory without --force.

License gate matrix

SPDX id	Risk floor	Allowed actions
MIT, Apache-2.0, BSD, ISC	as scored	any
MPL-2.0	med	any (file-level copyleft; record in risk notes)
LGPL-3.0	med	npm-dep, keep-as-reference, extract-module (with care)
GPL-3.0, AGPL-3.0	high	keep-as-reference, skip
BUSL-1.1, SSPL-1.0	high	keep-as-reference, skip
PolyForm-Noncommercial-1.0.0	high	keep-as-reference, skip, extract-non-commercial-portion-only (legal)
Custom / unidentified	high	keep-as-reference (with risk note: license unverified)

Requirements

• Python 3.10+ (no third-party deps).
• A host repo with an examples/ directory.
• Optional but useful: an OpenSpec workflow for the drafted change directories.

Status

v1.0.0 — extracted from the recodee monorepo (PR recodeee/recodee#1059).