tykimos/agent-native-agent/ana-update

ana-update — compare with upstream, then port feature by feature

A per-user ANA (e.g. das-ana) started from the base but has its own domain code, file names and UI. So an update is never "copy the repo over". It is: diff by feature → the user picks → port each picked feature with its skill → verify → record.

ana-diff.mjs ──► report (✓ present · ◐ partial · ✗ missing · module differs · runtime differs)
     │                      │
     │            user picks features
     ▼                      ▼
 .ana-sync.json ◄── verify ◄── port with the feature's skill (chat-window, context-chips, …)
 (--record)

The feature list lives in upstream `features.json`. Each feature has anchors (element ids, function names, API routes), the skill that ports it, modules to copy as-is, and npm deps.

In the app: the Update tab

The Update tab (Waiting · In progress · Done) runs this whole flow from the dashboard.

• Check for updates:
• Clones or fetches upstream into .ana/upstream (ANA_UPSTREAM_URL to change the source).
• Runs ana-diff.mjs against the ANA (ANA_UPDATE_TARGET to compare another folder).
• Lists one item per missing or partial feature, newer module, and the shared runtime (/api/update/check, stored in .ana/updates.json).
• Bring it in:
• Marks the item In progress.
• Sends the agent a chat instruction with the skill to follow, the missing anchors, modules, npm deps and the upstream checkout path.
• The agent ports it, verifies, updates the PRD if what the app does changed, and reports with POST /api/update-act {id, action: done|fail, reason?}.
• The shared runtime asks for confirmation first.
• Skip hides the item from every later check (until Restore). Done or failed items come back only when upstream has moved to a new commit. Items that are already in the ANA move to Done by themselves.

When you, the agent, receive an [Update] instruction, do exactly the porting steps below for that one feature and report back with the curl in the instruction.

0. Get the latest skills (once per machine, then just update)

The per-feature skills ship with the upstream repo as a Claude Code plugin. Install them so this ANA's agent can load them:

claude plugin marketplace add tykimos/agent-native-agent
claude plugin install ana@agent-native-agent
# later, to pick up newer skills:
claude plugin marketplace update agent-native-agent && claude plugin update ana@agent-native-agent

Without the plugin, read the same skills from the clone: <upstream>/skills/<name>/SKILL.md.

1. Diff (read-only)

Run from anywhere; the script needs only Node and git.

# upstream = GitHub (default), cloned to a temp dir
node <upstream>/skills/ana-update/scripts/ana-diff.mjs --target <path to the ANA>
# or against a local checkout / another URL
node ana-diff.mjs --target ~/ana/das-ana --upstream ~/ana/base-ana
node ana-diff.mjs --target . --upstream https://github.com/tykimos/agent-native-agent --json

If you don't have the script yet: git clone --filter=blob:none https://github.com/tykimos/agent-native-agent /tmp/ana-up and run it from there.

Read the last line: ANA_DIFF present=… partial=… missing=… runtime=same|differs|not-found todo=<ids>.

It scans the target's own .js/.mjs/.cjs/.html (not tests, node_modules, .ana/, data/). It also finds the channel-core.js the ANA actually uses, which may be a shared ../channel-core.js on a host.

2. Report to the user before changing anything

Give a short table in the user's language, grouped by skill. For each row: what it does for them (from summary in features.json), and its state. Call out:

• ◐ partial: the ANA has an older/custom version. List the missing anchors; porting means merging, not replacing.
• module differs: a copied module (agent-log.js, graph-index.js, codex-settings.js) exists but is older. Usually safe to replace whole, because these modules have no domain code. Check the target didn't edit it: diff it first.
• runtime differs: channel-core.js is shared by every ANA on a host. Updating it is a separate decision. Ask explicitly, name the other ANAs that share it, and replace the whole file, never a patch. Several chat features need the newer runtime (per-session ledgers, per-person recent session).
• changes since last sync: if .ana-sync.json exists, the script lists upstream commits since then. Summarize them.

Then ask which features to apply. A sensible default: everything from the chat-window skill first (most visible), then context-chips, then the rest.

3. Port each picked feature with its skill

Load the skill named in the report and follow its Porting section. Common rules for all of them:

1. Find the target's extension points first. These are:

• the page file (usually dashboard.html)
• the API module passed as extraApi to channel-core's createApp (dashboard-api.js in the base, das-api.js in das-ana, …)
• server.js options

1. Copy standalone modules whole (copy in features.json), then add the routes/UI that use them.
2. Take code from upstream by anchor. Run grep -n '<anchor>' <upstream>/dashboard.html to find each block: the HTML element, its CSS rules, and its JS functions. Bring the whole block, then rename ids only if they collide with the target's.
3. Keep the target's domain code and look. Use its CSS tokens (--blue, --surface, …). If a token is missing, add it to the target's :root.
4. Never patch `channel-core.js` per ANA. If a feature needs a newer runtime, stop and ask (step 2).
5. Don't touch other ANAs' `.ana/` or their ports/tmux sessions.

4. Verify

• the target's own tests (node test.cjs or npm test)
• re-run ana-diff.mjs: the ported features must show ✓
• open the page at phone width (390px) and desktop and exercise each feature (each skill has a checklist)
• restart only that ANA's server, the way it is normally run (launchd kickstart -k, tmux, run.sh restart). Never `killall node`: it kills every ANA and the Codex CLIs.

5. Record

node ana-diff.mjs --target <ANA> --upstream <same upstream> --record

This writes <ANA>/.ana-sync.json (upstream commit, date, features present). The next update lists only upstream commits since then.

Git safety

• Commit only when the user asks, and push right away if the checkout is kept in sync with a remote. A launchd "sync" job that does git reset --hard origin/main will wipe unpushed commits. Check launchctl list | grep sync and ~/Library/LaunchAgents/*sync* first.
• If something goes wrong, the reflog keeps the commit: git reflog, then git branch backup/<name> <sha>.

Keeping this working (for upstream maintainers)

When you add or rename a user-facing feature in the base, update features.json (anchors, skill, copy, npm) and the skill's Porting section. test.cjs fails if an anchor no longer exists in the base.