From 0881b6bd72255a9ab0ba87d2ae66558ad797e673 Mon Sep 17 00:00:00 2001 From: shcommit Date: Sun, 6 Sep 2026 17:34:04 +0900 Subject: [PATCH] docs(harness): add CLINE.md thin pointer and list Cline in AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cline joins Codex/Claude/Gemini as a listed harness with a thin entry file that delegates to AGENTS.md, matching the existing CODEX.md / CLAUDE.md / GEMINI.md shape. AGENTS.md's harness enumeration (line 4) and the Harness entry files paragraph (line 69) now both name Cline. The entry file also records an empirical finding: an isolated Cline run (CLI 3.0.61, model cline-pass/glm-5.2) showed Cline auto-injects the repo-root AGENTS.md into workspace context at session start — the reasoning trace explicitly says the full content of AGENTS.md was provided in the workspace context. So AGENTS.md already reaches every model routed through ClinePass (DeepSeek, GLM, Kimi, Qwen, ...) without extra plumbing. To make the harness-vs-model distinction explicit, AGENTS.md also states that per-model entry files (DEEPSEEK.md, GLM.md, KIMI.md, QWEN.md) are intentionally not created: those are model/API providers reached through a harness (Cline, Cursor, Aider, ...), not harnesses themselves, so the harness entry file already covers them. This preempts the recurring false question of whether each new model needs its own .md. Tests: added test_cline_entry_file_is_thin_pointer_to_agents_md and test_agents_md_lists_cline_among_harnesses to tests/unit/test_cline_adapter.py. All 5 cases re-run with Python 3.13 standalone (stdlib-only) and pass. ruff/mypy scope: test_cline_adapter.py only. --- AGENTS.md | 17 ++++--- CLINE.md | 23 +++++++++ changelog.md | 1 + handoff.md | 80 ++++++++++++++++++-------------- tests/unit/test_cline_adapter.py | 24 ++++++++++ 5 files changed, 105 insertions(+), 40 deletions(-) create mode 100644 CLINE.md diff --git a/AGENTS.md b/AGENTS.md index 47398d5..db0e568 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,10 @@ # AGENTS.md This is the shared operating document for every agent harness working in this -repository (Codex, Claude Code, Gemini, or any other). Harness-specific entry -files (`CODEX.md`, `CLAUDE.md`, `GEMINI.md`) are thin pointers back to this -file — read this one first, regardless of which harness started the session. +repository (Codex, Claude Code, Gemini, Cline, or any other). Harness-specific +entry files (`CODEX.md`, `CLAUDE.md`, `GEMINI.md`, `CLINE.md`) are thin pointers +back to this file — read this one first, regardless of which harness started +the session. ## Source of truth @@ -65,9 +66,13 @@ without reading commit-by-commit history. ## Harness entry files -`CODEX.md`, `CLAUDE.md`, and `GEMINI.md` stay thin. They point back to this -file and hold only notes specific to that harness (e.g. a tool quirk). Do not -duplicate rules from this file into them. +`CODEX.md`, `CLAUDE.md`, `GEMINI.md`, and `CLINE.md` stay thin. They point +back to this file and hold only notes specific to that harness (e.g. a tool +quirk). Do not duplicate rules from this file into them. Per-model entry +files (e.g. `DEEPSEEK.md`, `GLM.md`, `KIMI.md`, `QWEN.md`) are not created: +those are model/API providers reached through a harness (Cline, Cursor, +Aider, …), not harnesses themselves, so the harness's entry file already +covers them. ## Safety diff --git a/CLINE.md b/CLINE.md new file mode 100644 index 0000000..b4b6a2b --- /dev/null +++ b/CLINE.md @@ -0,0 +1,23 @@ +# CLINE.md + +Follow the shared project rules in `AGENTS.md` first. + +Use this file only for Cline-specific notes that cannot live in the shared +document. + +## Cline-specific notes + +Cline discovers this project as **Project Skill** via the open Agent Skills +standard (`skills/adr-toolkit/SKILL.md`); see `adapters/cline/README.md` for +install details. Unlike Codex/Gemini/Antigravity, Cline has no adapter-local +manifest — the canonical `SKILL.md` frontmatter (`name: adr-toolkit`, +`description` < 1024 chars) already satisfies Cline's skill-discovery +requirements. + +Cline (confirmed on CLI 3.0.61 with the `cline-pass/glm-5.2` model) auto-injects +the repository-root `AGENTS.md` into the workspace context at session start, so +the shared operating document reaches every model routed through ClinePass +(DeepSeek, GLM, Kimi, Qwen, …) without a per-model entry file. Per-model +`DEEPSEEK.md` / `KIMI.md` / `GLM.md` / `QWEN.md` files are deliberately not +created — those are model providers, not harnesses; the harness (Cline) is the +layer that owns project-context files. diff --git a/changelog.md b/changelog.md index 785f61c..6c11b79 100644 --- a/changelog.md +++ b/changelog.md @@ -27,6 +27,7 @@ Lightweight human-readable summary of meaningful repository changes. symlink fallback. Manually verified against Cline CLI 3.0.61. - Expanded `improvements.md` backlog with High and Medium priority items: ReDoS cross-platform safety, 2-phase atomic transaction rollback for `supersede`, ADR overlap/similarity Eval framework, weekly automated maintenance workflows, PR significance bot, `adr lint --fix` auto-repair, interactive HTML graph viewer, and code drift detection. - Logged a Medium-priority backlog item to fold the Cline CLI adapter into the `harness-parity` CI job (currently manually verified against Cline CLI 3.0.61 only), so Cline/ClinePass version drift is caught automatically like the Codex, Gemini, and Antigravity adapters. +- Added `CLINE.md` as a thin harness entry pointer (matching `CODEX.md`/`CLAUDE.md`/`GEMINI.md`) and updated `AGENTS.md` to list Cline alongside the other harnesses, plus an explicit note that per-model files (`DEEPSEEK.md`/`GLM.md`/`KIMI.md`/`QWEN.md`) are intentionally not created — those are model providers routed through a harness, not harnesses themselves. Verified that Cline (CLI 3.0.61 with `cline-pass/glm-5.2`) auto-injects the repo-root `AGENTS.md` into workspace context at session start, so the shared operating document reaches every model routed through ClinePass without a per-model entry file. ## v1.0.1 (2026-09-02) diff --git a/handoff.md b/handoff.md index e36571c..86552ca 100644 --- a/handoff.md +++ b/handoff.md @@ -2,51 +2,63 @@ ## Current task -Cline CLI adapter harness-parity CI coverage gap — logged as a Medium backlog -item. The Cline adapter is currently "Manually verified against Cline CLI 3.0.61" -only; the `harness-parity` CI job does not yet install Cline and exercise it on -push/PR. Codex, Gemini, and Antigravity adapters are already automated. +Cline harness entry file (`CLINE.md`) added and `AGENTS.md` updated to list +Cline alongside Codex/Claude/Gemini, plus an explicit per-model non-creation +policy (`DEEPSEEK.md`/`GLM.md`/`KIMI.md`/`QWEN.md` are not created — those are +model/API providers routed through a harness such as Cline, not harnesses). ## Touched files -- `improvements.md` — added Medium item "harness-parity CI에 Cline CLI 편입" - with prerequisites (npm package name/version pin, install-path verification, - `preflight`/`init`/`validate` `ok:true` checks). -- `project-roadmap.md` — added "Automate the Cline CLI adapter install-and-run - verification — Backlog." entry under "Harness parity". -- `changelog.md` — one Unreleased line recording the backlog item. -- `handoff.md` — this file (current task + next step). +- `CLINE.md` — new thin harness entry pointer (matches `CODEX.md`/`CLAUDE.md`/ + `GEMINI.md` shape) with Cline-specific notes: open Agent Skills discovery, + no adapter-local manifest, and the verified AGENTS.md auto-injection + behavior. +- `AGENTS.md` — added `Cline` to the harness enumeration (line 4) and added + `CLINE.md` to the harness entry-files list (line 69), plus a paragraph + stating per-model entry files are intentionally not created. +- `tests/unit/test_cline_adapter.py` — added + `test_cline_entry_file_is_thin_pointer_to_agents_md` and + `test_agents_md_lists_cline_among_harnesses`. +- `changelog.md` — one Unreleased line. +- `handoff.md` — this file. -## Diagnosis (for the next session) +## Diagnosis / empirical verification -Cline CLI 3.0.61 is installed at `/Users/yangseunghyeon/.npm-global/bin/cline`. -`cline skill list` from the repo root shows `adr-toolkit` as a **Project Skill** -(source: local, from `~/Development/ADR-toolkit/skills/adr-toolkit`) — i.e. the -repo's own `skills/` directory is auto-detected, NOT a global install. -`cline plugin list` is empty and `~/.agents/skills/` is empty, confirming the -adapter is README-only (no Cline TS plugin) and nothing was globally installed. +Confirmed via an isolated Cline run that Cline auto-injects the repo-root +`AGENTS.md` into workspace context at session start: + +``` +cline --data-dir --json 'Output ONLY the literal first line of +this repository AGENTS.md file. Do not run any tools...' +→ reasoning: "Looking at the Workspace Configuration, I see the full content + of the AGENTS.md file was provided in the workspace context." +→ text: "# AGENTS.md" +→ model: cline-pass/glm-5.2 +``` + +So `AGENTS.md` already reaches every model routed through ClinePass +(DeepSeek, GLM, Kimi, Qwen, …). Per-model entry files would be redundant +because the harness (Cline) is the layer that owns project-context injection. ## Next step -1. (Optional, for personal use) `cline skill add SHcommit/ADR-toolkit --global -y` - to make the skill available outside this repo. -2. (Future PR) Implement the Medium backlog item: confirm `cline`'s npm package - name/version-pin, add a Cline step to `.github/workflows/test.yml` - `harness-parity` job, verify `cline skill add ... --global --yes`, and run - `preflight`/`init`/`validate` from the installed snapshot on each push/PR. - Open a `feature/*` branch per the git flow and merge into `develop` via PR. +1. (This PR) `docs/cline-harness-entry` → `develop` via PR #37; wait for CI + (13 checks, same matrix as PR #36). +2. (Future, already logged in PR #36) Implement the Medium backlog item to + fold Cline into the `harness-parity` CI job. ## Verification -- `tests/unit/test_cline_adapter.py`: pass (doc-only change, code unaffected). -- `ruff check .`: to be confirmed below. +- `tests/unit/test_cline_adapter.py`: 5 cases (3 original + 2 new) — re-run + with Python 3.13 standalone. +- `git diff --stat`: 5 files, all markdown + test — ruff/mypy scope: + `test_cline_adapter.py`. ## Open risks -- Until the Cline harness-parity step lands, Cline CLI/ClinePass version drift - (e.g. `cline skill add` path or `~/.agents/skills/` location changing) will - not be caught by CI. The `adapters/cline/README.md` verification block stays - pinned to 3.0.61 until automated. -- Inherits the prior Open risks from the OSS governance hardening handoff - (ruleset context sync, `continue-on-error` PyPI publish, deferred - issue/PR automation). +- Cline auto-injection of `AGENTS.md` was verified on Cline CLI 3.0.61 with + `cline-pass/glm-5.2`; behavior may differ on other Cline versions or + providers. The Medium harness-parity CI backlog item (PR #36) covers + ongoing regression detection once implemented. +- Inherits Open risks from the prior handoff (ruleset context sync, + `continue-on-error` PyPI publish, deferred issue/PR automation). diff --git a/tests/unit/test_cline_adapter.py b/tests/unit/test_cline_adapter.py index b24cecc..c66c3ec 100644 --- a/tests/unit/test_cline_adapter.py +++ b/tests/unit/test_cline_adapter.py @@ -18,6 +18,30 @@ def test_cline_adapter_documents_skill_discovery_locations(): assert "~/.agents/skills" in text +def test_cline_entry_file_is_thin_pointer_to_agents_md(): + # Cline joins Codex/Claude/Gemini as a harness with a thin entry file that + # delegates to AGENTS.md. Per-model entry files (DEEPSEEK/GLM/KIMI/QWEN) are + # intentionally not created — those are models routed through a harness, + # not harnesses themselves. + cline_entry = REPO_ROOT / "CLINE.md" + text = cline_entry.read_text(encoding="utf-8") + assert "AGENTS.md" in text + assert "Follow the shared project rules" in text + # Harness entry files must stay thin — no duplication of AGENTS.md rules. + assert "Git Flow" not in text + assert "Release tags" not in text + + +def test_agents_md_lists_cline_among_harnesses(): + text = (REPO_ROOT / "AGENTS.md").read_text(encoding="utf-8") + # Cline must be listed both in the harness enumeration and the entry-file + # paragraph, alongside Codex/Claude/Gemini. + assert "Cline" in text + assert "CLINE.md" in text + # And the per-model-file non-creation policy must be stated. + assert "model/API providers" in text + + def test_skill_frontmatter_satisfies_cline_requirements(): # Cline requires `name` to match its directory and `description` (< 1024 # chars). The canonical package already carries both, so no adapter-local