agentsys: Instructions file for Codex

AgentSys

Marketplace, installer and shared library for the agent-sh plugins. Works on Claude Code, OpenCode, Codex CLI, Cursor and Kiro. Plugins live in their own repos in the agent-sh GitHub org and are pinned by commit in .claude-plugin/marketplace.json; this repo holds the installer (bin/cli.js), the dev CLI (bin/dev-cli.js), lib/ (maintained here; plugin repos vendor their own copies), adapters, docs, checklists and the site.

Critical Rules

1. This is a production project with real users: a breaking change reaches every plugin user at once. A feature or fix ships with tests for the changed behavior, edge cases included, and keeps the docs accurate.
2. Optimize for developers using the plugins in their own repos, not for internal convenience here.
3. Record finished work in CHANGELOG.md and the reply. Summary, audit or completion files (*_AUDIT.md, *_SUMMARY.md, *_COMPLETION.md) clutter the repo, so leave them out.
4. Every change reaches main through a PR, whatever its size, including a one-line fix or an urgent hotfix. Never push to main directly. Keep the branch short-lived and rebase it on main before you open the PR. PRs give review, CI and an easy rollback.
5. Self-review every PR: a fresh-context subagent reviews the diff and posts its review as a PR comment. Address every comment from revuto (the revuto-review check) and every CI failure: fix it, or reply with why not. Merge through the PR once CI is green. When revuto is capped or down, do not wait and do not re-trigger it: the self-review is enough, and the PR body says so. Review bots are not waited on beyond the PR's CI.
6. Before a multi-file change, read the checklist that applies; multi-file changes have hidden dependencies:
   • Cross-platform work: checklists/cross-platform-compatibility.md (the master reference)
   • Release: checklists/release.md
   • New command, agent, skill or lib module: checklists/new-command.md, checklists/new-agent.md, checklists/new-skill.md, checklists/new-lib-module.md
   • OpenCode plugin update: checklists/update-opencode-plugin.md
   • lib/repo-intel changes: checklists/repo-intel.md
7. Work is done when every item of that checklist is done. That includes linting new or changed commands, agents, skills, hooks or prompts with agnix (npx agnix <path>), checking OpenCode and Codex compatibility, and updating the bin/cli.js mappings for a new command or agent. The pre-push hook runs agnix on the changed agent configs and blocks the push on an error.
8. Status output uses the plain-text markers [OK], [ERROR], [WARN], [CRITICAL] and markdown, with no emojis or ASCII-art boxes: they cost tokens and parse worse.
9. gh and git on Windows: escape $ as \$ in GraphQL queries, avoid != in jq (use == "A" or == "B"), and prefer double quotes with escaped inner quotes over single quotes. gh pr checks reports state (SUCCESS, FAILURE, PENDING), not conclusion. The Windows shell treats $ and ! differently and these fail silently.
10. Run the pre-commit and pre-push hooks; when one blocks, fix the reported cause and retry.
11. Fix every failing test you meet, including ones that look out of scope. A green run has to mean everything works.
12. Report script failures before manual fallback. When a project script fails (npm test, npm run ..., scripts/*, agentsys-dev, node bin/dev-cli.js), report the exact error, find the cause and fix the script. NEVER silently fall back to doing its work by hand: that hides broken tooling.