kit-update
Skill0 starsChanged 4 months agoMITView on GitHub
Propagate improvements from the source kit to a project that adopted it. Diffs kit-managed files, classifies changes as safe/needs-review/new, never clobbers local customizations silently, bumps kit_version after applying.
In this repository29 other files it gives its agents.
- adopt-existing-projectSkill
- adrSkill
- branch-conflict-checkSkill
- ci-watchSkill
- compound-learningsSkill
- config-auditSkill
- cost-checkSkill
- coverage-ratchetSkill
- doc-syncSkill
- eval-harnessSkill
- flaky-triageSkill
- followup-trackingSkill
- incident-captureSkill
- kit-doctorSkill
- logging-initSkill
- migration-checkSkill
- new-project-bootstrapSkill
- nightly-auditSkill
- observability-checkSkill
- parallel-workSkill
- perf-budgetSkill
- pr-babysitterSkill
- pre-prSkill
- prompt-regressionSkill
- releaseSkill
- session-handoffSkill
- sync-healthSkill
- using-the-kitSkill
- writing-kit-skillsSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 6 are distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Run this when the source kit ships improvements you want to pull into a project that already adopted it.
- Distinctive: line 63
If the project version is already at or ahead of the source kit version, report that and stop.
- Very specific: line 187
If the project has no .claude/kit-manifest.sha256 (adopted before the manifest shipped), fall back to the git-blame heuristic below, and …
- Distinctive: line 216
Before applying anything, emit:
- Distinctive: line 250
Do not apply without a clear instruction to proceed.
- Very specific: line 279
After applying all changes (at least one SAFE or NEW file was written), update kit_version in the project's .claude/kit.yaml to match the …
- Distinctive: line 304
If no files were applied (all SAFE files declined, all NEEDS REVIEW skipped), do not bump the version.
- Distinctive: line 309
After applying, invoke the kit-doctor skill to confirm the updated install is correctly wired.
- Very specific: line 350
Never report a file as updated unless you actually wrote it.
≈ “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.
Files
Kit Update
Run this when the source kit ships improvements you want to pull into a project that already adopted it. It diffs kit-managed files one by one, classifies each change, and applies only what is safe to apply without your input. Anything the project customized comes to you for review. Always dry-run first.
Progress ledger. An apply run prompts per file and can be interrupted —
keep a ledger at .claude/scratch/kit-update-ledger.md (see
docs/PROGRESS_LEDGER.md): record each file's classification and, during
apply, each per-file decision (applied / kept project version / skipped)
as you go. On resume, do not re-ask for files already decided. Delete the
ledger after Step 7.
You need two paths:
- Source kit — the foundation-kit repo (default:
~/project-foundation-kitor the path inkit_sourceif the project'skit.yamlsets it). - Project — the repo you are updating (the current working directory).
Workflow
Step 0 — Locate both roots
# source kit root
KIT_ROOT="${KIT_SOURCE:-$HOME/project-foundation-kit}"
# project root (cwd)
PROJECT_ROOT="$(git rev-parse --show-toplevel)"Confirm both directories exist and both contain .claude/kit.yaml. If either
is missing, stop with a clear error — do not guess.
Step 1 — Compare versions
python3 -c "
import yaml
kit = yaml.safe_load(open('$KIT_ROOT/.claude/kit.yaml'))['kit_version']
proj = yaml.safe_load(open('$PROJECT_ROOT/.claude/kit.yaml'))['kit_version']
print(f'Source kit: {kit}')
print(f'Project: {proj}')
import packaging.version as pv
if pv.Version(proj) >= pv.Version(kit):
print('Project is already at or ahead of source kit — nothing to do.')
exit(0)
print(f'Update available: {proj} → {kit}')
"If the project version is already at or ahead of the source kit version, report that and stop. Do not proceed.
Step 2 — Enumerate kit-managed files
Kit-managed files are everything under these paths in the source kit — the same
set the manifest (scripts/gen-manifest.sh) covers:
.claude/skills/*/SKILL.md
.claude/agents/*.md
.claude/hooks/*.sh
.claude/settings.template.jsonBuild the list (relative paths, one per line):
( cd "$KIT_ROOT" && {
find .claude/skills -name 'SKILL.md'
find .claude/agents -maxdepth 1 -name '*.md'
find .claude/hooks -name '*.sh'
[ -f .claude/settings.template.json ] && echo .claude/settings.template.json
} 2>/dev/null | sort )Exclude kit.yaml itself — that is per-project configuration, not a kit-managed
template (per SPEC §12.1, kit-update manages files, not config; the mode map is
/kit-menu's job). Note that .claude/kit-manifest.sha256 is itself
kit-managed, but it is not diffed or prompted like a content file — it is
handled by Step 5's recording rule (copied wholesale to stamp the adopted
version). Do not add it to the per-file classification list in Step 3.
Step 3 — Classify each file (dry-run)
Classification is manifest-based. The project carries a recorded
.claude/kit-manifest.sha256 — the sha256sum-format list of kit-managed
paths and their hashes as of the kit version the project last adopted
(copied in at install/update time; see Step 5 and SPEC §12.1). That recorded
baseline is what makes the SAFE-vs-NEEDS-REVIEW split real: it is the third
point of a 3-way comparison between the project's current copy, the version the
project adopted, and the source kit HEAD.
For each kit-managed relative path $REL, gather three facts:
- source hash — sha256 of
$KIT_ROOT/$REL(the kit HEAD). - project hash — sha256 of
$PROJECT_ROOT/$REL(absent if the file is missing in the project). - recorded hash — the hash for
$RELin the project's recorded.claude/kit-manifest.sha256(absent if the path is not listed).
Then classify:
| Scenario | Classification | Action |
| project hash == source hash | SKIP | Up to date — project copy already equals kit HEAD |
| file absent in project | NEW | Offer to add it |
| project hash == recorded hash and source differs (project never touched it since adopting) | SAFE | Apply automatically (dry-run: show diff) |
| project hash != recorded hash and source differs (locally modified) | NEEDS REVIEW | Show 3-way diff; ask before touching |
$REL not in the recorded manifest (adopted pre-manifest, or a project-authored file shadowing a new kit path) and source differs | NEEDS REVIEW | Never SAFE — there is no baseline to prove the project copy is untouched |
The two rules that keep this honest: a file is SAFE only when the project's current hash exactly matches what the manifest recorded (proving the project never edited it), and a path missing from the recorded manifest is never SAFE — without a recorded baseline we cannot distinguish an untouched adopted file from a divergent local one, so it goes to review.
Path mapping — settings. The manifest tracks the source path
.claude/settings.template.json, but installs write it to the project as
.claude/settings.json (bootstrap copies it; adoption merges into an existing
one). For this one file, hash the project's .claude/settings.json and compare
it against the recorded hash of .claude/settings.template.json — and never
classify it SAFE: when the source template changed since the recorded version,
it is always NEEDS REVIEW. Settings are security-sensitive configuration
(hook wiring, permissions); changes are merged by hand and re-checked with
config-audit, never auto-applied. A project with no .claude/settings.json
at all is NEW.
# sha256 of a file, portable (Linux coreutils / macOS): prints just the hash
kit_sha256() {
if command -v sha256sum >/dev/null 2>&1; then
sha256sum "$1" | awk '{print $1}'
else
shasum -a 256 "$1" | awk '{print $1}'
fi
}
MANIFEST="$PROJECT_ROOT/.claude/kit-manifest.sha256"
# recorded hash for an exact relative path from the project's manifest
recorded_hash() {
# match the path column exactly (sha256sum format: "<hash><2 spaces><path>")
awk -v p="$1" '$2 == p {print $1; exit}' "$MANIFEST"
}
# For each kit-managed relative path $REL:
SRC_HASH="$(kit_sha256 "$KIT_ROOT/$REL")"
if [ ! -e "$PROJECT_ROOT/$REL" ]; then
echo "NEW"
else
PROJ_HASH="$(kit_sha256 "$PROJECT_ROOT/$REL")"
REC_HASH="$(recorded_hash "$REL")"
if [ "$PROJ_HASH" = "$SRC_HASH" ]; then
echo "SKIP" # already equals kit HEAD
elif [ -z "$REC_HASH" ]; then
echo "NEEDS REVIEW" # no recorded baseline for this path
elif [ "$PROJ_HASH" = "$REC_HASH" ]; then
echo "SAFE" # untouched since adoption; source changed
else
echo "NEEDS REVIEW" # locally modified
fi
fiFor NEEDS REVIEW files, produce the 3-way diff for the report by showing the
source-vs-project diff (diff "$PROJECT_ROOT/$REL" "$KIT_ROOT/$REL"); note in
the prompt whether the divergence is from a local edit (recorded hash present
but mismatched) or from a missing baseline (path not in the manifest).
Bash only — no Python here (SPEC §10, Tier-0: kit machinery is bash + git).
Fallback — no recorded manifest (heuristic)
If the project has no .claude/kit-manifest.sha256 (adopted before the
manifest shipped), fall back to the git-blame heuristic below, and prefix the
report with a WARN:
WARN: no .claude/kit-manifest.sha256 in this project — classification is a
git-blame heuristic and will over-report NEEDS REVIEW (e.g. after squash
merges). It becomes exact once a manifest is recorded on the next apply.
See SPEC §12.1 / follow-up PT10.Heuristic: diff the project's copy against the source kit.
# For each kit-managed relative path $REL (fallback only):
diff "$KIT_ROOT/$REL" "$PROJECT_ROOT/$REL" > /dev/null 2>&1
# exit 0 → identical → SKIP
# exit 1 → differs → SAFE if project never touched it, else NEEDS REVIEW
# file missing in project → NEWTo distinguish SAFE from NEEDS REVIEW without a manifest: check
git diff HEAD -- "$REL" / git blame in the project. If git shows the
project-side file was modified after the kit was adopted (any local commit
changes it), classify as NEEDS REVIEW; otherwise SAFE. This is the heuristic the
manifest replaces — never trust it as strongly as a recorded hash.
Step 4 — Print the dry-run report
Before applying anything, emit:
## Kit Update — Dry Run
Source kit: <version>
Project: <version>
SAFE to apply (no local modifications):
.claude/skills/pre-pr/SKILL.md
.claude/hooks/secret-scan-diff.sh
...
NEEDS REVIEW (project has local modifications):
.claude/skills/nightly-audit/SKILL.md
--- source kit
+++ project
@@ ... @@
<3-way diff excerpt>
NEW files (not present in project):
.claude/skills/kit-doctor/SKILL.md
.claude/skills/kit-update/SKILL.md
...
SKIP (already up to date):
.claude/hooks/require-worktree.sh
...Stop here unless the user explicitly asked for --apply. If dry-run only,
print the report and exit.
Step 5 — Apply (only with explicit confirmation)
Do not apply without a clear instruction to proceed. When confirmed:
- SAFE files — copy from source kit to project, overwriting. No prompt needed.
- NEEDS REVIEW files — show the full diff and ask: "Apply source kit version, keep project version, or skip?" For each file, wait for the answer before moving to the next. Never clobber a customized file without a per-file explicit answer.
- NEW files — ask: "Add this file?" For each new file, wait for confirmation.
- SKIP files — do nothing.
Record the manifest — after all per-file decisions are made, copy the source kit's
.claude/kit-manifest.sha256into the project at the same path, overwriting any previously recorded manifest. This stamps the version the project just adopted and is what makes the next update's Step 3 classification exact (SPEC §12.1).cp "$KIT_ROOT/.claude/kit-manifest.sha256" \ "$PROJECT_ROOT/.claude/kit-manifest.sha256"Note — this is by design, not a bug: any file where the user chose "keep project version" now hash-mismatches the freshly recorded manifest (the manifest lists the new source hash; the project kept the old content). On the next update that file correctly re-classifies NEEDS REVIEW rather than being silently overwritten as SAFE. Record the manifest even if some files were declined; a recorded baseline is always more accurate than none.
Step 6 — Bump kit_version
After applying all changes (at least one SAFE or NEW file was written), update
kit_version in the project's .claude/kit.yaml to match the source kit:
python3 -c "
import yaml, re
with open('$PROJECT_ROOT/.claude/kit.yaml') as f:
content = f.read()
with open('$KIT_ROOT/.claude/kit.yaml') as f:
new_ver = yaml.safe_load(f)['kit_version']
updated = re.sub(
r'(kit_version:\s*[\"\']).+?([\"\'])',
lambda m: m.group(1) + new_ver + m.group(2),
content,
count=1,
)
if updated == content:
print('ERROR: kit_version line not found/changed — version NOT bumped')
raise SystemExit(1)
with open('$PROJECT_ROOT/.claude/kit.yaml', 'w') as f:
f.write(updated)
print('kit_version bumped to', new_ver)
"If no files were applied (all SAFE files declined, all NEEDS REVIEW skipped), do not bump the version.
Step 7 — Run kit-doctor
After applying, invoke the kit-doctor skill to confirm the updated install
is correctly wired. A kit-doctor FAIL after update means a file was applied
that broke a dependency — revert with git restore and investigate.
Output
Emit one of these reports, depending on whether this was a dry run or a full apply run:
Dry run:
## Kit Update — Dry Run
(report from Step 4)
Run with --apply to apply SAFE changes and prompt for NEEDS REVIEW and NEW.Apply run:
## Kit Update — Applied
Source kit: <version>
Project: <old version> → <new version>
Updated:
.claude/skills/pre-pr/SKILL.md SAFE applied
.claude/hooks/secret-scan-diff.sh SAFE applied
Reviewed:
.claude/skills/nightly-audit/SKILL.md kept project version (user choice)
Added:
.claude/skills/kit-doctor/SKILL.md added
.claude/skills/kit-update/SKILL.md added
Skipped (already up to date):
.claude/hooks/require-worktree.sh
manifest: recorded (.claude/kit-manifest.sha256 → <new version>)
kit_version: <old> → <new>
Next: run kit-doctor to verify the updated install.Never report a file as updated unless you actually wrote it. Never bump
kit_version unless at least one file was written.
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
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.

