fix: address communication drift between opinionated toolkit claims and facts#61
Merged
Merged
Conversation
…redictable 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
'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 <noreply@anthropic.com>
…aming '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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…table '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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…nstall 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 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR tightens repository documentation/spec language to reduce “communication drift” by removing overstated or outdated claims and aligning phrasing across the README and the session spec.
Changes:
- Replaces remaining “deterministic” phrasing with more accurate language around consistency/predictability.
- Removes or corrects stale/incorrect platform and ecosystem claims (e.g., Copilot support, removed sidecar references).
- Adds clarifying context where external resources or alternatives could be misconstrued as canonical project guidance.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
README.md |
Corrects/clarifies platform claims, removes stale references, and adds more accurate framing around portability and external links. |
specs/context_aware_ai_session_spec.md |
Updates remaining “deterministic” phrasing to emphasize consistency/predictability in the session model and workflow family mapping. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Addresses communication drift identified in a PR we received — places where the README and spec made claims that were factually wrong, overstated, inconsistent with each other, or presented opinionated choices as facts.
Changes
deterministiclanguage cleanup — spec (§4.1 footnote, §10.8 workflow table) and README (session state section) still useddeterministicafter PR Replace false determinism claim with accurate reduced-variance language #46 replaced it withreduced variancein the Core Principles table. Aligned all remaining occurrences toconsistent and predictable.agents/openai.yamlsidecars after PR chore(skills): remove openai sidecars #60 deleted them.AGENTS.md. It does. Row updated to reflect full Copilot support across VS Code, coding agent, and code review.Files changed
README.mdspecs/context_aware_ai_session_spec.md🤖 Generated with Claude Code