Use this repo as the source for reusable agent assets, and use chezmoi for selected machine-level pointers and non-secret local config. Do not put live runtime state, credentials, histories, caches, logs, or SQLite state into either this repo or public skill installs.
| Layer | Owner | Examples | Sync method |
|---|---|---|---|
| Reusable agent assets | agent-scripts |
skills/, bin/, docs, validation scripts, optional hooks |
Git commit and push |
| Repo-managed Codex plugins | agent-scripts |
plugins/, .agents/plugins/marketplace.json |
Remote-backed repo marketplace install and reinstall |
| Published skill installs | bunx skills from the GitHub skills/ subpath |
Selected Claude Code, Pi, Codex skill copies | Re-run explicit install commands |
| Machine pointers | chezmoi or harness-specific setup | symlinks or scripts that point tools at this repo | Chezmoi source repo or explicit local setup |
| Stable personal defaults | chezmoi, with care | selected model, reasoning effort, sandbox default | Template or idempotent update script |
| Runtime state | local machine only | auth, sessions, logs, caches, memories, SQLite files | Do not sync |
Do not treat a dated machine snapshot as configuration authority. Inspect the current host before applying chezmoi or changing a pointer:
chezmoi source-path
chezmoi status
readlink ~/.codex/AGENTS.md
readlink ~/.claude/CLAUDE.md
readlink ~/.pi/agent/AGENTS.mdThe intended instruction targets are the three files under this repository's
global-agent-instructions/ directory. Chezmoi may own a pointer, but it must
not own the live harness runtime directory that contains it.
Do not manage the entire live ~/.codex directory. It contains mutable runtime
files such as auth, history, logs, goals, memories, model caches, plugin state,
and SQLite databases.
For ~/.codex/config.toml, avoid blindly replacing the file because Codex also
writes plugin, marketplace, trust, and UI state there. The safe path is:
- Keep an audited list of desired stable keys.
- Apply those keys with a small idempotent chezmoi script or a carefully reviewed template.
- Preserve Codex-managed sections unless intentionally resetting the machine.
Stable candidates:
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"Machine-local or Codex-managed sections to preserve:
[projects.*]trust entries.[marketplaces.*]local cache paths.[plugins.*]installed plugin state.- UI onboarding and keymap state unless intentionally standardized.
Keep local Codex plugin source in this repo under plugins/<plugin-name>/.
Keep the repo marketplace at .agents/plugins/marketplace.json; it is
repository metadata, not machine runtime state.
The marketplace currently publishes two independent plugins:
chezmoi-syncchecks and reviews chezmoi drift from Codex.codex-pushover-notifysends turn-completion notifications and exposes Pushover MCP tools. Its credentials remain machine-local; setup and checks are documented inplugins/codex-pushover-notify/README.md.
For chezmoi-sync:
plugins/chezmoi-sync/hooks/hooks.jsonregisters aSessionStarthook.plugins/chezmoi-sync/scripts/chezmoi-check.shis read-only and exits zero; it reports only.plugins/chezmoi-sync/scripts/chezmoi-review.shis the explicit review helper for status and optional diff/fetch.
The installed startup hook currently resolves its script only at
$HOME/IT/agent-scripts/plugins/chezmoi-sync/scripts/chezmoi-check.sh. That
checkout and executable script must exist, bash must be available, and
chezmoi must be on the hook's PATH. Otherwise the hook exits without a
report. A machine using another checkout location must run the review helper
directly until the hook implementation supports a configurable path.
The plugin intentionally does not bundle Codex skills. Keep mutating actions
explicit: review chezmoi-review.sh --diff, choose chezmoi add,
chezmoi apply, or chezmoi update, then re-run the review.
Install or verify the repo marketplace on this machine from the remote, then install the plugins that machine should use:
codex plugin marketplace add https://github.com/sjunepark/agent-scripts.git --ref main
codex plugin add chezmoi-sync@personal
codex plugin add codex-pushover-notify@personal
codex plugin list --marketplace personal --jsonDo not leave this repo's marketplace pointed at /Users/sejunpark/IT/agent-scripts
or another local working tree for normal machine use. Local marketplace paths
are only for temporary development testing.
After editing plugin metadata, hooks, scripts, or MCP configuration for ongoing
use, update that plugin's cachebuster, validate it, commit and push first, then
refresh the remote-backed marketplace snapshot and reinstall the affected
plugin. For example, for chezmoi-sync:
python3 ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
/Users/sejunpark/IT/agent-scripts/plugins/chezmoi-sync
git add plugins/chezmoi-sync
git commit -m "Update chezmoi sync plugin"
git push origin main
codex plugin marketplace upgrade personal
codex plugin add chezmoi-sync@personalRun the plugin validation before committing any plugin change. Script-only edits still need the commit, push, marketplace upgrade, and affected-plugin reinstall flow before they affect remote-backed installs.
Do not manage ~/.codex/plugins/cache, plugin trust records, or installed
plugin state through chezmoi. Recreate those with codex plugin marketplace add, codex plugin add, /plugins, and /hooks on each machine.
Machine-specific lifecycle repairs use the standalone hook module in
codex-hooks/ instead of a plugin. This repository owns the canonical manifest
and scripts; bin/install-codex-hooks copies the scripts and merges the owned
registrations into ~/.codex without replacing unrelated hooks. Codex remains
the owner of hook trust state. The repair boundaries and upstream removal tests
are in
codex-lifecycle-workarounds.md.
Keep ~/.agents/skills as a generated user-scope skill install location, not
as a chezmoi-managed directory. Codex discovers user skills there, and other
harnesses may also report skills from that shared location. It also holds
external/manual skills classified in skill-registry.json, so do not replace
it with a symlink to this repo.
Treat this repo's skills/ directory as the published catalog. A skill being
published here means it can be installed from the GitHub skills/ subpath; it
does not mean it belongs in every global agent install. Use
skill-registry.json for the authoritative scope, provenance, installation
targets, and installation manager. Select project profiles or direct
declarations in the project's committed sjskills.toml; catalog publication
or registry membership alone does not install a skill.
Run bin/sjskills plan --global from this repo to inspect exact managed-root
state against the one fixed baseline. sjskills, not chezmoi, owns
reconciliation. Machine profiles and host inference are retired; manual and
workflow entries remain with their recorded manager.
The delegate-ui-to-claude orchestration skill is intentionally installed only
for Codex. Impeccable is not a machine-global prerequisite: when the skill
delegates work in a UI repository, it provisions Claude's project-scoped copy
with npx --yes impeccable@latest install -y --providers=claude --scope=project
if needed and refreshes an existing copy with the matching update command.
Using @latest is intentional: delegation should use the current published
Impeccable workflow rather than a pinned or long-lived local CLI.
The intended harness exposure stays under .claude/, including the Impeccable
skill tree and Claude hook settings. Codex-facing copies such as
.agents/skills/impeccable, user-level Impeccable skills under ~/.agents or
~/.codex, and Impeccable entries in .codex/hooks.json are conflicts; the
skill reports them and asks the user to remove them rather than deleting them
automatically. Shared hook files should retain their unrelated entries.
Greenfield work, redesigns, missing product context, and other consequential
design choices use resumable approval phases. Claude returns questions or
options to Codex, Codex relays them to the user, and implementation resumes in
the same Claude session after approval. Claude remains read-only during these
phases; Codex may persist an approved PM-owned contract such as PRODUCT.md
when Impeccable needs it to derive the next options. Scoped work that inherits
an established product and visual world can use a one-shot run; so can work
for which the user explicitly authorizes unattended design decisions.
Do not reproduce the reconciler's placement work in chezmoi. It maps the
registry's .agents target to ~/.agents/skills and .claude to
~/.claude/skills, and creates no Pi-specific copy. Read-only inspection is:
bin/sjskills plan --globalGlobal apply uses trusted provenance only; it does not adopt or replace a
preexisting desired-path tree merely because the bytes happen to match.
Verified global updates preserve prior content in manifest-backed quarantine
under ~/.agents/.sjskills-global/. Former-profile and other non-baseline
placements remain report-only in v1. Restore uses the reported identifier and
refuses to overwrite:
bin/sjskills restore --global <quarantine-id>Do not put bin/sjskills apply --global or global restore into chezmoi bootstrap.
Those real-home mutations require a separate reviewed, evidence-bound rollout
plan and explicit authorization. Chezmoi may run the read-only global plan
after this repo is cloned, but it must not own or copy the generated skill
roots. scripts/audit-global-skills is only a read-only transition wrapper
for that plan; its former profile and mutation arguments are retired.
Keep repo-maintenance rules in this repository's root AGENTS.md. Keep global
personal defaults in separate harness-specific files even when most guidance
is shared, so tool-specific behavior does not leak between agents. Point each
harness at its file:
~/.codex/AGENTS.md -> /Users/sejunpark/IT/agent-scripts/global-agent-instructions/global-codex.md
~/.claude/CLAUDE.md -> /Users/sejunpark/IT/agent-scripts/global-agent-instructions/global-claude.md
~/.pi/agent/AGENTS.md -> /Users/sejunpark/IT/agent-scripts/global-agent-instructions/global-pi.md
These files should contain durable personal defaults only. Keep multi-step procedures in skills and route to them with a concise harness-specific rule. Do not mix personal defaults with this repo's maintenance-specific rules. Pointer ownership may vary by machine; use the inspection commands above to identify whether chezmoi or explicit local setup owns each one before editing.
- Install Codex, Claude Code, Pi, Node.js, Bun, Git, chezmoi, and the 1Password CLI.
- Apply chezmoi only after resolving any pending managed-file diffs.
- Clone or update this repo.
- Provision
op-agentusing the 1Password host setup. - Run
scripts/validate-skills. - Register the remote-backed repo Codex marketplace and install the desired
repo plugins. Configure Pushover credentials locally if installing
codex-pushover-notify. - Run
bin/sjskills plan --globalto inspect managed-root state without changing it. Use the separate rollout plan for any explicitly authorized global mutation. - Apply or verify Codex stable config keys.
- Re-authenticate other tools locally; do not copy auth files from another machine.