# Update

> Update Git Workflow skills and Claude/Codex project agents from a source checkout or installed plugin, with dry-run, pruning, customization detection, and legacy migration support. Use when the user asks to update, refresh, or synchronize Git Workflow.

- Skill: `rlajous/update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rlajous/update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rlajous/update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: rlajous (https://skillmd.com/u/rlajous)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rlajous/update

---


# Update Git Workflow

Follow [runtime compatibility](../../references/runtime-compatibility.md). Claude Code users invoke this as `/update`; Codex users invoke it as `$update`.

## 1. Parse options

- `--dry-run`: calculate and display changes without writing.
- `--prune`: include previously managed files that no longer exist in the source as removal candidates.
- `--force`: overwrite customized managed files after still showing their diffs.
- `--host <claude|codex|both>`: synchronize only the selected host assets; otherwise infer installed hosts and ask if ambiguous.
- `--source <path-or-git-url>`: use an explicit Git Workflow checkout, plugin directory, or Git URL.

Unknown options are errors. Destructive pruning is never implied by `--force` alone.

## 2. Resolve project and source

Resolve the project root from Git, then accept either `.git-workflow/`, `.claude/`, or `.codex/` as evidence of an existing installation. Resolve the source in this order:

1. `--source`
2. `{PACKAGE_ROOT}`, derived from the absolute physical directory containing this loaded
   `SKILL.md` as `{SKILL_DIR}/../..`, when it contains `.codex-plugin/plugin.json`
3. `PLUGIN_ROOT`, then `CLAUDE_PLUGIN_ROOT`, as compatibility fallbacks only when the host cannot
   expose the loaded skill path; verify the manifest before accepting either value
4. `source` recorded in `.git-workflow/version.json`

Never substitute an empty package variable or silently fall back to `/scripts`. If no complete
source resolves, stop before writing and report every candidate checked.

For an explicit Git URL, clone it shallowly into a newly created temporary directory, validate it, and remove the temporary clone on success or failure. Do not perform a default network clone when an installed package root or ledger source is available. Validate that the source contains `skills/`, `agents/`, `.codex/agents/`, and a valid `.codex-plugin/plugin.json`. Stop without writing if it is incomplete.

## 3. Build the synchronization set

Use the synchronizer bundled with `setup`, resolved relative to this skill as
`{SKILL_DIR}/../setup/scripts/sync-project.mjs`, to calculate and apply this set. Always run it
first with `--dry-run`; after the user reviews changes, rerun without `--dry-run`. Add `--force`
only when changed files were approved, and add `--confirm-prune` only after separate confirmation
of listed prune candidates.

```bash
node "{SKILL_DIR}/../setup/scripts/sync-project.mjs" --source <source> --target <project> --host <codex|claude|both> --dry-run
```

Synchronize only components relevant to the installation:

| Source | Target | When |
|---|---|---|
| `skills/*/` | `.claude/skills/*/` | Manual Claude installation |
| `agents/*.md` | `.claude/agents/*.md` | Manual Claude installation |
| `references/*.md` | `.claude/references/*.md` | Manual Claude installation |
| `.codex/agents/*.toml` | `.codex/agents/*.toml` | Codex project agents |

Codex plugin skills are updated by the plugin manager and must not be copied into `.codex/skills/` by this workflow.

For every target, classify it as missing (`+`), changed (`~`), identical (`=`), or orphaned (`?`). Show a unified diff for changed text files.

## 4. Protect customizations

- Without `--force`, ask once before overwriting the listed changed files. A rejection preserves all changed files while still allowing missing files to install.
- With `--force`, overwrite changed managed files only after showing the summary.
- `--prune` may remove only paths recorded as managed in the version ledger. Never remove an untracked local skill or agent merely because the source lacks the same name.
- Show prune candidates and require explicit confirmation even with `--force`.
- `--dry-run` performs no writes, removals, directory creation, or ledger updates.

Use atomic per-file replacement where practical. A failure must not truncate the previous target.

## 5. Migrate and record state

If `.git-workflow/config.yaml` is absent and `.claude/config.yaml` exists, offer the same non-destructive copy used by `$setup`; do not make migration a prerequisite for updating agents.

After a successful non-dry-run update, the synchronizer rewrites `.git-workflow/version.json` with version `2.5.2`, the resolved source, timestamp, hosts, and the exact relative paths managed by this run. Preserve the user's workflow configuration, local hook opt-in, PR context, status report, and reviewed-SHA ledger.

## Output

Report installed, updated, unchanged, preserved, pruned, and failed files separately. If any item fails, return a non-success summary with the exact recovery command. Otherwise suggest `/status` for Claude Code or `$status` for Codex.