开发与测试
doc-sync
Incremental skill updater that maps git diffs to affected skills and optionally auto-syncs via a post-commit hook
aspenkit · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add aspenkit/aspens --skill doc-sync技能说明
name: doc-sync description: Incremental skill updater that maps git diffs to affected skills and optionally auto-syncs via a post-commit hook triggers: files: - src/commands/doc-sync.js - src/lib/diff-classifier.js - src/lib/diff-helpers.js - src/lib/git-hook.js - src/lib/git-helpers.js - src/prompts/doc-sync.md - src/prompts/doc-sync-refresh.md - src/prompts/partials/preservation-contract-refresh.md keywords: - doc sync - doc-sync - refresh - post-commit hook - install-hook - diff classifier - changetype filter
You are working on doc-sync, the incremental skill update command (aspens doc sync).
Key Concepts
- Monorepo-aware:
getGitRoot(repoPath)resolves the actual git root.projectPrefix(toGitRelative) computes the subdirectory offset.scopeProjectFiles()filters changed files to the project subdirectory. Diffs are fetched fromgitRootbut file paths are project-relative. - Multi-target publish:
configuredTargets()reads.aspens.jsonfor all configured targets.chooseSyncSourceTarget()picks the best source (prefers Claude if both exist). LLM generates for the source target;publishFilesForTargets()transforms output for all other configured targets.graphSerializedandrepoPathare passed through to the transform context for conditional architecture references and disk-based instructions file loading. - Backend routing:
runLLM()fromrunner.jsdispatches torunClaude()orrunCodex()based onconfig.backend(defaults to source target's id). - Diff-based flow: Gets
git diff HEAD~N..HEADfrom git root, scopes changed files to project prefix, then feeds diff plus existing skill contents and graph context to the selected backend. - Changetype filter (Phase 1):
isNoOpDiff()fromdiff-classifier.jsskips the LLM call entirely on lockfile-only diffs and diffs touching zero code-bearing files.LOCK_FILESandCODE_BEARING_EXTSare the source of truth — extend them here, not at call sites. - Prompt path variables: Passes
{ skillsDir, skillFilename, instructionsFile, configDir }from source target toloadPrompt()for path substitution in prompts. - Refresh mode (
--refresh): Skips diff entirely. Reviews every skill against the current codebase. Base skill refreshed first, then domain skills in parallel batches ofPARALLEL_LIMIT(3). Also refreshes instructions file and reports uncovered domains. Refresh mode runsensureRootKeyFilesSection(legacy stripper) beforesyncSkillsSectionso any leftover## Key Filesblocks from old docs are removed. - Deterministic section repair:
repairDeterministicSections()runs a no-LLM pass that re-injects## Skillsand## Behaviorinto the root instructions file from on-disk state and strips any legacy## Key Filesblock viaensureRootKeyFilesSection. Called from the no-op / "up to date" sync paths so missing-section drift is fixed every invocation. The normal sync flow also runs the same Skills + Behavior + legacy-strip block on the canonical instructions file after the LLM step. - Graph rebuild on every sync: Calls
buildRepoGraph+persistGraphArtifacts(with source target) to keep graph fresh.graphSerializedreturn value is captured and forwarded topublishFilesForTargetsfor conditional Codex architecture refs. Graph failure is non-fatal. - Legacy v0.7 hub-block cleanup:
notifyLegacyHubBlockIfPresent()surfaces a one-line notice on the first sync after upgrade whenCLAUDE.md/AGENTS.mdstill carries the legacy## Key Fileshub-counts block, so the diff that strips it isn't alarming.regenerateStaleCodeMap()force-rebuilds.claude/code-map.mdon no-op syncs when it still carries the legacy**Hub files**block. - Graceful response handling: After LLM returns, if output has content but no
<file>tags, treats it as "no updates needed" with a verbose-only warning. The prompt explicitly requests an empty response when nothing needs updating. - Graph-aware skill mapping:
mapChangesToSkills()checks direct file matches viafileMatchesActivation()(fromskill-reader.js) and also whether changed files are imported by files matching a skill's activation block. - Interactive file picker: When diff exceeds 80k chars and TTY is available, offers multiselect with skill-relevant files pre-selected.
- Prioritized diff:
buildPrioritizedDiff()gives skill-relevant files 60k char budget, everything else 20k (80k total). Cuts atdiff --gitboundaries. - Token optimization: Affected skills sent in full; non-affected skills send only path + description line.
- Split writes: Direct-write files (
.claude/,CLAUDE.md, rootAGENTS.md) usewriteSkillFiles(). Directory-scopedAGENTS.mdfiles (e.g.src/AGENTS.md) usewriteTransformedFiles(). - Skill-rules regeneration: After writing, regenerates
skill-rules.jsonviaextractRulesFromSkills()— only for targets withsupportsHooks: true(Claude). UseshookTargetfrom publish targets list. findExistingSkillsis target-aware: Usestarget.skillsDirandtarget.skillFilenameto locate skills for any target.- Git hook (monorepo-aware):
installGitHook()installs at the git root with per-project scoping. Hook usesPROJECT_PATHderived from project-relative offset. Each subproject gets its own labeled hook block (# >>> aspens doc-sync hook (label) >>>) with a unique function name (__aspens_doc_sync_<slug>). Multiple subprojects can coexist in one post-commit hook. Hook skips aspens-only commits scoped to the project prefix. 5-minute per-project cooldown via/tmp/aspens-sync-<hash>.lock; logs to/tmp/aspens-sync-<hash>.log(truncated to last 100 lines past 200). Unlabeled v0.6-era blocks are auto-upgraded on re-install. - Force writes: doc-sync always calls
writeSkillFileswithforce: true.
Critical Rules
runLLMis called with `allowedTools: