--- name: udecode/sync-vision source: https://app.decimal.ai/s/udecode-sync-vision@1/SKILL.md source_sha256: 21592d76aec0 --- # Sync Vision Handle `$ARGUMENTS`. `VISION.md` is living project taste. Treat it like the project doctrine layer: learn from repeated human answers, agent misses, plans, docs, skills, research, reviews, and handoffs, then ignore noise. This skill is the incremental sync lane. It does not replace a `vision` router. It keeps root `VISION.md` current by analyzing changed durable inputs since the last synced commit. Root `VISION.md` is the mandatory essential read and single project vision source. ## Autogoal Dependency Use `autogoal` before mutable work. This is a derived autogoal workflow. - Prefer a repo-owned `docs/plans/templates/sync-vision.md` when it exists. - Otherwise use the `autogoal` `task` template with `agent-native` and `docs` packs when available. - Default flow: one-shot sync. - Preview flow: one-shot planning, no vision-doc patch and no baseline advancement. - Required evidence: command, artifact, source audit, classification ledger, and N/A rows. - `autogoal` owns lifecycle, first-checkpoint requirement extraction, completion semantics, output-budget discipline, and `check-complete.mjs`. - `sync-vision` owns input-range accounting, candidate classification, root doctrine patch rules, status semantics, and baseline advancement. Goal handle shape: ```txt Sync vision; done when changed inputs are classified, VISION.md is patched or reaffirmed, baseline semantics are recorded, and checks pass; plan docs/plans/.md. ``` ## State Durable state lives in: ```txt docs/sync/vision/status.json docs/sync/vision/runs/--to-/ ``` `status.json` fields: - `lastSyncedCommit`: every relevant committed input through this commit has been classified as `captured`, `reaffirmed`, `rejected`, `run-specific`, `owner-routed`, or `deferred-with-question`. - `lastSyncedAt`: when the baseline was advanced. - `lastRunDir`: latest run artifact directory. - `lastTargetCommit`: latest target commit analyzed. - `pendingRunDir`: run with unresolved decisions, or `null`. Never advance `lastSyncedCommit` merely because artifacts were written. Advance only after the committed range is fully accounted for. Working-tree overlays are visible in artifacts but are not baselined until committed. Working-tree overlays include relevant untracked files. New doctrine docs, plans, rule files, and root docs must be visible in artifacts before commit, but they are not baselined until committed. ## Optional Config Projects may customize the helper with: ```txt docs/sync/vision/config.json ``` Supported fields: - `includePathspecs`: extra git pathspecs to collect. - `exactInputFiles`: extra exact file paths. - `inputPathPrefixes`: extra directory prefixes. - `excludePathPrefixes`: extra excluded prefixes. - `trackedExts`: extra text-like extensions. - `patterns`: extra candidate regexes by category. Keep config project-local. Do not put private URLs, account IDs, or temporary branch state in dotai. ## Commands - `status`: read `status.json`, current `HEAD`, committed diff count, and working-tree overlay count. No writes. - `preview`: write run artifacts and recommendations. Do not patch `VISION.md`. Do not advance baseline. - `sync`: default. Write artifacts, patch root `VISION.md` for high-confidence reusable decisions, route non-vision owners, and advance baseline only if all committed inputs are classified. - `advance`: update `status.json` to current `HEAD` only after the active plan proves the range is fully accounted for. Use the helper for accounting from the project root: ```bash node .agents/skills/sync-vision/scripts/collect-vision-diff.mjs --status node .agents/skills/sync-vision/scripts/collect-vision-diff.mjs --dry-run node .agents/skills/sync-vision/scripts/collect-vision-diff.mjs node .agents/skills/sync-vision/scripts/collect-vision-diff.mjs --advance --plan docs/plans/.md ``` The helper writes: - `changed-files.tsv` - `candidate-lines.tsv` - `summary.md` - `run.json` ## Default Input Scope Analyze changed durable inputs, not the whole repo every time: - `VISION.md` - `AGENTS.md` - `.agents/AGENTS.md` - `.agents/rules/**` - `skills/**` when the repo uses top-level source skills, as dotai does - `docs/plans/**` - `docs/sync/**` except `docs/sync/vision/runs/**` - `docs/research/**` - `docs/solutions/**` - `content/docs/**` - other Markdown-like root docs when they appear in the changed-file list Generated `.agents/skills/**` mirrors are not primary input when a source rule or top-level `skills/**` source exists. Use generated mirrors only for sync audits. ## Classification Every candidate line or theme becomes one of: - `captured`: patch root `VISION.md` with a compact latest-state rule. - `reaffirmed`: already covered by root; record the section. - `rejected`: stale, one-off, contradicted, too narrow, or not project taste. - `run-specific`: belongs in the active plan only. - `owner-routed`: belongs in a skill/rule, research doc, benchmark target, package docs, product spec, behavior spec, or migration guide instead of `VISION.md`. - `deferred-with-question`: missing taste; queue one concise question and do not advance the baseline unless the range can be safely accounted for without it. Promote to root `VISION.md` when the rule is reusable project doctrine: global taste, source order, cross-boundary law, public API doctrine, proof standards, review attention, owner-specific doctrine, or supervisor stop conditions. Do not promote: - temporary command output; - one-off route state; - old branch summaries; - raw issue bodies; - generated mirror noise; - artifact paths; - broad history that does not change a future decision. ## Sync Workflow 1. Load `autogoal`, create or continue a `sync-vision` plan, and copy every user requirement into checkpoint zero. 2. Read root `VISION.md`. 3. Read `docs/sync/vision/status.json` if present. 4. Run the helper in `status` or collection mode. 5. Read `summary.md`, `candidate-lines.tsv`, and the changed source files that actually contain high-signal candidates. 6. Cluster candidates by reusable decision, not by file. 7. Classify each cluster. 8. Patch root `VISION.md` only for `captured` clusters. Write current-state doctrine, not changelog prose. 9. Route owner-specific misses to the owner: - skill/rule miss -> local skill source or installed shared skill owner; - behavior law -> product behavior/spec docs or owning plan skill; - automation miss -> owning supervisor skill; - research-system miss -> research owner; - migration miss -> migration owner; - benchmark truth -> benchmark target/script owner; - docs/API mismatch -> docs or package owner. 10. Record a decision ledger in the plan or run summary. 11. If agent rules or shared skills changed, run the repo's generation or skill validation command. 12. Run the active plan completion checker when available. 13. Advance `lastSyncedCommit` only when the committed range is fully classified. ## Baseline Advancement Advance baseline when all are true: - committed diff range was collected from prior `lastSyncedCommit` to target; - every candidate cluster has a classification; - root `VISION.md` was patched or explicitly reaffirmed for reusable taste; - owner-routed items have concrete owners; - deferred questions are listed with recommendations; - generated mirrors are synced when source rules changed; - the active plan passes its completion check when one exists. Do not advance baseline when: - the run is `status` or `preview`; - a candidate changes product/API taste and no default can be inferred; - a source rule changed but generated mirror sync failed; - the helper reports a git/ref error; - only uncommitted overlay input exists. ## Final Handoff Include: - base commit, target commit, and whether baseline advanced; - changed input count and candidate count; - root vision doc changes; - reaffirmed existing sections; - rejected/noise clusters; - owner-routed follow-ups; - deferred questions; - changed files; - commands run; - next `sync-vision` command. Keep it short. The run artifacts hold the detail.