From d5e0a949b85b98cb4c71ae45b033adeaafe7b9d7 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 08:25:27 +0200 Subject: [PATCH 01/12] chore(skills): remove openai sidecars --- skills/create-agents-md/agents/openai.yaml | 7 ------- skills/create-checkpoint/agents/openai.yaml | 7 ------- skills/create-project-instructions/agents/openai.yaml | 7 ------- skills/create-skill/agents/openai.yaml | 7 ------- skills/create-usercontext-instructions/agents/openai.yaml | 7 ------- skills/repository-drift-control/agents/openai.yaml | 7 ------- skills/restore-checkpoint/agents/openai.yaml | 7 ------- skills/validate-agents-md/agents/openai.yaml | 7 ------- skills/validate-project-instructions/agents/openai.yaml | 7 ------- skills/validate-skill/agents/openai.yaml | 7 ------- .../validate-usercontext-instructions/agents/openai.yaml | 7 ------- 11 files changed, 77 deletions(-) delete mode 100644 skills/create-agents-md/agents/openai.yaml delete mode 100644 skills/create-checkpoint/agents/openai.yaml delete mode 100644 skills/create-project-instructions/agents/openai.yaml delete mode 100644 skills/create-skill/agents/openai.yaml delete mode 100644 skills/create-usercontext-instructions/agents/openai.yaml delete mode 100644 skills/repository-drift-control/agents/openai.yaml delete mode 100644 skills/restore-checkpoint/agents/openai.yaml delete mode 100644 skills/validate-agents-md/agents/openai.yaml delete mode 100644 skills/validate-project-instructions/agents/openai.yaml delete mode 100644 skills/validate-skill/agents/openai.yaml delete mode 100644 skills/validate-usercontext-instructions/agents/openai.yaml diff --git a/skills/create-agents-md/agents/openai.yaml b/skills/create-agents-md/agents/openai.yaml deleted file mode 100644 index 7b52ac8..0000000 --- a/skills/create-agents-md/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Create AGENTS.md" - short_description: "Generate a root AGENTS.md for any repo" - default_prompt: "Use create-agents-md to generate an AGENTS.md file for this repository" - -policy: - allow_implicit_invocation: true diff --git a/skills/create-checkpoint/agents/openai.yaml b/skills/create-checkpoint/agents/openai.yaml deleted file mode 100644 index 6067f51..0000000 --- a/skills/create-checkpoint/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Create Checkpoint" - short_description: "Capture session state as a checkpoint file" - default_prompt: "Use create-checkpoint to capture the current session state before ending" - -policy: - allow_implicit_invocation: false diff --git a/skills/create-project-instructions/agents/openai.yaml b/skills/create-project-instructions/agents/openai.yaml deleted file mode 100644 index 236b00f..0000000 --- a/skills/create-project-instructions/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Create Project Instructions" - short_description: "Generate a project-context AGENTS.md" - default_prompt: "Use create-project-instructions to generate a project AGENTS.md with role and phase defaults" - -policy: - allow_implicit_invocation: true diff --git a/skills/create-skill/agents/openai.yaml b/skills/create-skill/agents/openai.yaml deleted file mode 100644 index b7671d3..0000000 --- a/skills/create-skill/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Create Skill" - short_description: "Generate a new canonical SKILL.md file" - default_prompt: "Use create-skill to generate a new SKILL.md artifact for a workflow skill" - -policy: - allow_implicit_invocation: true diff --git a/skills/create-usercontext-instructions/agents/openai.yaml b/skills/create-usercontext-instructions/agents/openai.yaml deleted file mode 100644 index 6cf4e69..0000000 --- a/skills/create-usercontext-instructions/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Create User Context" - short_description: "Create a user context instructions file" - default_prompt: "Use create-usercontext-instructions to create a user context file through structured discovery" - -policy: - allow_implicit_invocation: true diff --git a/skills/repository-drift-control/agents/openai.yaml b/skills/repository-drift-control/agents/openai.yaml deleted file mode 100644 index d88ea9c..0000000 --- a/skills/repository-drift-control/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Repository Drift Control" - short_description: "Check spec, template, and doc alignment" - default_prompt: "Use repository-drift-control to check and enforce consistency across spec, templates, and docs" - -policy: - allow_implicit_invocation: false diff --git a/skills/restore-checkpoint/agents/openai.yaml b/skills/restore-checkpoint/agents/openai.yaml deleted file mode 100644 index 68d4580..0000000 --- a/skills/restore-checkpoint/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Restore Checkpoint" - short_description: "Restore session state from a checkpoint file" - default_prompt: "Use restore-checkpoint to restore session state from a checkpoint artifact" - -policy: - allow_implicit_invocation: false diff --git a/skills/validate-agents-md/agents/openai.yaml b/skills/validate-agents-md/agents/openai.yaml deleted file mode 100644 index 6f1c5f5..0000000 --- a/skills/validate-agents-md/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Validate AGENTS.md" - short_description: "Validate an AGENTS.md with scored report" - default_prompt: "Use validate-agents-md to validate this AGENTS.md file and produce a scored compliance report" - -policy: - allow_implicit_invocation: true diff --git a/skills/validate-project-instructions/agents/openai.yaml b/skills/validate-project-instructions/agents/openai.yaml deleted file mode 100644 index ac57c29..0000000 --- a/skills/validate-project-instructions/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Validate Project Instructions" - short_description: "Validate a project AGENTS.md with scores" - default_prompt: "Use validate-project-instructions to validate a project-context AGENTS.md and produce a scored report" - -policy: - allow_implicit_invocation: true diff --git a/skills/validate-skill/agents/openai.yaml b/skills/validate-skill/agents/openai.yaml deleted file mode 100644 index 94aa425..0000000 --- a/skills/validate-skill/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Validate Skill" - short_description: "Validate a SKILL.md with scored report" - default_prompt: "Use validate-skill to validate this SKILL.md artifact and produce a scored compliance report" - -policy: - allow_implicit_invocation: true diff --git a/skills/validate-usercontext-instructions/agents/openai.yaml b/skills/validate-usercontext-instructions/agents/openai.yaml deleted file mode 100644 index 22137ee..0000000 --- a/skills/validate-usercontext-instructions/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Validate User Context" - short_description: "Validate user context file with scores" - default_prompt: "Use validate-usercontext-instructions to validate a user context file and produce a scored compliance report" - -policy: - allow_implicit_invocation: true From 1e3afce2e6e193fc2515cd46b6fa069f42ffe52b Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:17:28 +0200 Subject: [PATCH 02/12] fix(spec,readme): replace surviving 'deterministic' with consistent/predictable language The spec's Core Principles table was updated in PR #46 to use 'reduced variance' instead of 'determinism', but two spec footnotes and two README session-state descriptions kept the old term. This aligns all remaining occurrences with the established reduced-variance framing. Co-Authored-By: Claude Sonnet 5 --- README.md | 4 ++-- specs/context_aware_ai_session_spec.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 39d8819..ab28432 100644 --- a/README.md +++ b/README.md @@ -180,7 +180,7 @@ 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. @@ -188,7 +188,7 @@ State behavior rules: - 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. --- diff --git a/specs/context_aware_ai_session_spec.md b/specs/context_aware_ai_session_spec.md index 264645f..2fac925 100644 --- a/specs/context_aware_ai_session_spec.md +++ b/specs/context_aware_ai_session_spec.md @@ -85,7 +85,7 @@ When multiple `AGENTS.md` files exist: | **Tone** | Communication voice (analytical, direct, encouraging, neutral). | Yes | Yes | | **Interaction Mode** | Initiative level (advisory, pair-programming, driver). | Optional* | Yes | -*Project `AGENTS.md` files should define a default Interaction Mode to keep collaboration behavior deterministic at session start. +*Project `AGENTS.md` files should define a default Interaction Mode to keep startup behavior consistent and predictable. ### 4.2 Persistence Rules @@ -467,7 +467,7 @@ Skill-first repositories should group canonical skills into clear operational fa | Family | Purpose | |--------|---------| | Creation workflows | Generate or regenerate instruction artifacts | -| Validation workflows | Evaluate artifacts and produce deterministic findings | +| Validation workflows | Evaluate artifacts and produce consistent, reproducible findings | | Governance workflows | Coordinate repository-level policy, lifecycle, and drift control | --- From db9e32019c992e11641b3d6a9b9e26ea0206b899 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:17:45 +0200 Subject: [PATCH 03/12] fix(readme): remove stale openai.yaml sidecar claim PR #60 removed all skills/*/agents/openai.yaml sidecars but the Codex section of the README still described them. Remove the sentence since the files no longer exist. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index ab28432..9ea6350 100644 --- a/README.md +++ b/README.md @@ -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//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. From b3cbc552748d34325cae2efdfe73fb0dedd0c3cf Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:18:00 +0200 Subject: [PATCH 04/12] fix(readme): remove implied roadmap from Copilot Code Review caveat 'does not yet support' implied future support was planned. State the current limitation factually without making claims about GitHub's roadmap. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9ea6350..1022fa2 100644 --- a/README.md +++ b/README.md @@ -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)** | Keep `AGENTS.md` in your project root; Copilot reads it automatically | Copilot Code Review does not support `AGENTS.md` — add `.github/copilot-instructions.md` if you need Code Review coverage | | **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 | From 3e141850091c9f70fc4340d27c8944e2256d3f47 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:25:15 +0200 Subject: [PATCH 05/12] fix(readme): replace 'works seamlessly' with honest cross-platform framing 'Works seamlessly' directly contradicted the following sentence that acknowledged platform variance. Fold the caveat into the bullet and simplify the paragraph to remove the redundant restatement. Co-Authored-By: Claude Sonnet 5 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1022fa2..3773732 100644 --- a/README.md +++ b/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. --- From 8b8df484496fb2b6cbbedc2f0b076a3392ff5356 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:31:57 +0200 Subject: [PATCH 06/12] fix(readme): clarify agentskills.io is a third-party community site The link was presented without context, implying it was a canonical or project-maintained source. Add a parenthetical so readers know it is external and not maintained by this project. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3773732..5a72003 100644 --- a/README.md +++ b/README.md @@ -196,7 +196,7 @@ State behavior rules: 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/` From 329520285197aa2f95f8a751199599969bd5f09e Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:32:12 +0200 Subject: [PATCH 07/12] fix(readme): correct inaccurate CLAUDE.md comparison in alternatives table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'No layering' was wrong — CLAUDE.md and .cursorrules do support nested files. The real gap is the absence of a personal-vs-project separation that travels across all projects and tools. Reframe around what is actually missing rather than a capability these tools do have. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5a72003..509e5e8 100644 --- a/README.md +++ b/README.md @@ -517,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 | From c8b37b911b952a97c4e26f82a2bc3dd939a5ff03 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:32:39 +0200 Subject: [PATCH 08/12] fix(readme): clarify plugin vs template distribution models The README presented both distribution models without explaining the relationship. Add a brief callout at the top of the template section so readers understand when each model applies before committing to a fork. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 509e5e8..5e6635f 100644 --- a/README.md +++ b/README.md @@ -536,6 +536,8 @@ Each project `AGENTS.md` should define: ## Getting Started with This Template Repository +> **Plugin vs. template:** If you only need the skills, install the plugin (see [Installing as a Plugin](#installing-as-a-plugin) above) — no fork needed. Use the template route below if you want to own a private copy of the full framework and store your personal context files in the same repository. + This is a **GitHub template repository**. Here's how to use it: ### Creating Your Own Instance From 6277763af81d10388778ea496dfe56f4a8719329 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:46:34 +0200 Subject: [PATCH 09/12] fix(readme): correct Copilot Code Review AGENTS.md support claim The platform table incorrectly stated that Copilot Code Review does not support AGENTS.md. Copilot reads AGENTS.md across VS Code, the coding agent, and code review. Remove the false caveat and expand the platform label to reflect full Copilot support. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5e6635f..f96530a 100644 --- a/README.md +++ b/README.md @@ -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 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 | From d516cc2249167b8df1407f4e9b659a56a2f28734 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 10:49:13 +0200 Subject: [PATCH 10/12] fix(readme): deprecate template repository path in favour of plugin install The template distribution model is being phased out. Update the callout at the top of the template section to direct new users to the plugin instead of recommending the template fork. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f96530a..71be4c4 100644 --- a/README.md +++ b/README.md @@ -536,7 +536,7 @@ Each project `AGENTS.md` should define: ## Getting Started with This Template Repository -> **Plugin vs. template:** If you only need the skills, install the plugin (see [Installing as a Plugin](#installing-as-a-plugin) above) — no fork needed. Use the template route below if you want to own a private copy of the full framework and store your personal context files in the same 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: From abcb1db5021c0f94559f4f397e746a6bc9a838cf Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 11:06:04 +0200 Subject: [PATCH 11/12] fix(spec): align validation workflow phrasing with rest of PR MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changed 'consistent, reproducible' to 'consistent and predictable' to match the replacement wording used in all other deterministic → predictable changes in this branch (addressed Copilot review comment). Co-Authored-By: Claude Sonnet 5 --- specs/context_aware_ai_session_spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/context_aware_ai_session_spec.md b/specs/context_aware_ai_session_spec.md index 2fac925..6b7903d 100644 --- a/specs/context_aware_ai_session_spec.md +++ b/specs/context_aware_ai_session_spec.md @@ -467,7 +467,7 @@ Skill-first repositories should group canonical skills into clear operational fa | Family | Purpose | |--------|---------| | Creation workflows | Generate or regenerate instruction artifacts | -| Validation workflows | Evaluate artifacts and produce consistent, reproducible findings | +| Validation workflows | Evaluate artifacts and produce consistent and predictable findings | | Governance workflows | Coordinate repository-level policy, lifecycle, and drift control | --- From aa70aa946d5e7dd6a69a606f7cb38f4ac8b09259 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 7 Jul 2026 11:09:58 +0200 Subject: [PATCH 12/12] chore(release): bump version to 1.4.3 Patch release for communication drift fixes. Updates version references across spec, README, AGENTS.md, templates, skills, and sample artifacts. Adds CHANGELOG entry and updates spec last_updated date. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 8 ++--- CHANGELOG.md | 31 +++++++++++++++++++ README.md | 10 +++--- docs/spec-rationale.md | 4 +-- skills/create-agents-md/SKILL.md | 2 +- skills/create-project-instructions/SKILL.md | 2 +- .../create-usercontext-instructions/SKILL.md | 2 +- .../references/quality-checklist.md | 2 +- skills/validate-agents-md/SKILL.md | 2 +- skills/validate-project-instructions/SKILL.md | 2 +- .../SKILL.md | 2 +- specs/context_aware_ai_session_spec.md | 8 ++--- templates/AGENTS_template.md | 2 +- .../usercontext_template.instructions.md | 6 ++-- .../sample_usercontext.instructions.md | 4 +-- 15 files changed, 59 insertions(+), 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 357d582..1ffabde 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - + # 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) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3376177..9a29045 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 71be4c4..94e791f 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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 @@ -486,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 --- diff --git a/docs/spec-rationale.md b/docs/spec-rationale.md index 51e1526..6283f1f 100644 --- a/docs/spec-rationale.md +++ b/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. diff --git a/skills/create-agents-md/SKILL.md b/skills/create-agents-md/SKILL.md index 5ed8408..a2d95cd 100644 --- a/skills/create-agents-md/SKILL.md +++ b/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 `` as an HTML comment at the top of the generated `AGENTS.md`. +4. Stamp `` 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. diff --git a/skills/create-project-instructions/SKILL.md b/skills/create-project-instructions/SKILL.md index 37f681b..b6331f8 100644 --- a/skills/create-project-instructions/SKILL.md +++ b/skills/create-project-instructions/SKILL.md @@ -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 `` as an HTML comment at the top of the generated `AGENTS.md`. +5. Stamp `` 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 diff --git a/skills/create-usercontext-instructions/SKILL.md b/skills/create-usercontext-instructions/SKILL.md index 976b35d..fdfbee7 100644 --- a/skills/create-usercontext-instructions/SKILL.md +++ b/skills/create-usercontext-instructions/SKILL.md @@ -32,7 +32,7 @@ Load or attach this file's contents into your AI session to activate the workflo 1. Run phased discovery using `references/discovery-phases.md`. 2. Normalize findings into required schema using `references/output-schema.md`. 3. Apply format contract from `references/output-format.md`. -4. Stamp `spec_version: "1.4.2"` in the YAML frontmatter of the generated artifact. +4. Stamp `spec_version: "1.4.3"` in the YAML frontmatter of the generated artifact. 5. Validate against `references/quality-checklist.md` before final output. 6. If structured metadata is requested, apply `references/json-metadata-schema.md`. diff --git a/skills/create-usercontext-instructions/references/quality-checklist.md b/skills/create-usercontext-instructions/references/quality-checklist.md index 9c8a219..6e4cc3a 100644 --- a/skills/create-usercontext-instructions/references/quality-checklist.md +++ b/skills/create-usercontext-instructions/references/quality-checklist.md @@ -1,7 +1,7 @@ # Quality Checklist: create-usercontext-instructions Before finalizing: -- [ ] Frontmatter includes `description`, `applyTo`, and `spec_version: "1.4.2"`. +- [ ] Frontmatter includes `description`, `applyTo`, and `spec_version: "1.4.3"`. - [ ] All 15 required sections exist in correct order. - [ ] No unresolved placeholders remain unless user requested placeholders. - [ ] Privacy-sensitive fields respect user constraints. diff --git a/skills/validate-agents-md/SKILL.md b/skills/validate-agents-md/SKILL.md index 8a5632b..aa9398b 100644 --- a/skills/validate-agents-md/SKILL.md +++ b/skills/validate-agents-md/SKILL.md @@ -29,7 +29,7 @@ Load or attach this file's contents into your AI session to activate the workflo ## Workflow 1. Run validation phases from `references/phase-checks.md`. -2. Check for `` comment: flag as WARNING if absent (pre-existing files may predate this requirement); flag as WARNING if present but older than `1.4.2`. +2. Check for `` comment: flag as WARNING if absent (pre-existing files may predate this requirement); flag as WARNING if present but older than `1.4.3`. 3. Generate report using `references/report-contract.md`. 4. Apply deterministic scoring from `references/scoring.md`. 5. Classify findings into critical/warning/enhancement buckets. diff --git a/skills/validate-project-instructions/SKILL.md b/skills/validate-project-instructions/SKILL.md index 845332a..b0f1d08 100644 --- a/skills/validate-project-instructions/SKILL.md +++ b/skills/validate-project-instructions/SKILL.md @@ -29,7 +29,7 @@ Load or attach this file's contents into your AI session to activate the workflo ## Workflow 1. Run validation phases from `references/phase-checks.md`. -2. Check for `` comment: flag as WARNING if absent (pre-existing files may predate this requirement); flag as WARNING if present but older than `1.4.2`. +2. Check for `` comment: flag as WARNING if absent (pre-existing files may predate this requirement); flag as WARNING if present but older than `1.4.3`. 3. Generate report using `references/report-contract.md`. 4. Apply deterministic scoring from `references/scoring.md`. 5. Classify findings into critical/warning/enhancement buckets. diff --git a/skills/validate-usercontext-instructions/SKILL.md b/skills/validate-usercontext-instructions/SKILL.md index 5c4c128..9191c78 100644 --- a/skills/validate-usercontext-instructions/SKILL.md +++ b/skills/validate-usercontext-instructions/SKILL.md @@ -29,7 +29,7 @@ Load or attach this file's contents into your AI session to activate the workflo ## Workflow 1. Run validation phases from `references/phase-checks.md`. -2. Check for `spec_version` field in YAML frontmatter: flag as WARNING if absent (pre-existing files may predate this requirement); flag as WARNING if present but older than `1.4.2`. +2. Check for `spec_version` field in YAML frontmatter: flag as WARNING if absent (pre-existing files may predate this requirement); flag as WARNING if present but older than `1.4.3`. 3. Generate report using `references/report-contract.md`. 4. Apply deterministic scoring from `references/scoring.md`. 5. Classify findings into critical/warning/enhancement buckets. diff --git a/specs/context_aware_ai_session_spec.md b/specs/context_aware_ai_session_spec.md index 6b7903d..084c777 100644 --- a/specs/context_aware_ai_session_spec.md +++ b/specs/context_aware_ai_session_spec.md @@ -1,17 +1,17 @@ --- -version: 1.4.2 +version: 1.4.3 context_type: specification document_type: technical_specification created: 2025-10-20 -last_updated: 2026-05-12 +last_updated: 2026-07-07 status: active intended_audience: AI-assisted developers, system designers, prompt engineers, LLM-based tooling architects license: Open for adaptation and refinement --- -# Context-Aware AI Session Flow Specification (v1.4.2) +# Context-Aware AI Session Flow Specification (v1.4.3) -**Version:** 1.4.2 | **Updated:** 2026-05-12 | **Status:** Active +**Version:** 1.4.3 | **Updated:** 2026-07-07 | **Status:** Active > This document contains the normative rules. For background reasoning, extended examples, end-to-end scenarios, and future enhancement notes, see [`docs/spec-rationale.md`](../docs/spec-rationale.md). diff --git a/templates/AGENTS_template.md b/templates/AGENTS_template.md index 838bb04..68795ee 100644 --- a/templates/AGENTS_template.md +++ b/templates/AGENTS_template.md @@ -1,4 +1,4 @@ - + # AGENTS.md Template diff --git a/templates/usercontext_template.instructions.md b/templates/usercontext_template.instructions.md index 832645b..d349b6b 100644 --- a/templates/usercontext_template.instructions.md +++ b/templates/usercontext_template.instructions.md @@ -1,14 +1,14 @@ --- description: Personal AI collaboration context for [Your Name] - [Primary Focus] ([Primary Ecosystem]) applyTo: "**/*" -spec_version: "1.4.2" +spec_version: "1.4.3" --- # User Context – [Your Name] ([Your Role/Title]) > **Purpose:** This file defines your persistent **User Context** for instruction-based AI collaboration across providers. > Load this first, then layer project-specific instructions for focused work. -> Aligned with the **Context-Aware AI Session Flow Specification v1.4.2**. +> Aligned with the **Context-Aware AI Session Flow Specification v1.4.3**. You are an AI assistant working with **[Your Name]**, a [location]-based [profession/role]. @@ -301,4 +301,4 @@ This file is designed for: --- -© [Year] [Your Name] – Personal User Context Instructions (Spec v1.4.2) +© [Year] [Your Name] – Personal User Context Instructions (Spec v1.4.3) diff --git a/usercontexts/sample_usercontext.instructions.md b/usercontexts/sample_usercontext.instructions.md index 43a47ec..b9a4e68 100644 --- a/usercontexts/sample_usercontext.instructions.md +++ b/usercontexts/sample_usercontext.instructions.md @@ -1,7 +1,7 @@ --- description: Personal AI collaboration context for Jordan Kim - iOS Engineering (Apple) applyTo: "**/*" -spec_version: "1.4.2" +spec_version: "1.4.3" --- > **Note:** This is an illustrative example — Jordan Kim is not a real person. This file demonstrates realistic specificity, opinionated constraints, and lived-in project status that make a user context file genuinely useful. @@ -10,7 +10,7 @@ spec_version: "1.4.2" > **Purpose:** This file defines your persistent **User Context** for instruction-based AI collaboration across providers. > Load this first, then layer project-specific instructions for focused work. -> Aligned with the **Context-Aware AI Session Flow Specification v1.4.2**. +> Aligned with the **Context-Aware AI Session Flow Specification v1.4.3**. You are an AI assistant working with **Jordan Kim**, a Toronto-based senior iOS developer.