diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a5fe0e5..bdd4c8a 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "contextdocs", - "version": "1.5.0", + "version": "1.6.0", "description": "Your AI agent maintains its own context files — a Claude Code plugin with an AGENTS-first model that covers Codex, Copilot, Cursor, Gemini, and 3 more tools. Signal Gate filtering, Context Guard hooks, health scoring, and MEMORY.md promotion.", "author": { "name": "Little Bear Apps", diff --git a/.release-please-manifest.json b/.release-please-manifest.json index dd8fde7..0d1bebe 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "1.5.0" + ".": "1.6.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 55c46b4..ec9a97d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,49 +5,63 @@ All notable changes to ContextDocs will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [1.5.0](https://github.com/littlebearapps/contextdocs/compare/v1.4.0...v1.5.0) (2026-03-15) +## [1.6.0](https://github.com/littlebearapps/contextdocs/compare/v1.5.0...v1.6.0) (2026-05-08) +> Modernises ContextDocs for the May 2026 AI-coding-tool ecosystem. Headlines: Cursor `.cursor/rules/*.mdc` migration so projects work in Cursor's Agent mode again, Cline `.clinerules/` directory mode with path-scoped rules, opt-in six-section AGENTS.md scaffold, three new health checks (16 total), richer skill activation via `when_to_use` frontmatter, and Copilot bridge marked optional now that Copilot's coding agent loads AGENTS.md natively. ### Added -* add UserPromptSubmit hook for context-related skill activation ([#15](https://github.com/littlebearapps/contextdocs/issues/15)) ([98c3106](https://github.com/littlebearapps/contextdocs/commit/98c31066185275d7267f0123678924ba8383602e)) +* **Modern Cursor support** — `ai-context` now emits `.cursor/rules/agents.mdc` with `description` / `globs` / `alwaysApply` frontmatter so projects work in Cursor's Agent mode (legacy `.cursorrules` is no longer documented upstream and is ignored in Agent mode). Legacy file is preserved when already present. ([8d72344](https://github.com/littlebearapps/contextdocs/commit/8d72344d8c6f766d95025e11297be519a77d52d5)) +* **Modern Cline directory mode** — `ai-context` now defaults to `.clinerules/agents.md` directory layout with optional `paths:` per-file frontmatter for path-scoped rules. Flat `.clinerules` is preserved when already present. ([8d72344](https://github.com/littlebearapps/contextdocs/commit/8d72344d8c6f766d95025e11297be519a77d52d5)) +* **Six-section AGENTS.md scaffold** — opt-in `--scaffold=six-section` flag for `/ai-context init` generates the GitHub Blog Apr 2026 template (commands · testing · project structure · code style · git workflow · boundaries). Default scaffold unchanged for existing users. ([8d72344](https://github.com/littlebearapps/contextdocs/commit/8d72344d8c6f766d95025e11297be519a77d52d5)) +* **3 new context-verify checks (16 total)** — modern Cursor layout (deducts 2 if only `.cursorrules`), modern Cline layout (deducts 2 if flat `.clinerules`), and Copilot bridge optionality (advisory). ([decac12](https://github.com/littlebearapps/contextdocs/commit/decac12b223b9f950f2f8bbcf71f5801fe5f9003)) +* **Hook `if:` permission-rule matchers** — Tier 2 commit guard registration now uses `if: "Bash(git commit*)"` (Claude Code v2.1.85+) so hooks fire only on actual commit commands; older Claude Code versions fall back to in-script substring guards. ([cb9f160](https://github.com/littlebearapps/contextdocs/commit/cb9f160f49a63ad1b3d1a88d61abfff7c4f311a7)) +* **Skill `when_to_use` frontmatter** — all three skills now split activation hints between `description` (key use case) and `when_to_use` (trigger phrases + skip-when negatives), matching the Claude Code v2.1.119 1,536-character combined cap for richer NL activation. ([8d72344](https://github.com/littlebearapps/contextdocs/commit/8d72344d8c6f766d95025e11297be519a77d52d5)) +* **Plugin `$schema` field** — `.claude-plugin/plugin.json` now declares `"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json"` for editor autocomplete and `claude plugin validate` validation. Claude Code ignores this field at load time. ([0fc3324](https://github.com/littlebearapps/contextdocs/commit/0fc3324) / [05050ba](https://github.com/littlebearapps/contextdocs/commit/05050ba)) +* **Cross-platform context drift cleanup + standalone verify CLI** ([#28](https://github.com/littlebearapps/contextdocs/issues/28)) ([1527dbe](https://github.com/littlebearapps/contextdocs/commit/1527dbe974397c4652fb8f64d8052d0e9f097332)) + +### Changed +* **Copilot bridge marked optional** — Copilot's coding agent has supported AGENTS.md natively [since Aug 2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/); `.github/copilot-instructions.md` is only emitted when needed for tool-specific scoping. `context-verify` adds an advisory check. ([510720f](https://github.com/littlebearapps/contextdocs/commit/510720f16d61cdc8e9e06b128668afd5d488418a)) +* **`context-updater` agent pinned to haiku** for cheap surgical edits; `disallowedTools: [WebSearch, WebFetch]` made explicit. ([5c7ffb5](https://github.com/littlebearapps/contextdocs/commit/5c7ffb5)) +* **FAQ filename renamed** `docs/faq/index.md` → `docs/faq/faq.md` ([#29](https://github.com/littlebearapps/contextdocs/issues/29)) for cleaner help-centre URL `/help/contextdocs/faq/` (was `/help/contextdocs/index/`). Pure file rename — no content change. Marketing-site 301 redirect handled separately. ([0fc3324](https://github.com/littlebearapps/contextdocs/commit/0fc3324)) ### Fixed -* align SKILL.md and CLAUDE.md with canonical description ([bb4b750](https://github.com/littlebearapps/contextdocs/commit/bb4b750b7916359a15184aea18462e2eec76b02e)) -* Context Guard hooks false positive on infrastructure rule files ([#13](https://github.com/littlebearapps/contextdocs/issues/13)) ([ab0cd47](https://github.com/littlebearapps/contextdocs/commit/ab0cd4728bffb386d93e7742b6262a04a28115a3)) +* Context Guard hooks no longer flag infrastructure rule files as false positives ([#13](https://github.com/littlebearapps/contextdocs/issues/13)) +* `ai-context` skill triggers more reliably when you describe stale context or MEMORY.md promotion scenarios +* `SKILL.md` and `CLAUDE.md` descriptions now match the canonical product definition across all tools -## [Unreleased] +### Verified Safe Against -### Added +This release was verified against four open Claude Code plugin issues — none affect ContextDocs: -* **Modern Cursor support** — `ai-context` now emits `.cursor/rules/agents.mdc` with `description` / `globs` / `alwaysApply` frontmatter so projects work in Cursor's Agent mode (legacy `.cursorrules` is no longer documented upstream and is ignored in Agent mode). Legacy file is preserved when already present. -* **Modern Cline directory mode** — `ai-context` now defaults to `.clinerules/agents.md` directory layout with optional `paths:` per-file frontmatter for path-scoped rules. Flat `.clinerules` is preserved when already present. -* **Six-section AGENTS.md scaffold** — opt-in `--scaffold=six-section` flag for `/ai-context init` generates the GitHub Blog Apr 2026 template (commands · testing · project structure · code style · git workflow · boundaries). Default scaffold unchanged for existing users. -* **3 new context-verify checks (16 total)** — modern Cursor layout (deducts 2 if only `.cursorrules`), modern Cline layout (deducts 2 if flat `.clinerules`), and Copilot bridge optionality (advisory). -* **Hook `if:` permission-rule matchers** — Tier 2 commit guard registration now uses `if: "Bash(git commit*)"` (Claude Code v2.1.85+) so hooks fire only on actual commit commands; older Claude Code versions fall back to in-script substring guards. -* **Skill `when_to_use` frontmatter** — all three skills now split activation hints between `description` (key use case) and `when_to_use` (trigger phrases + skip-when negatives), matching the Claude Code v2.1.119 1,536-character combined cap for richer NL activation. -* **Plugin `$schema` field** — `.claude-plugin/plugin.json` now declares `"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json"` for editor autocomplete and `claude plugin validate` validation. Claude Code ignores this field at load time. +* [anthropics/claude-code#44120](https://github.com/anthropics/claude-code/issues/44120) — plugin skills not discovered when `.claude/` directory exists in plugin (caveat noted; same family as known [#32184](https://github.com/anthropics/claude-code/issues/32184) headless-mode limitation) +* [anthropics/claude-code#46664](https://github.com/anthropics/claude-code/issues/46664) — `WorktreeCreate` hooks in plugin `hooks/hooks.json` never fire (we don't register this event) +* [anthropics/claude-code#49990](https://github.com/anthropics/claude-code/issues/49990) — bare `{type, command}` hook entry silently breaks entire hooks config (every entry wraps `{type, command}` in a `hooks: []` array under `matcher:` or `if:` scope) +* [anthropics/claude-code#54532](https://github.com/anthropics/claude-code/issues/54532) — SessionStart hook "ToolUseContext is required for prompt hooks" error (all hooks use `type: command`, never `type: prompt`) -### Changed +### Documentation -* **Copilot bridge marked optional** in docs and skill output — Copilot's coding agent has supported AGENTS.md natively since Aug 2025; `.github/copilot-instructions.md` is only emitted when needed for tool-specific scoping. `context-verify` adds an advisory check. -* **`context-updater` agent pinned to haiku** for cheap surgical edits; `disallowedTools: [WebSearch, WebFetch]` made explicit. -* **FAQ filename renamed** `docs/faq/index.md` → `docs/faq/faq.md` ([#29](https://github.com/littlebearapps/contextdocs/issues/29)) for cleaner help-centre URL `/help/contextdocs/faq/` (was `/help/contextdocs/index/`). Pure file rename — no content change. Marketing-site 301 redirect handled separately. +* Polish release notes and modernise guides for v1.6.0 — bridge file tables, check counts, version refs, FAQ entry on `.cursorrules` vs `.cursor/rules/agents.mdc` coexistence (this commit) +* Add `docs/faq/faq.md` for help-centre FAQPage schema ([#26](https://github.com/littlebearapps/contextdocs/issues/26)) ([130e103](https://github.com/littlebearapps/contextdocs/commit/130e1035f7785fc757f6f6f0082b99b204d67a21)) +* AGENTS-first refresh for v1.6.0 + Copilot bridge marked optional ([510720f](https://github.com/littlebearapps/contextdocs/commit/510720f16d61cdc8e9e06b128668afd5d488418a)) +* Document v1.6.0 unreleased changes ([bfd03c3](https://github.com/littlebearapps/contextdocs/commit/bfd03c3883dce76896f0d6340e4010100304a780)) +* Include `$schema` in llms.txt plugin manifest entry ([05050ba](https://github.com/littlebearapps/contextdocs/commit/05050bae75107b26ccb7b034070d7ec5a10a69ae)) +* Protect synced FAQ path in AGENTS.md and CLAUDE.md ([#27](https://github.com/littlebearapps/contextdocs/issues/27)) ([d48b09c](https://github.com/littlebearapps/contextdocs/commit/d48b09cafb536a7f14d4b053f061fb79d1d65982)) -### Fixed +## [1.5.0](https://github.com/littlebearapps/contextdocs/compare/v1.4.0...v1.5.0) (2026-03-15) -* Context Guard hooks no longer flag infrastructure rule files as false positives ([#13](https://github.com/littlebearapps/contextdocs/issues/13)) -* ai-context skill triggers more reliably when you describe stale context or MEMORY.md promotion scenarios -* SKILL.md and CLAUDE.md descriptions now match the canonical product definition across all tools -### Verified Safe Against +### Added + +* add UserPromptSubmit hook for context-related skill activation ([#15](https://github.com/littlebearapps/contextdocs/issues/15)) ([98c3106](https://github.com/littlebearapps/contextdocs/commit/98c31066185275d7267f0123678924ba8383602e)) -* [anthropics/claude-code#44120](https://github.com/anthropics/claude-code/issues/44120) — plugin skills not discovered when `.claude/` directory exists in plugin -* [anthropics/claude-code#46664](https://github.com/anthropics/claude-code/issues/46664) — `WorktreeCreate` hooks in plugin `hooks/hooks.json` never fire (we don't use this event) -* [anthropics/claude-code#49990](https://github.com/anthropics/claude-code/issues/49990) — bare `{type, command}` hook entry silently breaks entire hooks config -* [anthropics/claude-code#54532](https://github.com/anthropics/claude-code/issues/54532) — SessionStart hook "ToolUseContext is required for prompt hooks" error + +### Fixed + +* align SKILL.md and CLAUDE.md with canonical description ([bb4b750](https://github.com/littlebearapps/contextdocs/commit/bb4b750b7916359a15184aea18462e2eec76b02e)) +* Context Guard hooks false positive on infrastructure rule files ([#13](https://github.com/littlebearapps/contextdocs/issues/13)) ([ab0cd47](https://github.com/littlebearapps/contextdocs/commit/ab0cd4728bffb386d93e7742b6262a04a28115a3)) ## [1.4.0](https://github.com/littlebearapps/contextdocs/compare/v1.3.0...v1.4.0) (2026-03-13) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eac0eaf..a0252ff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ contextdocs/ │ ├── context-guard/SKILL.md # Hook installation │ └── context-verify/SKILL.md # Health scoring ├── commands/ # Slash commands -├── hooks/ # 6 opt-in shell scripts (Claude Code only) +├── hooks/ # 7 opt-in shell scripts (Claude Code only) └── upstream-versions.json # Pinned AGENTS.md spec + Claude Code release versions ``` diff --git a/README.md b/README.md index 232fbe2..1539cf2 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@

- Version + Version License Claude Code Plugin OpenCode Compatible @@ -69,13 +69,13 @@ ContextDocs solves the full lifecycle. It scans your codebase, generates `AGENTS **For Claude Code users:** Claude Code auto-loads `CLAUDE.md` every session. The generated `CLAUDE.md` starts with `@AGENTS.md`, which imports the canonical shared context directly — so you get the full conventions plus Claude-specific additions without duplication. Other tools (Codex CLI, Gemini CLI, Copilot, Cursor) load their own bridge files or `AGENTS.md` directly. -Then it keeps them fresh: `update` patches drift incrementally, `promote` moves Claude's auto-learned MEMORY.md patterns into CLAUDE.md, `context-verify` scores health 0–100 across 6 dimensions with 13 checks, and Context Guard hooks enforce freshness at session start, session end, and commit time — with the context-updater agent applying fixes automatically. +Then it keeps them fresh: `update` patches drift incrementally, `promote` moves Claude's auto-learned MEMORY.md patterns into CLAUDE.md, `context-verify` scores health 0–100 across 6 dimensions with 16 checks, and Context Guard hooks enforce freshness at session start, session end, and commit time — with the context-updater agent applying fixes automatically. --- ## 🎯 Features -ContextDocs generates AGENTS-first context for 8 AI coding tools from a single codebase scan, applies Signal Gate filtering to strip discoverable content, enforces line budgets (AGENTS.md <120, CLAUDE.md <80, other bridges <60), and scores health 0–100 across 6 dimensions with 13 verification checks. Context Guard hooks catch drift at session start, session end, and commit time. +ContextDocs generates AGENTS-first context for 8 AI coding tools from a single codebase scan, applies Signal Gate filtering to strip discoverable content, enforces line budgets (AGENTS.md <120, CLAUDE.md <80, other bridges <60), and scores health 0–100 across 6 dimensions with 16 verification checks (including modern Cursor `.cursor/rules/*.mdc` and Cline `.clinerules/` directory layouts). Context Guard hooks catch drift at session start, session end, and commit time. - 🧠 **Signal Gate filtering** — strips out discoverable content (directory listings, file trees, architecture overviews) so your context files contain only what actually helps AI tools, keeping them lean and under budget - 📋 **AGENTS-first generation + thin bridges** — shared conventions live once in `AGENTS.md`, while `CLAUDE.md`, `.cursor/rules/*.mdc`, `.clinerules/`, optional Copilot instructions, and compatibility bridges stay minimal and tool-specific diff --git a/SKILL.md b/SKILL.md index 4914983..0c52e7c 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: contextdocs description: Your AI agent maintains its own context files — a Claude Code plugin with an AGENTS-first model that covers Codex, Copilot, Cursor, Gemini, and 3 more tools. Signal Gate filtering, Context Guard hooks, health scoring, and MEMORY.md promotion. -version: "1.5.0" # x-release-please-version +version: "1.6.0" # x-release-please-version author: Little Bear Apps tags: - ai-context diff --git a/docs/faq/faq.md b/docs/faq/faq.md index b465eea..d2858ca 100644 --- a/docs/faq/faq.md +++ b/docs/faq/faq.md @@ -11,7 +11,7 @@ description: "Common questions about ContextDocs: installation, supported AI too ## What is ContextDocs and why should I use it? -ContextDocs is a Claude Code plugin that generates and maintains AI context files for your project — `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, `.windsurfrules`, `.clinerules`, and `GEMINI.md` — from a single codebase scan. It applies the **Signal Gate principle** so the files only contain what AI agents cannot already discover by reading source code on their own. +ContextDocs is a Claude Code plugin that generates and maintains AI context files for your project — `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/agents.mdc` (modern Cursor with frontmatter), `.clinerules/agents.md` (modern Cline directory mode), `.windsurfrules`, `GEMINI.md`, and an optional `.github/copilot-instructions.md` (Copilot loads AGENTS.md natively since Aug 2025) — from a single codebase scan. Legacy formats (`.cursorrules`, flat `.clinerules`) are preserved only when a project already uses them. It applies the **Signal Gate principle** so the files only contain what AI agents cannot already discover by reading source code on their own. The motivation is concrete: research from ETH Zurich (2026) shows that bloated context files reduce AI task success by roughly 3% and increase token costs by around 20%. Most teams either write too much, write the wrong things, or let context files go stale within a week. ContextDocs covers the full lifecycle — generation, drift patching, MEMORY.md promotion, freshness hooks, and 0–100 health scoring — so the files stay lean and accurate as your project evolves. diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 8998271..e595194 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -4,7 +4,7 @@ description: "Install ContextDocs, generate canonical AGENTS.md plus bridge file type: how-to difficulty: beginner time_to_complete: "5 minutes" -last_verified: "1.3.0" +last_verified: "1.6.0" # x-release-please-version related: - guides/troubleshooting.md order: 1 @@ -56,15 +56,19 @@ ContextDocs will: |------|------|--------| | AGENTS.md | Canonical shared context | <120 lines | | CLAUDE.md | Claude Code bridge (`@AGENTS.md` + Claude-specific notes) | <80 lines | -| .cursorrules | Cursor bridge | <60 lines | -| .github/copilot-instructions.md | GitHub Copilot bridge | <60 lines | +| .cursor/rules/agents.mdc | Modern Cursor bridge with frontmatter (default since v1.6.0) | <60 lines | +| .cursorrules | Legacy Cursor bridge — only emitted when already present (current Cursor versions ignore this in Agent mode) | <60 lines | +| .github/copilot-instructions.md | Optional Copilot bridge — Copilot's coding agent loads AGENTS.md natively (since Aug 2025); only emit when adding tool-specific scoping | <60 lines | | .windsurfrules | Windsurf compatibility bridge | <60 lines | -| .clinerules | Cline bridge | <60 lines | +| .clinerules/agents.md | Modern Cline bridge — directory mode with optional `paths:` per-file frontmatter (default since v1.6.0) | <60 lines | +| .clinerules | Legacy Cline bridge — flat-file fallback, only emitted when already present | <60 lines | | GEMINI.md | Gemini compatibility bridge | <60 lines | **For Claude Code users:** Claude Code auto-loads `CLAUDE.md` every session. The generated `CLAUDE.md` starts with `@AGENTS.md`, which imports the canonical shared context — so you get everything without duplication. The other bridge files are optional and only needed if team members use Copilot, Cursor, Windsurf, Cline, or Gemini. -**Tip:** To generate a single file, specify the tool: `/contextdocs:ai-context claude` or `/contextdocs:ai-context cursor`. +**Modern Cursor / Cline (v1.6.0+):** New projects get `.cursor/rules/agents.mdc` (with `description` / `globs` / `alwaysApply` frontmatter) and `.clinerules/agents.md` (directory mode) by default — these are what current Cursor and Cline versions actually load. Legacy `.cursorrules` and flat `.clinerules` are preserved only when a project already uses them, so existing repos don't break. + +**Tip:** To generate a single file, specify the tool: `/contextdocs:ai-context claude` or `/contextdocs:ai-context cursor`. To bootstrap with the [GitHub Blog Apr 2026 six-section AGENTS.md template](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) (commands · testing · project structure · code style · git workflow · boundaries), pass `--scaffold=six-section` to `/contextdocs:ai-context init`. --- @@ -76,7 +80,7 @@ Check that your generated files are healthy: /contextdocs:context-verify ``` -This scores your context files 0–100 across 6 dimensions with 13 checks: +This scores your context files 0–100 across 6 dimensions with 16 checks: - **Line budget** — are files within their size targets? - **Signal quality** — does the content pass Signal Gate (no discoverable content)? - **Path accuracy** — do referenced file paths actually exist? diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index 92b20ff..d24fbed 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -3,7 +3,7 @@ title: "Troubleshooting & FAQ" description: "Common ContextDocs issues and solutions — Signal Gate, Context Guard hooks, content filter errors, and cross-tool limitations." type: how-to difficulty: intermediate -last_verified: "1.5.0" # x-release-please-version +last_verified: "1.6.0" # x-release-please-version related: - guides/getting-started.md order: 2 @@ -96,17 +96,24 @@ The `promote` command moves confirmed patterns from MEMORY.md into CLAUDE.md: The AI coding tool landscape has converged around shared primitives. Most tools now support AGENTS.md, skills (SKILL.md), and hooks — not just static context files. -### Platform Support Matrix (March 2026) +### Platform Support Matrix (May 2026) | Feature | Claude Code | Gemini CLI | Copilot | Cursor | Codex CLI | OpenCode | Cline | Windsurf | |---------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| AGENTS.md auto-load | via @import | configurable | yes | yes | native | native | fallback | yes | +| AGENTS.md auto-load | via @import | configurable | native (Aug 2025) | yes | native | native | fallback | yes | +| Bridge file (modern) | CLAUDE.md | GEMINI.md | optional `.github/copilot-instructions.md` | `.cursor/rules/*.mdc` | AGENTS.md | AGENTS.md | `.clinerules/` (dir) | `.windsurf/rules/` | | Skills (SKILL.md) | yes | yes | yes | yes | yes | yes | merged | yes | | Hooks | 12 events | 11 events | 8 (preview) | 4+ events | 2 (exp) | partial | 3 events | enterprise | | Custom agents | yes | yes (exp) | yes | yes | yes | yes | read-only | limited | | Rules directory | yes | via ext | yes | yes | no | partial | yes | yes | | Plugin/extension model | plugin.json | extension | .github/ | marketplace | skills pkg | config | MCP | MCP | +**Cursor (May 2026):** Modern Cursor uses `.cursor/rules/*.mdc` with frontmatter (`description` / `globs` / `alwaysApply`). The legacy single-file `.cursorrules` is no longer documented and is **silently ignored in Agent mode**. ContextDocs v1.6.0+ emits `.cursor/rules/agents.mdc` by default and only generates `.cursorrules` for backwards compatibility when one already exists. + +**Cline (May 2026):** Modern Cline supports a `.clinerules/` directory containing per-file Markdown rules with optional `paths:` frontmatter for glob-scoped activation. ContextDocs v1.6.0+ emits the directory layout by default; flat `.clinerules` is preserved as a fallback when a project already uses one. + +**Copilot (Aug 2025+):** GitHub Copilot's coding agent supports AGENTS.md as native custom instructions. The `.github/copilot-instructions.md` bridge is now **optional** — only generate it when you need Copilot-specific PR or review scoping that doesn't belong in shared AGENTS.md. + ### What ContextDocs Delivers Per Platform | Tier | Platforms | Experience | @@ -123,7 +130,7 @@ The AI coding tool landscape has converged around shared primitives. Most tools **Codex CLI / Gemini CLI**: AGENTS.md is auto-loaded natively. Skills work if placed in the standard skills directory. -**Cursor / Copilot / Windsurf / Cline**: Run `/contextdocs:ai-context init` in Claude Code to generate all bridge files, or manually create the relevant context file (`.cursorrules`, `.github/copilot-instructions.md`, `.windsurfrules`, `.clinerules`). +**Cursor / Copilot / Windsurf / Cline**: Run `/contextdocs:ai-context init` in Claude Code to generate all bridge files. v1.6.0+ emits `.cursor/rules/agents.mdc` (modern Cursor), `.clinerules/agents.md` (modern Cline directory mode), `.windsurfrules` (compatibility), and only generates `.github/copilot-instructions.md` when needed (Copilot loads AGENTS.md natively since Aug 2025). Legacy `.cursorrules` and flat `.clinerules` are kept only when a project already uses them. **All platforms**: Run `bin/context-verify.sh` for 0-100 health scoring — no plugin system required. @@ -165,6 +172,18 @@ Yes. They work independently and complement each other. PitchDocs generates READ Only include in context files what AI agents cannot discover by reading source code on their own. This keeps files lean and effective. Research shows overstuffed context files reduce AI task success by ~3% and increase token costs by 20%. +### Why do I have both `.cursorrules` and `.cursor/rules/agents.mdc`? + +ContextDocs v1.6.0 ships both for safe migration. `.cursor/rules/agents.mdc` (modern format) is what current Cursor versions actually load — the legacy single-file `.cursorrules` is silently ignored in Agent mode as of 2026. ContextDocs only emits the legacy file when one already exists in the project, so existing repos don't break. Once your team is fully on modern Cursor, you can delete `.cursorrules` — `context-verify` flags this as redundant. + +### Why do I have both `.clinerules` (file) and `.clinerules/` (directory)? + +Modern Cline supports a `.clinerules/` directory with one Markdown file per rule and optional `paths:` per-file frontmatter for glob-scoped activation. ContextDocs v1.6.0 defaults to the directory layout for new projects but preserves a flat `.clinerules` file when one already exists. If both are present, the directory takes precedence in current Cline versions — you can safely delete the flat file once you've validated the new layout. + +### Do I still need `.github/copilot-instructions.md`? + +Probably not. GitHub Copilot's coding agent has supported AGENTS.md as native custom instructions [since Aug 2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/), so AGENTS.md is loaded automatically. ContextDocs v1.6.0 marks the Copilot bridge **optional** — only generate it when you need Copilot-specific PR review scoping that doesn't belong in shared AGENTS.md. `context-verify` adds an advisory check. + --- **Need help?** See [SUPPORT.md](../../SUPPORT.md) or [open an issue](https://github.com/littlebearapps/contextdocs/issues/new). diff --git a/docs/references/platform-capabilities.md b/docs/references/platform-capabilities.md index 69388c5..3396f51 100644 --- a/docs/references/platform-capabilities.md +++ b/docs/references/platform-capabilities.md @@ -7,7 +7,7 @@ last_verified: "1.5.0" # x-release-please-version # Platform Capabilities Reference -> **Last researched:** March 2026. The AI coding tool landscape evolves rapidly — verify against each tool's latest release notes. +> **Last researched:** May 2026 (Cursor, Claude Code, Copilot, Cline re-verified for ContextDocs v1.6.0); March 2026 baseline still applies for Gemini CLI, Codex CLI, OpenCode, Windsurf, Aider. The AI coding tool landscape evolves rapidly — verify against each tool's latest release notes. --- @@ -62,7 +62,7 @@ last_verified: "1.5.0" # x-release-please-version ### GitHub Copilot -**Context loading:** Auto-loads `.github/copilot-instructions.md` (repo-wide) and `.github/instructions/*.instructions.md` (path-scoped with `applyTo` glob). Also loads `AGENTS.md` from anywhere in the tree (nearest takes precedence). Custom agents in `.github/agents/*.agent.md`. +**Context loading:** Auto-loads AGENTS.md natively (since [Aug 28 2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) — confirmed May 2026); nested AGENTS.md works with nearest-in-tree precedence. Optional `.github/copilot-instructions.md` (repo-wide) and `.github/instructions/*.instructions.md` (path-scoped with `applyTo` glob) for Copilot-specific scoping. Custom agents in `.github/agents/*.agent.md`. ContextDocs v1.6.0+ marks the Copilot bridge as optional. **Extension model:** Plugins with 5 primitives — agents, skills, hooks, MCP servers, and instructions. Marketplace available. `/plugin install owner/repo` syntax. @@ -74,7 +74,7 @@ last_verified: "1.5.0" # x-release-please-version ### Cursor -**Context loading:** `.cursor/rules/*.mdc` (modern, replacing deprecated `.cursorrules`). Also loads `AGENTS.md` with directory-scoped overrides. Four activation modes: Always Apply, Apply Intelligently, Apply to Specific Files (globs), Apply Manually. +**Context loading:** `.cursor/rules/*.mdc` with frontmatter (`description` / `globs` / `alwaysApply`) — confirmed against `cursor.com/docs/context/rules` on 2026-05-06. The legacy single-file `.cursorrules` is no longer documented and is silently ignored in Agent mode. Also loads `AGENTS.md` with directory-scoped overrides. Four activation modes: Always Apply, Apply Intelligently, Apply to Specific Files (globs), Apply Manually. ContextDocs v1.6.0+ emits `.cursor/rules/agents.mdc` by default. **Extension model:** Plugin marketplace (since v2.4, Feb 2026). Plugins package skills, subagents, MCP servers, hooks, and rules. `/plugin install owner/repo` syntax. @@ -110,7 +110,7 @@ last_verified: "1.5.0" # x-release-please-version ### Cline -**Context loading:** `.clinerules` file or `.clinerules/` directory at project root. Auto-detects fallbacks: `.cursorrules`, `.windsurfrules`, `AGENTS.md`. Supports path-based conditional activation via `paths:` YAML frontmatter. +**Context loading:** `.clinerules/` directory (modern, default in 2026) with one Markdown file per rule and optional `paths:` YAML frontmatter for glob-scoped activation. Flat `.clinerules` file still works as fallback. Auto-detects further fallbacks: `.cursorrules`, `.windsurfrules`, `AGENTS.md`. ContextDocs v1.6.0+ emits the directory layout for new projects; flat `.clinerules` is preserved when already present. **Extension model:** MCP self-install. Hooks in `.clinerules/hooks/` (project) or `~/Documents/Cline/Rules/Hooks/` (global). @@ -165,12 +165,12 @@ last_verified: "1.5.0" # x-release-please-version | Tool | Documentation | Last Verified | |---|---|---| -| Claude Code | [code.claude.com/docs](https://code.claude.com/docs) | March 2026 | +| Claude Code | [code.claude.com/docs](https://code.claude.com/docs) | May 2026 | | Gemini CLI | [geminicli.com/docs](https://geminicli.com/docs) | March 2026 | -| GitHub Copilot | [docs.github.com/copilot](https://docs.github.com/copilot) | March 2026 | -| Cursor | [cursor.com/docs](https://cursor.com/docs) | March 2026 | +| GitHub Copilot | [docs.github.com/copilot](https://docs.github.com/copilot) | May 2026 | +| Cursor | [cursor.com/docs](https://cursor.com/docs) | May 2026 | | Codex CLI | [developers.openai.com/codex](https://developers.openai.com/codex) | March 2026 | | OpenCode | [opencode.ai/docs](https://opencode.ai/docs) | March 2026 | -| Cline | [docs.cline.bot](https://docs.cline.bot) | March 2026 | +| Cline | [docs.cline.bot](https://docs.cline.bot) | May 2026 | | Windsurf | [docs.windsurf.com](https://docs.windsurf.com) | March 2026 | | Aider | [aider.chat/docs](https://aider.chat/docs) | March 2026 | diff --git a/llms.txt b/llms.txt index 85ac626..c074d32 100644 --- a/llms.txt +++ b/llms.txt @@ -38,7 +38,7 @@ ## Optional - [Contributing](./CONTRIBUTING.md): Development setup, how to improve skills, modify hooks, submit PRs using conventional commits, content filter warning for high-risk files -- [Changelog](./CHANGELOG.md): Version history — v1.5.0 (current), v1.3.0, v1.2.0, v1.1.0, and v1.0.0 releases with migration guide from PitchDocs commands x-release-please-version +- [Changelog](./CHANGELOG.md): Version history — v1.6.0 (current), v1.5.0, v1.4.0, v1.3.0, v1.2.0, v1.1.0, and v1.0.0 releases with migration guide from PitchDocs commands x-release-please-version - [Support](./SUPPORT.md): Getting help, Signal Gate and Context Guard troubleshooting, content filter known issue, contact details, response times - [Context Quality Rule](./.claude/rules/context-quality.md): Auto-loaded quality rule for AI context files — AGENTS-first bridge consistency, path verification, version accuracy, sync points (Claude Code only) - [Context Awareness Rule](./.claude/rules/context-awareness.md): Auto-loaded context trigger map — suggests ContextDocs commands when context-relevant work is detected (Claude Code only)