@iamdevlinph/codex-kit 1.0.9 → 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
 
@@ -168,9 +174,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

@@ -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

@@ -13,15 +13,41 @@ 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
-  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
@@ -52,8 +78,13 @@ 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
@@ -84,6 +115,13 @@ 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

@@ -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}`;
@@ -600,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.9",
+  "version": "1.0.11",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {