agentleFS
nfeuernfeuer/project-foundation-kit/.claude/skills/adopt-existing-project/SKILL.md

adopt-existing-project

Skill0 starsChanged 4 months agoMITView on GitHub

Non-destructively bring the foundation kit into an existing repo — audit what's already there, report gaps ranked by leverage, merge (never overwrite) kit artifacts, and recommend a phased rollout the team can approve incrementally

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Check for: docs/DOCS_STANDARD.md, a followups.md anywhere in the tree (may be at docs/superpowers/specs/followups.md or another …

    line 121
  2. Very specific:

    Look for a canonical design document.

    line 146
  3. Distinctive:

    If §1.2 detected absolute paths in hook commands, add a row:

    line 210
  4. Very specific:

    If .claude/settings.json exists, add the kit's hook entries alongside the existing ones — never replace the file.

    line 222
  5. Distinctive:

    Read the existing workflow.

    line 241
  6. Very specific:

    After the approved hooks/skills/agents/settings land, copy the source kit's .claude/kit-manifest.sha256 into the project's .claude/.

    line 266
  7. Distinctive:

    Every write step checks for prior existence before acting.

    line 282
  8. Very specific:

    All changes above are printed as diffs and confirmed with the user before any file is written.

    line 286
  9. Distinctive:

    Never present adoption as a single big-bang change.

    line 294
  10. Distinctive:

    No behavior visible to collaborators who don't use Claude Code.

    line 302
  11. Very specific:

    If a file exists — CLAUDE.md, settings.json, .github/workflows/ci.yml, any hook script — show a diff and require confirmation.

    line 339
  12. Very specific:

    If the repo uses npm run test, make lint, or cargo test, those go into toolchain.* in kit.yaml verbatim.

    line 344
  13. Distinctive:

    If the repo has its own hooks or Makefile targets that the kit would duplicate, note them in the audit and wire them through the profile …

    line 349

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Adopt Existing Project

Brings the foundation kit's guardrails into a repo that is already in flight. The invariant is non-destructive: nothing the user authored is overwritten, nothing is changed without an explicit dry-run diff and approval, and adoption can be abandoned at any step without leaving the repo in a broken state.

Contrast with new-project-bootstrap, which writes from a blank slate. Here you audit first, close only the gaps the team agrees to close, and roll out in phases so the change is never all-or-nothing.

Run every phase from the repo root. No changes are written until you confirm the dry-run output.

Progress ledger. Adoption spans phases and approval pauses — keep a ledger at .claude/scratch/adopt-existing-project-ledger.md (see docs/PROGRESS_LEDGER.md). Check for an existing ledger before starting and resume from it (audit findings and per-phase approvals are the recorded results); update it after every phase step; mark a phase awaiting human approval as BLOCKED. Delete the ledger when adoption completes or is explicitly abandoned.


Workflow

Phase 1 — Audit (change nothing)

Collect ground truth about what the repo already has. Do not modify any file. Every command here is read-only.

1.1 CI workflows

# kit.yaml inference — detect CI system and jobs
ls .github/workflows/ 2>/dev/null || echo "no GitHub Actions workflows"
ls .gitlab-ci.yml .circleci/ .buildkite/ 2>/dev/null || true

For each workflow file, list the job names and the commands they run (lint, typecheck, test, build, deploy, etc.). Note which jobs are missing vs. the kit's expected set: lint, typecheck, test, migration-heads, secrets-scan.

1.2 .claude/ scaffolding

ls .claude/ 2>/dev/null || echo "no .claude dir"
cat .claude/settings.json 2>/dev/null || echo "no settings.json"

Hook detection follows settings.json — a repo may keep hook scripts under scripts/hooks/, .claude/hooks/, or any other directory and wire them via $CLAUDE_PROJECT_DIR or absolute paths in settings.json. Do not assume .claude/hooks/ is the canonical location.

# Extract every hook command string from settings.json once, then report
# (1) .sh path resolution and (2) P4 portability: absolute paths not anchored
# to $CLAUDE_PROJECT_DIR break on any other machine.
python3 - <<'PY'
import json, os, re, sys

try:
    data = json.load(open(".claude/settings.json"))
except Exception as e:
    print(f"no settings.json or parse error: {e}"); sys.exit(0)

# Walk the nested hooks structure: hooks.<Event>[{matcher, hooks:[{command}]}]
cmds = []
for hook_list in data.get("hooks", {}).values():
    for entry in (hook_list if isinstance(hook_list, list) else []):
        for h in (entry.get("hooks", []) if isinstance(entry, dict) else []):
            cmd = h.get("command", "") if isinstance(h, dict) else ""
            if cmd:
                cmds.append(cmd)

# (1) Hook scripts — resolve every .sh token against the working tree
print(f"{len(cmds)} hook command(s) found" if cmds
      else "no hook commands found in settings.json")
for cmd in cmds:
    for token in cmd.split():
        if token.endswith(".sh"):
            resolved = token.replace("$CLAUDE_PROJECT_DIR", ".") \
                            .replace("${CLAUDE_PROJECT_DIR}", ".")
            exists = os.path.isfile(resolved)
            executable = os.access(resolved, os.X_OK) if exists else False
            status = "executable" if executable else \
                     ("NOT EXECUTABLE" if exists else "MISSING")
            print(f"  {token} -> {status}")

# (2) Portability — absolute paths not anchored to $CLAUDE_PROJECT_DIR
gaps = [(token, cmd[:80]) for cmd in cmds for token in cmd.split()
        if re.match(r'^[/~]', token) and '$CLAUDE_PROJECT_DIR' not in token]
for path, cmd_excerpt in gaps:
    print(f"  PORTABILITY GAP: absolute path '{path}'")
    print(f"    in command: {cmd_excerpt!r}")
    print(f"    -> use $CLAUDE_PROJECT_DIR/... for cross-machine portability")
if not gaps:
    print("no absolute paths in hook commands")
PY

From section (1), record which named hooks are wired (require-worktree, secret-scan-diff, prune-merged-worktrees, post-merge-prune, autoformat). Note any custom hooks the repo has added — those must be preserved.

Section (2) is the portability check: absolute paths in hook commands are a portability gap — record any found there in the gap report (Phase 2).

1.3 Docs taxonomy

ls docs/ 2>/dev/null || echo "no docs dir"
# followups.md may live at a non-standard path — search the whole tree
find . -name 'followups.md' -not -path '*/.git/*' | head

Check for: docs/DOCS_STANDARD.md, a followups.md anywhere in the tree (may be at docs/superpowers/specs/followups.md or another non-standard path), subdirs matching the kit's taxonomy (architecture/, domain/, workflows/, operations/, reference/). Note any existing structure — adopt around it, don't erase it.

1.4 Test, lint, and type config

# Python
cat pyproject.toml 2>/dev/null | grep -A5 '\[tool\.'
cat setup.cfg 2>/dev/null | grep -A3 '\[mypy\]\|\[flake8\]\|\[pytest\]'
# Node
cat package.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(list(d.get('scripts',{}).items()))" 2>/dev/null
cat .eslintrc* tsconfig.json 2>/dev/null | head -20
# Go
cat Makefile 2>/dev/null | grep -E 'lint|test|vet|fmt'

Extract the real lint, typecheck, and test commands. These become the toolchain.* values in the candidate profile — never replace them with kit defaults.

1.5 Spec file

ls spec*.md SPEC*.md docs/spec* README.md 2>/dev/null

Look for a canonical design document. If found, record its path — that becomes capabilities.spec.file.

1.6 Trunk branch

git remote show origin 2>/dev/null | grep 'HEAD branch'
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|.*/||'

1.7 Package manager / toolchain

ls pyproject.toml uv.lock poetry.lock Pipfile requirements*.txt \
   package.json pnpm-lock.yaml yarn.lock bun.lockb \
   go.mod Cargo.toml 2>/dev/null

Pick the first matching file to determine the language and manager. Set toolchain.install to the real install command (e.g. npm ci, go mod download, poetry install).

1.8 Logging reality check

# What does this repo actually log with? (see logging-init step 1 for the full probe)
grep -rEl --include='*.py' 'import (structlog|loguru)|import logging' src/ 2>/dev/null | head -3
grep -rEl --include='*.{js,ts}' "require\(['\"](pino|winston|bunyan)|from ['\"](pino|winston)" src/ lib/ 2>/dev/null | head -3
grep -rE --include='*.py' '^\s*print\(' src/ 2>/dev/null | wc -l
grep -rE --include='*.{js,ts}' 'console\.(log|error|warn)' src/ lib/ 2>/dev/null | wc -l

(Prune with --exclude-dir={.git,.venv,node_modules,__pycache__,dist,build}.) Record the classification — GREENFIELD / PRINT-ONLY (with site count) / PARTIAL / ESTABLISHED (library) — so the Phase 2 gap report states the logging gap from evidence, not assumption. The fix is the logging-init skill in Phase 4; do not wire anything now.

1.9 Infer a candidate kit.yaml

From the evidence above, draft a kit.yaml using the real commands and the best-fit preset (library / service / llm-app / frontend / data-pipeline). Mark every field inferred vs. confirmed. Print it — do not write it yet.


Phase 2 — Gap Report

Produce a ranked table of what's missing relative to the kit's practices. Rank by leverage (risk reduced × effort to close). For each gap, name the exact skill or hook that closes it.

Template:

#GapCurrent stateKit artifact that closes itEffort
1No worktree isolationAgents edit main directlyrequire-worktree.sh hook + parallel-work skillLow
2No secrets scan on pushSecrets can reach the remotesecret-scan-diff.sh hook (PreToolUse on Bash)Low
3CI has lint but no typecheckType errors ship undetectedAdd typecheck job to CI + pre-pr step 2Medium
4No pre-PR gatePRs go red after pushpre-pr skillLow
5No follow-ups logDeferred decisions get lostdocs/followups.md + followup-tracking skillLow
6No spec-sync loopSpec drifts from code silentlydoc-sync skill + spec-drift-checker agentMedium
7No eval harnessPrompt behavior unverifiableeval-harness + prompt-regression skillsHigh
8No structured logging (per §1.8: print-only, 87 sites)Failures may be swallowed; nothing is greppablelogging-init skill (probe → questions → wire) + fallback_alert.pyHigh
9No nightly auditDrift accumulates unnoticednightly-audit skill + cronMedium

Populate the table from the actual audit — omit rows where the repo already satisfies the criterion. Reorder by actual leverage for this repo.

If §1.2 detected absolute paths in hook commands, add a row: Hook commands use absolute paths | hardcoded /home/… or /mnt/… paths in settings.json hook commands | replace with $CLAUDE_PROJECT_DIR/… in each affected command string | Low.


Phase 3 — Merge, Don't Overwrite

Apply each approved gap closure. Rules:

Settings / hooks — merge JSON, don't replace

If .claude/settings.json exists, add the kit's hook entries alongside the existing ones — never replace the file. Show a diff:

# dry-run: what would be added to .claude/settings.json
python3 - <<'PY'
import json, sys
existing = json.load(open(".claude/settings.json"))
kit_hooks = <kit settings template content>
# merge: for each hook type (SessionStart, PreToolUse, PostToolUse),
# append kit entries that are not already present (compare by command string)
merged = merge_hooks(existing, kit_hooks)
print(json.dumps(merged, indent=2))
PY

Copy hook scripts that are absent; skip any that already exist under the same name. If the repo has a custom hook at the same path, emit a warning — do not overwrite.

CI — add missing jobs only

Read the existing workflow. Add only the jobs absent from it. Never delete or rename existing jobs. Show a unified diff of the workflow file before writing.

CLAUDE.md — write only if absent; otherwise diff

if [ -f CLAUDE.md ]; then
  echo "CLAUDE.md exists — showing proposed additions only (review before applying)"
  diff CLAUDE.md <(cat "$KIT/CLAUDE.template.md")
else
  echo "CLAUDE.md absent — will write from template"
fi

Fill placeholders from the audit (<stack>, <trunk_branch>, <spec_file>, etc.) before writing or diffing.

kit.yaml — write only if absent

if [ -f .claude/kit.yaml ]; then
  echo "kit.yaml exists — showing candidate profile for review; edit manually"
else
  echo "Writing inferred kit.yaml"
fi

Record the kit manifest

After the approved hooks/skills/agents/settings land, copy the source kit's .claude/kit-manifest.sha256 into the project's .claude/. It stamps the kit version adopted here so kit-update can later distinguish a locally-modified kit file from an untouched one instead of guessing (SPEC §12.1). Files the team chose to keep their own version of will hash-mismatch this baseline and correctly surface as NEEDS REVIEW on the next update — that is intended.

cp "$KIT/.claude/kit-manifest.sha256" .claude/kit-manifest.sha256

Docs and follow-ups — add, never clobber

  • docs/DOCS_STANDARD.md: copy if absent.
  • docs/followups.md: copy if absent; if present, append a ## Kit Adoption section with the gap items as open follow-ups.
  • Subdirs (docs/domain/, docs/workflows/, etc.): mkdir -p only — never touch existing files inside them.

Idempotency

Every write step checks for prior existence before acting. Re-running the skill after a partial adoption produces only the remaining changes, never duplicates.

Dry-run default

All changes above are printed as diffs and confirmed with the user before any file is written. Run with an explicit --apply flag (or user confirmation) to commit them.


Phase 4 — Incremental Rollout

Never present adoption as a single big-bang change. Recommend phases, each independently valuable, each requiring explicit human approval before the next.

Phase 1 — Safety net (1–2 hours, zero collaboration risk)

  • Hooks: secret-scan-diff on Bash push/PR-create.
  • Hooks: prune-merged-worktrees + post-merge-prune (safe on any repo).
  • Skills: pre-pr, ci-watch, branch-conflict-check.
  • Outcome: no PR arrives red; no secret leaks; branch queue stays healthy.
  • No behavior visible to collaborators who don't use Claude Code.

Phase 2 — Worktree isolation (coordinate with collaborators first)

  • Hook: require-worktree blocking edits on trunk.
  • Skill: parallel-work for concurrent sessions.
  • Outcome: agents never race on the same file.
  • This phase changes behavior for everyone using Claude Code on the repo. Flag it to the team before enabling. On a solo repo, enable freely.

Phase 3 — Doc / spec loop

  • Skills: doc-sync, followup-tracking, session-handoff.
  • Agents: spec-drift-checker, docs-updater.
  • capabilities.spec.file set in kit.yaml.
  • Outcome: every PR keeps docs and spec in sync; deferred decisions are tracked.

Phase 4 — Observability and evaluation

  • Skills: logging-init (driven by the §1.8 classification — asks its three questions, then wires additively; ESTABLISHED repos keep their library), eval-harness, prompt-regression, cost-check, nightly-audit.
  • Agents: observability-reviewer, test-gap-analyzer.
  • Reference implementations: fallback_alert.py (logging itself comes via logging-init).
  • Outcome: LLM behavior is verifiable; costs are tracked; silent failures are eliminated; a morning digest flags drift before it compounds.

Each phase can be the end state if the team decides the later phases aren't worth the overhead for their context.


Guardrails

Never enable require-worktree silently on a shared repo. It blocks edits on trunk for every Claude Code user on the repo, not just you. Always flag this to the team and get explicit buy-in before Phase 2.

Never overwrite a file the user authored. If a file exists — CLAUDE.md, settings.json, .github/workflows/ci.yml, any hook script — show a diff and require confirmation. Writing without review is forbidden.

Preserve existing tool commands. If the repo uses npm run test, make lint, or cargo test, those go into toolchain.* in kit.yaml verbatim. Never substitute uv run pytest or any other kit default without explicit instruction.

Recover custom hooks into kit.yaml. If the repo has its own hooks or Makefile targets that the kit would duplicate, note them in the audit and wire them through the profile rather than installing parallel commands.

Autoformat hook: match the language. The PostToolUse autoformat defaults to ruff. Before installing it, confirm the repo's formatter (prettier, gofmt, rustfmt) and substitute the correct command. Installing the wrong formatter silently reformats code.


Output

## Adopt Existing Project

### Audit Summary
- Repo: <name> | Trunk: <branch> | Stack: <language + package manager>
- Preset inferred: <preset>
- CI system: <GitHub Actions / GitLab CI / none> | Jobs found: <list>
- .claude/ present: <yes | no>
- settings.json: <present (N hook commands) | absent>
- Hooks wired (from settings.json): <list — each: executable / NOT EXECUTABLE / MISSING | none>
- Absolute paths in hook commands: <none | list of portability gaps>
- CLAUDE.md: <present | absent>
- Docs: <dir present — DOCS_STANDARD: yes/no, followups: yes/no (path if non-standard) | absent>
- Spec file: <path | none detected>
- Logging: <ESTABLISHED (<library>) | PARTIAL | PRINT-ONLY (N sites) | GREENFIELD>
- Toolchain detected: lint=<cmd>, typecheck=<cmd>, test=<cmd>, install=<cmd>
- Candidate kit.yaml: <printed above — review and confirm>

### Gap Report (ranked by leverage)
| # | Gap | Skill/hook that closes it | Effort |
|---|-----|--------------------------|--------|
| 1 | ... | ... | ... |
| N | ... | ... | ... |

### Proposed Changes (dry-run — nothing written yet)
- .claude/settings.json: <merge N hook entries — diff shown above>
- .claude/hooks/: <copy: require-worktree.sh, secret-scan-diff.sh | skip: already present>
- .claude/kit-manifest.sha256: <record — baseline for kit-update classification>
- .github/workflows/ci.yml: <add jobs: typecheck, migration-heads — diff shown above>
- CLAUDE.md: <absent — will write from template | present — proposed diff shown above>
- .claude/kit.yaml: <absent — will write | present — candidate profile shown for review>
- docs/DOCS_STANDARD.md: <copy | skip — present>
- docs/followups.md: <copy | append Kit Adoption section>
Confirm to apply? (y/N)

### Phased Rollout
Phase 1 (Safety net — apply now, no collaboration risk):
  [ ] secret-scan-diff hook
  [ ] prune-merged-worktrees + post-merge-prune hooks
  [ ] pre-pr, ci-watch, branch-conflict-check skills

Phase 2 (Worktree isolation — coordinate with team first):
  [ ] require-worktree hook  ← BEHAVIOR CHANGE for all Claude Code users
  [ ] parallel-work skill

Phase 3 (Doc / spec loop):
  [ ] doc-sync, followup-tracking, session-handoff skills
  [ ] spec-drift-checker, docs-updater agents
  [ ] capabilities.spec.file set in kit.yaml

Phase 4 (Observability + eval):
  [ ] eval-harness, prompt-regression, cost-check, nightly-audit skills
  [ ] observability-reviewer, test-gap-analyzer agents
  [ ] logging_setup.py + fallback_alert.py reference impls

Human approves each phase before the next begins.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.