@cleocode/skills 2026.9.21 → 2026.9.23

package/skills/ct-docs-lookup/references/version-specific-docs.md

@@ -1,220 +0,0 @@
-# Version-Specific Docs
-
-Library APIs drift across versions — sometimes silently (default value
-changes), sometimes loudly (renames, removals). This reference covers
-how to lock the docs lookup to the version the user actually runs,
-and how to handle migrations and deprecated APIs.
-
-## Why Version Pinning Matters
-
-The cost of citing the wrong version is high.
-
-- Drizzle ORM v1.0.0-beta renamed `relations()` to `defineRelations()`.
-  A 0.x user given a v1 example will copy code that doesn't import.
-- Next.js 15 changed default `fetch` cache from `force-cache` to
-  `no-store`. A user on 14 reading a 15 doc will not see the behavior
-  they expect.
-- React 19 introduced new hooks. A React 18 user copying a React 19
-  example gets `useActionState is not defined`.
-
-In each case, the failure mode is "confidently wrong answer". The
-remedy is always: pin to the user's actual version before fetching.
-
-## Finding the User's Version
-
-The skill SHOULD detect the user's installed version before opening
-Step 2.
-
-```bash
-# Node.js projects
-jq -r '.dependencies.next, .devDependencies.next | select(.)' package.json
-
-# Cargo projects
-cargo tree -p drizzle 2>/dev/null  # if applicable
-grep -A 1 '^drizzle-orm =' Cargo.toml
-
-# Python projects
-grep '^next' requirements.txt
-pip show next 2>/dev/null | grep '^Version'
-
-# Generic — search for any lockfile entry
-grep -A 1 'next:' pnpm-lock.yaml | head -3
-```
-
-If detection fails (no lockfile, version not pinned), ask the user
-or default to the project's stated version.
-
-## Version Format Matching
-
-Context7 IDs accept several version forms:
-
-```text
-/vercel/next.js                    # all versions; unspecified
-/vercel/next.js/v15                # latest within v15.x
-/vercel/next.js/v15.0.0            # exactly v15.0.0
-/vercel/next.js/v15.0.0-canary.7   # specific canary
-```
-
-Match the granularity of the user's question:
-
-- General "how do I do X with library" → unversioned or major-pinned.
-- Migration "from N to M" → both major-pinned: `/lib/vN` and `/lib/vM`.
-- Bug investigation "in 15.0.3 specifically X happens" → exact pin.
-
-## Major-Version Migrations
-
-When the user is upgrading from major N to major N+1, run two fetches.
-
-```bash
-# From-version: what works today
-npx ctx7@latest docs /drizzle-team/drizzle-orm/v0.36 "how do I define relations"
-
-# To-version: what they will move to
-npx ctx7@latest docs /drizzle-team/drizzle-orm/v1.0.0-beta "how do I define relations"
-
-# Compose the migration story:
-# 1. Show the current API
-# 2. Show the new API
-# 3. Show the mapping
-```
-
-The migration story has THREE parts. Skipping any of them produces
-confusion:
-
-- **Current API.** What the user has now.
-- **New API.** What it becomes.
-- **Mapping.** Mechanical translation between them.
-
-Documenting only the new API leaves the user wondering "but my code
-uses X — what does that become?"
-
-## Deprecated APIs
-
-When a fetched doc mentions an API as deprecated:
-
-1. Surface the deprecation explicitly. Don't bury it.
-2. Show the recommended replacement, fetched from the same docs.
-3. Cite when deprecation began and when removal is planned (if stated).
-
-Example output:
-
-```markdown
-The `relations()` helper in Drizzle ORM 0.x is deprecated as of v1.0.0-beta.
-Use `defineRelations` instead.
-
-| Drizzle 0.x | Drizzle 1.x (beta) |
-|-------------|--------------------|
-| `relations(table, (helpers) => ({ ... }))` | `defineRelations(schema, (t) => ({ ... }))` |
-
-Deprecation announced: v1.0.0-beta (2025-Q4).
-Planned removal: TBD (the 0.x line is still supported through 2026).
-```
-
-## Version Drift Detection
-
-Run a sanity check before answering — does the user's installed
-version match what they think they're using?
-
-```bash
-# User says "I'm on Next.js 15".
-$ jq -r '.dependencies.next' package.json
-"14.3.0"
-
-# Drift! Surface it:
-# > Your package.json says Next.js 14.3.0, not 15. Are you planning
-# > to upgrade, or did you mean 14? I'll fetch docs for what's
-# > installed unless you confirm 15 is the target.
-```
-
-This catches the common case where the user's mental model is ahead
-of (or behind) their actual install.
-
-## Multi-Library Lookups
-
-A single question may span multiple libraries. Resolve each
-independently with the right version pin.
-
-```bash
-# Question: "How do I integrate Better-Auth with Drizzle ORM in a
-#  Svelte 5 SvelteKit project?"
-
-# Three libraries; resolve each with project's actual version
-npx ctx7@latest library "Better-Auth" "..."
-npx ctx7@latest library "Drizzle ORM" "..."
-npx ctx7@latest library "SvelteKit" "..."
-
-# Then three fetches:
-npx ctx7@latest docs /better-auth/better-auth        "integration with drizzle"
-npx ctx7@latest docs /drizzle-team/drizzle-orm/v1    "integration with better-auth"
-npx ctx7@latest docs /sveltejs/kit/v2                "hooks for auth middleware"
-```
-
-Compose the answer from the three. Cite each library's version
-explicitly so the user knows what works with what.
-
-## When Versioned Docs Aren't Available
-
-Context7's catalog doesn't always have per-version slices. When a
-version pin returns "no matches":
-
-1. Drop one granularity level (e.g., `/v15.0.0-canary.7` → `/v15`).
-2. Drop another (`/v15` → `/vercel/next.js` unversioned).
-3. Add a note that version-specific data may be missing — recommend
-   the user verify against the official release notes.
-
-## Reading Release Notes
-
-When the question is "what changed in version X", release notes are
-often a better source than API docs. Two routes:
-
-```bash
-# Route 1 — Context7 may have it indexed
-npx ctx7@latest docs /vercel/next.js "release notes for v15"
-
-# Route 2 — WebFetch the official release notes page
-# (use when Context7 doesn't have release notes specifically)
-WebFetch: https://nextjs.org/blog/next-15  "summarize the breaking changes"
-```
-
-Release notes are more concise than docs and explicitly call out
-deprecations and removals — exactly what migration questions need.
-
-## Citing Versions
-
-Every code example produced from a version-pinned fetch MUST cite the
-version.
-
-```markdown
-GOOD:
-Use `defineRelations` (Drizzle ORM v1.0.0-beta and later):
-
-```typescript
-import { defineRelations } from "drizzle-orm";
-// ...
-```
-
-BAD:
-Use `defineRelations`:
-
-```typescript
-import { defineRelations } from "drizzle-orm";
-// ...
-```
-(no version context — reader doesn't know if their version supports it)
-```
-
-When the user copies the code and it doesn't work, the version citation
-is the first thing they check. Give it to them up front.
-
-## Skill Boundary
-
-This reference covers version handling within docs-lookup. It does NOT
-cover:
-
-- Migration code generators (out of scope; that's task-executor work).
-- Upgrade plan authoring (out of scope; that's spec-writer work).
-- Pinning the user's project to a new version (out of scope; that's a
-  task for the human or the executor).
-
-Docs-lookup just produces the version-accurate documentation. The
-downstream skills act on it.

package/skills/ct-master-tac/SKILL.md

@@ -1,120 +0,0 @@
----
-name: ct-master-tac
-description: >-
-  Master Tactical Bundle for CleoOS autonomous execution. Installs the complete
-  primitive library needed to run the full agentic execution layer on a fresh CleoOS
-  install: 12 CANT protocol files (research, consensus, architecture-decision,
-  specification, decomposition, implementation, validation, testing, contribution,
-  release, artifact-publish, provenance), the canonical platform team definition, and
-  the skills manifest entry. Use when bootstrapping a new CleoOS project, verifying that
-  all protocol primitives are present, or recovering a broken protocol tree. Triggers on:
-  "install master tac", "bootstrap protocols", "tools.skill.install ct-master-tac",
-  "verify protocol bundle", "repair protocol files", "fresh CleoOS install".
-version: 1.0.0
-core: false
-category: meta
-protocol: null
-argument-hint: "[--verify] [--force]"
-allowed-tools: ["Read", "Write", "Bash(cp *)", "Bash(ls *)", "Bash(mkdir *)", "Bash(test *)"]
-dependencies:
-  - ct-cleo
-sharedResources:
-  - subagent-protocol-base
-compatibility:
-  - claude-code
-  - cursor
-  - windsurf
-  - gemini-cli
-license: MIT
-install-hook: "tools.skill.install ct-master-tac"
-metadata:
-  version: 1.0.0
-  tier: internal
-  install: internal
-  stability: deprecated
----
-
-# ct-master-tac — Master Tactical Bundle
-
-> **Provenance**: @task T430, @epic T382, @umbrella T377
-> **Bundle version**: 1.0.0 — ships with CleoOS v2026.4.x
-
-The Master TAC (Tactical Asset Cache) plugin bundles every protocol primitive the
-autonomous execution layer requires. After `tools.skill.install ct-master-tac`, a
-fresh CleoOS install has batteries-included support for the full RCASD-IVTR+C
-lifecycle.
-
----
-
-## What's Inside
-
-### 12 CANT Protocol Files (`bundled/protocols/`)
-
-| File | ID | Stage | Skill |
-|------|----|-------|-------|
-| `research.cant` | RSCH | research | ct-research-agent |
-| `consensus.cant` | CONS | consensus | ct-consensus-voter |
-| `architecture-decision.cant` | ADR | architecture-decision | ct-adr-recorder |
-| `specification.cant` | SPEC | specification | ct-spec-writer |
-| `decomposition.cant` | DCMP | decomposition | ct-epic-architect |
-| `implementation.cant` | IMPL | implementation | ct-task-executor |
-| `validation.cant` | VALID | validation | ct-validator |
-| `testing.cant` | TEST | testing | ct-ivt-looper |
-| `contribution.cant` | CONT | cross-cutting | ct-contribution |
-| `release.cant` | REL | release | ct-release-orchestrator |
-| `artifact-publish.cant` | ART | release | ct-artifact-publisher |
-| `provenance.cant` | PROV | release | ct-provenance-keeper |
-
-### Platform Team (`bundled/teams/platform.cant`)
-
-Canonical 3-tier team definition with planning-lead, engineering-lead, and
-validation-lead. Mirrors the `.cleo/teams.cant` seed from a standard CleoOS init.
-
----
-
-## Install Behaviour
-
-```bash
-tools.skill.install ct-master-tac
-```
-
-The install hook:
-
-1. Copies `bundled/protocols/*.cant` to
-   `packages/core/src/validation/protocols/cant/` (skips files that already exist
-   unless `--force` is provided).
-2. Copies `bundled/teams/platform.cant` to `.cleo/teams.cant` (skips if exists).
-3. Verifies that all 12 protocol files are present and parseable.
-4. Emits an install summary to stdout.
-
-Running install a second time is a no-op (idempotent).
-
----
-
-## Verify Mode
-
-```bash
-tools.skill.install ct-master-tac --verify
-```
-
-Read-only. Checks that all bundled files are present at their target locations and
-reports any missing or mismatched files without writing anything.
-
----
-
-## Plugin Boundary (§11 criteria)
-
-This plugin meets all three §11 criteria from `docs/specs/CLEO-OPERATION-CONSTITUTION.md`:
-
-- **(a)** Requires reading protocol CANT files managed outside the core CLI binary.
-- **(b)** Reads `bundled/` assets not managed by the CLEO core package.
-- **(c)** Removing it from core does not break any mandatory agent workflow — it is
-  a bootstrap/recovery utility only.
-
----
-
-## Upgrade Path
-
-When new protocol files are added, bump `version` in this SKILL.md and
-`manifest.json`, add the new `.cant` file to `bundled/protocols/`, and update the
-`manifest.json` `files` array. The install hook will copy the new file on next run.

package/skills/ct-master-tac/__tests__/install.test.ts

@@ -1,304 +0,0 @@
-/**
- * Install verification tests for the ct-master-tac plugin (T431).
- *
- * Asserts:
- * - SKILL.md has valid YAML frontmatter
- * - manifest.json parses correctly and references the correct files
- * - All files referenced in manifest.json `files` array exist under bundled/
- * - Install is idempotent (second run produces no additional writes)
- * - Bundle contains exactly 12 protocol files + 1 platform team file
- *
- * @task T431
- * @epic T382
- * @umbrella T377
- */
-
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const thisFile = fileURLToPath(import.meta.url);
-/** Absolute path to the ct-master-tac root directory */
-const skillRoot = resolve(dirname(thisFile), '..');
-
-/**
- * Parse YAML frontmatter from a Markdown file.
- * Returns the raw frontmatter string between the opening and closing `---`.
- */
-function extractFrontmatter(content: string): string | null {
-  const match = /^---\r?\n([\s\S]*?)\r?\n---/m.exec(content);
-  return match ? match[1] : null;
-}
-
-/**
- * Minimal frontmatter key extractor — no external deps, just key: value lines.
- */
-function parseFrontmatterKeys(fm: string): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const line of fm.split('\n')) {
-    const m = /^(\w[\w-]*):\s*(.*)$/.exec(line.trimEnd());
-    if (m) {
-      result[m[1]] = m[2].replace(/^["']|["']$/g, '');
-    }
-  }
-  return result;
-}
-
-/**
- * Read the nested `metadata:` map the way scripts/skills/lib/skill-frontmatter.mjs
- * does: the indented `key: value` lines directly under a top-level `metadata:`.
- */
-function parseFrontmatterMetadata(fm: string): Record<string, string> {
-  const result: Record<string, string> = {};
-  const lines = fm.split('\n');
-  const start = lines.findIndex((l) => l.trimEnd() === 'metadata:');
-  if (start === -1) return result;
-  for (const line of lines.slice(start + 1)) {
-    const m = /^\s+([A-Za-z][\w-]*):\s*(.*)$/.exec(line.trimEnd());
-    if (!m) break;
-    result[m[1]] = m[2].replace(/^["']|["']$/g, '');
-  }
-  return result;
-}
-
-// ---------------------------------------------------------------------------
-// Mock install helper for idempotency test
-// ---------------------------------------------------------------------------
-
-interface InstallResult {
-  copiedFiles: string[];
-  skippedFiles: string[];
-}
-
-/**
- * Simulated install helper — copies bundled/ files to target paths.
- * Returns lists of copied and skipped files so idempotency can be verified.
- */
-function mockInstall(
-  manifestFiles: string[],
-  alreadyInstalled: Set<string>,
-): InstallResult {
-  const copiedFiles: string[] = [];
-  const skippedFiles: string[] = [];
-
-  for (const f of manifestFiles) {
-    if (alreadyInstalled.has(f)) {
-      skippedFiles.push(f);
-    } else {
-      copiedFiles.push(f);
-    }
-  }
-
-  return { copiedFiles, skippedFiles };
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('ct-master-tac plugin (T431)', () => {
-  describe('SKILL.md frontmatter', () => {
-    const skillMdPath = join(skillRoot, 'SKILL.md');
-
-    it('SKILL.md exists', () => {
-      expect(existsSync(skillMdPath)).toBe(true);
-    });
-
-    it('SKILL.md contains valid frontmatter delimiters', () => {
-      const content = readFileSync(skillMdPath, 'utf-8');
-      const fm = extractFrontmatter(content);
-      expect(fm).not.toBeNull();
-    });
-
-    it('frontmatter has required fields: name, description, metadata.version, metadata.tier', () => {
-      const content = readFileSync(skillMdPath, 'utf-8');
-      const fm = extractFrontmatter(content);
-      expect(fm).not.toBeNull();
-      const keys = parseFrontmatterKeys(fm!);
-      expect(keys['name']).toBe('ct-master-tac');
-      expect(keys['description']).toBeTruthy();
-      // T12648: version and tier live under `metadata:` (skills SSoT, D11157).
-      const metadata = parseFrontmatterMetadata(fm!);
-      expect(metadata['version']).toMatch(/^\d+\.\d+\.\d+$/);
-      expect(['core', 'on-demand', 'internal']).toContain(metadata['tier']);
-      expect(keys['tier']).toBeUndefined();
-      if (keys['version'] !== undefined) expect(keys['version']).toBe(metadata['version']);
-    });
-  });
-
-  describe('manifest.json', () => {
-    const manifestPath = join(skillRoot, 'manifest.json');
-    let manifest: Record<string, unknown>;
-
-    it('manifest.json exists', () => {
-      expect(existsSync(manifestPath)).toBe(true);
-    });
-
-    it('manifest.json parses as valid JSON', () => {
-      const raw = readFileSync(manifestPath, 'utf-8');
-      expect(() => {
-        manifest = JSON.parse(raw) as Record<string, unknown>;
-      }).not.toThrow();
-    });
-
-    it('manifest has required top-level keys', () => {
-      const raw = readFileSync(manifestPath, 'utf-8');
-      manifest = JSON.parse(raw) as Record<string, unknown>;
-      expect(manifest['name']).toBe('ct-master-tac');
-      expect(manifest['version']).toBeTruthy();
-      expect(Array.isArray(manifest['files'])).toBe(true);
-    });
-
-    it('files array contains exactly 13 entries (12 protocols + 1 team)', () => {
-      const raw = readFileSync(manifestPath, 'utf-8');
-      manifest = JSON.parse(raw) as Record<string, unknown>;
-      const files = manifest['files'] as string[];
-      expect(files).toHaveLength(13);
-    });
-
-    it('files array contains at least 12 protocol entries', () => {
-      const raw = readFileSync(manifestPath, 'utf-8');
-      manifest = JSON.parse(raw) as Record<string, unknown>;
-      const files = manifest['files'] as string[];
-      const protocolFiles = files.filter((f) => f.startsWith('bundled/protocols/'));
-      expect(protocolFiles.length).toBeGreaterThanOrEqual(12);
-    });
-
-    it('files array contains platform team entry', () => {
-      const raw = readFileSync(manifestPath, 'utf-8');
-      manifest = JSON.parse(raw) as Record<string, unknown>;
-      const files = manifest['files'] as string[];
-      expect(files).toContain('bundled/teams/platform.cant');
-    });
-  });
-
-  describe('bundled files exist', () => {
-    it('all files referenced in manifest.json exist under bundled/', () => {
-      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
-      const manifest = JSON.parse(raw) as { files: string[] };
-      const missingFiles: string[] = [];
-
-      for (const f of manifest.files) {
-        const abs = join(skillRoot, f);
-        if (!existsSync(abs)) {
-          missingFiles.push(f);
-        }
-      }
-
-      expect(missingFiles).toEqual([]);
-    });
-
-    it('each bundled protocol file is non-empty', () => {
-      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
-      const manifest = JSON.parse(raw) as { files: string[] };
-      const emptyFiles: string[] = [];
-
-      for (const f of manifest.files.filter((f) =>
-        f.startsWith('bundled/protocols/'),
-      )) {
-        const abs = join(skillRoot, f);
-        const content = readFileSync(abs, 'utf-8');
-        if (content.trim().length === 0) {
-          emptyFiles.push(f);
-        }
-      }
-
-      expect(emptyFiles).toEqual([]);
-    });
-
-    it('each bundled protocol file has CANT frontmatter (kind: protocol)', () => {
-      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
-      const manifest = JSON.parse(raw) as { files: string[] };
-      const badFiles: string[] = [];
-
-      for (const f of manifest.files.filter((f) =>
-        f.startsWith('bundled/protocols/'),
-      )) {
-        const abs = join(skillRoot, f);
-        const content = readFileSync(abs, 'utf-8');
-        if (!content.includes('kind: protocol')) {
-          badFiles.push(f);
-        }
-      }
-
-      expect(badFiles).toEqual([]);
-    });
-  });
-
-  describe('idempotent install (mock)', () => {
-    it('first install copies all 13 files', () => {
-      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
-      const manifest = JSON.parse(raw) as { files: string[] };
-      const already = new Set<string>();
-
-      const result = mockInstall(manifest.files, already);
-      expect(result.copiedFiles).toHaveLength(13);
-      expect(result.skippedFiles).toHaveLength(0);
-    });
-
-    it('second install (files already present) skips all 13 files', () => {
-      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
-      const manifest = JSON.parse(raw) as { files: string[] };
-      // Simulate first install — all files now "present"
-      const already = new Set<string>(manifest.files);
-
-      const result = mockInstall(manifest.files, already);
-      expect(result.copiedFiles).toHaveLength(0);
-      expect(result.skippedFiles).toHaveLength(13);
-    });
-
-    it('partial install (3 missing) copies only missing files', () => {
-      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
-      const manifest = JSON.parse(raw) as { files: string[] };
-      // 10 of 13 already installed
-      const already = new Set<string>(manifest.files.slice(0, 10));
-
-      const result = mockInstall(manifest.files, already);
-      expect(result.copiedFiles).toHaveLength(3);
-      expect(result.skippedFiles).toHaveLength(10);
-    });
-  });
-
-  describe('bundle completeness', () => {
-    const EXPECTED_PROTOCOLS = [
-      'research.cant',
-      'consensus.cant',
-      'architecture-decision.cant',
-      'specification.cant',
-      'decomposition.cant',
-      'implementation.cant',
-      'validation.cant',
-      'testing.cant',
-      'contribution.cant',
-      'release.cant',
-      'artifact-publish.cant',
-      'provenance.cant',
-    ] as const;
-
-    for (const protocol of EXPECTED_PROTOCOLS) {
-      it(`bundled/protocols/${protocol} exists`, () => {
-        expect(
-          existsSync(join(skillRoot, 'bundled', 'protocols', protocol)),
-        ).toBe(true);
-      });
-    }
-
-    it('bundled/teams/platform.cant exists', () => {
-      expect(existsSync(join(skillRoot, 'bundled', 'teams', 'platform.cant'))).toBe(
-        true,
-      );
-    });
-
-    it('bundle contains exactly 12 CANT protocol files', () => {
-      const protocolFiles = EXPECTED_PROTOCOLS.filter((f) =>
-        existsSync(join(skillRoot, 'bundled', 'protocols', f)),
-      );
-      expect(protocolFiles).toHaveLength(12);
-    });
-  });
-});

package/skills/ct-master-tac/bundled/README.md

@@ -1,40 +0,0 @@
-# ct-master-tac Bundle Contents
-
-> @task T430 @epic T382 @umbrella T377
-> Source: `packages/skills/skills/ct-master-tac/bundled/`
-
-This directory holds the canonical bundle assets shipped with the `ct-master-tac` plugin.
-
-## protocols/
-
-Copies of the 12 CANT protocol files from
-`packages/core/src/validation/protocols/cant/`.
-
-Each file defines a protocol primitive in the RCASD-IVTR+C lifecycle:
-
-| File | ID | RCASD Stage |
-|------|----|-------------|
-| `research.cant` | RSCH | R — Research |
-| `consensus.cant` | CONS | C — Consensus |
-| `architecture-decision.cant` | ADR | A — Architecture Decision |
-| `specification.cant` | SPEC | S — Specification |
-| `decomposition.cant` | DCMP | D — Decomposition |
-| `implementation.cant` | IMPL | I — Implementation |
-| `validation.cant` | VALID | V — Validation |
-| `testing.cant` | TEST | T — Testing |
-| `contribution.cant` | CONT | cross-cutting |
-| `release.cant` | REL | R — Release |
-| `artifact-publish.cant` | ART | release sub-protocol |
-| `provenance.cant` | PROV | release sub-protocol |
-
-## teams/
-
-| File | Description |
-|------|-------------|
-| `platform.cant` | Canonical 3-tier CleoOS platform team seed |
-
-## Maintenance
-
-When protocol files change in `packages/core/src/validation/protocols/cant/`,
-re-copy them here and bump the version in `ct-master-tac/manifest.json` and
-`ct-master-tac/SKILL.md`.