Skip to content

Latest commit

 

History

History
298 lines (242 loc) · 13.6 KB

MAINTAINERS.md

File metadata and controls

298 lines (242 loc) · 13.6 KB

Codex-Kit Maintainer Guide

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.

Visibility boundary

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.

Development setup

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 typecheck

The compiler must report 7.0.1-rc. Open the repository root in the editor so it discovers tsconfig.json.

Repository setup

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.

Initial npm publication

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-checks

The initial publication of this package is already complete. Do not repeat this step for normal releases.

Configure Trusted Publishing

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.

Publish a release

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:check

Inspect the dry-run contents. They should contain only:

  • assets/agents/*.toml
  • assets/skills/codex-kit-audit-agents/**
  • assets/skills/codex-kit-reconcile-agents/**
  • assets/SUBAGENT_ROUTING.md
  • assets/TEMPLATE_AGENTS.md
  • bin/codex-kit.js
  • bin/routing-hook.js
  • LICENSE
  • package.json
  • README.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 main

The 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.

Promote a reusable guideline

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:

  1. Add any immediately needed project-specific wording to that project's AGENTS.md.
  2. Generalize the rule in the project's TEMPLATE_AGENTS.md, removing local paths, commands, integrations, and exceptions.
  3. Merge only that generalized change into the root TEMPLATE_AGENTS.md here; the build copies it into assets/TEMPLATE_AGENTS.md.
  4. Run the full verification commands and publish a new package version.
  5. Run project sync in downstream projects.
  6. Ask Codex to reconcile each AGENTS.md and applicable project skills under .agents/skills, review the result, then run project mark-applied.

A guideline is template-worthy only when it applies across future projects regardless of their exact stack or file layout.

Update devices and downstream projects

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 install

Refresh each project's template reference:

pnpm dlx @iamdevlinph/codex-kit@latest project sync --cwd /path/to/project

project 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.

Verification

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

References