Agent Skills: Sync Vision

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:

Sync vision; done when changed inputs are classified, VISION.md is patched or reaffirmed, baseline semantics are recorded, and checks pass; plan docs/plans/<path>.md.

State

Durable state lives in:

docs/sync/vision/status.json
docs/sync/vision/runs/<date>-<base>-to-<target>/

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:

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:

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/<plan>.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.