| name | sync |
| description | Explicit user-invoked sync, install, update, or repair for Promode for Codex project files. Use only when the user invokes `$promode-codex:sync` or explicitly asks the main agent to sync Promode project files. |
Make the current project ready for Promode for Codex by syncing the bundled
Promode custom-agent templates into project `.codex/agents/`, syncing the
Promode doctrine bundle into `.codex/promode/docs/`, and removing legacy
hook-based Promode artifacts. After a successful sync, perform a best-effort
GitHub check and warn if this plugin copy is older than the latest available
Promode for Codex version.
<required_reading>
Read before acting:
../../standard/docs/codex-assumptions.md- All files in
../../standard/agents/
../../standard/docs/index.md../../standard/docs/opinion-register.md
</required_reading>
1. Verify the target project with `pwd` and `git status --short`.
2. Run the bundled sync helper:
```bash
python3 {plugin_root}/scripts/install-project-agents.py {project_path}
```
Use `--skip-upgrade-check` only for offline or deterministic validation
runs.
3. Preserve non-Promode files under `.codex/agents/` and `.codex/hooks.json`.
Treat `.codex/agents/promode_*.toml` and `.codex/promode/docs/` as
Promode-owned generated mirrors.
4. Do not edit `AGENTS.md` unless the user explicitly asks.
5. Do not install Promode main-session hooks. Promode is activated explicitly
with `$promode-codex:activate` in each session.
6. If the helper warns that a newer plugin is available, tell the user to run
`codex plugin marketplace upgrade promode-codex`, then start a new task or
session. If the updated plugin is not visible, restart Codex.
7. Verify all eleven `.codex/agents/promode_*.toml` files exist and that
`.codex/promode/docs/opinion-register.md` exists.
8. Tell the user to start a new task or session so project custom-agent roles
are discovered. If the roles do not appear, restart Codex. Then run
`$promode-codex:activate` in sessions where they want Promode behavior.
<success_criteria>
The project has the eleven Promode custom-agent files under .codex/agents/,
the Promode doctrine bundle under .codex/promode/docs/, legacy Promode hook
artifacts are absent, non-Promode project files were preserved, stale plugin
cache warnings are surfaced when detected, and the user knows the new-session,
restart-if-needed, and activation sequence.
</success_criteria>
