/sync-vision

name: sync-vision
description: Sync root VISION.md from changed human and agent inputs; use when project taste, doctrine, or maintainer judgment should learn from recent plans, docs, skills, reviews, or repeated misses.
disable-model-invocation: true

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 `autogoa