@iamdevlinph/codex-kit 1.1.6 → 1.1.7

package/README.md

@@ -119,6 +119,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 +136,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:

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

@@ -612,6 +612,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,12 +628,16 @@ 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

package/package.json

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