skillpacks 0.1.0

package/packs/gitops/claude/sync/archive/v0.3/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: sync
+description: Pull latest changes from remote and report status
+type: shipping
+version: v0.3
+argument-hint:
+---
+
+# Sync
+
+Pull the latest changes from the remote repository and report status.
+
+## Process
+
+1. **Check current state:**
+   - Run `git status` to check for uncommitted changes.
+   - If there are uncommitted changes, stash them first (`git stash`), pull, then pop the stash. Warn the user about the stash.
+
+2. **Pull from remote:**
+   - Run `git pull --rebase origin <current-branch>`.
+   - If rebase conflicts occur, abort the rebase (`git rebase --abort`), try `git pull --no-rebase` instead, and report any merge conflicts for the user to resolve.
+
+3. **Check for outstanding work:**
+   - Check if `tasks/roadmap.md` exists for the full plan, and `tasks/todo.md` for the current phase.
+   - If `tasks/todo.md` exists, read it and look for unchecked items (`- [ ]`).
+   - If there are incomplete items, summarise: which phase is current, what the next step is, and how many steps/phases remain.
+   - If `tasks/manual-todo.md` exists, count unchecked manual tasks and include in the summary.
+   - If `tasks/record-todo.md` or `tasks/recurring-todo.md` exists, count unchecked advisory items and include those counts separately. Do not treat them as active plan steps.
+   - If all items are checked, report that the plan is complete.
+   - If neither file exists, note that there is no active plan.
+
+4. **Check provisioned agent config:**
+   - If `CLAUDE.md` or `AGENTS.md` contains `<!-- provision-agentic-config vX.Y -->`, extract the version.
+   - Read the canonical `provision-agentic-config` skill from the first existing path in this order:
+     1. `~/.claude/skills/provision-agentic-config/SKILL.md`
+     2. `~/.codex/skills/provision-agentic-config/SKILL.md`
+     3. `global/claude/provision-agentic-config/SKILL.md` in the current repo, when present
+     4. `global/codex/provision-agentic-config/SKILL.md` in the current repo, when present
+   - Extract the `version:` field from the canonical skill's YAML frontmatter.
+   - Extract the canonical provisioned blocks from the same skill:
+     - `CLAUDE.md`: the fenced block under `Required Claude Block` or the section that says "The Claude block to insert into `./CLAUDE.md`".
+     - `AGENTS.md`: the fenced block under `Required AGENTS Block` or the section that says "The AGENTS block to insert into `./AGENTS.md`".
+   - Compare each existing project file against its corresponding canonical block after normalizing line endings and trimming only leading/trailing whitespace around the block. Do not ignore changed bullets, headings, command examples, or policy text.
+   - If the installed skill version is newer than the provisioned version in either file, warn: `⚠ CLAUDE.md provisioned with vX.Y but provision-agentic-config is at vX.Y — consider re-running /provision-agentic-config`
+   - If the version comment is missing from `CLAUDE.md` or `AGENTS.md`, note: `ℹ No provision version found in CLAUDE.md/AGENTS.md — run /provision-agentic-config to add version tracking`
+   - If a project file has the current version comment but the provisioned block content differs from the canonical block, warn: `⚠ CLAUDE.md provisioned block differs from the canonical provision-agentic-config vX.Y block — re-run /provision-agentic-config`
+   - If a canonical block cannot be extracted, fall back to the version-only check and note: `ℹ Could not extract canonical provision-agentic-config block; checked version comment only`
+   - If none of the canonical skill files exists, skip this check silently.
+   - Always report the local canonical source path used and its `version:` field when this check runs.
+
+5. **Resolve GitHub freshness preference:**
+   - Use the user-local machine-wide preference file at `~/.agentic-skills/preferences.json`.
+   - Read `sync.github_freshness_check`, whose only allowed values are `"ask"`, `"always"`, and `"never"`.
+   - If the file or key is missing, ask the user once which default to remember:
+     - Always check GitHub during sync
+     - Never check GitHub during sync
+     - Ask each time
+   - Create `~/.agentic-skills/preferences.json` if needed and save the selected value as:
+     ```json
+     {
+       "sync": {
+         "github_freshness_check": "ask"
+       }
+     }
+     ```
+   - If the value is `"always"`, check GitHub remote freshness automatically.
+   - If the value is `"never"`, skip GitHub freshness checks and report that local canonical `provision-agentic-config` was used without a GitHub check.
+   - If the value is `"ask"`, ask before checking GitHub for this sync.
+   - Treat malformed JSON or an unsupported value as missing preference and ask again before writing one of the allowed values.
+
+6. **Optional GitHub freshness check:**
+   - Only run this check when the resolved preference or explicit user approval says to check GitHub.
+   - Compare the local `agentic-skills` checkout against `origin/HEAD` using non-mutating commands such as `git remote get-url origin`, `git rev-parse HEAD`, `git rev-parse origin/HEAD`, and, when remote freshness is explicitly enabled, `git fetch --dry-run` or an equivalent non-mutating freshness probe.
+   - Report the local checkout commit, remote URL, local `origin/HEAD` commit if available, and whether the local checkout appears behind the remote.
+   - Do not pull, fast-forward, rebase, install, or mutate the checkout from plain `/sync`.
+   - If a GitHub check shows the local checkout is stale, recommend `/init-agentic-skills update` for an explicit update.
+
+7. **Report status:**
+   - Branch name
+   - Commits pulled (if any) — show short log of new commits
+   - Whether stashed changes were re-applied
+   - Any conflicts that need manual resolution
+   - Current `git status`
+   - **Agent config drift** — provisioning version, local canonical source path/version, and canonical block match/drift status for `CLAUDE.md` and `AGENTS.md`, if checked
+   - **GitHub freshness** — preference value, whether GitHub was checked, and the local checkout/remote status; when skipped, say local canonical was used
+   - **Outstanding work** — summary from step 3 (next step, current phase, remaining work, pending manual tasks) or "No active plan"
+   - **Advisory tasks** — pending record/recurring counts, if those files exist
+
+8. **Post-sync actions:**
+
+   a) Check if `sync.md` exists at the project root.
+
+   b) **If `sync.md` exists** — parse and execute it:
+      - Read `sync.md` and identify sections by H2 headings.
+      - **Dependencies** (aliases: "Deps", "Dependency Management"):
+        Execute shell commands found in fenced code blocks (e.g., `npm install`). Report output briefly.
+      - **Conflict Resolution** (aliases: "Conflicts"):
+        If the pull introduced merge conflicts (from step 2), apply the guidance in this section. For example, if it says "accept theirs for lockfiles", run the appropriate `git checkout --theirs` command. If no conflicts exist, skip silently.
+      - **Custom** (aliases: "Project-Specific", "Scripts", "Setup"):
+        Execute shell commands found in fenced code blocks in order. Report output briefly.
+      - **Notifications** (aliases: "Awareness", "Alerts", "Watch"):
+        For each bullet point, check if the mentioned file or directory was modified in the pulled commits (use `git diff --name-only` against the pre-pull HEAD). If any match, print a prominent alert with the bullet's description.
+      - Sections with unrecognised headings: skip with a note ("Skipped unknown sync.md section: <heading>").
+      - Report a summary of all post-sync actions taken.
+
+   c) **If `sync.md` does not exist** — suggest creating one:
+      - Analyse the project to detect:
+        - Package manager (look for `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Pipfile.lock`, `requirements.txt`, `go.sum`, `Cargo.lock`, `Gemfile.lock`, `composer.lock`)
+        - Common scripts (check `package.json` scripts, `Makefile`, `Justfile` for build/codegen/migrate targets)
+        - Config templates (`.env.example`, `docker-compose.yml`, `config/`)
+      - Present a suggested `sync.md` to the user with detected actions pre-filled, following the format in the **sync.md format** section below.
+      - Ask: "Would you like me to create this `sync.md`? You can customise it anytime."
+      - **Only create the file if the user approves.**
+
+## sync.md format
+
+The `sync.md` file lives at the project root. It uses H2 sections as categories. Shell commands go in fenced code blocks; prose guidance goes in bullet points.
+
+```markdown
+# Post-Sync Actions
+
+## Dependencies
+
+Commands to run after pulling to keep local dependencies up to date.
+
+```sh
+npm install
+```
+
+## Conflict Resolution
+
+Project-specific guidance for handling merge conflicts.
+
+- Always accept theirs for `package-lock.json` — regenerate via install command above
+- For `generated/` files, regenerate with `npm run codegen` instead of resolving manually
+
+## Custom
+
+Project-specific scripts or commands to run after sync.
+
+```sh
+npm run codegen
+```
+
+## Notifications
+
+Files and patterns to check for changes after a pull. Alert the user if any were modified.
+
+- `.env.example` — check for new environment variables you may need to add to `.env`
+- `CLAUDE.md` — review if project conventions were updated
+- `config/` — warn about config schema changes
+```
+
+## Constraints
+- Do not force-push or rewrite history.
+- Do not auto-resolve merge conflicts — report them and let the user decide. However, if `sync.md` has a **Conflict Resolution** section, follow its guidance for the specific files/patterns it covers.
+- If stash pop fails due to conflicts, leave the stash intact and report it.
+- Post-sync commands from `sync.md` run in the project root directory.
+- If any post-sync command fails, report the error and continue with remaining actions (do not abort).
+- Never auto-create `sync.md` without explicit user approval.
+- Do not execute commands from `sync.md` sections that are commented out with HTML comments (`<!-- ... -->`).
+- Plain `/sync` must not update the `agentic-skills` checkout, pull from GitHub for the local canonical source, or reinstall skills. Only `/init-agentic-skills update` / `/init-agentic-skills latest` may perform that explicit update flow after confirmation.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/gitops/codex/commit-and-push-by-feature/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## v0.1 - 2026-05-30
+
+- Added the pack install artifact boundary so `.agents/project.json` is committed for pack configuration changes while generated `.claude/skills/**` and `.codex/skills/**` roots are never bucketed, staged, or committed.
+
+## v0.0
+
+- Initial Codex feature-bucket commit and push workflow.

package/packs/gitops/codex/commit-and-push-by-feature/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: commit-and-push-by-feature
+description: Commit and push all changes to GitHub grouped by logical feature/function buckets with conventional commit messages
+type: shipping
+version: v0.1
+---
+
+# Commit And Push By Feature
+
+Invoke as `$commit-and-push-by-feature`.
+
+Use this skill when the user wants current changes committed and pushed in sensible feature-oriented buckets rather than one undifferentiated commit.
+
+## Process
+
+1. Inspect `git status` and relevant diffs to understand the change set.
+1a. **Pack install artifact boundary:** Treat `.agents/project.json` as the committed project designation. When pack configuration changed, bucket and commit `.agents/project.json`. Treat `.claude/skills/**` and `.codex/skills/**` as generated local skill roots recreated by `/pack`, `$pack`, or `scripts/pack.sh refresh`; generated skill roots must not be staged or committed. If those roots are untracked, leave them uncommitted and report them as generated local artifacts. If any path under those roots is already tracked or modified as a tracked file, stop unless the current task explicitly includes repository hygiene to untrack or ignore generated skill roots.
+1b. For non-trivial mutations, confirm the caller has produced a `docs/quality-gate-contract.md` ship manifest for the exact shipping boundary before staging. The manifest must include: User goal, Changed files, Per-file purpose, User-goal mapping, Tests run, Skipped tests, Adversarial review, Residual risk, Rollback note, and Next command.
+1c. If the change set includes non-trivial source changes, confirm the manifest records a targeted `quality-sweep audit`, `$expert-review`, configured review lane, or explicitly justified equivalent adversarial review. If the review is missing, stop before committing.
+1d. Confirm validation evidence distinguishes executable checks from documentation-only or task-only checks. If non-trivial source changes rely only on documentation/task checks, stop before committing unless the manifest gives a concrete skipped-test rationale and residual-risk explanation.
+1e. If the work being shipped follows a user correction, confirm the pre-commit ship manifest proves the exact shipping boundary includes a `tasks/lessons.md` update for the current correction. Treat the correction as repeatable unless the manifest proves otherwise. If it exposed a workflow failure, confirm the same shipping boundary includes the relevant skill contract, validation script, fixture, or test enforcement update, or a `Correction enforcement:` entry with the blocker or not-applicable rationale and the concrete follow-up file/command when needed.
+2. Partition changes into logical buckets such as `auth`, `api`, `ui`, `tests`, `docs`, `build`, or `refactor`.
+3. Prefer 2 to 6 commits unless the change set is genuinely tiny.
+4. For each bucket:
+   - Stage only the files for that bucket
+   - Verify the staged diff matches the intended scope
+   - Commit with a conventional message such as `feat(scope): summary`, `fix(scope): summary`, `refactor(scope): summary`, `test(scope): summary`, `docs(scope): summary`, or `chore(scope): summary`
+5. Do not leave unrelated tracked changes behind. Either bucket them too or stop and explain the blocker. Generated local skill roots under `.claude/skills/**` or `.codex/skills/**` are the exception: do not bucket, stage, or commit them, even in final leftover cleanup.
+6. Determine the primary branch: prefer `main`; if it does not exist, use `master`. If neither exists, stop and explain the blocker.
+7. Ensure the commits land on the primary branch from step 6:
+   - If already on `main` or `master`, stay there.
+   - If on any other branch, switch to the primary branch before committing and pushing. Carry the working tree across only if it can be done safely.
+   - If switching would discard work, introduce conflicts you cannot resolve confidently, or otherwise prevent a safe move onto the primary branch, stop and explain the blocker. Do **not** push the feature branch instead.
+8. Push the resulting commits to the primary branch. `commit-and-push-by-feature` means commit **and** push when the workflow succeeds.
+
+## Safety
+
+- Do not amend or rewrite history unless the user explicitly asks.
+- Stop if you detect likely secrets or credentials in the diff.
+- If hooks or tests fail and the expected fix is straightforward, fix them and continue; otherwise report the blocker.
+- Do not commit or push a non-trivial mutation without a ship manifest that covers the exact files being shipped. If unrelated tracked changes are present, the manifest must identify which files are included and why the remaining files are safe to leave untouched.
+- Do not treat documentation-only or task-only checks as sufficient executable verification for source changes. Require a skipped-test rationale when no executable check was run.
+- Do not ship a user-correction follow-up unless the manifest proves the current correction's `tasks/lessons.md` update is in the exact shipping boundary and includes either an enforcement update or a `Correction enforcement:` rationale. If claiming an existing rule already covers the correction, require the manifest to cite the exact file and rule/check and explain why it would have prevented the corrected behavior.
+
+## Output
+
+Report:
+
+- Branch name
+- Commits created, with hash and subject
+- Final `git status` outcome
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/gitops/codex/commit-and-push-by-feature/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Commit By Feature"
+  short_description: "Commit and push by logical bucket"
+  default_prompt: "Use $commit-and-push-by-feature to group the current git changes into logical commits and push them safely."
+
+policy:
+  allow_implicit_invocation: true

package/packs/gitops/codex/commit-and-push-by-feature/archive/v0.0/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: commit-and-push-by-feature
+description: Commit and push all changes to GitHub grouped by logical feature/function buckets with conventional commit messages
+type: shipping
+version: v0.0
+---
+
+# Commit And Push By Feature
+
+Invoke as `$commit-and-push-by-feature`.
+
+Use this skill when the user wants current changes committed and pushed in sensible feature-oriented buckets rather than one undifferentiated commit.
+
+## Workflow
+
+1. Inspect `git status` and relevant diffs to understand the change set.
+1b. For non-trivial mutations, confirm the caller has produced a `docs/quality-gate-contract.md` ship manifest for the exact shipping boundary before staging. The manifest must include: User goal, Changed files, Per-file purpose, User-goal mapping, Tests run, Skipped tests, Adversarial review, Residual risk, Rollback note, and Next command.
+1c. If the change set includes non-trivial source changes, confirm the manifest records a targeted `quality-sweep audit`, `$expert-review`, configured review lane, or explicitly justified equivalent adversarial review. If the review is missing, stop before committing.
+1d. Confirm validation evidence distinguishes executable checks from documentation-only or task-only checks. If non-trivial source changes rely only on documentation/task checks, stop before committing unless the manifest gives a concrete skipped-test rationale and residual-risk explanation.
+1e. If the work being shipped follows a user correction, confirm the pre-commit ship manifest proves the exact shipping boundary includes a `tasks/lessons.md` update for the current correction. Treat the correction as repeatable unless the manifest proves otherwise. If it exposed a workflow failure, confirm the same shipping boundary includes the relevant skill contract, validation script, fixture, or test enforcement update, or a `Correction enforcement:` entry with the blocker or not-applicable rationale and the concrete follow-up file/command when needed.
+2. Partition changes into logical buckets such as `auth`, `api`, `ui`, `tests`, `docs`, `build`, or `refactor`.
+3. Prefer 2 to 6 commits unless the change set is genuinely tiny.
+4. For each bucket:
+   - Stage only the files for that bucket
+   - Verify the staged diff matches the intended scope
+   - Commit with a conventional message such as `feat(scope): summary`, `fix(scope): summary`, `refactor(scope): summary`, `test(scope): summary`, `docs(scope): summary`, or `chore(scope): summary`
+5. Do not leave unrelated tracked changes behind. Either bucket them too or stop and explain the blocker.
+6. Determine the primary branch: prefer `main`; if it does not exist, use `master`. If neither exists, stop and explain the blocker.
+7. Ensure the commits land on the primary branch from step 6:
+   - If already on `main` or `master`, stay there.
+   - If on any other branch, switch to the primary branch before committing and pushing. Carry the working tree across only if it can be done safely.
+   - If switching would discard work, introduce conflicts you cannot resolve confidently, or otherwise prevent a safe move onto the primary branch, stop and explain the blocker. Do **not** push the feature branch instead.
+8. Push the resulting commits to the primary branch. `commit-and-push-by-feature` means commit **and** push when the workflow succeeds.
+
+## Safety
+
+- Do not amend or rewrite history unless the user explicitly asks.
+- Stop if you detect likely secrets or credentials in the diff.
+- If hooks or tests fail and the expected fix is straightforward, fix them and continue; otherwise report the blocker.
+- Do not commit or push a non-trivial mutation without a ship manifest that covers the exact files being shipped. If unrelated tracked changes are present, the manifest must identify which files are included and why the remaining files are safe to leave untouched.
+- Do not treat documentation-only or task-only checks as sufficient executable verification for source changes. Require a skipped-test rationale when no executable check was run.
+- Do not ship a user-correction follow-up unless the manifest proves the current correction's `tasks/lessons.md` update is in the exact shipping boundary and includes either an enforcement update or a `Correction enforcement:` rationale. If claiming an existing rule already covers the correction, require the manifest to cite the exact file and rule/check and explain why it would have prevented the corrected behavior.
+
+## Output
+
+Report:
+
+- Branch name
+- Commits created, with hash and subject
+- Final `git status` outcome
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/gitops/codex/sync/CHANGELOG.md

@@ -0,0 +1,27 @@
+# sync Changelog
+
+## v0.4
+
+- Add warn-only skill-install drift check: run `scripts/pack.sh doctor` against the resolved `agentic-skills` checkout and report `stale`/`unknown` project skill installs with the `scripts/pack.sh refresh` fix
+- Keep plain sync non-mutating; never auto-refresh installs
+
+## v0.3
+
+- Add remembered user-local GitHub freshness preference at `~/.agentic-skills/preferences.json`
+- Require local canonical `provision-agentic-config` source/version reporting during sync
+- Keep plain sync non-mutating and route explicit checkout refreshes to `$init-agentic-skills update`
+
+## v0.2
+
+- Add canonical `CLAUDE.md`/`AGENTS.md` block drift checks against `provision-agentic-config`
+- Fall back to repo-local `provision-agentic-config` when installed skill files are unavailable
+- Report agent config drift in sync status
+
+## v0.1
+
+- Add provisioning version check: compare `<!-- provision-agentic-config vX.Y -->` in CLAUDE.md/AGENTS.md against installed skill version
+- Warn when provisioned blocks are stale
+
+## v0.0
+
+- Initial version with pull, stash, conflict handling, outstanding work check, and sync.md support

package/packs/gitops/codex/sync/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: sync
+description: Pull latest changes from remote and report status
+type: shipping
+version: v0.4
+---
+
+# Sync
+
+Invoke as `$sync`.
+
+Pull the latest changes from the remote repository and report status.
+
+## Process
+
+1. Check current state:
+   - Run `git status` to check for uncommitted changes.
+   - If there are uncommitted changes, stash them first, pull, then pop the stash. Warn the user about the stash.
+2. Pull from remote:
+   - Run `git pull --rebase origin <current-branch>`.
+   - If rebase conflicts occur, abort the rebase, try `git pull --no-rebase` instead, and report any merge conflicts for the user to resolve.
+3. Check for outstanding work:
+   - Check if `tasks/roadmap.md` exists for the full plan, and `tasks/todo.md` for the current phase.
+   - If `tasks/todo.md` exists, read it and look for unchecked items (`- [ ]`).
+   - If there are incomplete items, summarise: which phase is current, what the next step is, and how many steps/phases remain.
+   - If `tasks/manual-todo.md` exists, count unchecked manual tasks and include in the summary.
+   - If `tasks/record-todo.md` or `tasks/recurring-todo.md` exists, count unchecked advisory items and include those counts separately. Do not treat them as active plan steps.
+   - If all items are checked, report that the plan is complete.
+   - If neither file exists, note that there is no active plan.
+4. Check provisioned agent config:
+   - If `CLAUDE.md` or `AGENTS.md` contains `<!-- provision-agentic-config vX.Y -->`, extract the version.
+   - Read the canonical `provision-agentic-config` skill from the first existing path in this order:
+     1. `~/.codex/skills/provision-agentic-config/SKILL.md`
+     2. `~/.claude/skills/provision-agentic-config/SKILL.md`
+     3. `global/codex/provision-agentic-config/SKILL.md` in the current repo, when present
+     4. `global/claude/provision-agentic-config/SKILL.md` in the current repo, when present
+   - Extract the `version:` field from the canonical skill's YAML frontmatter.
+   - Extract the canonical provisioned blocks from the same skill:
+     - `CLAUDE.md`: the fenced block under `Required Claude Block` or the section that says "The Claude block to insert into `./CLAUDE.md`".
+     - `AGENTS.md`: the fenced block under `Required AGENTS Block` or the section that says "The AGENTS block to insert into `./AGENTS.md`".
+   - Compare each existing project file against its corresponding canonical block after normalizing line endings and trimming only leading/trailing whitespace around the block. Do not ignore changed bullets, headings, command examples, or policy text.
+   - If the installed skill version is newer than the provisioned version in either file, warn: `⚠ CLAUDE.md provisioned with vX.Y but provision-agentic-config is at vX.Y — consider re-running $provision-agentic-config`
+   - If the version comment is missing from `CLAUDE.md` or `AGENTS.md`, note: `ℹ No provision version found in CLAUDE.md/AGENTS.md — run $provision-agentic-config to add version tracking`
+   - If a project file has the current version comment but the provisioned block content differs from the canonical block, warn: `⚠ CLAUDE.md provisioned block differs from the canonical provision-agentic-config vX.Y block — re-run $provision-agentic-config`
+   - If a canonical block cannot be extracted, fall back to the version-only check and note: `ℹ Could not extract canonical provision-agentic-config block; checked version comment only`
+   - If none of the canonical skill files exists, skip this check silently.
+   - Always report the local canonical source path used and its `version:` field when this check runs.
+5. Check skill-install drift (track-latest):
+   - Project-local pack/skill installs under `.claude/skills` and `.codex/skills` are managed copies stamped with `.agentic-skills-managed`, which now records `source_version` and `source_sha`. When canonical sources in the `agentic-skills` checkout move ahead, the installed copies fall behind.
+   - Resolve the `agentic-skills` checkout from any install marker's `source=` path (the parent above `.../packs/..` or `.../global/..` is the repo root). If no managed install exists or the checkout cannot be resolved, skip this check silently.
+   - Run `scripts/pack.sh doctor` from the project root using that checkout (read-only; it never mutates installs).
+   - Fold any `stale` skills into the Report status block with the fix command `scripts/pack.sh refresh`. Report `unknown` skills as "run `scripts/pack.sh refresh` to enable drift tracking" and leave `pinned` skills noted as frozen.
+   - Must not mutate. Plain `$sync` only warns; it never runs `refresh`, re-copies, or otherwise changes installs. Direct the user to `scripts/pack.sh refresh` (or enable auto-refresh) for the actual update.
+6. Resolve GitHub freshness preference:
+   - Use the user-local machine-wide preference file at `~/.agentic-skills/preferences.json`.
+   - Read `sync.github_freshness_check`, whose only allowed values are `"ask"`, `"always"`, and `"never"`.
+   - If the file or key is missing, ask the user once which default to remember:
+     - Always check GitHub during sync
+     - Never check GitHub during sync
+     - Ask each time
+   - Create `~/.agentic-skills/preferences.json` if needed and save the selected value as:
+     ```json
+     {
+       "sync": {
+         "github_freshness_check": "ask"
+       }
+     }
+     ```
+   - If the value is `"always"`, check GitHub remote freshness automatically.
+   - If the value is `"never"`, skip GitHub freshness checks and report that local canonical `provision-agentic-config` was used without a GitHub check.
+   - If the value is `"ask"`, ask before checking GitHub for this sync.
+   - Treat malformed JSON or an unsupported value as missing preference and ask again before writing one of the allowed values.
+7. Optional GitHub freshness check:
+   - Only run this check when the resolved preference or explicit user approval says to check GitHub.
+   - Compare the local `agentic-skills` checkout against `origin/HEAD` using non-mutating commands such as `git remote get-url origin`, `git rev-parse HEAD`, `git rev-parse origin/HEAD`, and, when remote freshness is explicitly enabled, `git fetch --dry-run` or an equivalent non-mutating freshness probe.
+   - Report the local checkout commit, remote URL, local `origin/HEAD` commit if available, and whether the local checkout appears behind the remote.
+   - Do not pull, fast-forward, rebase, install, or mutate the checkout from plain `$sync`.
+   - If a GitHub check shows the local checkout is stale, recommend `$init-agentic-skills update` for an explicit update.
+8. Report status:
+   - Branch name
+   - Commits pulled (if any) — show short log of new commits
+   - Whether stashed changes were re-applied
+   - Any conflicts that need manual resolution
+   - Current `git status`
+   - **Agent config drift** — provisioning version, local canonical source path/version, and canonical block match/drift status for `CLAUDE.md` and `AGENTS.md`, if checked
+   - **Skill-install drift** — any `stale` project skill installs (with `vOld → vNew`), `unknown` installs needing a refresh to enable tracking, and the `scripts/pack.sh refresh` fix command; report "all installs current" when none are stale, or skip the line when no managed installs exist
+   - **GitHub freshness** — preference value, whether GitHub was checked, and the local checkout/remote status; when skipped, say local canonical was used
+   - **Outstanding work** — summary from step 3 (next step, current phase, remaining work, pending manual tasks) or "No active plan"
+   - **Advisory tasks** — pending record/recurring counts, if those files exist
+9. Post-sync actions:
+   a) Check if `sync.md` exists at the project root.
+   b) **If `sync.md` exists** — parse and execute it:
+      - Read `sync.md` and identify sections by H2 headings.
+      - **Dependencies** (aliases: "Deps", "Dependency Management"): Execute shell commands in fenced code blocks. Report output briefly.
+      - **Conflict Resolution** (aliases: "Conflicts"): If the pull introduced merge conflicts (from step 2), apply the guidance in this section. If no conflicts, skip silently.
+      - **Custom** (aliases: "Project-Specific", "Scripts", "Setup"): Execute shell commands in fenced code blocks in order. Report output briefly.
+      - **Notifications** (aliases: "Awareness", "Alerts", "Watch"): For each bullet, check if the mentioned file/directory was modified in pulled commits (`git diff --name-only` against pre-pull HEAD). If any match, print a prominent alert.
+      - Unrecognised headings: skip with a note.
+      - Report a summary of all post-sync actions taken.
+   c) **If `sync.md` does not exist** — suggest creating one:
+      - Analyse the project to detect: package manager (look for lockfiles), common scripts (package.json, Makefile, Justfile), config templates (.env.example, docker-compose.yml).
+      - Present a suggested `sync.md` following the format below.
+      - Ask: "Would you like me to create this `sync.md`?"
+      - **Only create the file if the user approves.**
+
+## sync.md format
+
+The `sync.md` file lives at the project root. H2 sections are categories. Shell commands go in fenced code blocks; prose guidance goes in bullet points.
+
+```markdown
+# Post-Sync Actions
+
+## Dependencies
+
+```sh
+npm install
+```
+
+## Conflict Resolution
+
+- Always accept theirs for `package-lock.json`
+
+## Custom
+
+```sh
+npm run codegen
+```
+
+## Notifications
+
+- `.env.example` — check for new environment variables
+- `CLAUDE.md` — review if project conventions were updated
+```
+
+## Constraints
+
+- Do not force-push or rewrite history.
+- Do not auto-resolve merge conflicts — report them and let the user decide. However, if `sync.md` has a Conflict Resolution section, follow its guidance for the specific files/patterns it covers.
+- If stash pop fails due to conflicts, leave the stash intact and report it.
+- Post-sync commands from `sync.md` run in the project root directory.
+- If any post-sync command fails, report the error and continue with remaining actions.
+- Never auto-create `sync.md` without explicit user approval.
+- Do not execute commented-out sections (`<!-- ... -->`).
+- Plain `$sync` must not update the `agentic-skills` checkout, pull from GitHub for the local canonical source, or reinstall skills. Only `$init-agentic-skills update` / `$init-agentic-skills latest` may perform that explicit update flow after confirmation.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/gitops/codex/sync/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Sync"
+  short_description: "Pull latest changes from remote"
+  default_prompt: "Use $sync to pull and sync with the remote repository."
+
+policy:
+  allow_implicit_invocation: true

package/packs/gitops/codex/sync/archive/v0.0/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: sync
+description: Pull latest changes from remote and report status
+type: shipping
+version: v0.0
+---
+
+# Sync
+
+Invoke as `$sync`.
+
+Pull the latest changes from the remote repository and report status.
+
+## Workflow
+
+1. Check current state:
+   - Run `git status` to check for uncommitted changes.
+   - If there are uncommitted changes, stash them first, pull, then pop the stash. Warn the user about the stash.
+2. Pull from remote:
+   - Run `git pull --rebase origin <current-branch>`.
+   - If rebase conflicts occur, abort the rebase, try `git pull --no-rebase` instead, and report any merge conflicts for the user to resolve.
+3. Check for outstanding work:
+   - Check if `tasks/roadmap.md` exists for the full plan, and `tasks/todo.md` for the current phase.
+   - If `tasks/todo.md` exists, read it and look for unchecked items (`- [ ]`).
+   - If there are incomplete items, summarise: which phase is current, what the next step is, and how many steps/phases remain.
+   - If `tasks/manual-todo.md` exists, count unchecked manual tasks and include in the summary.
+   - If `tasks/record-todo.md` or `tasks/recurring-todo.md` exists, count unchecked advisory items and include those counts separately. Do not treat them as active plan steps.
+   - If all items are checked, report that the plan is complete.
+   - If neither file exists, note that there is no active plan.
+4. Report status:
+   - Branch name
+   - Commits pulled (if any) — show short log of new commits
+   - Whether stashed changes were re-applied
+   - Any conflicts that need manual resolution
+   - Current `git status`
+   - **Outstanding work** — summary from step 3 (next step, current phase, remaining work, pending manual tasks) or "No active plan"
+   - **Advisory tasks** — pending record/recurring counts, if those files exist
+5. Post-sync actions:
+   a) Check if `sync.md` exists at the project root.
+   b) **If `sync.md` exists** — parse and execute it:
+      - Read `sync.md` and identify sections by H2 headings.
+      - **Dependencies** (aliases: "Deps", "Dependency Management"): Execute shell commands in fenced code blocks. Report output briefly.
+      - **Conflict Resolution** (aliases: "Conflicts"): If the pull introduced merge conflicts (from step 2), apply the guidance in this section. If no conflicts, skip silently.
+      - **Custom** (aliases: "Project-Specific", "Scripts", "Setup"): Execute shell commands in fenced code blocks in order. Report output briefly.
+      - **Notifications** (aliases: "Awareness", "Alerts", "Watch"): For each bullet, check if the mentioned file/directory was modified in pulled commits (`git diff --name-only` against pre-pull HEAD). If any match, print a prominent alert.
+      - Unrecognised headings: skip with a note.
+      - Report a summary of all post-sync actions taken.
+   c) **If `sync.md` does not exist** — suggest creating one:
+      - Analyse the project to detect: package manager (look for lockfiles), common scripts (package.json, Makefile, Justfile), config templates (.env.example, docker-compose.yml).
+      - Present a suggested `sync.md` following the format below.
+      - Ask: "Would you like me to create this `sync.md`?"
+      - **Only create the file if the user approves.**
+
+## sync.md format
+
+The `sync.md` file lives at the project root. H2 sections are categories. Shell commands go in fenced code blocks; prose guidance goes in bullet points.
+
+```markdown
+# Post-Sync Actions
+
+## Dependencies
+
+```sh
+npm install
+```
+
+## Conflict Resolution
+
+- Always accept theirs for `package-lock.json`
+
+## Custom
+
+```sh
+npm run codegen
+```
+
+## Notifications
+
+- `.env.example` — check for new environment variables
+- `CLAUDE.md` — review if project conventions were updated
+```
+
+## Constraints
+
+- Do not force-push or rewrite history.
+- Do not auto-resolve merge conflicts — report them and let the user decide. However, if `sync.md` has a Conflict Resolution section, follow its guidance for the specific files/patterns it covers.
+- If stash pop fails due to conflicts, leave the stash intact and report it.
+- Post-sync commands from `sync.md` run in the project root directory.
+- If any post-sync command fails, report the error and continue with remaining actions.
+- Never auto-create `sync.md` without explicit user approval.
+- Do not execute commented-out sections (`<!-- ... -->`).
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.