| name | claude-seed-sync |
| description | Audits a project's installed Claude seed docs against the toolkit's current seed source and proposes per-section edits without overwriting customizations. Use when asked to "sync seeds", "update my seeds", "check seed drift", "did the toolkit seeds change", or when reconciling `CLAUDE.md` and `.claude/` preambles after an upstream toolkit update. |
Claude seed sync
Surfaces drift between the toolkit's current seed docs and what was installed in this project, then proposes targeted edits. The CLI emits seed content. This skill diffs, reasons, and writes the proposal to a review file. It does not write target files until the user confirms.
Guards
- If the
aitk CLI is not on PATH, stop: ❌ aitk CLI not found. Install the toolkit first.
- If no
.claude/ directory exists at the project root, stop: ❌ No .claude/ directory found. Run aitk claude init first.
Step 1: read toolkit sources
Run both in parallel from the project root:
aitk claude seeds list --json 2>/dev/null
aitk standards list --json 2>/dev/null
Seeds emit an array of {name, source, target, content}. Standards emit {standards: [{name, description, target, content}]}. In both cases target is the path relative to the project root where the file installs. Merge the two into one list of entries tagged by source (seed or standard).
If the target project has no .claude/standards/ directory, skip the standards stage silently.
Step 2: read installed copies
For each entry in the merged list, read the file at its target path from the project root. Run reads in parallel. Mark missing files for Add treatment. Skip non-text seeds (.json) for section diffing. Record a one-line note in the scope table that the user can compare manually.
When detecting target-only files for local-only flagging, skip files the toolkit's own walkers regenerate from sibling frontmatter (today: any index.md produced by aitk indexes regen). They are absent from source catalogs by design, so flagging them as local-only is a false positive.
Note on settings.json: the seed now ships only the PostToolUse hook block. If a target project's .claude/settings.json carries attribution or permissions keys, those are stale: the user-level ~/.claude/settings.json (installed via aitk claude setup) owns them now. Flag those keys in the scope table for removal rather than diffing them as content drift.
Step 3: diff per section
For each seed file present in both sides, parse the body into a preamble (everything between H1 and the first H2) plus one part per ## header, then compare part by part. Treat the preamble as a single unit with the same verdicts as a section. Use (preamble) as its label in the proposal.
- Identical: ignore.
- Toolkit-only section (present in source, absent in target): candidate to Add.
- Target-only section (present in target, absent in source): preserve, never propose removal. These are user customizations.
- Drifted section (present in both, content differs): candidate to Update.
- If the target version looks customized (extra bullets, project-specific paths, filled-in placeholders), call it out as Customized. Default action: skip, record in the scope table only, never numbered.
- If the target version looks like the original toolkit version with the toolkit having moved on, call it out as Stale. Default action: propose update.
The user judges intent. The skill makes the judgment legible.
Absorbed-already check
Before proposing an Update, grep the target section for the seed text's keywords. If the rule is already implied by an adjacent bullet in the target version, drop the proposal and record the section as in sync in the scope table.
Step 4: write the proposal to the review file
Derive a slug from the current git branch: run git branch --show-current and replace / with -. Fall back to latest on empty output.
Write the full proposal to .claude/review/seed-audit-<slug>.md at the main worktree root. Do not print the proposal inline.
Structure: a summary block at the top, a legend, a scope table, then one H2 per numbered item. Number items across all files so the user can reference them by number. Fuse the status, action, and target into each H2. Every item starts as 📝 pending.
# Seed audit: <slug>
**Pending:** <all numbers>
Legend: ✅ applied · ⏭ skipped · 📝 pending
How to respond: fill in `Decision:` per item (`apply` or `skip`), then ping. Chat shortcut: `all`, `none`, or a list of numbers.
## Scope
Group rows by source. `Seeds` first, then `Standards`. Mark target-only files (present in target, absent in source) as `local-only` and leave them untouched.
| Source | File | Status | Note |
| -------- | ---------- | ---------- | ---------------------------- |
| seed | `<target>` | diffed | <counts> |
| seed | `<target>` | in sync | |
| seed | `<target>` | skipped | non-text, compare manually |
| seed | `<target>` | customized | <section> skipped by default |
| standard | `<target>` | diffed | <counts> |
| standard | `<target>` | local-only | not in toolkit, preserved |
## 1. 📝 Update → `<target-path>` / <section>
Why: <one-line reason>
```diff
- <project line removed>
<unchanged context line>
* <seed line added>
```
Decision:
## 2. 📝 Add → `<target-path>` / <section>
Why: <one-line reason>
```diff
- <seed section body, each line prefixed with +>
```
Decision:
Update items show both sides in one diff block: removed lines from the project version with -, added lines from the seed version with +, unchanged context lines without a prefix. Add items show only + lines. Customized sections appear in the scope table only, never numbered. A file with no drift still appears in the scope table as in sync.
After writing, tell the user ✅ Wrote proposal to .claude/review/seed-audit-<slug>.md. Ask them to fill in Decision: per item, then re-ping or use the chat shortcut.
Rewrite the review file in place whenever the proposal changes mid-review. The file stays the source of truth for the current decisions.
Step 5: apply
Re-read the review file as source of truth. For each item, parse Decision::
apply (or affirmative): run the Edit, flip emoji to ✅.skip: leave the target section as-is, flip emoji to ⏭.defer or empty: leave 📝 pending, no action.- Contains
? or unrecognized verb: leave 📝 pending, no action.
Chat shortcut: the user replies with all, none, or a comma-separated list of numbers. Apply only the numbered items.
Apply edits one at a time via Edit, replacing one section at a time. Never rewrite a whole file. Claude Code's tool permission dialog is the confirmation gate per edit.
As each item resolves, update its status in the review file: flip the H2 emoji from 📝 to ✅ for applied or ⏭ for skipped. Refresh the summary block counts at the top. Do not delete the review file. It stays as a receipt until the next claude-seed-sync run overwrites it or the user clears it.
After completion
Output one line per action taken:
✅ Updated: <target-path> / <section>⏭ Skipped: <target-path> / <section>
End with a one-line bucket summary: ✅ Applied: <nums> | ⏭ Skipped: <nums> | 📝 Pending: <nums>. Omit empty buckets. If anything is pending, remind the user they can fill in a Decision: and re-ping, or commit a skip with skip <nums> in chat.
If the user accepted nothing, output:
✅ No changes applied.
