Sync Team Profiles

sync-team-profiles

Wraps bin/sync-team-profiles.sh. On first run it shallow-clones each registered team-profile source (git clone --depth=1); on subsequent runs it does a shallow fetch (git fetch --depth=1) and git reset --hard FETCH_HEAD to advance to the latest commit. Every profile under the cache is then validated against profiles/_schema.json, and valid profiles are registered under /.

1. Pre-flight

• Config at ~/.claude/nyann/config.json must have at least one

entry in team_profile_sources[]. If empty, route to add-team-source first.

• Uses the sync interval from each source. When the user says

"force refresh" / "ignore the interval" / "pull now", pass --force.

• When the user names a specific source ("sync just the platform-

team profiles"), pass --name so unrelated sources don't get pulled.

2. Invoke

bin/sync-team-profiles.sh \
  [--user-root ] \
  [--force] \
  [--name ]

Network operation. Expect up to a few seconds per source. The backend is resilient — a failing source logs the error and moves on to the next.

3. Interpret the JSON summary

Top-level shape is four arrays (see schemas/team-sync-result.schema.json):

• synced[] — sources that pulled this run. Each entry: {name, synced_at}.
• skipped[] — sources within their interval window. Each entry:

{name, reason: "within-interval", next_due}. Tell the user the next-due timestamp; they can re-run with --force if they need to pull immediately.

• registered[] — every profile that passed schema validation.

Each entry: {source, name, namespaced, path}. The namespaced field is what to use with bootstrap-project --profile .

• invalid[] — anything that didn't make it through (fetch

failure, clone failure, hand-edited config with a bad ref/url, TOCTOU on the cache dir, profile that fails schema validation). Each entry: {name|source, kind, error} where kind is one of invalid-name, invalid-ref, invalid-url, fetch-failed, clone-failed, toctou, invalid-schema. Show these but don't treat any single one as fatal — the script logs and moves on to the next source.

4. After sync

• Tell the user how many profiles are newly available.
• Suggest inspect-profile / to see what a specific

team profile does.

• Suggest bootstrap-project --profile / to apply

one to a repo.

5. When a source errors

• git clone / git fetch failures are usually auth or network

issues and surface in invalid[] with kind: clone-failed or fetch-failed. The error string passes through nyann::redact_url before reaching the JSON, so any embedded https://@host credentials are scrubbed — safe to relay verbatim. Don't try to auth-fix on the user's behalf.

• Corrupted cache (/cache// contains partial

data) — safe to delete the cache dir and re-run. Confirm before deleting; it's a file-system mutation.

When to hand off

• "Add a new source" → add-team-source.
• "My team profile collides with a starter profile" — by design,

user + team profiles can shadow starters. Clarify which version will win (user > team > starter) and let the user decide if the shadow is intentional.

• "Drift detection: is my cached team profile out of sync with the

remote?" → that's check-team-drift (separate backend; not in this skill's scope).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: thettwe
• Source: thettwe/nyann
• License: MIT

Install and usage instructions live in the source repository linked above.