Imported from Mar5929/claude-toolkit (plugins/project-init/skills/project-sync/SKILL.md). Install upstream with npx skills add Mar5929/claude-toolkit --skill project-sync. Copyright stays with the author.

project-sync: bring an existing project up to the toolkit

project-init lays foundations in a NEW project. This skill is its sibling for EXISTING projects: figure out what the toolkit provides, check the current project against it, report the gaps, then close the gaps the user approves.

Run the steps in order. Never change anything before step 4.

Step 1: inventory the toolkit

First, refresh the installed toolkit so this audit sees the latest. This skill reads the toolkit from the installed plugin copy (option 1 below), and that copy does NOT update itself when the repo changes on GitHub. A merged change sits on GitHub until each machine pulls it. So before inventorying, update the local copy: inside a Claude Code session run /plugin marketplace update claude-toolkit, or from a terminal run claude plugin marketplace update claude-toolkit. Skip this only when you are reading from a freshly-pulled local clone (option 2). A stale plugin copy produces a stale audit, so the project silently misses the newest rules and systems, which is the exact failure this step guards against.

Build the list of things the toolkit currently provides. Do not hard-code today's list; read the toolkit itself so new systems are picked up automatically as it grows.

• Locate the toolkit files, in order of preference:
  1. They ship with this plugin. From this skill's directory, ../../library/ holds rules/general/ (with its README.md index), rules/salesforce/ (with its own index), tools/, templates/, and guides/. The sibling skill's ../project-init/references/ holds thin-claudemd.md and setup-flow.md, and the plugin root holds .claude-plugin/plugin.json.
  2. A local clone of the toolkit repo, if the user has one.
  3. Fetch the repo (Mar5929/claude-toolkit), or ask the user where it lives.
• For a separately packaged system such as system-guide or second-brain, locate its installed plugin or the sibling source in the local toolkit clone. During the read-only audit, the marketplace manifest is enough to report availability. Install the system plugin only after the owner approves adoption, then use its canonical sources instead of maintaining copies in project-init.
• Enumerate, at minimum:
  • every rule file in library/rules/general/, noting from its README.md which are default ON and which are conditional, and what each rule currently says, so step 2 can tell a project copy that is merely worded differently from one that is genuinely behind; Salesforce projects also get the library/rules/salesforce/ files
  • the Plain English output style file and setting. This is the only style the toolkit ships and its default for project setup. Check the installed file against library/output-styles/plain-english.md and check the selected name separately. Preserve an owner's deliberate choice of another style
  • the per-server MCP tool rules in ../../library/guides/mcp-best-practices.md; these are conditional, so only audit the servers this project connects
  • each system from the setup gates: hooks, System Guide, project knowledge, knowledge layer
  • the document folder Gate 1 offers every project, docs/designs/. It is the folder plus a short README.md plus its own line in the codemap, and a folder with no codemap line is a folder no agent opens, so check all three parts. ../project-init/references/setup-flow.md has what it holds and how long a file in it lives. It only applies where work items are tracked outside the repository; a project on the Git-ignored .work-items/ tracker keeps each design with its own item, so the folder is not a gap there. A project that was offered it and declined is not missing it; record the decline so this audit stops raising it
  • the multi-part kits, which are a tool plus a rule plus a hook rather than a single file, so a partial install looks like a pass unless you check each part: the Salesforce permission set kit (salesforce-permissions-retrieval.md), the Salesforce dependency graph (salesforce-dependency-graph.md, whose tool is ../../library/tools/kb/), and, for every other stack, the graphify code graph (graphify-dependency-graph.md, whose rule is library/rules/general/dependency-graph.md)
  • the work-tracker plugin, root .work-items/, and any older delivery/work-items/, engagement/work-items/, or root work-items/ tree
  • the work-item lifecycle rule in .claude/rules/, the declared tracker, and its stage markers (a local stage field or GitHub stage labels). Local mode also needs the current work skill and CLI for active-item selection, progress, validation, and completion events. Missing optional fields on legacy items are valid; never backfill them.
  • the root CLAUDE.md quick-save table and its matching rules. Expect a knowledge/ row only for configured project knowledge and a .work-items/ row only for configured local tracking. Each row points to the canonical manual, rule, or skill and does not repeat the full procedure. Report a missing or stale row, a row for an absent system, and a configured quick-save system whose owning instructions are missing or outdated
  • the hooks-library plugin. Audit spec-check-reminder under PostToolUse only where session-skills is installed. Check its settings entry and copied script. Report any retired work-item-stage-reminder script or registration for removal, preserving all other hooks. Also report the retired memory-pr-hook plus wrap-up-ritual.md route for removal after the current knowledge package is installed.
  • a project still carrying the retired voice rules (writing-and-language.md, how-to-reply.md, treat-owner-as-non-technical.md, define-your-terms.md). All four were removed from the toolkit in favor of an output style. Report them, but see step 4 before touching any
  • a project still carrying the retired style hooks (style-reminder under UserPromptSubmit, writing-guard under Stop, or their scripts and .claude/style-reminder.json and .claude/writing-guard.json config files). Both were removed from the toolkit in August 2026 as per-message overhead. Report them for removal: delete the settings entry, the script, and the config file, leaving every other hook entry alone
  • a project still carrying explain-simply-reminder under UserPromptSubmit. The toolkit shipped it in September 2026 and removed it in issue #271, where the plain-english output style replaced it. Report it for removal, and offer the style in its place rather than a bare deletion. Match on the script name, never on the event: memory-reminder.mjs sits under the same event, belongs to project knowledge, and stays
  • a project still carrying a .claude/output-styles/plain-language.md file, at any vintage. The toolkit removed that style in issue #245. Offer to replace it with the current plain-english.md and select Plain English, unless the owner deliberately chose another style
  • the short CLAUDE.md the toolkit now writes inside each major folder, per ../project-init/references/folder-claudemd.md. Read that file so step 2 can tell a missing one from a folder the toolkit deliberately skips (any folder with a README.md index, and everything under .claude/)
  • each conversation skill and helper agent offered by the setup flow, which ship in the session-skills plugin
  • anything newer listed in the toolkit README under "What's here now"
  • skip roadmap items; they are not built and cannot be audited. The current project-knowledge package is shipped and must be inventoried from its plugin. Existing retired v1 integration remains a separate local finding
• Note the toolkit version (from plugin.json or marketplace.json) for the sync record in step 5.

Step 2: audit the current project

For each inventory item, look for evidence in the project. Judge by intent, not exact wording: a CLAUDE.md that says "work on your own branch and land by pull request" satisfies parallel-agent-sessions.md even if the prose differs. Typical checks:

• CLAUDE.md and .claude/rules/: does CLAUDE.md exist and point at .claude/rules/, and does that folder carry each default-ON general rule (a file, or the rule's intent folded into CLAUDE.md)? Judge by intent, not exact wording or file name.

• Output style: does the project have .claude/output-styles/plain-english.md and select "outputStyle": "Plain English" in its committed settings? Check .claude/settings.local.json for an override too. The setting must match the file's name, and the installed guidance should match the current shipped meaning. Report a missing file, stale guidance, or mismatched selection as a gap. A deliberate owner choice of another style is an exception to preserve, not a gap to overwrite. Concise is a Claude Code built-in, not a toolkit default. A leftover plain-language selection needs migration.

• CLAUDE.md health (presence is not enough, see below).

• Can a Codex session actually reach the rules? (see below). A project can hold every rule and still deliver almost none of them to Codex.

• Hooks: are guard and orientation hooks configured (the project's .claude/ settings and hook scripts)?

• Salesforce dependency graph (Salesforce projects only): does tools/kb/ exist with every file the toolkit ships, is .claude/rules/dependency-graph.md present, are the graph and freshness artifacts gitignored, and is the freshness Stop hook wired in .claude/settings.json? Classify it partial when the tool is there but the rule or the hook is not, because that is the state where the graph quietly ages and nobody is told to use it. A project that has the older wording (a structural-layer rule, or a tools/kb/ copy predating the toolkit's) is present-but-behind, not missing: report the differences and offer to bring it in line. Never run a Salesforce CLI command during this check; the tool reads local files only.

• Graphify code graph (non-Salesforce projects): is the graphify command available, is graphify-out/ gitignored, is .claude/rules/dependency-graph.md present, and are the auto-rebuild git hooks installed in THIS clone? Check the last one by looking for graphify's post-commit and post-checkout hooks in the repository's hidden git hooks folder, or wherever core.hooksPath points. Classify partial when the tool is present but the rule or the hooks are not, and say which. Two findings are worth calling out because nothing else makes them visible:

  • Hooks missing in this clone. Git hooks are never committed, so a clone made after setup has none, and its graph stops updating while still answering questions confidently. The fix is graphify hook install, run once, here.
  • A hand-written rule. A .claude/rules/dependency-graph.md that does not match the library file is behind: report the differences and offer the current version, same as any other drifted rule.

  A project that deliberately rebuilds by hand with graphify update . instead of using hooks is not missing anything. Record that choice so a later sync does not re-raise it.

• System Guide: report exactly on, off, or needs repair, and name the configured guide path whenever one is available. Read the previous sync record, project-root .system-guide.json, the required guide files, and the project's active plugin selection. A plugin present in a marketplace, cache, or checkout is only available; it does not prove the project enabled it.

  • off: .system-guide.json is absent or has enabled: false. Preserve a recorded decline and do not raise it again. An enabled plugin or an existing folder alone does not change this state.
  • on: the config is valid and enabled, its relative in-project guidePath exists, the required entry, tour, section indexes, and layer folders are present, and system-guide@claude-toolkit is enabled at project scope for each supported host the project uses.
  • needs repair: an enabled config is malformed or unsafe, a required guide part is missing, the plugin is unavailable or inactive for a host that uses it, or the System Guide check reports a problem. Name every problem; do not collapse this into off.

  When the System Guide tool is available, run its cheap read-only status path from the canonical plugin source:

  node <system-guide-plugin>/tools/system-guide.mjs status --root <project-root> --json

  Also inspect project activation because that status reports project config and guide health, not whether a static plugin copy is selected in this project. When the tool is unavailable, read the config and required paths directly and report that tool validation is unavailable. Do not install anything during the audit. A suitable existing guide without config remains off and is an adoption candidate, never an automatic adoption; preserve its established location and ask the owner in step 4.

• Project knowledge layout: read the folder, never go by folder names alone. There is no detector script. Classify exactly one state:

  • current layout: knowledge/README.md starts with <!-- claude-toolkit:knowledge-manual -->, the flat memory and specification folders and their indexes exist, and any saved files use current YAML frontmatter. A fresh setup with no saved files is current;
  • partial current layout: the flat folders and indexes have current signatures, but the managed manual is missing. Offer to restore it and do not convert approved files;
  • older layout: knowledge/memory/ has subfolders by type (context/, decisions/, domain/, and the rest), or knowledge/memory/tags.md exists, or frontmatter carries source: owner-paraphrase and session:;
  • none: no second-brain signatures are present; or
  • mixed or unknown: signatures conflict, are partial, or an ordinary folder could be mistaken for the system.

  Ignore .system-guide.json and the configured System Guide tree while making this classification. A guide-only knowledge/system/ tree is none for second-brain setup, not an older or mixed knowledge layout. Mixed or unknown stops adoption and conversion: name exactly what you found and ask. Never move an ordinary folder called memory, prds, specs, or knowledge on its name alone.

• Old folder name: a project set up before the rename has knowledge/specs/ where the current layout has knowledge/prds/. That is the same folder under its old name, not an older layout. Report it, list what is in it, and offer to rename it with git mv and fix every pointer to the old path. Do nothing without the owner's yes. If both folders exist, stop, say what is in each, and ask. The second-brain skill has the steps.

• Packaged runtime: for a current layout, also check the installed managed knowledge/README.md against the packaged template byte for byte; remember, recall, retire, reflect, second-brain, and session-search skills; .claude/tools/build-knowledge-index.mjs, check-knowledge.mjs, and frontmatter.mjs; .claude/hooks/knowledge-session-start.mjs registered under Claude SessionStart; the pull-request and work-item reminders registered under PreToolUse with the Bash matcher; SOUL.md; the short root routes in CLAUDE.md and AGENTS.md; and the equivalent .codex/hooks.json loader where native Codex hooks are supported. A missing manual is partial. A changed manual is outdated: show the diff and ask before restoring the managed copy. Neither finding is a reason to rewrite approved knowledge.

  When the checker is present, run it during every read-only audit of a current layout, even when the runtime is otherwise complete:

  node .claude/tools/check-knowledge.mjs

  Report every problem it names and offer to fix only those files. If the tool itself is missing, report the runtime gap first and use the packaged copy only to inspect, never to write.

• Obsidian boundary: check that only knowledge/.obsidian/app.json is shared, that it creates relative Markdown links and automatic link updates, and that .gitignore excludes every other .obsidian file. A shared core plugin list, workspace, hotkeys, appearance, plugin, theme, or device file is an optional cleanup finding, not required project knowledge.

• Knowledge document map: inventory existing specifications, brainstorms, ADRs, architecture and system maps, roadmaps, project overviews, runbooks, glossaries, references, and raw artifact folders. Report likely canonical homes, duplicates, contradictions, missing indexes, broken routes, and live work state copied into persistent documents. Distinguish observed facts, inference, owner-confirmed intent, and unknowns when the difference matters.

• Retired v1 status: v1 is the old Neon/MCP architecture and is not a v3 migration source. Identify only its local integration surface: .mcp.json, .claude/settings.json, .codex/config.toml, hook registrations and wrappers, curator agents, v1 rules, outbox scaffolding, and any local brain/ or memories/ path. Do not call the Worker, read Neon, open token files, or inspect legacy memory content.

• V1 activity: report whether automatic digest, recall, capture, session-end curation, curator reminders, or MCP connections are still wired for Claude or Codex. A flag in .claude/settings.json is not enough when a Codex wrapper supplies its own environment, so trace each committed hook entry to the command it runs.

• Retirement choices: recommend reversible local deactivation first: disable every automatic v1 hook and remove the v1 MCP connection from committed Claude and Codex configuration. Also offer removal of specifically listed committed v1 files after separate approval. Never bundle deletion of a non-empty outbox, cache, ignored file, token, connector, database, or cloud resource into ordinary project sync.

• Knowledge layer: knowledge/memory/ is the persistent knowledge layer. Do not create a second store. Existing v1 curator files, know-* nodes, SHA pins, and drift reports remain retired and are never refreshed, reconciled, imported, or used as current truth.

• Standalone toolkit skills: check the previous sync record and the available host plugins. The conversation skills ship together in the session-skills plugin, so classify it as available to invoke, previously declined, or not applicable. A project that declined an individual plugin before the merge has that recorded under the old name; treat the record as applying to the skill, not the package. Include work-guide, requirements-helper, and solution-helper, plus the packaged delivery-researcher and delivery-reviewer agents. Compare the installed version and host-visible capabilities with the current package; source files alone do not establish that this session can invoke them. Offer a refresh when these methods are missing from an accepted installation. They use the existing tracker and project guidance, including work-item variations. Do not require local work items, copy specialist instructions, create a separate guidance file, or configure a default team. Do not look for a copied SKILL.md inside the project because the canonical skill stays in its plugin. handoff is the one to recommend rather than merely list: it works with no output style, no project knowledge system, and no hooks, and the moment it covers, a session about to clear its context, is the one nothing else can catch. It also makes every handoff prompt open with the goal of the work and puts a second agent between the draft and the owner, so facts do not get less accurate each time work is handed on. A project already running handoff at version 0.2.0 or earlier has neither; say so, because refreshing the plugin is what closes it. Report it as a gap alongside .claude/rules/offer-context-handoff.md, since the rule is what covers the owner asking for a handoff in their own words.

• Where work items are tracked: read the root instructions for a structural pointer naming a tracker, and for a recorded decline. Classify as one of: answered and set up, answered and declined, or never asked. A project that has .work-items/ or an older work-items/ tree but no pointer counts as never asked. Never-asked is a gap to offer in step 4; a recorded decline is respected and not raised again.

• Quick saves: read the root CLAUDE.md and the project's recorded choices. For configured project knowledge, confirm that knowledge/ is named and points to knowledge/README.md plus the installed knowledge direct-commit rule. For configured local tracking, confirm that .work-items/ is named and points to the local tracker instructions. Report rows for systems that are absent, declined, external, or no longer selected. Do not infer a quick-save folder from its name; any additional row needs an explicit owner designation and a canonical instruction source.

• Work-item stages: check the unscoped work-item-stages.md rule and the tracker it names. Local mode uses the current work CLI; GitHub mode uses stage labels. Report the retired stage-reminder script and registration for removal, not installation. If the tracker question was never answered, ask that first. Do not add guessed stages to existing items.

• Rules the toolkit dropped on 2026-08-31: spec-before-you-build.md and track-open-topics.md. The toolkit no longer ships either one. When a project still carries one in .claude/rules/, report it as a rule the toolkit has dropped, say in one line what it used to do, and offer to delete it. Never delete it without approval. A project may have come to depend on it, and that is the owner's call.

• Work tracker: detect root .work-items/ first. If it contains .work-tracker.yaml and per-item ITEM.yaml records, run work validate and classify the system as present or partial from its output. Confirm that .gitignore ignores the whole folder and Git tracks none of its contents. Separately detect older delivery/work-items/, engagement/work-items/, and root work-items/ trees. Classify those as ready for preview-first conversion, not as a competing tracker. Never move, copy, delete, or stop tracking them during the read-only audit.

• Old GitHub mirror settings: when an older .work-tracker.json exists, report whether it contains GitHub settings and say they will not be carried into local-folder mode. Do not create, link, sync, or modify GitHub during the audit. If the owner wants shared GitHub tracking, offer the separate GitHub Projects board answer instead.

• Previous sync record: read it if present (step 5 format) so deliberate opt-outs are respected.

Classify every item: present, outdated (present, but behind the toolkit's current version, see below), partial, missing, retired (a v1 integration that should be deactivated or removed), declined (the owner previously opted out), or not applicable (say why).

System Guide uses its user-facing states on, off, and needs repair in this same report. Keep a prior decline beside off so the state is clear without turning a respected choice back into a gap.

Rule drift

A rule the project already has can still be out of date. The toolkit's rules get amended, and an amendment reaches a project only when something goes looking for it. Checking that a rule is present will never find one, so a project can pass every check above and still be running a rule as it was written six months ago.

For each rule the project carries, read the toolkit's current version alongside the project's copy and ask what the toolkit version says that the project's copy does not cover. Compare the points made, not the words used. Projects are told in step 4 to fold rules into their own voice, so different wording is expected and is not drift.

Three outcomes:

• The same points in different words. Not drift. Leave it and say nothing.
• The toolkit makes a point the project's copy does not. This is drift. Report the specific missing point in plain language, not a text diff, and classify the item outdated.
• The project makes a point the toolkit's version does not. The project is ahead. Never overwrite it. Flag it for port-back in the wrap-up.

The previous sync record names the toolkit version last synced against. When that is behind the current toolkit version, rules are the first place to look. When there is no sync record, check them all.

The same drift question applies to any toolkit text a project copies, not only .claude/rules/. Startup routes and copied hooks are checked against their current packaged sources rather than paraphrased from memory.

Codex reachability: can AGENTS.md deliver the rules?

Every check above asks whether a rule EXISTS. None asks whether the agent actually receives it. Those are different questions, and they have different answers for the two programs.

• Claude Code loads .claude/rules/ automatically. Every .md file there without paths: frontmatter is in context at session start. No import needed, and CLAUDE.md does not have to mention the folder for it to work.
• Codex discovers AGENTS.md files, not Claude rule files. It expands no import syntax, so an @ line is not a load instruction, but it does follow a plain instruction to open a file. The toolkit's AGENTS.md is one line: Read CLAUDE.md in this folder and follow it. Everything else reaches Codex through CLAUDE.md, which opens with Read .claude/rules first.

So a project can pass every file check while that two-hop route is broken. Report:

• AGENTS.md is the one line and nothing else. Anything more is a hand-maintained second copy of CLAUDE.md that drifts. Report every extra section as a trim, and say what in CLAUDE.md already covers it.
• The second hop. Confirm CLAUDE.md still carries Read .claude/rules first. Without it the chain stops at CLAUDE.md and Codex never reaches the rules.
• Nested AGENTS.md files. The toolkit keeps one root file. Report any other, and propose deleting it.
• Dead imports. Grep both root files for @ lines. Report any that resolve to nothing, especially wildcards such as @.claude/rules/**, which look load-bearing and expand to nothing in either program.
• Host limits. Report when local Codex settings prevent that route or the startup hook from reaching the session. Do not assume Claude settings apply.
• Whether a guard hook covers the gap. Claude Code PreToolUse hooks do not fire for Codex, and ~/.codex/config.toml usually registers none. A rule Codex cannot see, backed by a hook that never runs for Codex, is unenforced in both directions at once. Flag that combination explicitly; it is the worst state a project can be in and it is invisible to every other check.

The fix, when the owner approves it, is the one-line AGENTS.md written out in ../project-init/references/root-file-examples.md.

Skip this check only when the owner confirms Codex never runs in the project.

CLAUDE.md health

A project can pass every check above and still have a CLAUDE.md nobody reads. The file only ratchets: sessions add to it and nothing tells a session to subtract. So audit its shape, not just its presence. CLAUDE.md is a router and a map, answering five questions and nothing else: what is this project, what is in each folder and file and when do I open it, what tools does this project run on, which configured folders use quick saves, and where is work tracked. Read the file and report:

• Size. How many lines? Anthropic targets under 200 lines, because the file loads into every session and a bloated one makes agents ignore the instructions that matter. Past that, flag it and say which sections account for the bulk.
• Duplication against .claude/rules/. For each rule file in that folder, is the same rule also spelled out in CLAUDE.md? Restating it is worse than moving it, because the two copies drift and neither wins. List every rule that is said twice.
• A communication section. How to talk to the owner lives once, in the owner's own ~/.claude/, and is in force in every project. A copy here is duplication. Flag it for removal.
• Multi-step procedures. Anything reading as a numbered sequence of steps belongs in a skill, which loads on demand instead of in every session. Name each one and propose where it goes.
• A codemap that became a changelog. Codemap entries should be one line per folder or module, saying what is in it and when to open it. Flag entries carrying dated history ("2026-07-17 changed X, decision #17"); that history belongs in Git and the applicable specification or persistent memory.
• A missing tools section. Name the MCP servers, generated graphs or indexes, and build, test, and deploy commands the project actually runs. Any the file does not name is a tool a session will not reach for. Propose the row, naming the command and where the detail lives.
• The fixed lines above the title. CLAUDE.md should open with the SOUL route (only where SOUL.md exists and project knowledge was declined), then the owner's verbatim self-check instruction, then the owner's verbatim continuity instruction. ../project-init/references/thin-claudemd.md has the exact wording. Report any missing, and report any reworded copy, since the wording is the owner's and is not to be edited.
• Lines an agent never needed. For each line ask whether removing it would make an agent get something wrong. Flag every line where the answer is no, starting with: what a session could find in one command (a folder is Git-ignored, a file is generated, a directory is empty), and where something came from or when it arrived ("this folder came in with the latest toolkit sync"). These arrive one at a time, usually from a sub-agent tidying up at the end of a task, and in an old file they are most of the bulk.
• Context sources the codemap does not name. Look for folders holding context an agent should pull in on demand: ai-external-knowledge/, docs/designs/, knowledge/prds/, captured reference data. Any one the codemap does not name is a folder no agent will open, however good what is in it. Propose the line, saying what is inside and when to open it. For those two also say how long a file in each lives, since that is the part a session gets wrong: a design is deleted once that area's PRD is current, and a PRD is kept for the life of the area.
• Live state that belongs in the tracker. Current phase, next action, and open TODOs drift the moment they are written here.
• Project-knowledge startup parity. When the current layout is installed, confirm both hosts register the same loader and that it reads, in order, SOUL.md, knowledge/README.md, knowledge/project.md, knowledge/current.md, and the entry lines of both indexes. Confirm it loads no other memory and fails open when a file is absent. CLAUDE.md carries only the short fallback. Any copied policy is stale duplication.
• Stale content. Anything the code, paths, or decisions have since contradicted.

Report this as findings with a recommended trim, not as a pass or fail, and treat the trim as one more item the owner opts into at step 4. One constraint on any trim you propose:

• Check cross-references before renumbering. Grep the repo for references to CLAUDE.md section or rule numbers. If a trim would renumber sections other files point at, say exactly which, and let the owner choose between renumbering with the fixes and keeping the numbering stable.

Folder CLAUDE.md files

The toolkit now writes a short CLAUDE.md inside each major folder. Claude Code loads it only when an agent reads a file in that folder, which is what lets the root file stay short without losing the detail. Read ../project-init/references/folder-claudemd.md first, then walk the project's folders and report each one as:

• Present. The folder already has its own CLAUDE.md. Leave it alone. Do not rewrite it into the toolkit's wording; the project wrote it on purpose.
• Missing. A major folder the toolkit recognizes, with no CLAUDE.md and no README.md index. This is a gap.
• Skipped by design. A folder with a README.md index, or anything under .claude/, the complete knowledge/ tree, or a folder another plugin creates and indexes. Not a gap. Say so rather than leaving it off the list, so it does not get raised again next run.
• Not recognized. A folder the toolkit did not create and whose purpose you cannot tell from the repository. Do not propose a file for it and do not guess what it is for. List it and ask the owner in step 4.

Two things this check never does. It never reports a nested AGENTS.md as missing, because toolkit projects deliberately use one root file even though Codex supports layering. And it never proposes moving a behavior rule out of .claude/rules/ into a folder file, because a file that loads only sometimes cannot carry a rule that applies always.

Step 3: report before touching anything

Show one table: item, status, and what specifically is missing or drifted. Make no changes in this step. Let the user pick what to fix, and recommend an order: resolve mixed signatures, install or migrate project knowledge, retire duplicate local wiring as a separate choice, then update rules and other systems. Existing v1 wiring does not block the new knowledge layout.

Step 4: close the approved gaps, one at a time

Work the way project-init does: explain what the item is for, recommend how it should look in THIS project, confirm, act, summarize. Ground rules:

• Opt-in per item. A "no" gets recorded, not argued with.

• Adapt to the project. Fold rules into the existing CLAUDE.md's voice and structure; don't paste toolkit text verbatim over a file that has its own style.

• Never weaken something the project already does better than the toolkit version. If the project's variant is an improvement, leave it and flag it for port-back instead (see wrap-up).

• For an approved outdated rule, add only the missing points, written in the project's existing voice. Never replace the file wholesale with the toolkit's text: that throws away every local adaptation the project made on purpose, and those adaptations are the reason the wording differs in the first place.

• For an approved output style gap, install or update .claude/output-styles/plain-english.md from library/output-styles/plain-english.md and set "outputStyle": "Plain English" in the committed .claude/settings.json. Preserve local wording that deliberately adapts the style; reconcile missing guidance instead of discarding it. Offer to remove the retired .claude/output-styles/plain-language.md after the replacement is in place. The selected value must match the style's name. Resolve a local settings override with the owner rather than silently leaving conflicting selections. Preserve deliberate choices of another style. The new voice starts in the next session.

• For the retired voice rules, propose the swap, never a bare deletion. A project on the old setup has working guidance; removing it before the style is in leaves the project with neither. Install and verify Plain English first, then offer to delete .claude/rules/writing-and-language.md, how-to-reply.md, treat-owner-as-non-technical.md, and define-your-terms.md. Say the remaining cost out loud so the owner is choosing with it in view: a helper agent never receives an output style at all, so writing plainly is all a helper agent gets.

• For an approved folder CLAUDE.md gap, do one folder at a time, and offer the move with it. Adding the folder file alone leaves the root CLAUDE.md exactly as long as it was, which is the whole thing this is meant to fix. So for each folder the owner approves:

  1. Show the draft folder file: what the folder holds, how to work in it, and where the detail lives.
  2. Show the lines in the root CLAUDE.md that are about that folder, and offer to move them into the folder file, leaving one line in the codemap pointing at it.
  3. Never move a behavior rule out of the root file or out of .claude/rules/. Four other things never move either: how to talk to the owner, the pointers to the most dangerous rules, the project-knowledge startup route, and the codemap lines themselves. They are named in ../project-init/references/thin-claudemd.md under "What must stay in the root file".
  4. When the project has an AGENTS.md, do not copy the folder detail into it. AGENTS.md tells Codex to open a folder's CLAUDE.md before editing files there, so one copy is enough. If the project pins the two root files to each other with a shared block and a check, the block covers only the part that genuinely must match: the fixed lines above the title, Communication, the project-knowledge route, and the rules too dangerous to reach late.
  5. Never create a nested AGENTS.md.

• For a folder listed as not recognized in step 2, ask the owner what it is for in plain words, then either write the file from their answer or record the skip. Do not infer a purpose from the folder name.

• For a retired memory-pr-hook plus wrap-up-ritual.md finding, first confirm the current packaged pull-request reminder and remember skill are installed. Then offer removal of the obsolete hook registration, copied script, config, and rule as one reversible cleanup. Never leave two pull-request reminders active.

• For an approved System Guide change, use the canonical system-guide plugin and its CLI rather than copying its setup or maintenance rules here.

  • To turn an off project on, first install and enable system-guide@claude-toolkit at project scope. Then run setup --root with the owner-approved relative --guide-path and one --source kind:completeness:relative/path per source. A new guide normally uses knowledge/system/. This creates no second-brain files.
  • For an existing suitable guide, show the location and what setup would add. Pass --adopt only after the owner explicitly chooses adoption. Never move the guide merely to use the plugin, and never overwrite existing bytes.
  • For needs repair, run status and check, repair only the named config, activation, or required-file gaps, then rerun both. Preserve all meaning and unrelated guide content. A repair does not approve a meaning change.
  • To disable the guide, run its disable command. Keep its config and content so it can be re-enabled. Do not remove second-brain files. Removing or disabling second-brain likewise leaves an enabled guide and its plugin behavior intact.
  • When enabled, add the exact shared root fallback from ../project-init/references/thin-claudemd.md once in CLAUDE.md. Do not repeat it in AGENTS.md. The System Guide plugin owns configured Claude startup status; the second brain reports only the off case.

• For any approved project-knowledge gap, install or refresh the second-brain plugin first, then follow the state-specific path below.

  • None: show the tree from the plugin README, obtain approval, and ask the owner what the project is, why it exists, what finished looks like, its boundaries, who is involved, and where active work is tracked. Use those exact answers for SOUL.md and knowledge/project.md, then install the complete layout and runtime. Preserve .system-guide.json and its guide path. A guide-only knowledge/system/ tree is not migration input.
  • Older layout: use the second-brain skill's conversion path. Count the files first and show the owner the total. Convert in batches of ten, mapping the old fields to the new ones, and show each batch for approval. This is the one place approval comes after the write, and only because every one of those files was already approved once in its old shape. Anything that will not map cleanly is stopped on and named, never guessed. Flatten the subfolders, delete knowledge/memory/tags.md, repair every changed link, and remove the old machinery only after the checker passes.
  • Current: install only missing runtime or rebuild the indexes. Never rewrite approved documents merely to match current formatting.
  • Mixed or unknown: stop without writing and show the conflicting signatures.

  For an approved none, older layout, or current path, finish the same adoption unit before calling the system installed:

  1. Copy the packaged build-knowledge-index.mjs, check-knowledge.mjs, and frontmatter.mjs into .claude/tools/.
  2. Copy the packaged knowledge-session-start.mjs, save-reminder.mjs, work-item-close.mjs, and command-parsing.mjs into .claude/hooks/.
  3. Copy the packaged knowledge manual unchanged to knowledge/README.md. When a copy differs, show the diff and get approval before replacing it. Copy the packaged memory-self-improvement.md template to knowledge/memory-self-improvement.md when the project has no such file. What that file learns is per project, so never replace one that exists.
  4. Merge, never replace, .claude/settings.json: disable private auto-memory, enable second-brain@claude-toolkit, register the fail-open Claude SessionStart loader, and register both reminders under PreToolUse with the Bash matcher.
  5. Add the same short startup and fallback pointer to root AGENTS.md and CLAUDE.md. Merge the same fail-open loader into .codex/hooks.json without removing other hooks, with at least 5,000 tokens of additional context.
  6. Add the Obsidian ignore allowlist so only knowledge/.obsidian/app.json is shared.
  7. Run node .claude/tools/build-knowledge-index.mjs, then node .claude/tools/check-knowledge.mjs. Both must pass. Then run the startup loader and confirm it prints SOUL.md, the manual, knowledge/project.md, knowledge/current.md, and the entry lines of both indexes, once each and in that order.
  8. After converting a folder off an older layout, run the reflect skill once. A conversion is exactly when duplicates and contradictions surface.

  Do not remove old runtime or root routes until their current replacements are present and these checks pass.

• Do not install second-brain v1 or import its content. For an existing v1 project, offer the following separately after reporting the exact local scope:

  1. Deactivate: remove v1 MCP entries and automatic hook registrations from committed Claude and Codex configuration. Preserve old scripts and agents temporarily.
  2. Remove local integration: delete only the committed v1 files and settings the owner explicitly approves. Neither option contacts the Worker or Neon, reads legacy memory, imports anything into project knowledge, or deletes cloud infrastructure. Installing the current system does not imply either v1 choice. Account-level connectors, local token cleanup, and cloud deletion are separate owner-approved work.

• For an approved Salesforce dependency graph gap, install the whole kit from ../../library/guides/salesforce-dependency-graph.md: the tools/kb/ folder, the gitignore entries, the rule, and the freshness Stop hook. Never install the rule alone. Run the verify steps in that file before calling it done. If the project already has its own copy of the tool, show the differences and let the owner choose which side wins rather than overwriting edits they made.

• For an approved graphify gap, install the whole kit from ../../library/guides/graphify-dependency-graph.md: the tool, the gitignore entry, library/rules/general/dependency-graph.md into .claude/rules/, and the auto-rebuild hooks. Never install the rule alone, and never install it on a Salesforce project, which uses the bundled metadata graph and its own rule of the same name instead.

• When the project was never asked where work items are tracked, ask the Gate 1 question from ../project-init/references/work-tracking-choice.md and follow that file for whichever answer comes back. Add the one-line pointer to CLAUDE.md and AGENTS.md, unless the answer is "somewhere else, or nothing yet", in which case record the decline instead.

• For an approved work-item stages gap, the tracker choice comes first. A stage standard with no tracker to hold it is advice nobody can follow, so if the Gate 1 question was never answered, ask it and finish that answer before installing any part of this. Then update the rule and tracker and remove the retired hook if present:

  1. Copy library/rules/general/work-item-stages.md into .claude/rules/.

  2. Set up the stage marker the chosen tracker needs. For the local tracker that is already there, since stage is a field work update --stage writes. For a GitHub Projects board, create the fourteen labels on the repository, in order, so they sort:

     for stage in 01-discovery 02-refinement 03-requirements-approved        04-solution-design 05-breakdown 06-implementation-plan 07-tracking-setup        08-build 09-testing 10-bug-fixing 11-user-approval 12-pr-and-push        13-deployment 14-spec-update; do
       gh label create "$stage" --description "Work-item stage $stage" || true
     done

     Show the owner the list and wait for a yes before creating anything on GitHub, the same as every other board change. A label that already exists is left exactly as it is.

  3. Remove the retired work-item-stage-reminder registration and copied script after the owner approves the sync. Keep other hooks in the same matcher. The lifecycle rule handles orientation before substantial work; there is no replacement hook.

  Then retire any label that now means the same thing as a stage, so the project has one vocabulary instead of two. A board set up before this has a refined label, which is 03-requirements-approved under another name: point the root instructions at the stage label, and offer to delete the old one. Never relabel existing issues in bulk. They carry no stage until someone sets one.

• When the owner names a different tracker than the one already recorded, rewrite the pointer. Never delete tickets, issues, or boards from the tracker they are leaving; moving existing work across is theirs to do by hand.

• For an approved quick-save gap, preserve the project's selected systems and existing root-file voice. Add or update only the applicable rows from ../project-init/references/thin-claudemd.md, and install or refresh their matching rules. The knowledge/ row permits approved knowledge-only work to use the primary checkout and land directly on the default branch even while implementation continues in a worktree. The .work-items/ row uses the existing shared, Git-ignored local store with no worktree, commit, or push. Remove a misleading row when its system is no longer configured. Do not add a local path for an external tracker or a recorded no-tracker choice.

• For an approved new local work-tracker gap, install the plugin and run work init. It creates YAML work items under Git-ignored .work-items/. Say plainly that these records stay in the current checkout.

• For an approved older-tracker conversion, run work migrate --from <path> first and show the preview. Run it again with --apply only after approval. Validate the copied tracker and show every REQUIREMENTS.md still in refining. Leave the old tracker unchanged until the owner verifies the copy and separately approves removing it.

• Local-folder mode has no GitHub mirror. When the owner wants shared GitHub tracking, return to the Gate 1 choice and set up a GitHub Projects board as the tracker instead.

Step 5: record the sync

Write a short sync record so future runs know where things stand. Default location: .claude/toolkit-sync.md, with at most a one-line structural pointer from CLAUDE.md or AGENTS.md when useful. Do not turn either root file into a sync changelog. Record:

• the toolkit version synced against, and the date. The next run reads this to decide whether the project's rules may have fallen behind, so record it even when nothing changed
• items set up or already present
• items brought up to date, naming what was added to each
• items the owner deliberately declined, so future syncs never re-nag about a considered "no"
• System Guide state and its actual configured path, or the owner's recorded decline. Record this independently from the second-brain choice.

Wrap-up

1. Summarize: fixed, already present, declined, deferred.
2. Note follow-ups for anything deferred, including separate connector, token, or cloud cleanup for a retired v1 integration.
3. Port-back reminder: if the project had a better version of a toolkit item, or this sync surfaced an improvement, offer to draft a PR back to the claude-toolkit repo so every other project benefits.