sync-horizon

What this skill does

# Sync Horizon

Synchronize eve-skillpacks with the latest state of the eve-horizon repository.

## Core Insight

System docs often lag behind implementation. Features ship via feat commits with plans marked "Implemented" — but `docs/system/` may not update for weeks. This sync goes to the source: **plans, code changes, and commit messages** tell us what actually shipped. System docs are one signal among many, not the primary driver.

## Prerequisites

- The eve-horizon repo must be at `../eve-horizon` (sibling directory)
- `.sync-state.json` must exist in the repo root (create from template if missing)
- `.sync-map.json` must exist in the repo root

## Architecture: Orchestrator + Parallel Workers

You (the orchestrator) discover what shipped and dispatch focused workers. Each worker handles one update in isolation with its own context budget.

The orchestrator reads **lightweight signals** (commit log, plan headers, file stats, CLI module list). Workers read the **heavy content** (plan bodies, code diffs, source docs, target files).

## Output Standards

- Distill only shipped platform behavior. Plans marked Implemented/Complete describe shipped features.
- Do not carry roadmap content into skillpacks. Ignore plans marked Proposed/Draft and sections like `Planned (Not Implemented)`, `What's next`, or "current vs planned" framing.
- Keep `eve-work/eve-read-eve-docs/SKILL.md` task-first: route by intent, load only the minimal reference files needed.
- Keep reference docs scoped and actionable — curated distillations, not copies.

## Workflow

### Phase 1: Deep Discovery (orchestrator)

Read lightweight signals from multiple dimensions to understand what actually shipped.

#### 1a. Commit log

```bash
cd ../eve-horizon && git log --oneline <last_synced_commit>..HEAD
```

Categorize commits:
- `feat:` — new capabilities (primary interest)
- `fix:` — bugfixes that may affect documented behavior
- `docs:` — documentation changes (check if they describe already-shipped features)
- `chore:` / `refactor:` — usually no skillpack impact, but note removals

#### 1b. Plan intelligence

This is the richest signal. Plans describe what shipped, why, and how.

```bash
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- docs/plans/
```

For each changed plan, read its **header only** (first 15-20 lines) to extract status:

```bash
cd ../eve-horizon && head -20 docs/plans/<plan-file>.md
```

Categorize:
- **Shipped**: Status contains `Implemented`, `Complete`, or `Done` — these are the primary source of truth for new capabilities
- **In progress**: Status contains `In Progress`, `Partially Implemented` — note for awareness but don't distill unfinished work
- **Proposed/Draft**: Status contains `Proposed`, `Plan`, `Draft`, `Ready to build` — skip entirely
- **Removed**: Plan files deleted in this range — something was deprecated or abandoned

**IMPORTANT**: Do not read full plan bodies. Just headers. Workers will read the plans they need.

#### 1c. Code signal

New CLI commands, DB migrations, and package changes confirm what shipped and reveal capabilities that plans may not fully describe.

```bash
# New/changed/removed CLI commands
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/cli/src/commands/

# New DB migrations (table/column names reveal capability shape)
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/db/migrations/

# Key package changes (new modules, removed modules)
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/shared/src/ packages/api/src/ packages/worker/src/ packages/gateway/src/ --stat-name-width=120 | head -50
```

#### 1d. System doc changes

Still a useful signal — especially for removals and corrections.

```bash
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- docs/system/ AGENTS.md
```

#### 1e. Current CLI surface

Snapshot the current CLI command modules. This is the ground truth for what agents can invoke.

```bash
cd ../eve-horizon && ls packages/cli/src/commands/*.ts
```

### Phase 2: Capability Synthesis (orchestrator)

**STOP and think.** This is the critical step. Cross-reference all signals to build a capability map.

For each **shipped plan** (Implemented/Complete), create a capability entry:

```
Capability: <name>
  Plan: docs/plans/<file>.md (status: Implemented)
  Feat commits: <matching commit hashes>
  Code signal: <new CLI commands, new migrations, new/removed modules>
  System doc: <updated/created/unchanged>
  Scope: <which platform areas this touches>
  One-line summary: <what this capability does, from the plan header>
```

Also create entries for capabilities evidenced by feat commits that have **no corresponding plan** — these are smaller features or fixes that shipped directly.

Also note **removals**: plans deleted, CLI commands removed, modules deleted. These need to be cleaned from our skills too.

### Phase 3: Cascade Analysis (orchestrator)

For each capability in the map, determine its impact on `eve-read-eve-docs`:

#### 3a. Reference doc impact

For each capability, ask:
1. Does an existing reference already cover this area? → Worker updates it
2. Is this a new primitive that needs its own reference? → Worker creates it
3. Was something removed? → Worker cleans stale content from affected references

Cross-reference against the current reference index in `eve-work/eve-read-eve-docs/SKILL.md` and the `reference_docs` section of `.sync-map.json`.

#### 3b. SKILL.md routing impact

Check if `eve-work/eve-read-eve-docs/SKILL.md` needs:
- New entries in the Task Router
- New entries in the Index
- New rows in the Intent Coverage Matrix
- New trigger keywords in the frontmatter
- Removal of stale entries for deprecated capabilities

#### 3c. Other skill impact

Check `.sync-map.json` `skill_triggers` and `composite_triggers` for other skills affected. Also consider:
- `eve-se/eve-manifest-authoring` — if manifest shape changed
- `eve-se/eve-deploy-debugging` — if deploy/infra behavior changed
- `eve-se/eve-auth-and-secrets` — if auth model changed
- `eve-work/eve-agent-memory` — if storage primitives changed
- `eve-design/eve-fullstack-app-design` — if app patterns changed

### Phase 4: Plan Work Items (orchestrator)

For each update identified in Phase 3, create a work item:

- **Title**: `Update <target-file>: <capability name>`
- **Description** — everything a worker needs to operate independently:
  - The eve-horizon repo path (`../eve-horizon`)
  - The commit range: `<last_synced_commit>..HEAD`
  - Which plan(s) to read (the shipped plans relevant to this update)
  - Which source files to diff or read (code, system docs)
  - The target file path to update or create
  - Whether this is a reference doc update, skill update, new reference, or removal
  - The appropriate worker instructions from below

Add a final work item: `Update sync state and produce report` — blocked until all updates finish.

If any work item touches `eve-work/eve-read-eve-docs`, also add:
- `Run state-today compliance scan for eve-read-eve-docs`
- `Validate progressive-access routing in eve-read-eve-docs/SKILL.md`
- `Update .sync-map.json with any new reference doc mappings`

### Phase 5: Dispatch Workers (parallel)

Spawn one background worker per work item. Launch them all at once.

**Each worker prompt must be self-contained.** The worker has no access to the orchestrator's conversation. Include:

1. The plan file(s) to read — these are the primary source of truth
2. The git diff command for relevant code/doc changes
3. The target file to read and modify
4. The capability summary from Phase 2
5. The appropriate worker instructions from below

#### Worker Instructions: Reference Doc Update

> Your primary sources are **shipped plans** (marked Implemented/Complete) and **code changes**.
> System docs are secondary — they may lag behind or be absent.
>
> 1. Read the plan(s) listed in your task — understand what shipped and w