---
name: llp-adopt
description: Bring LLP to a repository and keep its installed skills current — the single entry point for "set up LLP here" and "update the LLP skills". Scaffold mode (fresh structure), retrofit mode (survey the codebase, draft a provenance-tagged root LLP, propose an adoption plan), install step (copy skills from a tagged release with a receipt), and update mode (verified, diff-approved skill updates).
source: ccheever/llp@v0.5.2
title: llp-adopt
canonical_url: https://skilld.dev/gh/expo/exact/llp-adopt
last_updated: 2026-11-12T06:01:29.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install expo/exact/llp-adopt`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/llp-adopt`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/expo/exact/llp-adopt) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/llp-adopt`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/llp-adopt --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/llp-adopt --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# llp-adopt

<!-- @ref https://github.com/ccheever/llp/blob/v0.5.2/llp/0001-adopting-llp.guide.md — the workflow this automates -->
<!-- @ref https://github.com/ccheever/llp/blob/v0.5.2/llp/0010.000-skill-installation-and-updates.spec.md — install/update design, receipts, trust model -->
<!-- @ref https://github.com/ccheever/llp/blob/v0.5.2/llp/0000-linked-literate-programming.explainer.md#provenance-for-generated-rationale — tagging rules for generated docs -->

One entry point for "add LLP to this project" and "update the LLP skills". Invoke as `/llp-adopt` (auto-detect scaffold/retrofit), `--mode scaffold` / `--mode retrofit`, or `/llp-adopt update`.

## Trigger

"Set up / bring LLP to this repo," for any repository state; "update the LLP skills," in any repo with installed skills.

## Invariants — adoption

- MUST extend an existing `llp/` tree if one exists — never start a second setup layer.
- MUST write only new files and clearly-marked managed blocks; existing user prose is never overwritten without showing a diff and asking. Reruns MUST be idempotent (no duplicate files or blocks).
- MUST keep every generated document `Draft` and provenance-tagged: claims are `[observed]` (say where), `[confirmed]` (named human + date), or `[inferred]` — and `[inferred]` claims never survive into a document proposed for promotion.
- MUST propose `@ref` annotations and apply them only after approval — no mass annotation, and none on volatile early code.
- MUST NOT create a batch of speculative LLPs in either mode; establish orientation and the loop, then hand off.
- When a tool expects `CLAUDE.md`, symlink it to `AGENTS.md` when safe rather than maintaining divergent copies.

## Invariants — install and update (LLP 0010.000)

- MUST install only from a tagged release (the tag's tree is the release), as copies never symlinks, and write a receipt beside the installation: origin, tag, resolved commit, profile flags (core; `review-plus`; `delivery`, which also records the repo's delivery policy in repo-local config), and a per-file content hash. The receipt — not `source:` frontmatter — is the trust root for updates.
- MUST confirm before writing user/global skill directories (they affect every repo for that user); project-local may proceed more freely.
- Update MUST three-way-check each file against the receipt hash. Any mismatch is a local fork: abort the coupled update, never clobber, and offer discard (restore managed copy) or detach (file leaves the managed set permanently; receipt records it; later updates ignore it and note upstream changes without applying).
- Update MUST present the full changeset for the installed profile *as defined at the target tag* as one diff, revalidate the approved state immediately before mutation, and be recoverable to either endpoint (the receipt write is the commit point). Runs are single-flight per installation.
- If upstream is unreachable, a tag moved or vanished, or content can't be verified against the resolved commit: report exactly that and write nothing. Cannot-verify never degrades to guess.

## Workflow

> **Recipe (advisory)** — *Adoption:* inspect first (existing `llp/`? agent files? how much code?): little to mine → **scaffold**; substantial history → **retrofit**. Both share the spine: `llp/` with its `current/` and `foundation/` overlay directories, root LLP 0000 (`Explainer`, `**Role:** Root`, `Draft` — linked into `current/`; it enters `foundation/` when the author makes it `Active`), the `AGENTS.md` managed block. Retrofit adds: survey, draft root LLP, propose 2–5 subsystem LLPs, layered annotation plan (LLP 0001). *Install:* offer after the managed blocks; default profile core, flags opt-in. *Update:* fetch the tag's tree (shallow clone or archive; git required), diff, approve, apply as a staged set with prior bytes retained until the receipt lands; rollback is `git revert` where the installation is committed, the backups otherwise. *Releasing (this repo):* bump `source:` pins and pinned URLs → commit → tag → push tag — a skill-file change is not installable until tagged.

## Artifact

Scaffold: `llp/` with `current/` (holding the link to the new root) and an empty `foundation/`, an LLP 0000 skeleton, the managed blocks. Retrofit: those plus a survey summary, `Draft` provenance-tagged document(s), and a proposed adoption plan. Install/update: pinned skill copies, the receipt, and (with the `delivery` flag) the repo policy file.

## Hand-offs

- Corpus exists → daily work starts with `llp-orient`; author follow-on docs with `llp-create`.
- Ratify generated drafts with `llp-review` where stakes warrant; keep healthy with `llp-maintain` — whose audit notes stale pins and hands back to `/llp-adopt update`.
