@iamdevlinph/codex-kit 1.0.8 → 1.0.9

package/README.md

@@ -2,7 +2,7 @@
 
 Portable Codex setup for new devices and multiple projects. It provides:
 
-- four custom subagents: explorer, quick implementer, implementer, and reviewer
+- three automatically routed roles plus a manual quick implementer
 - automatic global role routing
 - a reusable, stack-neutral `AGENTS.md` template
 - safe commands for global setup, project synchronization, and reconciliation
@@ -37,26 +37,43 @@ routing hook supplies the current `SUBAGENT_ROUTING.md`; the root classifies the
 task and delegates substantive work to the exact matching role. The role's agent
 TOML—not the routing policy—selects its model and reasoning effort. To avoid
 subagent startup overhead, the root may directly handle planning, conversation,
-read-only checks, documentation, configuration bookkeeping, template
-reconciliation, and explicit low-risk one-file edits.
+read-only checks, documentation, bookkeeping, and clear changes spanning up to
+roughly three files. Automatic delegation is reserved for broad discovery,
+large multi-file implementation or debugging, and high-risk review.
+
+`quick-implementer` remains installed for explicit manual delegation but is not
+selected by the default automatic route. The root reuses delegated test evidence
+and normally performs only lightweight integration checks.
 
 `global configure` sets these defaults while preserving unrelated settings:
 
 ```toml
 model = "gpt-5.6-sol"
-model_reasoning_effort = "medium"
+model_reasoning_effort = "low"
 plan_mode_reasoning_effort = "high"
 ```
 
-This keeps ordinary root work lighter while retaining high reasoning in Plan
+This keeps ordinary root work light while retaining high reasoning in Plan
 Mode. Override either effort independently when needed:
 
 ```sh
 codex-kit global configure \
-  --reasoning-effort medium \
+  --reasoning-effort low \
   --plan-reasoning-effort high
 ```
 
+Automatic role models are tuned by task shape: Terra-medium performs broad
+repository exploration, Luna-high performs large implementation slices, and
+Sol-high reviews consequential changes. Luna-medium `quick-implementer` remains
+manual-only.
+
+Delegation is time-bounded. The root waits once for up to 60 seconds, requests
+one progress update, and then enforces a three-minute read/review/manual-quick
+deadline or five-minute implementation deadline. Validation commands that make
+no progress for two minutes are stopped unless the repository documents a
+longer normal runtime. Root and worker never run the same validation
+concurrently.
+
 Before changing these keys, codex-kit creates a timestamped `config.toml`
 backup and records their previous values. `global uninstall` restores those
 values without replacing unrelated configuration changed afterward.

package/assets/SUBAGENT_ROUTING.md

@@ -7,7 +7,8 @@ model name; each agent definition owns its model and reasoning effort.
 The parent owns requirements, architecture, sequencing, integration, and final
 validation. It may directly handle planning, conversation, status, read-only
 checks, documentation and instruction updates, configuration bookkeeping,
-template reconciliation, and explicit low-risk edits isolated to one file.
+template reconciliation, and clear low-to-medium-risk changes spanning up to
+roughly three files when no broad discovery or architectural decision is needed.
 When a substantive route below matches, spawn that exact role before performing
 the role's work. The user does not need to request delegation.
 
@@ -15,10 +16,8 @@ Select custom agents by exact name:
 
 - Broad repository discovery, contract tracing, or search across many files:
   `code-explorer`
-- Well-specified implementation that benefits from isolated editing or focused
-  tests, usually localized to a few files:
-  `quick-implementer`
-- Multi-file behavior changes, debugging, migrations, or substantial tests:
+- Large multi-file behavior changes, non-obvious debugging, migrations, or
+  substantial tests:
   `implementer`
 - Independent review of security-sensitive, architectural, public-API,
   concurrency, migration, or otherwise difficult-to-validate changes:
@@ -34,16 +33,33 @@ Prefer the parent fast path when delegation would cost more than the work. Do no
 spawn a subagent solely because a tool will write a file. Delegate based on task
 complexity, context isolation, testing needs, and review risk.
 
+`quick-implementer` remains installed for explicit manual delegation, but the
+default automatic routing policy does not select it.
+
 An assigned implementation agent performs its edits directly and must not
-delegate them again. Use either `quick-implementer` or `implementer` for one
-implementation slice, not both. Read-only agents never modify files.
+delegate them again. Use one implementation agent per slice. Read-only agents
+never modify files.
 
 For every delegation:
 
 - Give the agent a bounded task and the relevant requirements.
+- Include the role deadline: three minutes for `code-explorer`,
+  `code-reviewer`, or a manually requested `quick-implementer`; five minutes
+  for `implementer`.
 - Request a concise, decision-ready result.
-- Wait for the result before integrating or validating dependent work.
-- Reuse returned evidence instead of repeating the same exploration.
+- Wait once for at most 60 seconds. If the agent is still running, request one
+  concise progress update. Never issue consecutive wait cycles without new
+  progress, steering, or independent useful work.
+- If the role deadline expires, tell the agent to stop commands and return its
+  stable partial result. Interrupt it if it does not respond, preserve its
+  edits, and finish locally.
+- Do not run the same validation concurrently in the parent and worker. A
+  validation command that produces no result within two minutes is hung unless
+  repository guidance documents a longer normal runtime; stop it and report the
+  evidence instead of retrying it repeatedly.
+- Reuse returned exploration and test evidence. The parent should run only
+  lightweight integration checks unless the work is high-risk or the evidence
+  is incomplete.
 
 There is no commit-pusher role. Never delegate Git publishing. Do not stage,
 commit, tag, or push unless the user explicitly requests that operation in the

package/assets/agents/code-explorer.toml

@@ -1,12 +1,12 @@
 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 = "gpt-5.6-terra"
 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.`
+Begin your first user-visible response with this progress message exactly once: `Delegating to custom code-explorer — gpt-5.6-terra, 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.
 
@@ -24,6 +24,7 @@ You locate and distill the code relevant to a task so the orchestrator never has
 
 ## Rules
 - Keep it lean: exploration is retrieval, not reasoning. Stop searching once you can answer the question — don't exhaustively map the repo.
+- Finish within three minutes. At the deadline, stop searching and return the best supported partial report immediately.
 - 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.

package/assets/agents/code-reviewer.toml

@@ -18,6 +18,7 @@ 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.
+- Finish within three minutes. At the deadline, stop and return the findings already supported by the diff.
 - 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.

package/assets/agents/implementer.toml

@@ -18,6 +18,8 @@ You write the actual code, its unit tests, and you run those tests to prove the
 
 ## Rules
 - No change is done until its tests are green and you've shown the output.
+- Finish within five minutes. At the deadline, stop running commands and return the stable edits with exact incomplete or failing validation evidence.
+- Run one validation process at a time. Stop a command that produces no result within two minutes unless repository guidance documents a longer normal runtime; report it as hung instead of repeatedly retrying it.
 - 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

@@ -1,5 +1,5 @@
 name = "quick-implementer"
-description = "Focused 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."
+description = "Manual-only focused agent for small, mechanical, well-specified changes in one or two files. Not selected by codex-kit's default automatic routing. Implements the change, adds or updates focused tests when applicable, and runs narrow validation."
 model = "gpt-5.6-luna"
 model_reasoning_effort = "medium"
 developer_instructions = """
@@ -8,6 +8,7 @@ developer_instructions = """
 Begin your first user-visible response with this progress message exactly once: `Delegating to custom quick-implementer — gpt-5.6-luna, medium reasoning.`
 
 Handle small, explicit, low-risk code or configuration changes with minimal context and output.
+This role is available for explicit manual delegation and is not part of codex-kit's default automatic route.
 
 ## 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`.
@@ -21,6 +22,7 @@ Proceed only when the requested change is well specified, localized to one or tw
 
 ## Rules
 - Never broaden scope or refactor adjacent code.
+- Finish within three minutes. Stop a validation command that produces no result within two minutes and return the stable edits with the hang reported.
 - 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

@@ -21,7 +21,7 @@ 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 = "medium";
+const DEFAULT_REASONING_EFFORT = "low";
 const DEFAULT_PLAN_REASONING_EFFORT = "high";
 const sha256 = (data) => createHash("sha256").update(data).digest("hex");
 const read = (file) => readFileSync(file);
@@ -796,7 +796,7 @@ Options by command:
     --force                   Replace modified config managed by codex-kit.
     --orchestrator MODEL      Set the root/orchestrator model (default: gpt-5.6-sol).
     --model MODEL             Alias for --orchestrator.
-    --reasoning-effort LEVEL       Set normal reasoning effort (default: medium).
+    --reasoning-effort LEVEL       Set normal reasoning effort (default: low).
     --plan-reasoning-effort LEVEL  Set Plan-mode reasoning effort (default: high).
 
   global list, global uninstall
@@ -811,7 +811,7 @@ Options by command:
 
 Examples:
   codex-kit global install --force
-  codex-kit global configure --reasoning-effort medium --plan-reasoning-effort high
+  codex-kit global configure --reasoning-effort low --plan-reasoning-effort high
   codex-kit project sync --cwd /path/to/project --force
   codex-kit project status --cwd /path/to/project`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamdevlinph/codex-kit",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {