@iamdevlinph/codex-kit 1.0.1

package/README.md

@@ -0,0 +1,178 @@
+# `@iamdevlinph/codex-kit`
+
+Portable Codex setup for new devices and multiple projects. It provides:
+
+- four custom subagents: explorer, quick implementer, implementer, and reviewer
+- global subagent-routing guidance without a `commit-pusher`
+- a reusable, stack-neutral `AGENTS.md` template
+- safe commands for global setup, project synchronization, and reconciliation
+
+The package contains no credentials. Global installation does not modify the
+Codex model configuration; configuration is a separate, explicit command.
+
+## Install on a device
+
+No npm or GitHub login is required:
+
+```sh
+pnpm dlx @iamdevlinph/codex-kit@latest global install
+pnpm dlx @iamdevlinph/codex-kit@latest global configure
+```
+
+`global install` copies reusable agents to `${CODEX_HOME:-~/.codex}` and
+maintains a marked routing section in the global `AGENTS.md`.
+
+`global configure` sets these defaults while preserving unrelated settings:
+
+```toml
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
+```
+
+Use a different Codex home when needed:
+
+```sh
+pnpm dlx @iamdevlinph/codex-kit@latest global install \
+  --codex-home /path/to/.codex
+pnpm dlx @iamdevlinph/codex-kit@latest global configure \
+  --codex-home /path/to/.codex
+```
+
+Inspect the installed setup:
+
+```sh
+pnpm dlx @iamdevlinph/codex-kit@latest global list
+```
+
+The summary shows the Codex home, orchestrator, reasoning effort, routing
+status, and installed custom agents without dumping unrelated configuration.
+
+Uninstall package-managed global files:
+
+```sh
+pnpm dlx @iamdevlinph/codex-kit@latest global uninstall
+```
+
+Modified managed files are preserved unless `--force` is supplied. An existing
+unmanaged `commit-pusher.toml` is reported but never silently deleted.
+
+## Commands
+
+| Action | Command |
+| --- | --- |
+| Install global agents and routing | `codex-kit global install` |
+| Configure the orchestrator | `codex-kit global configure` |
+| Inspect global configuration | `codex-kit global list` |
+| Remove package-managed global files | `codex-kit global uninstall` |
+| Initialize project guidance | `codex-kit project init` |
+| Refresh the project template reference | `codex-kit project sync` |
+| Check template reconciliation | `codex-kit project status` |
+| Record completed reconciliation | `codex-kit project mark-applied` |
+| Check for a package update | `codex-kit version check` |
+
+## Apply to a project
+
+For a project without `AGENTS.md`:
+
+```sh
+cd /path/to/project
+pnpm dlx @iamdevlinph/codex-kit@latest project init
+```
+
+This creates:
+
+- `AGENTS.md`, containing the reusable defaults and a project-specific section
+- `TEMPLATE_AGENTS.md`, a local reference copy used for future comparisons
+- `.codex-kit-state.json`, reconciliation bookkeeping
+
+The template reference is not an active Codex instruction file. Add repository
+commands, paths, architecture, integrations, and exceptions to the
+project-specific section of `AGENTS.md`.
+
+### Generate project-specific guidance
+
+For an existing project, use this prompt after initialization. For a new
+project, scaffold the initial stack first.
+
+```txt
+Explore this repository before changing code. Identify its languages,
+frameworks, package manager, scripts, directory structure, styling and component
+systems, form and validation libraries, data-access patterns, testing tools, and
+generated files.
+
+Update only the project-specific section of AGENTS.md with concise guidelines
+derived from the repository's actual dependencies, configuration, scripts, and
+established code patterns. Include exact verification commands. Preserve the
+managed shared-template block, avoid speculative preferences, and do not add
+rules for tools the repository does not use.
+```
+
+## Synchronize template updates
+
+Refresh a project's local template reference:
+
+```sh
+pnpm dlx @iamdevlinph/codex-kit@latest project sync
+codex-kit project status
+```
+
+`project sync` never edits `AGENTS.md`. It prints a prompt asking Codex to merge
+only applicable reusable changes while preserving local adaptations. After
+reviewing the semantic merge, record the applied template hash:
+
+```sh
+codex-kit project mark-applied
+```
+
+`mark-applied` updates only `.codex-kit-state.json`; it does not validate or
+modify `AGENTS.md`.
+
+If `TEMPLATE_AGENTS.md` was modified locally, synchronization preserves it and
+asks for review instead of overwriting it. Use `--force` only after intentionally
+discarding the local candidate changes.
+
+### Synchronize multiple projects
+
+Install the CLI once and keep a local path list:
+
+```sh
+pnpm add --global @iamdevlinph/codex-kit
+
+while IFS= read -r repo; do
+  [ -n "$repo" ] && codex-kit project sync --cwd "$repo"
+done < ~/.config/codex-kit/projects.txt
+```
+
+Update global agents and routing separately when those assets change:
+
+```sh
+pnpm add --global @iamdevlinph/codex-kit@latest
+codex-kit global install
+```
+
+## Check for a new version
+
+```sh
+codex-kit version check
+```
+
+The command queries the public npm registry only when requested. Normal project
+commands do not add network latency or depend on registry availability.
+
+## Requirements
+
+- Node.js 20 or newer
+- Codex with custom subagent support
+
+The published package has no runtime dependencies and uses only Node.js
+standard-library modules.
+
+## License
+
+`UNLICENSED`. Public availability on npm does not grant permission to reuse or
+redistribute the package beyond applicable law and npm's service terms.
+
+## References
+
+- [Codex custom subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
+- [Codex `AGENTS.md` discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md)

package/assets/SUBAGENT_ROUTING.md

@@ -0,0 +1,36 @@
+# Subagent Routing
+
+Keep focused, tightly coupled work in the parent task. Delegate only bounded,
+independent work when it materially reduces parent-context growth, latency, or
+cost. The user does not need to request subagents explicitly.
+
+The parent owns requirements, architecture, integration, and final validation.
+Never delegate the overall objective. Avoid parallel write-heavy work and never
+assign overlapping files to multiple agents.
+
+Do not delegate trivial conversation, known-target edits limited to one or two
+files, or straightforward commands. A slow command alone is not a reason to
+delegate.
+
+When delegation is worthwhile:
+
+- Prefer one subagent. Add more only for independent, non-overlapping work.
+- Give each agent a bounded task and request a concise, decision-ready report.
+- For parallel implementation, assign explicit file or module ownership.
+- Wait for relevant agents and synthesize their results in the parent task.
+- Reuse prior exploration and evidence instead of repeating it.
+
+Select custom agents by exact name:
+
+- Broad repository discovery or contract tracing: `code-explorer`
+- Mechanical, well-specified one- or two-file change: `quick-implementer`
+- Multi-file behavior change, debugging, or substantial tests: `implementer`
+- Independent review of high-risk or difficult-to-validate changes: `code-reviewer`
+
+Use either `quick-implementer` or `implementer` for a change, not both. Use the
+lowest reasoning effort that reliably fits the work. Do not substitute a generic
+agent when a matching custom role is available.
+
+There is no commit-pusher role. Never delegate Git publishing. Do not stage,
+commit, or push unless the user explicitly requests that operation in the current
+task; if requested, the parent handles it after review.

package/assets/TEMPLATE_AGENTS.md

@@ -0,0 +1,143 @@
+# Shared Agent Defaults
+
+Reusable defaults for coding agents. Adapt stack details, commands, paths,
+product context, and local conventions in the project-specific section outside
+the managed markers.
+
+## Context And Instruction Scope
+
+- Follow the repository's existing style, structure, architecture, and stronger
+  local instructions. Keep product and business decisions aligned with
+  `PLANS.md` when it exists.
+- Use `PLANS.md` for durable product context, business rules, sequencing,
+  priorities, deferred requirements, product or implementation decisions, and
+  major completed milestones.
+
+## Template Maintenance
+
+- Projects normally use `AGENTS.md` as the active instruction file. The source
+  template is `assets/TEMPLATE_AGENTS.md` in the private `codex-kit` repository
+  and public package.
+- A project-local `TEMPLATE_AGENTS.md` is an optional temporary sync/reference
+  copy, not an active file or automatic update path. Updating `AGENTS.md` does
+  not update either template, and an updated `AGENTS.md` need not be copied back
+  to its local reference.
+- Keep project-specific context outside the managed `AGENTS.md` block; keep only
+  reusable cross-project rules in the packaged template.
+- When a request introduces a reusable workflow preference, convention, agent
+  behavior, tooling default, or safety rule, tell the user it appears
+  template-level and update the current project's active instructions when
+  appropriate.
+- After a likely template-level project change, remind the user to update the
+  packaged template, publish a version, and sync affected projects. Specify:
+
+  - the target section and whether to add a bullet, subsection, or section
+  - whether it replaces an existing rule or adds one
+  - exact reusable wording or a concise patch
+  - for replacements, the old and new behavior
+  - for additions, why the rule applies across projects
+
+- Merge template updates into other projects without overwriting project-specific
+  context.
+
+## Template Sync Prompt
+
+When `codex-kit project sync` stages `TEMPLATE_AGENTS.md` beside an existing
+unmanaged `AGENTS.md`, use this prompt:
+
+```txt
+Convert this repository to the codex-kit managed AGENTS.md layout. Put the exact
+contents of TEMPLATE_AGENTS.md between
+<!-- BEGIN codex-kit:shared-template --> and
+<!-- END codex-kit:shared-template -->. Preserve every repository-specific
+instruction from the current AGENTS.md after the managed block under
+# Project-Specific Instructions, remove only duplicate shared rules, and do not
+change project behavior. Afterward, summarize what was preserved and whether any
+local rules appear template-worthy.
+```
+
+## Core Behavior
+
+- Match nearby code before introducing patterns, abstractions, dependencies, or
+  file organization. Consistency outranks personal preference and generic
+  best-practice refactors.
+- Keep changes minimal, localized, and limited to the request. Do not reorganize
+  major modules, refactor core systems, add frameworks, or change architecture
+  or project paradigms without explicit approval.
+- Work within imperfect architecture. If it prevents safe completion, stop,
+  explain the limitation, propose the smallest viable design change, and wait
+  for approval. Escalate blockers instead of bypassing them.
+- Reuse existing constants, schemas, enums, shared types, and components before
+  creating duplicates. Add reusable domain values at their existing source of
+  truth instead of scattering magic strings.
+
+## Project Discovery
+
+- Before changing code, inspect manifests, configuration, scripts, and nearby
+  files to identify the repository's actual stack, commands, and conventions.
+  Do not assume tools from other projects.
+- Keep discovered stack-specific guidance in the project's
+  `# Project-Specific Instructions`, not in this shared template.
+
+## Commands And Verification
+
+- Avoid broad commands. After changes, run the smallest targeted verification
+  that meaningfully validates them when practical, then report the command and
+  result. Use the repository's documented package manager and scripts.
+- Do not change dependencies, global tools, or the environment by default.
+- Do not run local or remote database inspection, generation, migration, or SQL
+  commands unless the task requires them.
+
+## Structure
+
+- Follow the repository's organization and naming. Prefer focused files and
+  split mixed responsibilities when readability improves.
+- Do not reorganize feature directories, shared modules, routes, server
+  boundaries, schemas, or state patterns unless requested and approved.
+
+## Data And Validation
+
+- Update schemas first, then generate migrations or derived types. Never edit
+  generated migration snapshots manually unless requested.
+- Validate form and server inputs explicitly. After successful mutations,
+  invalidate or refresh relevant cached data when applicable.
+
+## Planning
+
+- Read `PLANS.md` before product-facing work. Implement only the requested
+  feature, not the whole plan.
+- Record requirement, product, workflow, permission, priority, scope, deferral,
+  and durable implementation decisions in the relevant feature chunk/checklist,
+  not only narrative summaries.
+- After product-facing work, update the relevant item's state: implemented,
+  verified, deferred, or pending. Check items only after implementation and
+  verification; manual testing may revert them.
+- Record major completed, resume-worthy milestones in a concise `PLANS.md`
+  milestone or accomplishment section. State the technical scope and value;
+  never exaggerate impact or invent metrics.
+- Keep `PLANS.md` detailed enough for a fresh session, but exclude temporary
+  handoff state, command output, debugging notes, and scratch work unless they
+  represent durable decisions.
+- If `PLANS.md` conflicts with the current request, follow the request and update
+  the plan.
+
+## Repo Safety
+
+- Preserve user changes and unrelated dirty state. Never revert them without an
+  explicit request.
+- Never run destructive Git commands such as `git reset --hard` or
+  `git checkout --` without explicit approval.
+- Use `apply_patch` for manual edits.
+- Prefer `rg` and `rg --files` for approved searches.
+- Keep final responses concise and state what was verified or which manual
+  verification commands were suggested.
+
+## Completion Report
+
+After changes, summarize:
+
+1. changed files and behavior
+2. suggested verification, or commands run with explicit approval and results
+3. relevant `PLANS.md` items deferred, updated, or marked complete
+4. whether the change is template-level; if so, give the packaged template's
+   target section and exact addition or replacement

package/assets/agents/code-explorer.toml

@@ -0,0 +1,31 @@
+name = "code-explorer"
+description = "Read-only codebase scout. Use BEFORE planning or implementing when the task requires sweeping many files, directories, or naming conventions to locate relevant code, contracts, and gotchas. Returns a condensed structured report — never raw file dumps. Does not modify code."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+# Code Explorer (Read-Only Scout)
+
+Begin your first user-visible response with this progress message exactly once: `Delegating to custom code-explorer — gpt-5.6-luna, medium reasoning.`
+
+You locate and distill the code relevant to a task so the orchestrator never has to hold raw search output in its own context.
+
+## Workflow
+1. Clarify the target — Restate (to yourself) what the caller needs: which behavior, symbol, flow, or convention.
+2. Search wide, read narrow — Use grep/glob to fan out, then read only the excerpts needed to confirm relevance. Prefer reading specific line ranges over whole files.
+3. Trace the contract — For each relevant piece, note its inputs/outputs, callers, and any invariants or guards the implementer must respect.
+4. Report — Return the structured report below. Nothing else.
+
+## Report format (strict)
+- Conclusion — one paragraph answering the caller's question directly.
+- Relevant files — bullet list of `path:line` references, each with a one-line note on why it matters.
+- Key contracts & gotchas — invariants, existing patterns to follow, tests that cover the area.
+- Open questions — anything you could not resolve, stated explicitly.
+
+## Rules
+- Keep it lean: exploration is retrieval, not reasoning. Stop searching once you can answer the question — don't exhaustively map the repo.
+- Read-only: never edit, write, or run state-changing commands. Tests/builds are the implementer's job.
+- No raw dumps: never paste whole files or long grep output into your report — that defeats the purpose of delegating exploration.
+- If you find nothing, say so plainly and list where you looked.
+- Don't speculate about code you didn't read; mark inferences as inferences.
+"""

package/assets/agents/code-reviewer.toml

@@ -0,0 +1,25 @@
+name = "code-reviewer"
+description = "Senior code reviewer for high-risk, security-sensitive, architectural, public-API, migration, concurrency, or difficult-to-validate changes. Review-only: reports findings and does not implement fixes."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+# Code Reviewer
+
+Begin your first user-visible response with this progress message exactly once: `Delegating to custom code-reviewer — gpt-5.6-sol, high reasoning.`
+
+You are a senior engineer performing a focused review of the current git changes.
+
+## Method
+Preflight the diff (`git status -sb`, `git diff`, and `git diff --cached`), then
+review for correctness, regressions, security, reliability, missing tests, and
+architecture risks. Report only actionable findings, ordered P0 Critical through
+P3 Low, with precise file and line references.
+
+## Rules
+- Keep it lean: surface the few high-confidence, high-impact findings rather than an exhaustive nitpick list. Rank by severity.
+- Review only — do not modify code unless the caller explicitly asks you to fix findings.
+- Block merge on P0/P1; call out exploitability and impact for security findings.
+- If the diff is empty, say so and ask what to review.
+- End with a clear verdict: APPROVE / REQUEST_CHANGES / COMMENT.
+"""

package/assets/agents/implementer.toml

@@ -0,0 +1,24 @@
+name = "implementer"
+description = "Implements features and bug fixes with accompanying unit tests, then validates them by running the test suite. Use to write code and prove it works. Hands the diff back for review; does not self-approve."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "high"
+developer_instructions = """
+# Implementer (Code + Unit Tests + Validation)
+
+Begin your first user-visible response with this progress message exactly once: `Delegating to custom implementer — gpt-5.6-luna, high reasoning.`
+
+You write the actual code, its unit tests, and you run those tests to prove the change works.
+
+## Workflow
+1. Understand — Read the relevant files and the assigned slice before editing. Don't guess at contracts.
+2. Implement — Make the smallest change that satisfies the slice; follow existing patterns, naming, and idioms. Use secure-by-default patterns: never hardcode secrets — read from env vars / a secrets vault, and leave a `// TODO: load from env or secrets vault` marker where a credential belongs.
+3. Unit test — Add or update unit tests covering new behavior, edge cases, and failure paths.
+4. Validate — Run the unit tests (and linters/build if quick). Paste the actual result. If tests fail, fix and re-run — never report success on red.
+5. Hand off — Report exactly what changed, which tests were added, and the test output. State plainly if anything is unverified.
+
+## Rules
+- No change is done until its tests are green and you've shown the output.
+- Don't expand scope beyond the assigned slice; flag anything else you notice.
+- Never mark your own work as reviewed — that's the code-reviewer's job.
+- Never stage, commit, or push.
+"""

package/assets/agents/quick-implementer.toml

@@ -0,0 +1,27 @@
+name = "quick-implementer"
+description = "Low-cost agent for small, mechanical, well-specified changes in one or two files. Implements the change, adds or updates focused tests when applicable, and runs narrow validation. Escalates ambiguous or architectural work instead of guessing."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "low"
+developer_instructions = """
+# Quick Implementer
+
+Begin your first user-visible response with this progress message exactly once: `Delegating to custom quick-implementer — gpt-5.6-luna, low reasoning.`
+
+Handle small, explicit, low-risk code or configuration changes with minimal context and output.
+
+## Fit check
+Proceed only when the requested change is well specified, localized to one or two files, and does not require architecture decisions. If the contract is unclear, the affected surface is broader, or failures require deep diagnosis, stop and recommend `implementer`.
+
+## Workflow
+1. Read the target file, its immediate caller or consumer, and the nearest relevant test.
+2. Make the smallest in-scope edit. Preserve unrelated user changes.
+3. Add or update one focused test when behavior changes and a test harness exists.
+4. Run the narrowest relevant test, formatter, or config validation.
+5. Report changed files, validation result, and any unverified point in at most eight bullets.
+
+## Rules
+- Never broaden scope or refactor adjacent code.
+- Never claim success without showing the validation result.
+- Never commit or push.
+- Keep command output summarized; do not return raw file dumps.
+"""

package/bin/codex-kit.js

@@ -0,0 +1,696 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const isRecord = (value) => typeof value === "object" && value !== null;
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const ASSETS = join(ROOT, "assets");
+const AGENTS_DIR = join(ASSETS, "agents");
+const ROUTING_FILE = join(ASSETS, "SUBAGENT_ROUTING.md");
+const TEMPLATE_FILE = join(ASSETS, "TEMPLATE_AGENTS.md");
+const PACKAGE = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+const GLOBAL_BEGIN = "<!-- BEGIN codex-kit:subagent-routing -->";
+const GLOBAL_END = "<!-- END codex-kit:subagent-routing -->";
+const PROJECT_BEGIN = "<!-- BEGIN codex-kit:shared-template -->";
+const PROJECT_END = "<!-- END codex-kit:shared-template -->";
+const STATE_FILE = ".codex-kit-state.json";
+const PROJECT_STATE_FILE = ".codex-kit-state.json";
+const REGISTRY = PACKAGE.publishConfig?.registry ?? "https://registry.npmjs.org";
+const DEFAULT_ORCHESTRATOR = "gpt-5.6-sol";
+const DEFAULT_REASONING_EFFORT = "high";
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+const read = (file) => readFileSync(file);
+const readText = (file) => readFileSync(file, "utf8");
+function timestamp() {
+    return new Date().toISOString().replace(/[-:TZ.]/g, "");
+}
+function backup(file) {
+    if (!existsSync(file))
+        return null;
+    let destination = `${file}.codex-kit.bak-${timestamp()}`;
+    let suffix = 1;
+    while (existsSync(destination))
+        destination = `${file}.codex-kit.bak-${timestamp()}-${suffix++}`;
+    copyFileSync(file, destination);
+    console.log(`backup: ${destination}`);
+    return destination;
+}
+function write(file, data) {
+    mkdirSync(dirname(file), { recursive: true });
+    const temporary = `${file}.codex-kit.tmp-${process.pid}`;
+    writeFileSync(temporary, data);
+    renameSync(temporary, file);
+}
+function loadState(home) {
+    const file = join(home, STATE_FILE);
+    if (!existsSync(file))
+        return { version: PACKAGE.version, files: {} };
+    try {
+        const state = JSON.parse(readText(file));
+        return isRecord(state) && isRecord(state.files)
+            ? state
+            : { version: PACKAGE.version, files: {} };
+    }
+    catch {
+        throw new Error(`${file} is not valid JSON; move it aside before reinstalling.`);
+    }
+}
+function saveState(home, state) {
+    write(join(home, STATE_FILE), `${JSON.stringify(state, null, 2)}\n`);
+}
+function topLevelConfigEntries(contents) {
+    const entries = new Map();
+    let inTable = false;
+    for (const line of contents.split("\n")) {
+        if (/^\s*\[/.test(line)) {
+            inTable = true;
+            continue;
+        }
+        if (inTable)
+            continue;
+        const match = /^(\s*)(model|model_reasoning_effort)\s*=\s*(.*?)\s*$/.exec(line);
+        const key = match?.[2];
+        const value = match?.[3];
+        if (key && value !== undefined && !entries.has(key))
+            entries.set(key, { value, line });
+    }
+    return entries;
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function setTopLevelConfig(contents, desired) {
+    const lines = contents.split("\n");
+    const seen = new Set();
+    let firstTable = lines.length;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (line !== undefined && /^\s*\[/.test(line)) {
+            firstTable = index;
+            break;
+        }
+    }
+    for (let index = 0; index < firstTable; index++) {
+        const line = lines[index];
+        if (line === undefined)
+            continue;
+        const match = /^(\s*)(model|model_reasoning_effort)\s*=\s*(.*?)\s*$/.exec(line);
+        const key = match?.[2];
+        if (!match || !key || seen.has(key))
+            continue;
+        lines[index] = `${match[1]}${key} = ${tomlString(desired[key])}`;
+        seen.add(key);
+    }
+    const missing = Object.keys(desired)
+        .filter((key) => !seen.has(key))
+        .map((key) => `${key} = ${tomlString(desired[key])}`);
+    if (missing.length)
+        lines.splice(0, 0, ...missing, "");
+    return lines.join("\n");
+}
+function restoreTopLevelConfig(contents, config) {
+    const desired = config.desired ?? {};
+    const previous = config.previous ?? {};
+    const lines = contents.split("\n");
+    let firstTable = lines.length;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (line !== undefined && /^\s*\[/.test(line)) {
+            firstTable = index;
+            break;
+        }
+    }
+    const restored = new Set();
+    for (let index = 0; index < firstTable; index++) {
+        const line = lines[index];
+        if (line === undefined)
+            continue;
+        const match = /^(\s*)(model|model_reasoning_effort)\s*=\s*(.*?)\s*$/.exec(line);
+        const key = match?.[2];
+        if (!match || !key || restored.has(key))
+            continue;
+        if (match[3] !== tomlString(desired[key]))
+            continue;
+        const prior = previous[key];
+        if (prior?.present) {
+            lines[index] = `${match[1]}${key} = ${prior.value}`;
+        }
+        else {
+            lines.splice(index, 1);
+            index--;
+            firstTable--;
+        }
+        restored.add(key);
+    }
+    if (Object.values(previous).some((entry) => entry && !entry.present) && lines[0] === "")
+        lines.shift();
+    return lines.join("\n");
+}
+function loadProjectState(cwd) {
+    const file = join(cwd, PROJECT_STATE_FILE);
+    if (!existsSync(file))
+        return { version: 1, template: {} };
+    try {
+        const state = JSON.parse(readText(file));
+        return isRecord(state) && isRecord(state.template)
+            ? state
+            : { version: 1, template: {} };
+    }
+    catch {
+        throw new Error(`${file} is not valid JSON; move it aside before syncing.`);
+    }
+}
+function saveProjectState(cwd, state) {
+    write(join(cwd, PROJECT_STATE_FILE), `${JSON.stringify(state, null, 2)}\n`);
+}
+function templatePrompt() {
+    return `Template reference updated. Ask Codex:\n\nThe project's TEMPLATE_AGENTS.md was refreshed from codex-kit. Compare it with\nAGENTS.md and merge only new or changed reusable guidelines that apply to this\nrepository. Preserve project-specific instructions and existing adaptations. Do\nnot replace AGENTS.md wholesale. If a template rule conflicts with a local rule,\nkeep the local rule and report the conflict. Summarize what was added, updated,\nskipped, or adapted, and why. When finished, run codex-kit project mark-applied.`;
+}
+function managedBlock(content, begin, end) {
+    return `${begin}\n${content.trimEnd()}\n${end}`;
+}
+function replaceOrAppendBlock(original, content, begin, end) {
+    const start = original.indexOf(begin);
+    const finish = original.indexOf(end);
+    if ((start >= 0) !== (finish >= 0) || (start >= 0 && finish < start)) {
+        throw new Error(`Malformed managed block: expected both ${begin} and ${end}.`);
+    }
+    const block = managedBlock(content, begin, end);
+    if (start >= 0)
+        return `${original.slice(0, start)}${block}${original.slice(finish + end.length)}`;
+    return `${original.trimEnd()}${original.trim() ? "\n\n" : ""}${block}\n`;
+}
+function removeBlock(original, begin, end) {
+    const start = original.indexOf(begin);
+    const finish = original.indexOf(end);
+    if (start < 0 && finish < 0)
+        return original;
+    if (start < 0 || finish < start)
+        throw new Error(`Malformed managed block in AGENTS.md.`);
+    const before = original.slice(0, start).trimEnd();
+    const after = original.slice(finish + end.length).trimStart();
+    return `${before}${before && after ? "\n\n" : ""}${after}${before || after ? "\n" : ""}`;
+}
+function installFile(source, target, key, prior, force) {
+    const sourceData = read(source);
+    const sourceHash = sha256(sourceData);
+    const previous = prior.files[key];
+    if (!existsSync(target)) {
+        write(target, sourceData);
+        console.log(`installed: ${target}`);
+        return { target, hash: sourceHash, ownership: "created", backup: null };
+    }
+    const targetHash = sha256(read(target));
+    if (targetHash === sourceHash) {
+        console.log(`unchanged: ${target}`);
+        return previous ?? { target, hash: sourceHash, ownership: "preexisting", backup: null };
+    }
+    const safelyOwned = previous &&
+        previous.target === target &&
+        previous.ownership !== "preexisting" &&
+        previous.hash === targetHash;
+    if (!safelyOwned && !force) {
+        console.warn(`preserved modified or pre-existing file: ${target} (use --force to replace)`);
+        return previous ?? null;
+    }
+    const newBackup = backup(target);
+    write(target, sourceData);
+    console.log(`updated: ${target}`);
+    return {
+        target,
+        hash: sourceHash,
+        ownership: safelyOwned ? previous.ownership : "replaced",
+        backup: safelyOwned ? previous.backup : newBackup,
+    };
+}
+function installGlobal(options) {
+    const home = options.codexHome;
+    mkdirSync(home, { recursive: true });
+    const prior = loadState(home);
+    const next = {
+        version: PACKAGE.version,
+        files: {},
+        globalAgents: null,
+        config: prior.config ?? null,
+    };
+    for (const name of readdirSync(AGENTS_DIR).filter((name) => name.endsWith(".toml")).sort()) {
+        const key = `agents/${name}`;
+        const record = installFile(join(AGENTS_DIR, name), join(home, "agents", name), key, prior, options.force);
+        if (record)
+            next.files[key] = record;
+    }
+    const routingRecord = installFile(ROUTING_FILE, join(home, "SUBAGENT_ROUTING.md"), "routing", prior, options.force);
+    if (routingRecord)
+        next.files.routing = routingRecord;
+    for (const [key, record] of Object.entries(prior.files)) {
+        if (key in next.files)
+            continue;
+        const target = record.target;
+        if (!existsSync(target) || sha256(read(target)) !== record.hash) {
+            console.warn(`preserved stale modified or missing file: ${target}`);
+            next.files[key] = record;
+            continue;
+        }
+        if (record.ownership === "created") {
+            rmSync(target);
+            console.log(`removed stale: ${target}`);
+        }
+        else if (record.ownership === "replaced" && record.backup && existsSync(record.backup)) {
+            copyFileSync(record.backup, target);
+            console.log(`restored stale: ${target}`);
+        }
+    }
+    const globalAgents = join(home, "AGENTS.md");
+    const original = existsSync(globalAgents) ? readText(globalAgents) : "";
+    const updated = replaceOrAppendBlock(original, readText(ROUTING_FILE), GLOBAL_BEGIN, GLOBAL_END);
+    if (updated !== original) {
+        backup(globalAgents);
+        write(globalAgents, updated);
+        console.log(`updated: ${globalAgents}`);
+    }
+    next.globalAgents = { target: globalAgents };
+    saveState(home, next);
+    const commitPusher = join(home, "agents", "commit-pusher.toml");
+    if (existsSync(commitPusher)) {
+        console.warn(`warning: existing unmanaged commit-pusher remains at ${commitPusher}`);
+    }
+    console.log(`Codex kit ${PACKAGE.version} installed under ${home}`);
+}
+function configureGlobal(options) {
+    const home = options.codexHome;
+    mkdirSync(home, { recursive: true });
+    const configFile = join(home, "config.toml");
+    const desired = {
+        model: options.orchestrator,
+        model_reasoning_effort: options.reasoningEffort,
+    };
+    const priorState = loadState(home);
+    const original = existsSync(configFile) ? readText(configFile) : "";
+    const current = topLevelConfigEntries(original);
+    const priorConfig = priorState.config;
+    if (priorConfig?.target === configFile) {
+        const changedByUser = Object.entries(priorConfig.desired).some(([key, value]) => {
+            const entry = current.get(key);
+            return !entry || entry.value !== tomlString(value);
+        });
+        if (changedByUser && !options.force) {
+            console.warn(`preserved modified config: ${configFile} (use --force to replace)`);
+            return;
+        }
+    }
+    const updated = setTopLevelConfig(original, desired);
+    if (updated !== original) {
+        backup(configFile);
+        write(configFile, updated);
+        console.log(`configured orchestrator: ${configFile}`);
+    }
+    else
+        console.log(`unchanged: ${configFile}`);
+    const previous = priorConfig?.previous ?? {};
+    for (const key of Object.keys(desired)) {
+        if (key in previous)
+            continue;
+        const entry = current.get(key);
+        previous[key] = entry
+            ? { present: true, value: entry.value }
+            : { present: false };
+    }
+    priorState.version = PACKAGE.version;
+    priorState.config = {
+        target: configFile,
+        desired,
+        previous,
+    };
+    saveState(home, priorState);
+    console.log(`Orchestrator: ${desired.model}`);
+    console.log(`Reasoning effort: ${desired.model_reasoning_effort}`);
+}
+function listGlobal(options) {
+    const home = options.codexHome;
+    const configFile = join(home, "config.toml");
+    const globalAgents = join(home, "AGENTS.md");
+    const routingFile = join(home, "SUBAGENT_ROUTING.md");
+    const agentsDir = join(home, "agents");
+    const stateFile = join(home, STATE_FILE);
+    const state = loadState(home);
+    const config = existsSync(configFile) ? topLevelConfigEntries(readText(configFile)) : new Map();
+    const value = (key) => {
+        const raw = config.get(key)?.value;
+        if (!raw)
+            return "not set";
+        try {
+            return String(JSON.parse(raw));
+        }
+        catch {
+            return raw;
+        }
+    };
+    const managedTargets = new Set(Object.values(state.files).map((record) => record.target));
+    console.log(`Codex home: ${home}`);
+    console.log(`Config: ${configFile}${existsSync(configFile) ? "" : " (missing)"}`);
+    console.log(`Orchestrator: ${value("model")}`);
+    console.log(`Reasoning effort: ${value("model_reasoning_effort")}`);
+    console.log(`Kit state: ${existsSync(stateFile) ? state.version : "not installed"}`);
+    const hasRoutingBlock = existsSync(globalAgents) && readText(globalAgents).includes(GLOBAL_BEGIN);
+    console.log(`Global routing: ${hasRoutingBlock ? "installed" : "not installed"}`);
+    console.log(`Routing file: ${existsSync(routingFile) ? routingFile : "missing"}`);
+    console.log("Custom agents:");
+    const agents = existsSync(agentsDir)
+        ? readdirSync(agentsDir).filter((name) => name.endsWith(".toml")).sort()
+        : [];
+    if (!agents.length)
+        return console.log("  (none)");
+    for (const filename of agents) {
+        const file = join(agentsDir, filename);
+        const contents = readText(file);
+        const field = (key) => new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, "m").exec(contents)?.[1] ?? "not set";
+        const ownership = managedTargets.has(file) ? "managed" : "unmanaged";
+        console.log(`  ${field("name")} — ${field("model")}, ${field("model_reasoning_effort")} (${ownership})`);
+    }
+}
+function uninstallGlobal(options) {
+    const home = options.codexHome;
+    const statePath = join(home, STATE_FILE);
+    if (!existsSync(statePath)) {
+        console.log(`No installer state at ${statePath}; nothing removed.`);
+        return;
+    }
+    const state = loadState(home);
+    for (const record of Object.values(state.files)) {
+        const target = record.target;
+        if (!existsSync(target) || sha256(read(target)) !== record.hash) {
+            console.warn(`preserved modified or missing file: ${target}`);
+            continue;
+        }
+        if (record.ownership === "created") {
+            rmSync(target);
+            console.log(`removed: ${target}`);
+        }
+        else if (record.ownership === "replaced" && record.backup && existsSync(record.backup)) {
+            copyFileSync(record.backup, target);
+            console.log(`restored: ${target}`);
+        }
+        else {
+            console.log(`preserved pre-existing file: ${target}`);
+        }
+    }
+    const globalAgents = state.globalAgents?.target ?? join(home, "AGENTS.md");
+    if (existsSync(globalAgents)) {
+        const original = readText(globalAgents);
+        const updated = removeBlock(original, GLOBAL_BEGIN, GLOBAL_END);
+        if (updated !== original) {
+            backup(globalAgents);
+            if (updated)
+                write(globalAgents, updated);
+            else
+                rmSync(globalAgents);
+            console.log(`removed managed routing from: ${globalAgents}`);
+        }
+    }
+    if (state.config?.target) {
+        const configFile = state.config.target;
+        if (!existsSync(configFile)) {
+            console.warn(`preserved missing config: ${configFile}`);
+        }
+        else {
+            const originalConfig = readText(configFile);
+            const current = topLevelConfigEntries(originalConfig);
+            const changed = Object.entries(state.config.desired).some(([key, value]) => {
+                const entry = current.get(key);
+                return !entry || entry.value !== tomlString(value);
+            });
+            if (changed) {
+                console.warn(`preserved modified config: ${configFile}`);
+            }
+            else {
+                const restored = restoreTopLevelConfig(originalConfig, state.config);
+                if (restored !== originalConfig) {
+                    backup(configFile);
+                    if (restored.trim())
+                        write(configFile, restored);
+                    else
+                        rmSync(configFile);
+                    console.log(`restored config: ${configFile}`);
+                }
+            }
+        }
+    }
+    rmSync(statePath);
+    console.log(`Codex kit uninstalled from ${home}`);
+}
+function syncProject(options) {
+    const cwd = options.cwd;
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+        throw new Error(`Not a directory: ${cwd}`);
+    const agentsFile = join(cwd, "AGENTS.md");
+    const stagedTemplate = join(cwd, "TEMPLATE_AGENTS.md");
+    const template = readText(TEMPLATE_FILE);
+    const desired = Buffer.from(template);
+    const sourceHash = sha256(desired);
+    const state = loadProjectState(cwd);
+    const previousAvailable = state.template.availableHash;
+    if (existsSync(stagedTemplate)) {
+        const currentHash = sha256(read(stagedTemplate));
+        const locallyModified = currentHash !== sourceHash && (!previousAvailable || currentHash !== previousAvailable);
+        if (locallyModified && currentHash !== sourceHash && !options.force) {
+            console.warn(`preserved locally modified template: ${stagedTemplate} (use --force to replace)`);
+            console.log(`The installed kit has template ${PACKAGE.version}; review the local change before syncing.`);
+            return;
+        }
+        if (currentHash === sourceHash)
+            console.log(`unchanged: ${stagedTemplate}`);
+        else {
+            backup(stagedTemplate);
+            write(stagedTemplate, desired);
+            console.log(`refreshed template reference: ${stagedTemplate}`);
+        }
+    }
+    else {
+        write(stagedTemplate, desired);
+        console.log(`created template reference: ${stagedTemplate}`);
+    }
+    state.version = 1;
+    state.template = {
+        ...state.template,
+        availableHash: sourceHash,
+        availableVersion: PACKAGE.version,
+    };
+    saveProjectState(cwd, state);
+    if (!existsSync(agentsFile)) {
+        const contents = "# Project-Specific Instructions\n\n<!-- Add repository-specific commands, architecture, and exceptions here. -->\n";
+        write(agentsFile, contents);
+        console.log(`created project instructions file: ${agentsFile}`);
+    }
+    else if (readText(agentsFile).includes(PROJECT_BEGIN) || readText(agentsFile).includes(PROJECT_END)) {
+        console.warn(`preserved legacy managed template in: ${agentsFile}`);
+        console.warn("Ask Codex to migrate it to semantic template reconciliation before applying updates.");
+    }
+    console.log(templatePrompt());
+}
+function projectStatus(options) {
+    const cwd = options.cwd;
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+        throw new Error(`Not a directory: ${cwd}`);
+    const stagedTemplate = join(cwd, "TEMPLATE_AGENTS.md");
+    const agentsFile = join(cwd, "AGENTS.md");
+    const state = loadProjectState(cwd);
+    const availableHash = state.template.availableHash ?? null;
+    const appliedHash = state.template.appliedHash ?? null;
+    const sourceHash = sha256(read(TEMPLATE_FILE));
+    const localHash = existsSync(stagedTemplate) ? sha256(read(stagedTemplate)) : null;
+    console.log(`Project: ${cwd}`);
+    if (!localHash)
+        return console.log("Status: not initialized (run codex-kit project sync)");
+    if (!existsSync(agentsFile))
+        return console.log("Status: AGENTS.md missing (reconcile the template first)");
+    console.log(`Available: ${state.template.availableVersion ?? "unknown"} (${availableHash ?? "untracked"})`);
+    console.log(`Applied:   ${appliedHash ?? "never"}`);
+    if (sourceHash !== availableHash)
+        return console.log("Status: kit template update available; run project sync");
+    if (localHash !== availableHash)
+        return console.log("Status: local template changed; review it before syncing");
+    if (appliedHash !== localHash)
+        return console.log("Status: reconciliation required");
+    console.log("Status: up to date");
+}
+function markApplied(options) {
+    const cwd = options.cwd;
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+        throw new Error(`Not a directory: ${cwd}`);
+    const stagedTemplate = join(cwd, "TEMPLATE_AGENTS.md");
+    const agentsFile = join(cwd, "AGENTS.md");
+    if (!existsSync(stagedTemplate))
+        throw new Error(`Missing ${stagedTemplate}; run project sync first.`);
+    if (!existsSync(agentsFile))
+        throw new Error(`Missing ${agentsFile}; reconcile the template into AGENTS.md first.`);
+    const state = loadProjectState(cwd);
+    const appliedHash = sha256(read(stagedTemplate));
+    state.version = 1;
+    state.template = {
+        ...state.template,
+        appliedHash,
+        appliedAt: new Date().toISOString(),
+    };
+    saveProjectState(cwd, state);
+    console.log(`recorded template reconciliation: ${stagedTemplate}`);
+}
+function compareVersions(left, right) {
+    const parseVersion = (value) => {
+        const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value);
+        if (!match)
+            throw new Error(`Invalid package version: ${value}`);
+        return {
+            numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+            prerelease: match[4] ?? null,
+        };
+    };
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    for (let index = 0; index < 3; index++) {
+        const leftNumber = a.numbers[index];
+        const rightNumber = b.numbers[index];
+        if (leftNumber !== rightNumber)
+            return Math.sign(leftNumber - rightNumber);
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return Math.sign(a.prerelease.localeCompare(b.prerelease, "en", { numeric: true }));
+}
+function checkVersion() {
+    let latest = process.env.CODEX_KIT_LATEST_VERSION;
+    if (!latest) {
+        const executable = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
+        const result = spawnSync(executable, ["view", PACKAGE.name, "version", "--json", `--registry=${REGISTRY}`], { encoding: "utf8", timeout: 15_000 });
+        if (result.error)
+            throw new Error(`Unable to run pnpm: ${result.error.message}`);
+        if (result.status !== 0) {
+            const detail = result.stderr.trim() || "pnpm view failed";
+            throw new Error(`Unable to check ${REGISTRY}: ${detail}`);
+        }
+        try {
+            const value = JSON.parse(result.stdout);
+            latest = Array.isArray(value) && typeof value.at(-1) === "string"
+                ? value.at(-1)
+                : typeof value === "string"
+                    ? value
+                    : undefined;
+        }
+        catch {
+            latest = result.stdout.trim();
+        }
+    }
+    if (typeof latest !== "string" || !latest)
+        throw new Error("Registry returned no package version.");
+    console.log(`Installed: ${PACKAGE.version}`);
+    console.log(`Latest:    ${latest}`);
+    const comparison = compareVersions(PACKAGE.version, latest);
+    if (comparison === 0)
+        return console.log("codex-kit is up to date.");
+    if (comparison > 0)
+        return console.log("This local build is newer than the published package.");
+    console.log(`Update available. Run:
+  pnpm add --global ${PACKAGE.name}@latest
+  codex-kit global install`);
+}
+function parse(argv) {
+    const options = {
+        cwd: process.cwd(),
+        codexHome: resolve(process.env.CODEX_HOME || join(homedir(), ".codex")),
+        orchestrator: DEFAULT_ORCHESTRATOR,
+        reasoningEffort: DEFAULT_REASONING_EFFORT,
+        force: false,
+        positionals: [],
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === undefined)
+            continue;
+        if (arg === "--force")
+            options.force = true;
+        else if (arg === "--cwd" || arg === "--codex-home") {
+            const value = argv[++index];
+            if (!value)
+                throw new Error(`${arg} requires a path.`);
+            if (arg === "--cwd")
+                options.cwd = resolve(value);
+            else
+                options.codexHome = resolve(value);
+        }
+        else if (arg === "--orchestrator" || arg === "--model") {
+            const value = argv[++index];
+            if (!value)
+                throw new Error(`${arg} requires a model.`);
+            options.orchestrator = value;
+        }
+        else if (arg === "--reasoning-effort") {
+            const value = argv[++index];
+            if (!value)
+                throw new Error(`${arg} requires a value.`);
+            options.reasoningEffort = value;
+        }
+        else
+            options.positionals.push(arg);
+    }
+    return options;
+}
+function help() {
+    console.log(`codex-kit ${PACKAGE.version}
+
+Usage:
+  codex-kit global install [--codex-home PATH] [--force]
+  codex-kit global configure [--orchestrator MODEL] [--reasoning-effort LEVEL]
+  codex-kit global list [--codex-home PATH]
+  codex-kit global uninstall [--codex-home PATH]
+  codex-kit project init [--cwd PATH]
+  codex-kit project sync [--cwd PATH]
+  codex-kit project status [--cwd PATH]
+  codex-kit project mark-applied [--cwd PATH]
+  codex-kit version check
+  codex-kit --version
+
+Global configure defaults to gpt-5.6-sol with high reasoning and edits only
+the top-level model settings in CODEX_HOME/config.toml.
+Global install manages custom agents and a marked routing block under CODEX_HOME.
+Project sync refreshes TEMPLATE_AGENTS.md and never merges it into AGENTS.md.`);
+}
+export function main(argv = process.argv.slice(2)) {
+    const options = parse(argv);
+    if (options.positionals.includes("--version"))
+        return console.log(PACKAGE.version);
+    if (!options.positionals.length || options.positionals.includes("--help"))
+        return help();
+    const [scope, action] = options.positionals;
+    if (scope === "global" && action === "install")
+        return installGlobal(options);
+    if (scope === "global" && action === "configure")
+        return configureGlobal(options);
+    if (scope === "global" && action === "list")
+        return listGlobal(options);
+    if (scope === "global" && action === "uninstall")
+        return uninstallGlobal(options);
+    if (scope === "project" && (action === "init" || action === "sync"))
+        return syncProject(options);
+    if (scope === "project" && action === "status")
+        return projectStatus(options);
+    if (scope === "project" && action === "mark-applied")
+        return markApplied(options);
+    if (scope === "version" && action === "check")
+        return checkVersion();
+    throw new Error(`Unknown command: ${options.positionals.join(" ")}`);
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        main();
+    }
+    catch (error) {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@iamdevlinph/codex-kit",
+  "version": "1.0.1",
+  "description": "Portable Codex subagents and project AGENTS.md defaults.",
+  "type": "module",
+  "bin": {
+    "codex-kit": "bin/codex-kit.js"
+  },
+  "files": [
+    "assets/agents",
+    "assets/SUBAGENT_ROUTING.md",
+    "assets/TEMPLATE_AGENTS.md",
+    "bin"
+  ],
+  "scripts": {
+    "build": "pnpm exec tsc -p tsconfig.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit && pnpm exec tsc -p tsconfig.test.json --noEmit",
+    "test": "pnpm run build && pnpm exec tsc -p tsconfig.test.json && node --test .test-dist/test/*.test.js",
+    "prepack": "pnpm run build",
+    "pack:check": "pnpm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iamdevlinph/codex-kit.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.43",
+    "typescript": "7.0.1-rc"
+  },
+  "packageManager": "pnpm@11.5.2",
+  "license": "UNLICENSED"
+}