Instructions for developing and publishing the public @iamdevlinph/codex-kit
npm package. User-facing commands belong in README.md; do not put repository
administration or publishing credentials there.
The GitHub repository and npm package are public. Everything listed by
pnpm run pack:check is publicly downloadable.
npm always includes the root LICENSE, README.md, package.json, and
executable named by bin, regardless of the files allowlist.
MAINTAINERS.md, source, tests, and repository instructions must remain outside
that allowlist. The entire repository is covered by ISC.
The repository URL is visible in npm metadata because Trusted Publishing
requires package.json#repository.url to match the GitHub repository exactly.
npm may generate provenance attestations when the publishing workflow requests
them and GitHub supports them.
The repository uses Node.js 24 for maintainer tooling and tests while preserving
Node.js 20 compatibility for the published CLI. It pins pnpm 11.5.2,
TypeScript 7.0.1-rc, esbuild 0.28.1, and Node.js 20 type definitions. The
generated, untracked bin/ contains only the self-contained, unminified
codex-kit.js and routing-hook.js bundles. The root TEMPLATE_AGENTS.md is
the canonical template source; every build copies it to the published
assets/TEMPLATE_AGENTS.md path.
corepack enable
pnpm install --frozen-lockfile
pnpm exec tsc --version
pnpm run typecheckThe compiler must report 7.0.1-rc. Open the repository root in the editor so
it discovers tsconfig.json.
Use the public GitHub repository named iamdevlinph/codex-kit. Keep the npm
package name and GitHub namespace lowercase.
All repository files are licensed under ISC. Keep the root LICENSE and
package metadata synchronized.
The package must exist before npm can attach a Trusted Publisher. For a new package, publish the initial version once from an authenticated device:
npm login --auth-type=web
pnpm run typecheck
pnpm test
pnpm run pack:check
pnpm publish --access public --no-git-checksThe initial publication of this package is already complete. Do not repeat this step for normal releases.
Open the package on npmjs.com and configure Settings → Trusted Publisher:
| Field | Value |
|---|---|
| Provider | GitHub Actions |
| Organization or user | iamdevlinph |
| Repository | codex-kit |
| Workflow filename | publish.yml |
| Environment | Leave blank |
| Allowed action | npm publish |
Enter only publish.yml, not .github/workflows/publish.yml.
No publishing token or repository secret is required. Trusted Publishing uses
short-lived OIDC credentials. Do not add NPM_TOKEN, NODE_AUTH_TOKEN, or a
package PAT.
The workflow requires a GitHub-hosted runner, id-token: write, Node 22.14 or
newer, and npm 11.5.1 or newer. The current workflow uses Node 24 and npm 11.5.1.
Prepare the version and latest-only release notes with the repository-local
codex-kit-release skill, then validate:
node .agents/skills/codex-kit-release/release.mjs bump patch # or minor/major
pnpm run typecheck
pnpm test
pnpm run pack:checkInspect the dry-run contents. They should contain only:
assets/agents/*.tomlassets/skills/codex-kit-audit-agents/**assets/skills/codex-kit-reconcile-agents/**assets/SUBAGENT_ROUTING.mdassets/TEMPLATE_AGENTS.mdbin/codex-kit.jsbin/routing-hook.jsLICENSEpackage.jsonREADME.md
MAINTAINERS.md, AGENTS.md, RELEASE_NOTES.md, the repository-local
codex-kit-release skill, src/, tests, lockfiles, generated test output,
credentials, and local backups must not appear.
After reviewing the prepared version and notes, explicitly authorize and push
the release commit to main:
git add package.json RELEASE_NOTES.md
git commit -m "v<version>"
git push origin mainThe workflow checks that the version is one SemVer increment from the previous
tag and latest-only RELEASE_NOTES.md is non-empty and changed. After all checks
pass, it creates the immutable matching tag, publishes npm, then creates or
updates the public GitHub Release from the complete notes file. A push whose
version tag belongs to an ancestor skips cleanly.
If a workflow fails because of external configuration and no source change is
needed, rerun the failed job. If the tag already targets the tested commit, the
workflow reuses it; if npm already contains the version, it continues with the
GitHub Release. A manual push of the matching v* tag remains the recovery path.
The workflow never moves an existing tag.
Choose the narrowest scope:
| Change | Source of truth | Propagation |
|---|---|---|
| Personal behavior for every repository | Global routing or agent assets | Run global install on each device |
| Reusable project convention | root TEMPLATE_AGENTS.md |
Build copies to assets/TEMPLATE_AGENTS.md; publish a version, then sync and reconcile projects |
| Project-specific command, integration, or exception | Project AGENTS.md |
Keep it only in that project |
Do not put the complete project template in global ~/.codex/AGENTS.md. Keep
the global file as a small personal baseline.
When a project reveals a reusable guideline:
- Add any immediately needed project-specific wording to that project's
AGENTS.md. - Generalize the rule in the project's
TEMPLATE_AGENTS.md, removing local paths, commands, integrations, and exceptions. - Merge only that generalized change into the root
TEMPLATE_AGENTS.mdhere; the build copies it intoassets/TEMPLATE_AGENTS.md. - Run the full verification commands and publish a new package version.
- Run
project syncin downstream projects. - Ask Codex to reconcile each
AGENTS.mdand applicable project skills under.agents/skills, review the result, then runproject mark-applied.
A guideline is template-worthy only when it applies across future projects regardless of their exact stack or file layout.
global install configures the top-level model, model_reasoning_effort, and
plan_mode_reasoning_effort keys with the defaults documented in README.md.
global configure manages these keys when overriding the defaults. Both
commands back up config.toml and store the original managed values in
installer state so
global uninstall can restore them without rolling back unrelated later edits.
Successful project init and project sync calls atomically register the
canonical project path under $CODEX_HOME/codex-kit/projects/. global projects reads those records and applies the same offline status evaluation as
project status; it does not query npm, scan for historical projects, or stop
when one registered path is unavailable. project register performs the same
canonical, idempotent registration for an existing directory without reading
or modifying project state or checking npm. global projects remove requires a
TTY and deletes only explicitly selected registry records, including records
whose paths are unavailable. Installer state does not own the registry, so
global install and uninstall preserve it.
Global routing keeps the Sol root as planner/orchestrator. The routing file maps
task shapes to exact agent roles; each role's TOML independently selects its
model and reasoning effort. In formal Plan mode, the read-only planner agent
uses Astra-low for substantive repository analysis and implementation planning;
Sol remains visible, integrates the findings, and owns approved-plan execution.
A UserPromptSubmit hook injects the current policy
on each turn, and SubagentStart briefs delegated workers. Balanced routing
allows the root to perform clear changes spanning roughly three files directly.
Automatic delegation is reserved for broad discovery, large implementation or
debugging work, and high-risk review. quick-implementer remains available for
manual use. Implementation children edit directly without recursively
delegating, and the root reuses their test evidence instead of repeating full
validation by default. Multiple implementers may run concurrently only for
genuinely independent slices with exclusive ownership and separate validation;
shared contracts, configuration, artifacts, migrations, or dependency ordering
require one implementer or sequential execution.
The default root uses Sol-low outside and inside Plan Mode. Automatic roles use Astra-low for formal Plan mode planning, Terra-medium for exploration, Luna-high for implementation, and Sol-high for review. Delegation permits one 60-second wait followed by one status request; role deadlines are three minutes for exploration, review, and manual quick work, and five minutes for implementation. Stop validation after two minutes without output unless project guidance documents a longer runtime. Never run matching parent and worker validation concurrently.
global install merges only codex-kit's handlers into ~/.codex/hooks.json and
preserves unrelated handlers. It also installs the package-owned reconciliation
and explicit-only audit skills under ~/.codex/skills; list reports each status,
and uninstall removes/restores them according to recorded ownership.
Keep routing generic and role-based rather than referring to a model in the
policy.
New or changed command hooks require Codex's normal one-time trust review and a
new task or client restart before testing them.
Refresh global assets once per device when agent or routing files change:
pnpm dlx @iamdevlinph/codex-kit@latest global installRefresh each project's template reference:
pnpm dlx @iamdevlinph/codex-kit@latest project sync --cwd /path/to/projectproject sync updates only TEMPLATE_AGENTS.md and project state. It never
edits AGENTS.md, PLANS.md, or .agents/skills; its printed reconciliation
prompt briefly asks Codex to invoke codex-kit-reconcile-agents; the skill owns
the semantic instruction-architecture audit. It classifies existing and incoming
guidance by task relevance, preserves local adaptations and critical always-on
rules, keeps AGENTS.md as the smallest safe always-loaded router, routes
conditional knowledge through selectively read references, and reserves skills
for repeatable procedures. It preserves or conditionally creates PLANS.md as a
durable index, routes substantial feature detail to evidence-backed feature
plans, validates semantic ownership and reference integrity, reports UTF-8 byte
measurements and unresolved ambiguity, and checks expected idempotence before
marking applied. The CLI itself continues to create only its current scaffold
and state files.
Before either project init or project sync writes, it must verify the
installed package against the latest npm metadata. Stale builds, registry
failures, and malformed metadata fail closed. Stale builds print installed and
latest versions plus the exact pnpm dlx @iamdevlinph/codex-kit@latest project <init|sync> --cwd <path> rerun command. The CLI never auto-installs or executes
downloaded code.
When AGENTS.md is missing, synchronization creates a minimal project scaffold;
it does not merge the reusable template automatically. Missing or untouched
scaffold instructions produce a delimited initialization prompt that first
requires enough repository evidence for reliable project-specific guidance.
Existing guidance produces a separately delimited reconciliation prompt for
AGENTS.md and TEMPLATE_AGENTS.md. Both prompts invoke the packaged
reconciliation skill without duplicating its procedure. Downstream users must upgrade codex-kit and
refresh the global installation before syncing to receive both the enhanced
skill and template.
project audit is separate from synchronization: the CLI validates only the
target directory, then prints a marked prompt invoking
$codex-kit-audit-agents. The skill audits instruction, skill, workflow, and
test scope, applies the same conservative instruction and planning optimization,
and preserves justified regression and costly-risk coverage. It must leave
template reconciliation state untouched. The CLI must not contact npm, inspect
project state, register the project, or write any file; Codex may edit guidance
only after the user runs the emitted prompt. Users may run it deliberately after
substantial instruction changes or on an optional biweekly/monthly cadence; it
is never an always-on workflow or a separate project optimize command.
The semantic fixtures under src/test-fixtures/context-optimization/ encode
acceptable ownership, preservation, reference, routing, and no-op outcomes.
Their Vitest coverage proves fixture integrity, not model semantic equivalence.
For behavioral forward-evaluation, copy each fixture's before directory to a
temporary repository and run the applicable installed skill in a fresh Codex
session. Repeat the run to check for churn, then exercise README-only, UI,
database, payment-with-authentication-dependency, authentication/security,
release, unrelated-tooling, and combined UI/API requests. Inspect actual
file-read traces when available and record root-chain and selected-context byte
counts; label static routing checks when trace evidence is unavailable rather
than relying on self-reported reads.
pnpm install --frozen-lockfile
pnpm run typecheck
pnpm test
pnpm run pack:check