@iamdevlinph/codex-kit 1.0.10 → 1.0.11

package/README.md

@@ -41,6 +41,13 @@ 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.
 
+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.
@@ -133,13 +140,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
 

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

@@ -37,13 +37,17 @@ 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.
+- `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 `codex-kit project status` reports `reconciliation required`, compare the
+  template reference with `AGENTS.md`, apply relevant reusable changes, preserve
+  project-specific rules, reconcile applicable skills, then run
+  `codex-kit project mark-applied`.
+- 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 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
@@ -78,8 +82,9 @@ 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.
+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
@@ -110,6 +115,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/bin/codex-kit.js

@@ -622,7 +622,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.11",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {