diff --git a/.gitignore b/.gitignore index e01e0c9..edc00a8 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,7 @@ env/ adapters/codex/skills/adr-toolkit adapters/gemini-cli/skills/adr-toolkit adapters/antigravity/skills/adr-toolkit +.cline/skills/adr-toolkit # Task-by-task implementation plans (superpowers subagent-driven-development # artifacts) — kept locally for reference, not part of the public tree. diff --git a/README.md b/README.md index f70893a..f2fa9a7 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ of these adapters at it: | [Codex CLI](adapters/codex/) | Agent Plugins 1.0.0 manifest | [`adapters/codex/README.md`](adapters/codex/README.md) | | [Gemini CLI](adapters/gemini-cli/) | Extension manifest | [`adapters/gemini-cli/README.md`](adapters/gemini-cli/README.md) | | [Antigravity CLI](adapters/antigravity/) | Plugin manifest | [`adapters/antigravity/README.md`](adapters/antigravity/README.md) | +| [Cline CLI](adapters/cline/) | Open Agent Skills (no manifest) | [`adapters/cline/README.md`](adapters/cline/README.md) | | Anything else | Generic fallback | [`adapters/generic/README.md`](adapters/generic/README.md) — needs only markdown-reading and shell | **No AI harness at all?** `create --interactive` runs the same interview diff --git a/adapters/cline/README.md b/adapters/cline/README.md new file mode 100644 index 0000000..5c6cb34 --- /dev/null +++ b/adapters/cline/README.md @@ -0,0 +1,116 @@ +# Cline CLI adapter + +Cline CLI installs skills through the **open Agent Skills** standard — the same +`SKILL.md` + `skills/` convention this toolkit already ships — rather than a +harness-specific manifest file like the Codex, Gemini, and Antigravity adapters +use. There is no `plugin.json`/`gemini-extension.json` equivalent for Cline +skills, so this adapter is **README-only** (like `adapters/generic/`): it +documents how to point Cline at the existing `skills/adr-toolkit/` package. +**Manually verified against Cline CLI 3.0.61** (`cline --version`): discovery, +install, and the installed script layer all work — see "Verification status" +below. + +Cline CLI exposes a `skill` subcommand that forwards to the open skills CLI +(`npx skills`), and it discovers skills from the standard agent locations +(`~/.agents/skills/` globally, `.cline/skills/` per project). Because +`skills/adr-toolkit/SKILL.md` already carries the two fields Cline requires — +`name` matching its directory and `description` (under 1024 characters) — the +package installs as-is with no wrapper. + +## Install + +### From the published repository (recommended) + +The repository is public, so Cline installs the skill straight from GitHub: + +```bash +cline skill add SHcommit/ADR-toolkit --global +``` + +Add `-y`/`--yes` to skip the confirmation prompt. Drop `--global` to install +project-level (into the current project's `.cline/skills/`) instead of globally. + +### From a local clone + +A local checkout works the same way: + +```bash +cline skill add "$(pwd)/skills/adr-toolkit" --global +``` + +or symlink the package into Cline's skill directory yourself: + +```bash +# project-level +mkdir -p .cline/skills +ln -s "$(pwd)/skills/adr-toolkit" .cline/skills/adr-toolkit + +# global +mkdir -p ~/.agents/skills +ln -s "$(pwd)/skills/adr-toolkit" ~/.agents/skills/adr-toolkit +``` + +The symlink is created at install time, not committed to any repo — committing a +real symlink breaks on Windows checkouts that don't have `core.symlinks` enabled, +which this project's CI can't assume. + +### Confirm + +```bash +cline skill list +``` + +should list `adr-toolkit`. + +### Script-layer fallback + +Either way, run +`python skills/adr-toolkit/scripts/adr.py preflight --json` from your target +repository to confirm the script layer works standalone — this is the verified +working path regardless of skill-discovery status. + +## Why there's no manifest here + +Cline's "plugin" mechanism (`cline plugin install`, driven by a `package.json` +`cline` field) is for **TypeScript `AgentPlugin` modules** that register tools +and lifecycle hooks — a different extension point from a skill. ADR Toolkit is a +Python skill, so a TS plugin wrapper would be a rewrite with no benefit. The +always-on-hook use case (auto-running `check` on session start) is deliberately +out of scope — see `project-roadmap.md`'s "Harness parity" note. + +## Verification status + +Manually verified against Cline CLI 3.0.61 (`cline --version`) in an isolated +`HOME=$(mktemp -d)` so no state was written to the real `~/.cline`/`~/.agents`. + +``` +$ cline skill add SHcommit/ADR-toolkit --list +... +◇ Found 1 skill +│ adr-toolkit +│ Initialize, record, and check Architecture Decision Records by inspecting the repository and existing decisions before asking questions. + +$ cline skill add SHcommit/ADR-toolkit --yes --global +... +◇ Installed 1 skill +│ ✓ adr-toolkit (copied) +│ → ~/.agents/skills/adr-toolkit +``` + +The installed snapshot lands under `~/.agents/skills/adr-toolkit/` and carries +the whole `skills/adr-toolkit/` package. The script layer was run directly out of +it against a scratch git repository, producing correct `"ok": true` output for +`preflight`, `init --dir docs/decisions`, and `validate --dir docs/decisions` — +matching the Codex, Gemini CLI, and Antigravity adapters' verified depth. + +Two details worth knowing: + +- **The install location is `~/.agents/skills/`, not `~/.cline/...`.** The + skills CLI reports `~/.agents/skills/adr-toolkit` as the install path (the open + Agent Skills global directory Cline reads), even though Cline's CLI reference + mentions a `~/.cline/data/settings/skills/` global directory. Trust + `cline skill list` for where a given Cline version actually looks. +- **A project's own `skills/` directory is auto-detected.** Running + `cline skill list` inside this repository reports `adr-toolkit` from + `./skills/adr-toolkit` as a project skill, so a checkout of this repo is already + a working Cline project skill with no install step. diff --git a/changelog.md b/changelog.md index 32d6da8..8aaa2eb 100644 --- a/changelog.md +++ b/changelog.md @@ -4,6 +4,11 @@ Lightweight human-readable summary of meaningful repository changes. ## Unreleased +- Added a Cline CLI adapter (`adapters/cline/`) so Cline CLI and ClinePass users + can install the `skills/adr-toolkit` package. Cline installs skills through the + open Agent Skills standard (SKILL.md), so the adapter is README-only — no + manifest — documenting `cline skill add SHcommit/ADR-toolkit` plus a manual + 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. ## v0.3.2 (2026-09-02) diff --git a/handoff.md b/handoff.md index 58ab750..90f776e 100644 --- a/handoff.md +++ b/handoff.md @@ -2,7 +2,12 @@ ## Current task -Expanded `improvements.md` with High and Medium backlog items covering ReDoS cross-platform safety, 2-phase atomic transaction rollback, ADR overlap/similarity Eval infrastructure, weekly maintenance automation, PR significance bot, frontmatter auto-linter, interactive graph visualization, and code drift detection. +Added a Cline CLI adapter (`adapters/cline/`) so Cline CLI and ClinePass users +can install the `skills/adr-toolkit` package. Cline installs skills through the +open Agent Skills standard (SKILL.md), so the adapter is README-only — no +manifest. Discovery, install, and the installed script layer were manually +verified against Cline CLI 3.0.61. Tracked in GitHub issue #19; work is on the +`feature/cline-cli-adapter` branch. ## Scope @@ -17,7 +22,13 @@ Expanded `improvements.md` with High and Medium backlog items covering ReDoS cro ## Next step (for a new session picking this up cold) -Review the newly expanded `improvements.md` High/Medium items and pick an implementation candidate (e.g. `adr lint --fix` or ReDoS cross-platform guard). +The Cline adapter work is implemented but not yet committed. Run +`python3 -m pytest tests/unit tests/integration -q` and +`python3 scripts/sync_version.py --check`, then commit on +`feature/cline-cli-adapter`, push, open a PR into `develop`, and merge via the +Git Flow process (then delete the short-lived branch). CI's `harness-parity` job +still covers only Codex/Gemini; extending it to Cline CLI is a deferred +follow-up (non-interactive `npx skills` verification needs design). 1. `improvements.md`'s `### Low` → audit-report sub-group has exactly 1 diff --git a/tests/unit/test_cline_adapter.py b/tests/unit/test_cline_adapter.py new file mode 100644 index 0000000..b24cecc --- /dev/null +++ b/tests/unit/test_cline_adapter.py @@ -0,0 +1,37 @@ +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent.parent +CLINE_README = REPO_ROOT / "adapters" / "cline" / "README.md" +SKILL_MD = REPO_ROOT / "skills" / "adr-toolkit" / "SKILL.md" + + +def test_cline_adapter_readme_exists_and_documents_install(): + text = CLINE_README.read_text(encoding="utf-8") + assert "cline skill add" in text + assert "skills/adr-toolkit" in text + assert "SKILL.md" in text + + +def test_cline_adapter_documents_skill_discovery_locations(): + text = CLINE_README.read_text(encoding="utf-8") + assert ".cline/skills" in text + assert "~/.agents/skills" 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 + # manifest is needed for the Cline adapter. + text = SKILL_MD.read_text(encoding="utf-8") + assert "name: adr-toolkit" in text + assert SKILL_MD.parent.name == "adr-toolkit" + # Extract the description line from the YAML frontmatter and confirm it is + # present and under Cline's documented 1024-character limit. + lines = text.splitlines() + desc_lines = [ + line[len("description:"):].strip() + for line in lines + if line.startswith("description:") + ] + assert len(desc_lines) == 1 + assert 0 < len(desc_lines[0]) < 1024 diff --git a/tests/unit/test_readme.py b/tests/unit/test_readme.py index ee53c39..b211b73 100644 --- a/tests/unit/test_readme.py +++ b/tests/unit/test_readme.py @@ -33,3 +33,9 @@ def test_readme_documents_harness_adapters_including_antigravity(): assert "[Antigravity CLI](adapters/antigravity/)" in text assert "adapters/antigravity/README.md" in text + +def test_readme_documents_cline_cli_adapter(): + text = README.read_text(encoding="utf-8") + assert "[Cline CLI](adapters/cline/)" in text + assert "adapters/cline/README.md" in text +