@iamdevlinph/codex-kit 1.1.6 → 1.1.8

package/README.md

@@ -60,6 +60,12 @@ existing active guidance. During reconciliation, Codex merges only applicable
 rules into the project's `AGENTS.md` and preserves its local organization and
 adaptations.
 
+Both `project init` and `project sync` contact the public npm registry before
+writing project files. If the installed CLI is stale, or npm is unreachable or
+returns invalid metadata, the command fails without changing the project. Rerun
+with `pnpm dlx @iamdevlinph/codex-kit@latest` after the registry is available;
+stale builds print the exact command.
+
 ## Commands
 
 | Action | Command |
@@ -119,6 +125,13 @@ configuration, and scripts for Codex to derive reliable guidance. It creates:
 - `TEMPLATE_AGENTS.md` as the local template reference;
 - `.codex-kit-state.json` for reconciliation bookkeeping.
 
+The CLI continues to create only this scaffold, template reference, and state
+file set. During semantic reconciliation, Codex may create or maintain
+`PLANS.md` when repository evidence supports real durable decisions,
+roadmap/status, or resume-worthy completed milestones. Existing `PLANS.md`
+content is preserved and semantically merged; speculative history is never
+invented or backfilled.
+
 Initialization includes the first template sync. When the CLI prints an
 initialization or reconciliation prompt, copy the complete marked block into a
 Codex task opened at the project root.
@@ -129,11 +142,15 @@ After installing a newer package version, refresh the reference template:
 codex-kit project sync
 ```
 
-`project sync` never edits `AGENTS.md` or project skills. The reconciliation skill
-compares the refreshed template with the project's guidance and merges only
-applicable rules while preserving local organization and adaptations. If
+`project sync` never edits `AGENTS.md`, `PLANS.md`, or project skills. The
+reconciliation skill compares the refreshed template with the project's
+guidance and merges only applicable rules while preserving local organization
+and adaptations. It keeps always-on instructions in `AGENTS.md`, moves durable
+roadmap or history out of that file into `PLANS.md`, and reports any created or
+changed plan content. If
 `TEMPLATE_AGENTS.md` was modified locally, sync overwrites it with the packaged
-template. Keep durable local rules in `AGENTS.md`; recover overwritten template
+template. Keep always-on local rules in `AGENTS.md` and durable product context
+in `PLANS.md`; recover overwritten template
 edits through Git history when needed.
 
 After reconciliation and validation, Codex runs:
@@ -168,7 +185,10 @@ codex-kit project sync --cwd /path/to/project
 - Codex with custom subagent and lifecycle-hook support
 
 The published package contains no credentials or runtime dependencies. Version
-checks contact the public npm registry only when `codex-kit version check` runs.
+checks and project initialization/synchronization contact the public npm
+registry; project operations fail closed before writing when that check cannot
+verify the latest release. The CLI never auto-installs or executes downloaded
+code.
 
 ## Security and license
 

package/assets/TEMPLATE_AGENTS.md

@@ -12,6 +12,18 @@ product context, and local conventions in the project's active `AGENTS.md`.
   priorities, deferred requirements, product or implementation decisions, and
   major completed milestones.
 
+## PLANS.md Maintenance
+
+- Read and preserve an existing `PLANS.md` during initialization and template
+  reconciliation; semantically merge durable content instead of replacing it.
+- Create `PLANS.md` only when repository evidence contains real roadmap items,
+  durable decisions, or resume-worthy completed work. Never invent or backfill
+  speculative history.
+- Keep it concise, using sections such as current context, decisions,
+  roadmap/status, and major milestones. It is not a per-change changelog.
+- Move roadmap or history misplaced in `AGENTS.md` into `PLANS.md` when the
+  content is durable, and keep `AGENTS.md` focused on always-on instructions.
+
 ## Instructions And Skills
 
 - Keep `AGENTS.md` focused on durable, always-applicable repository context:

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

@@ -7,24 +7,32 @@ description: Reconcile a refreshed TEMPLATE_AGENTS.md with a project's AGENTS.md
 
 ## Procedure
 
-1. Inspect `AGENTS.md`, `TEMPLATE_AGENTS.md`, `.codex-kit-state.json`, the
-   project's existing `.agents/skills`, and `codex-kit project status`. Record
-   the initial status before making changes.
-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.
+1. Inspect `AGENTS.md`, any existing `PLANS.md`, `TEMPLATE_AGENTS.md`,
+   `.codex-kit-state.json`, the project's existing `.agents/skills`, and
+   `codex-kit project status`. Record the initial status before making changes.
+2. Preserve the existing `AGENTS.md` and `PLANS.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
+4. Preserve an existing `PLANS.md` and semantically merge durable product
+   context, decisions, roadmap/status, and resume-worthy milestones. Create it
+   only when repository evidence contains real durable content; never invent or
+   backfill speculative history. Move durable roadmap or history misplaced in
+   `AGENTS.md` into `PLANS.md`, keeping it concise rather than turning it into a
+   per-change changelog. Report whether `PLANS.md` was preserved, created, or
+   updated and why.
+5. 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
+6. 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. Never run `codex-kit project sync` on the user's behalf or recommend it for
+7. Never run `codex-kit project sync` on the user's behalf or recommend it for
    an unreleased local template edit. The user should run `project sync` only
    after updating codex-kit to a released version containing the template
    change. Run `codex-kit project mark-applied` only when the task follows a
@@ -32,7 +40,7 @@ description: Reconcile a refreshed TEMPLATE_AGENTS.md with a project's AGENTS.md
    recorded in step 1 was `reconciliation required`, and reconciliation and
    validation succeeded. Otherwise leave project state unchanged and report the
    remaining release, codex-kit update, user-run sync, and reconciliation steps.
-7. Summarize added, updated, skipped, adapted, and skill-moved guidance, with
+8. 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.

package/bin/codex-kit.js

@@ -575,6 +575,87 @@ function uninstallGlobal(options) {
 // src/project/commands.ts
 import { existsSync as existsSync6, statSync as statSync2 } from "node:fs";
 import { join as join6 } from "node:path";
+
+// src/version.ts
+function parseVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value);
+  if (!match) throw new Error(`Invalid package version: ${value}`);
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ?? null
+  };
+}
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  for (const [leftNumber, rightNumber] of [
+    [a.numbers[0], b.numbers[0]],
+    [a.numbers[1], b.numbers[1]],
+    [a.numbers[2], b.numbers[2]]
+  ])
+    if (leftNumber !== rightNumber) return Math.sign(leftNumber - rightNumber);
+  if (a.prerelease === b.prerelease) return 0;
+  if (!a.prerelease) return 1;
+  if (!b.prerelease) return -1;
+  return Math.sign(
+    a.prerelease.localeCompare(b.prerelease, "en", { numeric: true })
+  );
+}
+async function fetchLatestVersion() {
+  const url = `${REGISTRY}/${encodeURIComponent(PACKAGE.name)}/latest`;
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(15e3) });
+  } catch (error) {
+    throw new Error(
+      `Unable to check ${REGISTRY}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!response.ok)
+    throw new Error(
+      `Unable to check ${REGISTRY}: ${response.status} ${response.statusText}`
+    );
+  let value;
+  try {
+    value = await response.json();
+  } catch {
+    throw new Error("Registry returned no package version.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.version !== "string")
+    throw new Error("Registry returned no package version.");
+  const latest = value.version;
+  parseVersion(latest);
+  return latest;
+}
+async function getLatestVersion() {
+  const override = process.env.CODEX_KIT_LATEST_VERSION;
+  if (override) {
+    parseVersion(override);
+    return override;
+  }
+  return fetchLatestVersion();
+}
+async function checkVersion() {
+  const latest = await getLatestVersion();
+  console.log(`Installed: ${PACKAGE.version}`);
+  console.log(`Latest:    ${latest}`);
+  const comparison = compareVersions(PACKAGE.version, latest);
+  if (comparison === 0) {
+    console.log("codex-kit is up to date.");
+    return;
+  }
+  if (comparison > 0) {
+    console.log("This local build is newer than the published package.");
+    return;
+  }
+  console.log(
+    `Update available. Run:
+  pnpm add --global ${PACKAGE.name}@latest
+  codex-kit global install`
+  );
+}
+
+// src/project/commands.ts
 var STATE_FILE2 = ".codex-kit-state.json";
 var PROJECT_BEGIN = "<!-- BEGIN codex-kit:shared-template -->";
 var PROJECT_END = "<!-- END codex-kit:shared-template -->";
@@ -612,6 +693,11 @@ project-specific guidance to AGENTS.md based only on repository evidence,
 including exact verification commands. Then use the global
 $${RECONCILE_SKILL} skill to merge applicable reusable guidance from
 TEMPLATE_AGENTS.md while preserving AGENTS.md organization and local rules.
+Inspect and preserve any existing PLANS.md. Create or maintain a concise
+PLANS.md only when repository evidence contains real roadmap items, durable
+decisions, or resume-worthy completed work; never invent or backfill speculative
+history. Keep always-on repository instructions in AGENTS.md, move misplaced
+roadmap or history into PLANS.md, and report what PLANS.md work was done.
 Validate the final instruction changes, mark the template applied only after
 validation succeeds, and confirm codex-kit project status is up to date.
 ===== END CODEX INITIALIZATION PROMPT =====`;
@@ -623,21 +709,33 @@ function reconciliationPrompt() {
 Use the global $${RECONCILE_SKILL} skill to reconcile the existing AGENTS.md
 with the refreshed TEMPLATE_AGENTS.md.
 
-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.
+Inspect TEMPLATE_AGENTS.md, AGENTS.md, PLANS.md, .codex-kit-state.json,
+existing .agents/skills, and codex-kit project status. Preserve local
+adaptations and AGENTS.md/PLANS.md organization; merge only applicable reusable
+guidance. Preserve an existing PLANS.md, and create or update it only for
+evidence-backed durable decisions, roadmap/status, or resume-worthy milestones.
+Never invent or backfill speculative history. Move misplaced roadmap or history
+out of AGENTS.md, keeping critical always-on safety and authorization rules in
+AGENTS.md. The reconciliation must extract only concrete conditional procedures
+into validated skills. Do not copy the complete template or introduce managed
+markers. Report what PLANS.md content was preserved, created, or changed.
 
 Validate the final instruction changes. Mark applied only after reconciliation
 and validation succeed, confirm codex-kit project status is up to date, then
 report any template-worthy generalized promotion.
 ===== END CODEX RECONCILIATION PROMPT =====`;
 }
-function syncProject(options) {
+async function syncProject(options, action = "sync") {
   const { cwd } = options;
   requireDirectory(cwd);
+  const latest = await getLatestVersion();
+  if (compareVersions(PACKAGE.version, latest) < 0)
+    throw new Error(
+      `Installed: ${PACKAGE.version}
+Latest:    ${latest}
+Published guidelines are newer than this local build. Rerun with:
+  pnpm dlx ${PACKAGE.name}@latest project ${action} --cwd '${cwd.replaceAll("'", "'\\''")}'`
+    );
   const agentsFile = join6(cwd, "AGENTS.md");
   const stagedTemplate = join6(cwd, "TEMPLATE_AGENTS.md");
   const desired = Buffer.from(readText(TEMPLATE_FILE));
@@ -735,79 +833,6 @@ function markApplied(options) {
   console.log(`recorded template reconciliation: ${stagedTemplate}`);
 }
 
-// src/version.ts
-function parseVersion(value) {
-  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value);
-  if (!match) throw new Error(`Invalid package version: ${value}`);
-  return {
-    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
-    prerelease: match[4] ?? null
-  };
-}
-function compareVersions(left, right) {
-  const a = parseVersion(left);
-  const b = parseVersion(right);
-  for (const [leftNumber, rightNumber] of [
-    [a.numbers[0], b.numbers[0]],
-    [a.numbers[1], b.numbers[1]],
-    [a.numbers[2], b.numbers[2]]
-  ])
-    if (leftNumber !== rightNumber) return Math.sign(leftNumber - rightNumber);
-  if (a.prerelease === b.prerelease) return 0;
-  if (!a.prerelease) return 1;
-  if (!b.prerelease) return -1;
-  return Math.sign(
-    a.prerelease.localeCompare(b.prerelease, "en", { numeric: true })
-  );
-}
-async function fetchLatestVersion() {
-  const url = `${REGISTRY}/${encodeURIComponent(PACKAGE.name)}/latest`;
-  let response;
-  try {
-    response = await fetch(url, { signal: AbortSignal.timeout(15e3) });
-  } catch (error) {
-    throw new Error(
-      `Unable to check ${REGISTRY}: ${error instanceof Error ? error.message : String(error)}`
-    );
-  }
-  if (!response.ok)
-    throw new Error(
-      `Unable to check ${REGISTRY}: ${response.status} ${response.statusText}`
-    );
-  let value;
-  try {
-    value = await response.json();
-  } catch {
-    throw new Error("Registry returned no package version.");
-  }
-  if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.version !== "string")
-    throw new Error("Registry returned no package version.");
-  const latest = value.version;
-  parseVersion(latest);
-  return latest;
-}
-async function checkVersion() {
-  let latest = process.env.CODEX_KIT_LATEST_VERSION;
-  if (!latest) latest = await fetchLatestVersion();
-  if (!latest) throw new Error("Registry returned no package version.");
-  console.log(`Installed: ${PACKAGE.version}`);
-  console.log(`Latest:    ${latest}`);
-  const comparison = compareVersions(PACKAGE.version, latest);
-  if (comparison === 0) {
-    console.log("codex-kit is up to date.");
-    return;
-  }
-  if (comparison > 0) {
-    console.log("This local build is newer than the published package.");
-    return;
-  }
-  console.log(
-    `Update available. Run:
-  pnpm add --global ${PACKAGE.name}@latest
-  codex-kit global install`
-  );
-}
-
 // src/cli/options.ts
 import { homedir } from "node:os";
 import { join as join7, resolve as resolve2 } from "node:path";
@@ -856,8 +881,8 @@ Commands:
   global configure     Set the orchestrator and normal/Plan reasoning defaults.
   global list          Show model settings, routing status, and custom agents.
   global uninstall     Restore managed config values and remove package-owned files.
-  project init         Initialize AGENTS.md, TEMPLATE_AGENTS.md, and project state.
-  project sync         Refresh TEMPLATE_AGENTS.md without editing AGENTS.md.
+  project init         Initialize project files after checking the latest npm release.
+  project sync         Refresh the template after checking the latest npm release.
   project status       Show whether template changes still need reconciliation.
   project mark-applied Record the current template as reconciled with AGENTS.md.
   version check        Compare the installed version with the latest npm release.
@@ -882,6 +907,7 @@ Options by command:
 
   project init, project sync
     --cwd PATH  Use a project directory other than the current directory.
+                npm access is required; stale or unverifiable builds fail before writes.
 
   project status, project mark-applied
     --cwd PATH  Use a project directory other than the current directory.
@@ -910,7 +936,7 @@ async function main(argv = process.argv.slice(2)) {
   else if (scope === "global" && action === "uninstall")
     uninstallGlobal(options);
   else if (scope === "project" && (action === "init" || action === "sync"))
-    syncProject(options);
+    await syncProject(options, action);
   else if (scope === "project" && action === "status") projectStatus(options);
   else if (scope === "project" && action === "mark-applied")
     markApplied(options);

package/package.json

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