@iamdevlinph/codex-kit 1.0.10 → 1.0.12

package/README.md

@@ -5,6 +5,7 @@ Portable Codex setup for new devices and multiple projects. It provides:
 - three automatically routed roles plus a manual quick implementer
 - automatic global role routing
 - a reusable, stack-neutral `AGENTS.md` template
+- a package-owned `codex-kit-reconcile-agents` skill for semantic reconciliation
 - safe commands for global setup, project synchronization, and reconciliation
 
 The package contains no credentials. Global installation does not modify the
@@ -28,9 +29,13 @@ that they run the installed `${CODEX_HOME:-~/.codex}/codex-kit/routing-hook.js`.
 For one-off use without a global installation, prefix a command with
 `pnpm dlx @iamdevlinph/codex-kit@latest`.
 
-`global install` copies reusable agents to `${CODEX_HOME:-~/.codex}`, maintains
-a marked routing section in the global `AGENTS.md`, and adds package-owned
-handlers to the global `hooks.json` without replacing existing hooks.
+`global install` copies reusable agents and the
+`skills/codex-kit-reconcile-agents` skill to `${CODEX_HOME:-~/.codex}`, maintains
+the package routing section in global `AGENTS.md`, and adds package-owned
+handlers to `hooks.json` without replacing existing hooks. `global list` shows
+the reconciliation skill's ownership status. Install and uninstall preserve
+modified or user-owned skill files using the same backup/restore semantics as
+other package files.
 
 The Sol root plans, routes, coordinates, and validates. On every prompt, the
 routing hook supplies the current `SUBAGENT_ROUTING.md`; the root classifies the
@@ -41,6 +46,25 @@ 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.
 
+## Available subagents
+
+| Subagent | Routing | Model and effort | Used for |
+| --- | --- | --- | --- |
+| `code-explorer` | Automatic | `gpt-5.6-terra`, medium | Read-only broad repository discovery, contract tracing, and multi-file searches |
+| `implementer` | Automatic | `gpt-5.6-luna`, high | Large behavior changes, non-obvious debugging, migrations, and substantial tests |
+| `code-reviewer` | Automatic | `gpt-5.6-sol`, high | Read-only review of security-sensitive, architectural, public-API, concurrency, migration, or difficult-to-validate changes |
+| `quick-implementer` | Manual only | `gpt-5.6-luna`, medium | Small, mechanical, well-specified changes limited to one or two files |
+
+The root orchestrator is not a subagent. It owns planning, routing, integration,
+and final validation.
+
+For a substantial task that splits into genuinely independent slices, the root
+may run multiple `implementer` instances concurrently. Each receives exclusive
+file or module ownership and separate validation scope. Work that shares types,
+schemas, configuration, generated artifacts, migrations, lockfiles, or dependency
+ordering stays with one implementer or runs sequentially; multiple files alone
+do not justify duplicate agents.
+
 `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.
@@ -62,11 +86,6 @@ codex-kit global configure \
   --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
@@ -94,8 +113,8 @@ pnpm dlx @iamdevlinph/codex-kit@latest global list
 ```
 
 The summary shows the Codex home, orchestrator, normal and Plan-mode reasoning
-effort, routing-file and routing-hook status, and installed custom agents without
-dumping unrelated configuration.
+effort, routing-file and routing-hook status, reconciliation-skill status, and
+installed custom agents without dumping unrelated configuration.
 
 Uninstall package-managed global files:
 
@@ -133,13 +152,12 @@ pnpm dlx @iamdevlinph/codex-kit@latest project init
 
 This creates:
 
-- `AGENTS.md`, containing the reusable defaults and a project-specific section
+- `AGENTS.md`, containing a project-specific section ready for reconciliation
 - `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`.
+Add repository commands, paths, architecture, integrations, and exceptions to
+the project-specific section of `AGENTS.md`.
 
 ### Generate project-specific guidance
 
@@ -168,13 +186,14 @@ pnpm dlx @iamdevlinph/codex-kit@latest project sync
 codex-kit project status
 ```
 
-`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:
+`project sync` never edits `AGENTS.md` or project skills. It routes Codex to the
+global `codex-kit-reconcile-agents` skill, which inspects project state and
+existing skills, merges only applicable reusable changes, preserves local
+adaptations and organization, and may create or update a concrete conditional
+workflow under `.agents/skills`. Critical safety, authorization, secrets,
+database, deployment, and destructive-operation rules remain in `AGENTS.md`;
+do not copy the complete template or introduce managed markers. After semantic
+reconciliation and validation, record the applied template hash:
 
 ```sh
 codex-kit project mark-applied

package/assets/SUBAGENT_ROUTING.md

@@ -26,8 +26,17 @@ Select custom agents by exact name:
 For tasks with multiple phases, sequence only the roles that add value. For
 example, use `code-explorer` before implementation only when broad discovery is
 actually needed, and use `code-reviewer` after implementation only when the
-change meets its risk threshold. Avoid parallel write-heavy work and never assign
-overlapping files to multiple agents.
+change meets its risk threshold. Avoid parallel write-heavy work by default and
+never assign overlapping files to multiple agents.
+
+Multiple `implementer` instances may run concurrently only when a substantial
+task divides into genuinely independent slices. Give each instance exclusive
+ownership of named files or modules and a separate validation scope. Do not
+parallelize slices that share schemas, types, configuration, lockfiles, generated
+artifacts, migrations, or dependency ordering. If ownership overlaps or one
+slice depends on another, use one implementation agent or sequence the agents.
+The parent performs final integration validation after all slices return. Do not
+spawn duplicate agents merely because multiple files are involved.
 
 Prefer the parent fast path when delegation would cost more than the work. Do not
 spawn a subagent solely because a tool will write a file. Delegate based on task

package/assets/TEMPLATE_AGENTS.md

@@ -1,8 +1,7 @@
 # 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.
+product context, and local conventions in the project's active `AGENTS.md`.
 
 ## Context And Instruction Scope
 
@@ -37,15 +36,21 @@ the managed markers.
 
 ## 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.
+- `TEMPLATE_AGENTS.md` is a staged reference copy of codex-kit's reusable
+  instructions, not active project guidance. Active repository guidance lives
+  in `AGENTS.md` and applicable project skills under `.agents/skills`.
+- When the template is refreshed, `codex-kit project status` reports
+  `reconciliation required`, or a user requests template sync or mark-applied,
+  use the global `$codex-kit-reconcile-agents` skill. It compares the template
+  with `AGENTS.md`, project state, and existing skills; preserves local rules;
+  applies only relevant reusable changes; validates them; and marks applied
+  only after success.
+- Keep project-specific rules out of `TEMPLATE_AGENTS.md`. Treat local template
+  edits as candidates that must be generalized and promoted to the canonical
+  `assets/TEMPLATE_AGENTS.md` in the codex-kit repository. Updating `AGENTS.md`
+  does not update either template automatically.
+- Keep project-specific context out of the packaged template; keep only
+  reusable cross-project rules here.
 - 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
@@ -62,25 +67,16 @@ the managed markers.
 - 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. 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.
-```
+## Template reconciliation
+
+Do not copy the complete template into `AGENTS.md`, replace it wholesale, or
+introduce managed markers. If a legacy shared-template marker is present,
+preserve local content and reconcile its meaning safely without creating new
+markers. Summarize added, updated, skipped, adapted, and skill-moved guidance,
+including local/template conflicts and any generalized template-worthy
+promotion. Keep critical safety, authorization, secrets, database, deployment,
+and destructive-operation rules always-on in `AGENTS.md`; extract only concrete
+conditional procedures into validated project skills.
 
 ## Core Behavior
 
@@ -110,6 +106,13 @@ what moved into a skill, and whether any local rules appear template-worthy.
 - 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.
+- For behavior changes and bug fixes, add or update the smallest focused
+  automated tests that meaningfully prevent regression when the repository has
+  an established test setup.
+- Do not introduce a test framework or create low-value tests solely to satisfy
+  this rule. If automated coverage is impractical, explain why and perform the
+  strongest targeted verification available.
+- Run the relevant focused tests after changing tested behavior.
 - 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.

package/assets/skills/codex-kit-reconcile-agents/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: codex-kit-reconcile-agents
+description: Reconcile a refreshed TEMPLATE_AGENTS.md with a project's AGENTS.md and applicable skills while preserving local adaptations. Use when project status requires reconciliation, the template was refreshed, or the user requests an agent-template sync or mark-applied.
+---
+
+# Reconcile codex-kit agent guidance
+
+## Procedure
+
+1. Inspect `AGENTS.md`, `TEMPLATE_AGENTS.md`, `.codex-kit-state.json`, the
+   project's existing `.agents/skills`, and `codex-kit project status`. If a
+   codex-kit template backup exists, compare it with the refreshed template to
+   isolate the actual template change.
+2. Preserve the existing `AGENTS.md` organization and all project-specific
+   adaptations. Merge only reusable template guidance that applies to this
+   repository; report conflicts between local and template rules, and do not
+   replace `AGENTS.md` wholesale or copy the complete template into it.
+3. Keep critical always-on safety, authorization, secrets, database,
+   deployment, and destructive-operation rules in `AGENTS.md`.
+4. Extract only concrete, conditional, repeatable project procedures into a
+   focused skill under `.agents/skills/<skill-name>/SKILL.md`. Preserve relevant
+   existing skills, use valid YAML frontmatter, and do not create speculative
+   skills or duplicate detailed instructions.
+5. Review the final instruction diff for preserved local rules, duplicates, and
+   unintended template edits. Validate every created or modified project skill
+   with an available skill validator and run the repository's documented checks.
+   Do not mark the template applied until reconciliation and validation succeed.
+6. Run `codex-kit project mark-applied` only after successful reconciliation and
+   validation, then confirm `codex-kit project status` is up to date.
+7. Summarize added, updated, skipped, adapted, and skill-moved guidance, with
+   reasons. Identify genuinely reusable, generalized changes that should be
+   promoted to codex-kit's canonical template and report the target section and
+   wording.
+
+If legacy `codex-kit:shared-template` markers are present, preserve local
+content and reconcile their meaning semantically. Do not add, recreate, or
+depend on managed markers, and do not discard local adaptations.

package/assets/skills/codex-kit-reconcile-agents/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Reconcile Codex Agent Guidance"
+  short_description: "Semantically reconcile templates and project skills"
+  default_prompt: "Use $codex-kit-reconcile-agents to reconcile this project's agent guidance."

package/bin/codex-kit.js

@@ -9,6 +9,10 @@ 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 SKILLS_DIR = join(ASSETS, "skills");
+const RECONCILE_SKILL = "codex-kit-reconcile-agents";
+const RECONCILE_SKILL_FILE = join(SKILLS_DIR, RECONCILE_SKILL, "SKILL.md");
+const RECONCILE_SKILL_METADATA_FILE = join(SKILLS_DIR, RECONCILE_SKILL, "agents", "openai.yaml");
 const ROUTING_FILE = join(ASSETS, "SUBAGENT_ROUTING.md");
 const ROUTING_HOOK_FILE = join(ROOT, "bin", "routing-hook.js");
 const TEMPLATE_FILE = join(ASSETS, "TEMPLATE_AGENTS.md");
@@ -266,29 +270,15 @@ function saveProjectState(cwd, state) {
     write(join(cwd, PROJECT_STATE_FILE), `${JSON.stringify(state, null, 2)}\n`);
 }
 function templatePrompt() {
-    return `Template reference updated. Ask Codex:
+    return `Template reference updated. Use the global $${RECONCILE_SKILL} skill to reconcile it semantically.
 
-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.`;
+Inspect TEMPLATE_AGENTS.md, AGENTS.md, .codex-kit-state.json, existing
+.agents/skills, and codex-kit project status. Preserve local adaptations and
+AGENTS.md organization; merge only applicable reusable guidance. Keep critical
+always-on safety and authorization rules in AGENTS.md, extract only concrete
+conditional procedures into validated skills, and do not copy the complete
+template or introduce managed markers. Mark applied only after reconciliation
+and validation, then report any template-worthy generalized promotion.`;
 }
 function managedBlock(content, begin, end) {
     return `${begin}\n${content.trimEnd()}\n${end}`;
@@ -367,6 +357,12 @@ function installGlobal(options) {
     const routingRecord = installFile(ROUTING_FILE, join(home, "SUBAGENT_ROUTING.md"), "routing", prior, options.force);
     if (routingRecord)
         next.files.routing = routingRecord;
+    const reconciliationSkill = installFile(RECONCILE_SKILL_FILE, join(home, "skills", RECONCILE_SKILL, "SKILL.md"), `skills/${RECONCILE_SKILL}/SKILL.md`, prior, options.force);
+    if (reconciliationSkill)
+        next.files[`skills/${RECONCILE_SKILL}/SKILL.md`] = reconciliationSkill;
+    const reconciliationSkillMetadata = installFile(RECONCILE_SKILL_METADATA_FILE, join(home, "skills", RECONCILE_SKILL, "agents", "openai.yaml"), `skills/${RECONCILE_SKILL}/agents/openai.yaml`, prior, options.force);
+    if (reconciliationSkillMetadata)
+        next.files[`skills/${RECONCILE_SKILL}/agents/openai.yaml`] = reconciliationSkillMetadata;
     const hookRecord = installFile(ROUTING_HOOK_FILE, join(home, "codex-kit", "routing-hook.js"), "routing-hook", prior, options.force);
     if (hookRecord)
         next.files["routing-hook"] = hookRecord;
@@ -491,6 +487,16 @@ function listGlobal(options) {
         existsSync(routingHook.target) &&
         readText(routingHook.target).includes(routingHook.command));
     console.log(`Routing hook: ${hooksInstalled ? "installed" : "not installed"}`);
+    const skillTargets = [
+        [join(home, "skills", RECONCILE_SKILL, "SKILL.md"), state.files[`skills/${RECONCILE_SKILL}/SKILL.md`]],
+        [join(home, "skills", RECONCILE_SKILL, "agents", "openai.yaml"), state.files[`skills/${RECONCILE_SKILL}/agents/openai.yaml`]],
+    ];
+    const skillStatus = skillTargets.every(([target, record]) => existsSync(target) && record && sha256(read(target)) === record.hash)
+        ? "installed"
+        : skillTargets.some(([target]) => existsSync(target))
+            ? "modified or incomplete"
+            : "missing";
+    console.log(`Reconciliation skill: ${skillStatus}`);
     console.log("Custom agents:");
     const agents = existsSync(agentsDir)
         ? readdirSync(agentsDir).filter((name) => name.endsWith(".toml")).sort()
@@ -574,6 +580,14 @@ function uninstallGlobal(options) {
     }
     if (state.hooks)
         uninstallRoutingHooks(state.hooks);
+    const skillDir = join(home, "skills", RECONCILE_SKILL);
+    const skillMetadataDir = join(skillDir, "agents");
+    if (existsSync(skillMetadataDir) && statSync(skillMetadataDir).isDirectory() && !readdirSync(skillMetadataDir).length) {
+        rmSync(skillMetadataDir, { recursive: true });
+    }
+    if (existsSync(skillDir) && statSync(skillDir).isDirectory() && !readdirSync(skillDir).length) {
+        rmSync(skillDir, { recursive: true });
+    }
     const allowancesDir = join(home, "codex-kit", "allowances");
     if (existsSync(allowancesDir))
         rmSync(allowancesDir, { recursive: true, force: true });
@@ -622,7 +636,10 @@ function syncProject(options) {
     };
     saveProjectState(cwd, state);
     if (!existsSync(agentsFile)) {
-        const contents = "# Project-Specific Instructions\n\n<!-- Add repository-specific commands, architecture, and exceptions here. -->\n";
+        const contents = `# Project-Specific Instructions
+
+<!-- Add repository-specific commands, architecture, and exceptions here. -->
+`;
         write(agentsFile, contents);
         console.log(`created project instructions file: ${agentsFile}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamdevlinph/codex-kit",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "assets/agents",
     "assets/SUBAGENT_ROUTING.md",
     "assets/TEMPLATE_AGENTS.md",
+    "assets/skills",
     "bin"
   ],
   "scripts": {