Merge pull request #62 from MSiccDev/development

fix toolkit drift and update version

Author: MSicc

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- spec_version: 1.4.2 -->
+<!-- spec_version: 1.4.3 -->
 
 # AI Context Kit Agent Guide
 
@@ -11,7 +11,7 @@ This repository distinguishes:
 
 ## Source Of Truth And Precedence
 Use this order when files differ:
-1. **Specification (authoritative, v1.4.2):** `specs/context_aware_ai_session_spec.md`
+1. **Specification (authoritative, v1.4.3):** `specs/context_aware_ai_session_spec.md`
 2. **Templates (canonical structures):** `templates/*.instructions.md` and `templates/skill_template/SKILL.md`
 3. **Skills (canonical operational workflows):** `skills/*/SKILL.md` and skill-local references
 4. **Prompts:** `prompts/skills/*.prompt.md` (compatibility wrappers — must defer detailed logic to skills); `prompts/loop/*.prompt.md` (implementation loop steps — self-contained workflow prompts)
@@ -116,7 +116,7 @@ Alias policy:
 - Validation: skill-based validation workflows and reports
 
 ### Current Objectives
-- Keep templates and skills aligned with spec `v1.4.2`.
+- Keep templates and skills aligned with spec `v1.4.3`.
 - Maintain the AGENTS-first project-context model.
 - Preserve deterministic behavior and path stability.
 - Reduce duplication and migration noise.
@@ -197,7 +197,7 @@ When `specs/context_aware_ai_session_spec.md` changes, audit and update all impa
 - `AGENTS.md`
 
 ## Key References
-- Specification (v1.4.2): [`specs/context_aware_ai_session_spec.md`](specs/context_aware_ai_session_spec.md)
+- Specification (v1.4.3): [`specs/context_aware_ai_session_spec.md`](specs/context_aware_ai_session_spec.md)
 - Project operational defaults: this root `AGENTS.md` (Default State For This Repo)
 - User context template: [`templates/usercontext_template.instructions.md`](templates/usercontext_template.instructions.md)
 - Skill template: [`templates/skill_template/SKILL.md`](templates/skill_template/SKILL.md)

CHANGELOG.md

@@ -15,6 +15,37 @@ When a new version is released:
 
 ---
 
+## [1.4.3] - 2026-07-07
+
+### Fixed
+- Replaced all surviving `deterministic` phrasing (spec §4.1 footnote, §10.8 workflow table; README session state section) with `consistent and predictable` — aligns with the reduced-variance language established in v1.4.2
+- Removed stale `agents/openai.yaml` sidecar claim from README Codex section (sidecars were deleted in v1.4.2 but the description was not updated)
+- Corrected Copilot platform table row: Copilot Code Review does support `AGENTS.md`; removed incorrect caveat and expanded label to reflect full Copilot coverage
+- Replaced `"Works seamlessly"` with honest cross-platform framing that matches the platform-variance caveat already present in the same section
+- Added provenance note to `agentskills.io` link — clarifies it is a third-party community site, not a project-maintained resource
+- Corrected `CLAUDE.md` / `.cursorrules` comparison: `"No layering"` was factually wrong (both support nested files); reframed around the actual gap — no personal/project separation that travels across tools
+- Added deprecation callout to template repository section directing new users to the plugin instead
+
+### Safe to update from template
+- `specs/context_aware_ai_session_spec.md`
+- `README.md`
+- `templates/usercontext_template.instructions.md`
+- `templates/AGENTS_template.md`
+- `skills/create-agents-md/SKILL.md`
+- `skills/create-project-instructions/SKILL.md`
+- `skills/create-usercontext-instructions/SKILL.md`
+- `skills/create-usercontext-instructions/references/quality-checklist.md`
+- `skills/validate-agents-md/SKILL.md`
+- `skills/validate-usercontext-instructions/SKILL.md`
+- `skills/validate-project-instructions/SKILL.md`
+
+### Protect (never overwrite)
+- Your personal `*_usercontext.instructions.md`
+- Your project `AGENTS.md`
+- Any custom skills you have created
+
+---
+
 ## [1.4.2] - 2026-05-12
 
 ### Added

README.md

@@ -21,7 +21,7 @@ What began as a way to extract and reuse prompts across AI providers has evolved
 
 - **Layered architecture** – Personal user context + project `AGENTS.md` context create complete AI workspace configurations
 - **Skill-based workflows** – Create and validate context files using reusable skills with detailed operational logic
-- **Provider-agnostic** – Works seamlessly across different LLM environments
+- **Provider-agnostic** – Designed to work across different LLM environments; results may vary by platform
 
 ### The System
 
@@ -32,7 +32,7 @@ This framework consists of:
 - **Session specification** – How AI assistants should maintain and adapt context during work sessions
 - **Templates in `templates/`** – Canonical artifact structures aligned to the spec
 
-All components are designed to work across hosted and local LLM environments, ensuring that every AI assistant understands your background, working style, and project context without repeated explanations. Results may vary by platform, so you may need to adjust your context files accordingly.
+All components are designed to work across hosted and local LLM environments, ensuring that every AI assistant understands your background, working style, and project context without repeated explanations. You may need to adjust your context files for specific platforms.
 
 ---
 
@@ -97,7 +97,7 @@ ai-context-kit/
 │   └── context_aware_ai_session_spec.md              # Specification for AI session management
 │
 ├── templates/
-│  ├── usercontext_template.instructions.md           # Canonical v1.4.2 user context template (authoritative)
+│  ├── usercontext_template.instructions.md           # Canonical v1.4.3 user context template (authoritative)
 │  ├── AGENTS_template.md                             # Canonical AGENTS template (authoritative)
 │  └── skill_template/SKILL.md                        # Canonical skill template
 │
@@ -130,7 +130,7 @@ ai-context-kit/
 
 ---
 
-## Canonical Authority (Spec v1.4.2)
+## Canonical Authority (Spec v1.4.3)
 
 When guidance differs across files, use this authority order:
 
@@ -180,23 +180,23 @@ Session state is the active set of context values that governs assistant behavio
 | **Tone** | Communication style | Project defaults in `AGENTS.md` | Yes |
 | **Interaction Mode** | Initiative level (`advisory`, `pair`, `driver`) | Project defaults in `AGENTS.md` | Yes |
 
-Note: Interaction Mode is optional in the abstract session model, but project `AGENTS.md` should define a default to keep startup behavior deterministic.
+Note: Interaction Mode is optional in the abstract session model, but project `AGENTS.md` should define a default to keep startup behavior consistent and predictable.
 
 State behavior rules:
 - State persists across turns until explicitly changed or reset.
 - No silent transitions: project, role, phase, style, tone, and interaction mode must not change implicitly.
 - State can be changed with natural language or namespaced commands (for example `/namespace.mode`, `/namespace.phase`, `/namespace.style`, `/namespace.tone`, `/namespace.interact`).
 - `/namespace.context` shows current active state; `/namespace.reset` resets session state.
 
-**Purpose:** Keeps behavior deterministic, transparent, and aligned as work moves between planning, implementation, debugging, and review.
+**Purpose:** Keeps behavior consistent, transparent, and aligned as work moves between planning, implementation, debugging, and review.
 
 ---
 
 ## Agent Skills
 
 This repository provides for reusable **Agent Skills** for authoring and validation.
 
-- Documentation reference: https://agentskills.io/home
+- Documentation reference: https://agentskills.io/home *(third-party community site for the Agent Skills format — not maintained by this project)*
 - Canonical paths:
   - `templates/skill_template/SKILL.md`
   - `skills/`
@@ -260,13 +260,13 @@ The following paths are considered **canonical**:
 - `AGENTS.md`
   - Primary agent entrypoint (repo-specific operational contract)
 - `templates/`
-  - Canonical instruction templates (spec v1.4.2)
+  - Canonical instruction templates (spec v1.4.3)
 - `skills/`
   - Canonical workflow skills (`SKILL.md`-based folders)
 - `prompts/`
   - Composition wrappers for instruction/skill workflows
 - `specs/context_aware_ai_session_spec.md`
-  - Authoritative specification (v1.4.2+)
+  - Authoritative specification (v1.4.3+)
 - Root `README.md`
   - Human-facing entry point and workflow documentation
 
@@ -306,7 +306,7 @@ If paths must change, update the specification and README first, then adjust ski
 | Platform | Method | Limitations / Notes |
 |----------|---------|---------------------|
 | **Anthropic Claude Projects** | Add user context and `AGENTS.md` to project knowledge or project instructions | Large files compete with conversation history for context window space; keep files concise |
-| **GitHub Copilot (VS Code/IDE, coding agent)** | Keep `AGENTS.md` in your project root; Copilot reads it automatically | Copilot Code Review does not yet support `AGENTS.md` — add `.github/copilot-instructions.md` if you need Code Review coverage |
+| **GitHub Copilot (VS Code/IDE, coding agent, code review)** | Keep `AGENTS.md` in your project root; Copilot reads it automatically | — |
 | **OpenAI ChatGPT** | Paste user context into **Custom Instructions**; upload `AGENTS.md` as a file attachment | Custom Instructions has a tight character limit — long user context files will be silently truncated; maintain a condensed version and consult current OpenAI documentation for the latest limit |
 | **OpenAI Codex** | Keep `AGENTS.md` in your project root; Codex reads it automatically | — |
 | **Local scripts / APIs** | Concatenate user context + `AGENTS.md` when initializing conversations | Context window management is your responsibility; monitor token usage for long sessions |
@@ -397,8 +397,6 @@ claude plugin update ai-context-kit
 
 Codex auto-discovers skills from the `.agents/skills/` directory, scanning upward from the current working directory to the repo root. AI Context Kit ships a `.agents/skills/` directory whose entries are symlinks to the canonical `skills/` folders, so repo-local skill discovery and plugin packaging both point at the same source of truth.
 
-Each skill also includes an `agents/openai.yaml` sidecar (`skills/<name>/agents/openai.yaml`) with UI metadata consumed by the Codex skill picker.
-
 ### Auto-discovery (no install needed)
 
 If you clone this repo and run Codex from within it, all 11 skills are discovered automatically. No registration or import is required for repo-local use.
@@ -488,7 +486,7 @@ Each project `AGENTS.md` should define:
 - **Languages:** LLMs work best when instructions are in English, but you can include multilingual content in user context if needed (just be aware of potential comprehension issues)
 - **Versioning:** Update user context when skills/preferences evolve; update project `AGENTS.md` when phases/objectives change. Ideally, these should live in the same repository as your codebase once they are created.
 - **Discoverability:** Semantic file extensions help AI tools identify and load the appropriate instructions automatically
-- **Canonical structure:** The templates in `/templates` define the only supported artifact structures for spec v1.4.2
+- **Canonical structure:** The templates in `/templates` define the only supported artifact structures for spec v1.4.3
 
 ---
 
@@ -519,7 +517,7 @@ Each project `AGENTS.md` should define:
 
 | Approach | What it gives you | What's missing |
 |----------|------------------|----------------|
-| Single `CLAUDE.md` / `.cursorrules` | Quick, zero-overhead context for one tool | No portability, no layering, no validation — one file per tool |
+| Single `CLAUDE.md` / `.cursorrules` | Quick, zero-overhead context for one tool | No personal/project separation — the same file covers everything, no cross-tool portability, no structured validation |
 | Handwritten system prompt | Full control over phrasing | Re-explained every session, not versionable, not portable |
 | Per-project `AGENTS.md` only | Project-specific agent behavior | No personal layer — AI still doesn't know who you are |
 | **AI Context Kit** | Layered (personal + project), portable across providers, versioned, validated, skill-reusable | More upfront setup |
@@ -538,6 +536,8 @@ Each project `AGENTS.md` should define:
 
 ## Getting Started with This Template Repository
 
+> **Recommended: install the plugin** (see [Installing as a Plugin](#installing-as-a-plugin) above). The template repository path below is being phased out — new users should install via plugin instead.
+
 This is a **GitHub template repository**. Here's how to use it:
 
 ### Creating Your Own Instance

docs/spec-rationale.md

@@ -1,13 +1,13 @@
 ---
 context_type: rationale
 document_type: companion_document
-spec_version: 1.4.2
+spec_version: 1.4.3
 created: 2025-10-20
 last_updated: 2026-05-09
 status: active
 ---
 
-# Spec Rationale & Extended Reference (v1.4.2)
+# Spec Rationale & Extended Reference (v1.4.3)
 
 This document is the companion to [`specs/context_aware_ai_session_spec.md`](../specs/context_aware_ai_session_spec.md). It contains the background reasoning, extended examples, project profile illustrations, end-to-end scenarios, and future enhancement notes that were removed from the normative spec to keep it readable.
 

skills/create-agents-md/SKILL.md

@@ -32,7 +32,7 @@ Load or attach this file's contents into your AI session to activate the workflo
 1. Run seven-phase discovery using `references/discovery-phases.md`.
 2. Apply required element contract from `references/required-elements.md`.
 3. Generate artifact using `references/output-format.md`.
-4. Stamp `<!-- spec_version: 1.4.2 -->` as an HTML comment at the top of the generated `AGENTS.md`.
+4. Stamp `<!-- spec_version: 1.4.3 -->` as an HTML comment at the top of the generated `AGENTS.md`.
 5. Validate result against `references/quality-checklist.md`.
 6. Ensure links/paths remain relative and repository-accurate.
 

skills/create-agents-md/agents/openai.yaml

@@ -35,7 +35,7 @@ Load or attach this file's contents into your AI session to activate the workflo
    - `references/command-template.md`
    - `references/role-template.md`
 4. Apply artifact/summary contract from `references/output-format.md`.
-5. Stamp `<!-- spec_version: 1.4.2 -->` as an HTML comment at the top of the generated `AGENTS.md`.
+5. Stamp `<!-- spec_version: 1.4.3 -->` as an HTML comment at the top of the generated `AGENTS.md`.
 6. Validate completeness using `references/quality-checklist.md` before final output.
 
 ## Output Expectations