@iamdevlinph/codex-kit 1.0.8 → 1.0.10

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.
@@ -151,9 +168,13 @@ 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:
+`project sync` never edits `AGENTS.md` or project skills. It prints a prompt
+asking Codex to merge only applicable reusable changes while preserving local
+adaptations. Reconciliation keeps always-on rules in `AGENTS.md` and may create
+or update task-specific workflows under `.agents/skills` when the updated
+template warrants them. Critical safety and authorization rules remain in
+`AGENTS.md`, and speculative skills are avoided. After reviewing the semantic
+merge and any skill changes, record the applied template hash:
 
 ```sh
 codex-kit project mark-applied

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/TEMPLATE_AGENTS.md

@@ -13,6 +13,28 @@ the managed markers.
   priorities, deferred requirements, product or implementation decisions, and
   major completed milestones.
 
+## Instructions And Skills
+
+- Keep `AGENTS.md` focused on durable, always-applicable repository context:
+  architecture, conventions, commands, safety and authorization boundaries,
+  verification expectations, and concise pointers to specialized workflows.
+- Use project skills under `.agents/skills/<skill-name>/SKILL.md` for repeatable,
+  task-specific workflows or detailed guidance needed only for matching tasks.
+- In existing projects, review large task-specific procedures in `AGENTS.md`.
+  When a procedure is reusable and conditionally relevant, extract it into a
+  project skill and leave a concise routing rule in `AGENTS.md`.
+- Preserve critical safety, authorization, destructive-operation, database, and
+  deployment restrictions in `AGENTS.md`, even when a skill contains the
+  detailed workflow.
+- In new projects, begin with a concise `AGENTS.md`. Add a skill only after a
+  concrete repeatable workflow or specialized procedure is identified; do not
+  create speculative skills.
+- Avoid duplicating detailed instructions between `AGENTS.md` and `SKILL.md`.
+  Keep the always-on rule in `AGENTS.md` and the conditional procedure in the
+  skill.
+- Each project skill must use valid YAML frontmatter with a clear `name` and a
+  `description` that states when the skill should trigger.
+
 ## Template Maintenance
 
 - Projects normally use `AGENTS.md` as the active instruction file. The source
@@ -52,8 +74,12 @@ contents of TEMPLATE_AGENTS.md between
 <!-- 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.
+change project behavior. Review existing project skills under .agents/skills and
+move conditionally relevant, repeatable procedures out of AGENTS.md only when a
+skill is warranted. Preserve critical safety and authorization rules in
+AGENTS.md, preserve existing relevant skills, avoid speculative skills, and
+validate any skill you create or modify. Afterward, summarize what was preserved,
+what moved into a skill, and whether any local rules appear template-worthy.
 ```
 
 ## Core Behavior

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);
@@ -266,7 +266,29 @@ 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.`;
+    return `Template reference updated. Ask Codex:
+
+The project's TEMPLATE_AGENTS.md was refreshed from codex-kit. Compare it with
+AGENTS.md and merge only new or changed reusable guidelines that apply to this
+repository.
+
+Keep durable, always-applicable repository rules in AGENTS.md. When the updated
+template identifies a repeatable, task-specific procedure, inspect existing
+project skills under .agents/skills and create or update a skill only when it
+would reduce conditional detail in AGENTS.md. Preserve existing relevant skills
+and avoid duplicating detailed instructions between AGENTS.md and SKILL.md.
+
+Keep critical safety, authorization, database, deployment, and destructive-
+operation restrictions in AGENTS.md even when a skill contains the detailed
+workflow. Do not create speculative skills.
+
+Preserve project-specific instructions and existing adaptations. Do not replace
+AGENTS.md wholesale. If a template rule conflicts with a local rule, keep the
+local rule and report the conflict.
+
+Summarize what was added, updated, skipped, adapted, or moved into a skill, and
+why. Validate any created or modified skills. When finished, run codex-kit
+project mark-applied.`;
 }
 function managedBlock(content, begin, end) {
     return `${begin}\n${content.trimEnd()}\n${end}`;
@@ -796,7 +818,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 +833,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.10",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {