@cleocode/skills 2026.5.84 → 2026.5.87

package/skills/ct-research-agent/references/triggers-and-routing.md

@@ -0,0 +1,93 @@
+# Triggers and Routing
+
+When to load `ct-research-agent`, what tasks it owns, and how it hands off
+to neighboring skills in the RCASD-IVTR+C pipeline. The skill operates as the
+`research` protocol within the orchestrator's stage taxonomy and is the first
+skill invoked when an Epic enters its research lifecycle stage.
+
+## Primary Triggers
+
+Load this skill when the orchestrator (or the user) requests any of the
+following — the dispatch matrix in `manifest.json` enumerates the canonical
+keyword set.
+
+| Trigger phrase | Routing decision |
+|----------------|------------------|
+| "research <topic>" | Direct invocation — proceed with multi-source pull |
+| "investigate <area>" | Same as research; emphasize codebase + web blend |
+| "explore options for <decision>" | Treat as research → ct-consensus-voter |
+| "what does the literature say about X" | Web + Context7 lookup, no codebase |
+| "audit current <subsystem> implementation" | Codebase-only research; skip web |
+| "compare libraries for <use-case>" | Web + Context7 with `--research` flag |
+| "due-diligence on <vendor/tool>" | Web + reputation + license scan |
+
+The orchestrator's `cleo orchestrate spawn` prompt always carries a
+`stage: research` hint when the task's `pipelineStage` field equals
+`research`. The skill SHOULD honor that hint and SHOULD NOT advance the
+pipeline stage on its own — that is the orchestrator's responsibility once
+the research manifest entry is appended.
+
+## Anti-Triggers (Do NOT Load)
+
+The skill MUST NOT be loaded for the following requests because they belong
+to sibling skills that have narrower context budgets and stricter contracts.
+
+| Request | Correct skill |
+|---------|---------------|
+| "fix this failing test" | `ct-task-executor` |
+| "write the spec for X" | `ct-spec-writer` |
+| "validate this implementation against the spec" | `ct-validator` |
+| "decompose this epic into tasks" | `ct-epic-architect` |
+| "look up Next.js 15 middleware API" | `ct-docs-lookup` (single-library fetch) |
+| "decide between A and B" (no investigation needed) | `ct-consensus-voter` |
+| "explain this function" | (no skill — direct read suffices) |
+
+A useful heuristic: if the user already knows the answer and just wants it
+written down, route to `ct-spec-writer` or `ct-docs-write`. Research is for
+when the answer is not yet known.
+
+## Routing to Downstream Skills
+
+Research outputs typically feed one of these next stages. The manifest
+`chains_to` array enumerates the legal handoffs.
+
+1. **`ct-spec-writer`** — when findings produce testable requirements.
+   Pass the research file path and the synthesized recommendations as
+   spec input. Use this when the task description contains "spec",
+   "contract", "RFC", or "protocol".
+2. **`ct-epic-architect`** — when findings change the scope estimate of
+   an Epic. The architect re-decomposes based on the new evidence.
+3. **`ct-consensus-voter`** — when research surfaces two-or-more viable
+   options with comparable trade-offs. The voter resolves the choice
+   under HITL when confidence < 0.5.
+4. **`ct-task-executor`** — only when the research itself contains an
+   actionable next step that does not require a spec (e.g. "bump the
+   library version" or "delete deprecated path"). Rare.
+
+## Decision Tree
+
+```
+Is the answer already known and just needs documentation?
+├── YES → ct-docs-write
+└── NO → continue
+    │
+    Is this a single-library API question?
+    ├── YES → ct-docs-lookup
+    └── NO → ct-research-agent (this skill)
+        │
+        After research, do findings produce requirements?
+        ├── YES → ct-spec-writer next
+        └── NO → continue
+            │
+            Do findings produce a decision between options?
+            ├── YES → ct-consensus-voter next
+            └── NO → return manifest only, no chain
+```
+
+## Stage Hint Compliance
+
+The orchestrator's `pipeline_manifest` table tracks per-task stage
+progression. The research skill MUST append exactly one entry with
+`agent_type: "research"` and MUST NOT mutate stage fields directly. If
+findings indicate a stage advance is warranted, the skill SHOULD include
+that suggestion in `needs_followup` so the orchestrator can act on it.

package/skills/ct-skill-validator/SKILL.md

@@ -36,8 +36,27 @@ python ${CLAUDE_SKILL_DIR}/scripts/audit_body.py <skill-dir>
 
 # Manifest alignment check:
 python ${CLAUDE_SKILL_DIR}/scripts/check_manifest.py <skill-dir> <manifest.json>
+
+# Progressive-disclosure depth check (T9684 — CI gate):
+python ${CLAUDE_SKILL_DIR}/scripts/check_depth.py <skill-dir>
+
+# Repo-wide depth sweep:
+python ${CLAUDE_SKILL_DIR}/scripts/check_depth.py <repo-root> --all
 ```
 
+**Depth rule (T9684):** A skill PASSES when ANY of:
+
+- SKILL.md body has ≥ 100 content lines, OR
+- `references/` subdir has ≥ 3 markdown files, OR
+- `manifest.json` `references[]` array enumerates ≥ 3 files (all on disk)
+
+Pre-existing stubs are allowlisted with follow-up task IDs in
+`scripts/check_depth.py::ALLOWLIST`. Gold-standard skills:
+`ct-orchestrator` (9 refs) and `ct-skill-creator` (7 refs).
+
+The depth check runs on every PR touching `packages/skills/skills/**`
+via `.github/workflows/skills-depth-check.yml`.
+
 **Iteration rule**: If errors > 0, fix them in the skill's SKILL.md, re-run `validate.py`.
 Repeat until errors = 0. Do not proceed to Phase 2 while errors remain.
 

package/skills/ct-skill-validator/scripts/check_depth.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""
+CLEO Skill Depth Check — progressive-disclosure-depth rule (T9684).
+
+Fails when a skill's SKILL.md is below the depth threshold AND it has
+no references/ subdir with at least the manifest-declared reference
+files. The gold standard is ct-orchestrator (9 references) and
+ct-skill-creator (7 references); the rule is calibrated to flag
+stubs without forcing every skill to that depth.
+
+Rule logic:
+  PASS when ANY of:
+    - SKILL.md body has >= MIN_BODY_LINES content lines
+    - references/ subdir exists with >= MIN_REF_FILES files
+    - manifest.json references[] array populated with file paths that
+      all exist on disk
+
+  FAIL when:
+    - SKILL.md body < MIN_BODY_LINES lines AND
+    - references/ missing or has < MIN_REF_FILES files AND
+    - manifest.json references[] empty or files missing
+
+Error message points at the gold standard and lists expected files
+from the manifest entry (when present) so the fix is obvious.
+
+Usage:
+    check_depth.py <skill-directory>
+    check_depth.py <skill-directory> --manifest path/to/manifest.json
+    check_depth.py <skill-directory> --all                  # walk all skills under a root
+    check_depth.py <skill-directory> --json
+"""
+import sys
+import re
+import json
+import argparse
+from pathlib import Path
+
+
+# Calibration knobs — set against the post-T9567 state.
+# Adjust here, then re-run the audit to verify all 19 active skills pass.
+MIN_BODY_LINES = 100
+MIN_REF_FILES = 3
+GOLD_STANDARDS = ("ct-orchestrator", "ct-skill-creator")
+
+# Allowlist — pre-existing stub skills exempted at T9567 (E-SKILLS-DEPTH-BACKFILL).
+# Each entry MUST have a follow-up task ID. Remove the entry once that task lands
+# a depth backfill. New entries require owner approval — do not add silently.
+ALLOWLIST: dict[str, str] = {
+    "ct-codebase-mapper": "T9567-followup: pre-existing; depth-backfill deferred",
+    "ct-master-tac": "T9567-followup: pre-existing; depth-backfill deferred",
+    "ct-memory": "T9567-followup: pre-existing; depth-backfill deferred",
+    "ct-stickynote": "T9567-followup: ephemeral note skill; minimal-by-design",
+}
+
+
+def count_body_lines(skill_md_path: Path) -> int:
+    """Count content lines in the SKILL.md body (excluding frontmatter)."""
+    if not skill_md_path.exists():
+        return 0
+    raw = skill_md_path.read_text(encoding="utf-8")
+    if not raw.startswith("---"):
+        # No frontmatter — count whole file
+        return len(raw.split("\n"))
+    parts = raw.split("---", 2)
+    if len(parts) < 3:
+        return 0
+    body = parts[2].strip()
+    if not body:
+        return 0
+    return len(body.split("\n"))
+
+
+def manifest_references_for(skill_name: str, manifest_path: Path) -> list[str]:
+    """Return the references array from manifest.json for the given skill,
+    or empty list if not present."""
+    if not manifest_path.exists():
+        return []
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return []
+    for entry in data.get("skills", []):
+        if entry.get("name") == skill_name:
+            return entry.get("references", []) or []
+    return []
+
+
+def repo_root_of(skill_dir: Path) -> Path:
+    """Walk up from skill_dir to the repo root (heuristic: contains
+    `packages/skills/skills/manifest.json`)."""
+    cur = skill_dir.resolve()
+    for _ in range(10):
+        if (cur / "packages" / "skills" / "skills" / "manifest.json").exists():
+            return cur
+        if cur.parent == cur:
+            break
+        cur = cur.parent
+    return skill_dir  # fallback
+
+
+def check_depth(skill_path: Path, manifest_path: Path | None = None) -> tuple[bool, dict]:
+    """Run the depth check on a single skill directory.
+
+    Returns (passed, report_dict).
+    """
+    skill_dir = Path(skill_path).resolve()
+    skill_name = skill_dir.name
+    skill_md = skill_dir / "SKILL.md"
+    refs_dir = skill_dir / "references"
+
+    report: dict = {
+        "skill_name": skill_name,
+        "path": str(skill_dir),
+        "body_lines": 0,
+        "ref_files_on_disk": 0,
+        "manifest_references": [],
+        "manifest_references_missing": [],
+        "thresholds": {
+            "min_body_lines": MIN_BODY_LINES,
+            "min_ref_files": MIN_REF_FILES,
+        },
+        "passed": False,
+        "reasons": [],
+        "remediation": [],
+    }
+
+    # Threshold A: body length
+    body_lines = count_body_lines(skill_md)
+    report["body_lines"] = body_lines
+    body_passes = body_lines >= MIN_BODY_LINES
+
+    # Threshold B: references/ subdir
+    ref_files_on_disk = 0
+    if refs_dir.is_dir():
+        ref_files_on_disk = len([p for p in refs_dir.iterdir() if p.is_file() and p.suffix == ".md"])
+    report["ref_files_on_disk"] = ref_files_on_disk
+    refs_dir_passes = ref_files_on_disk >= MIN_REF_FILES
+
+    # Threshold C: manifest.json references populated and on disk
+    manifest_passes = False
+    if manifest_path is None:
+        # Auto-locate from repo root
+        root = repo_root_of(skill_dir)
+        manifest_path = root / "packages" / "skills" / "skills" / "manifest.json"
+
+    if manifest_path.exists():
+        manifest_refs = manifest_references_for(skill_name, manifest_path)
+        report["manifest_references"] = manifest_refs
+        if manifest_refs:
+            root = repo_root_of(skill_dir)
+            base = root / "packages" / "skills"
+            missing = []
+            for rel in manifest_refs:
+                ref_abs = base / rel
+                if not ref_abs.exists():
+                    # Try relative to skill_dir as fallback
+                    fallback = skill_dir / Path(rel).relative_to(Path(rel).parts[0]) \
+                        if Path(rel).parts else None
+                    if fallback is None or not fallback.exists():
+                        missing.append(rel)
+            report["manifest_references_missing"] = missing
+            manifest_passes = (len(manifest_refs) >= MIN_REF_FILES and not missing)
+
+    # Decide pass/fail — ANY threshold passes ⇒ depth check passes.
+    passed = body_passes or refs_dir_passes or manifest_passes
+    report["passed"] = passed
+
+    if body_passes:
+        report["reasons"].append(f"body_lines={body_lines} >= {MIN_BODY_LINES}")
+    if refs_dir_passes:
+        report["reasons"].append(f"references/ has {ref_files_on_disk} files >= {MIN_REF_FILES}")
+    if manifest_passes:
+        report["reasons"].append(
+            f"manifest references[] populated with {len(report['manifest_references'])} files (all on disk)"
+        )
+
+    # Allowlist override — exempted skills pass with a reason captured.
+    if not passed and skill_name in ALLOWLIST:
+        passed = True
+        report["passed"] = True
+        report["allowlisted"] = True
+        report["allowlist_reason"] = ALLOWLIST[skill_name]
+        report["reasons"].append(f"allowlisted: {ALLOWLIST[skill_name]}")
+
+    if not passed:
+        report["reasons"].append("none of the three thresholds met")
+        report["remediation"] = [
+            f"Expand SKILL.md body to >= {MIN_BODY_LINES} content lines (currently {body_lines}), OR",
+            f"Add references/ subdir with >= {MIN_REF_FILES} markdown files (currently {ref_files_on_disk}), OR",
+            "Populate manifest.json references[] array for this skill with file paths.",
+            f"Gold-standard examples: {', '.join(GOLD_STANDARDS)}.",
+        ]
+        if report["manifest_references_missing"]:
+            report["remediation"].append(
+                "Manifest references[] lists files that do not exist on disk: "
+                + ", ".join(report["manifest_references_missing"])
+            )
+
+    return passed, report
+
+
+def _print_report(report: dict) -> None:
+    """Print a single skill's depth report."""
+    name = report["skill_name"]
+    status = "PASS" if report["passed"] else "FAIL"
+    icon = "✅" if report["passed"] else "❌"
+    print(f"\n{icon} {status}  {name}")
+    print(f"     body_lines={report['body_lines']} (min {MIN_BODY_LINES})")
+    print(f"     ref_files_on_disk={report['ref_files_on_disk']} (min {MIN_REF_FILES})")
+    print(f"     manifest_references={len(report['manifest_references'])} files")
+    if report["manifest_references_missing"]:
+        print(f"     manifest_references_missing={report['manifest_references_missing']}")
+    for r in report["reasons"]:
+        print(f"     - {r}")
+    if not report["passed"]:
+        print("     remediation:")
+        for r in report["remediation"]:
+            print(f"       * {r}")
+
+
+def walk_all_skills(root: Path) -> list[Path]:
+    """Find all skill directories under packages/skills/skills/.
+    Skips manifest.json, _shared/, and any dir without SKILL.md."""
+    base = root if (root / "SKILL.md").exists() else (root / "packages" / "skills" / "skills")
+    if not base.is_dir():
+        return []
+    skills = []
+    for entry in sorted(base.iterdir()):
+        if not entry.is_dir():
+            continue
+        if entry.name.startswith("_") or entry.name.startswith("."):
+            continue
+        if (entry / "SKILL.md").exists():
+            skills.append(entry)
+    return skills
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="CLEO Skill Depth Check (T9684) — progressive-disclosure-depth"
+    )
+    parser.add_argument("skill_dir", help="Path to the skill directory (or repo root if --all)")
+    parser.add_argument("--manifest", help="Path to manifest.json (auto-located if omitted)")
+    parser.add_argument(
+        "--all", action="store_true",
+        help="Walk every skill under packages/skills/skills/",
+    )
+    parser.add_argument("--json", action="store_true", help="Output JSON instead of text")
+    args = parser.parse_args()
+
+    arg_path = Path(args.skill_dir).resolve()
+    manifest = Path(args.manifest).resolve() if args.manifest else None
+
+    if args.all:
+        skills = walk_all_skills(arg_path)
+        if not skills:
+            print(f"Error: no skill directories found under {arg_path}", file=sys.stderr)
+            return 1
+        all_reports = []
+        total_fail = 0
+        for s in skills:
+            passed, report = check_depth(s, manifest)
+            all_reports.append(report)
+            if not passed:
+                total_fail += 1
+        if args.json:
+            print(json.dumps({
+                "summary": {
+                    "total": len(all_reports),
+                    "passed": len(all_reports) - total_fail,
+                    "failed": total_fail,
+                    "thresholds": {
+                        "min_body_lines": MIN_BODY_LINES,
+                        "min_ref_files": MIN_REF_FILES,
+                    },
+                },
+                "skills": all_reports,
+            }, indent=2))
+        else:
+            print(f"=== CLEO Skill Depth Check (all skills under {arg_path}) ===")
+            for r in all_reports:
+                _print_report(r)
+            print(f"\n=== SUMMARY ===")
+            print(f"Total skills: {len(all_reports)}")
+            print(f"Passed: {len(all_reports) - total_fail}")
+            print(f"Failed: {total_fail}")
+        return 1 if total_fail > 0 else 0
+
+    # Single-skill mode
+    if not arg_path.is_dir():
+        print(f"Error: '{args.skill_dir}' is not a directory", file=sys.stderr)
+        return 1
+    if not (arg_path / "SKILL.md").exists():
+        print(f"Error: '{args.skill_dir}' has no SKILL.md", file=sys.stderr)
+        return 1
+
+    passed, report = check_depth(arg_path, manifest)
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        _print_report(report)
+    return 0 if passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/ct-spec-writer/SKILL.md

@@ -140,9 +140,70 @@ Non-compliant implementations SHOULD {remediation}.
 
 ---
 
+## Through SDK (preferred)
+
+Specifications are first-class docs SSoT records — created via
+`cleo docs add --type spec`, auto-attached to the parent task, and
+addressable by a stable slug. This is the canonical write path; the
+legacy "write to `docs/specs/<NAME>.md` and commit" pattern is
+deprecated below.
+
+### Write the spec attached to its parent task
+
+```bash
+cleo docs add T1234 docs/specs/auth-protocol.md \
+  --type spec \
+  --slug auth-protocol-v2 \
+  --desc "Auth protocol v2 — RFC 2119 requirements"
+```
+
+- `--type spec` is the canonical taxonomy value for a specification.
+  Other allowed values: `adr | research | handoff | note | llm-readme`.
+- `--slug` is the kebab-case retrieval handle. Use the spec topic +
+  version (e.g. `auth-protocol-v2`, `release-pipeline-v3`). The CLI
+  returns `E_SLUG_TAKEN` with 3 alternatives on collision — pick one
+  rather than silently overwriting.
+- The owner ID (`T1234`) auto-attaches the spec to its parent task so
+  downstream stages (`ct-validator`, decomposition, implementation)
+  can discover the spec via `cleo docs list --task T1234 --type spec`.
+
+### Publish the spec to a git-tracked path (when the spec must ship on disk)
+
+```bash
+cleo docs publish --for T1234 --to docs/specs/auth-protocol.md
+```
+
+Atomic tmp-then-rename. The published file lands in the next commit;
+the SSoT blob remains canonical and continues to track future versions.
+
+### Fetch the spec back by slug
+
+```bash
+cleo docs fetch auth-protocol-v2          # latest version
+cleo docs versions --for T1234            # every SHA version
+```
+
+### Discover sibling specs in this project
+
+```bash
+cleo docs list --type spec --project      # every spec in the project
+cleo docs list --task T1234 --type spec   # specs attached to T1234
+```
+
+## Deprecated: Direct filesystem write
+
+The legacy "write to `docs/specs/{{SPEC_NAME}}.md` and commit" pattern
+is deprecated. The on-disk file drifts from the SSoT, the spec has no
+slug for downstream skills to retrieve it by, and the task↔spec
+linkage exists only as a path convention. Migrate to
+`cleo docs add --type spec --slug <name>` for every new spec — and use
+`cleo docs sync --from docs/specs/<name>.md --for <taskId>` to
+back-fill existing on-disk specs into the SSoT.
+
 ## Output Location
 
-Specifications go in: `docs/specs/{{SPEC_NAME}}.md`
+Spec blobs live in the docs SSoT; published copies on disk go in
+`docs/specs/{{SPEC_NAME}}.md`.
 
 ---
 
@@ -202,3 +263,12 @@ This skill binds to the **specification** LOOM lifecycle stage. Governing ADRs:
 - [ADR-023 — protocol validation dispatch](../../../../.cleo/adrs/ADR-023-protocol-validation-dispatch.md) — defines how specifications are validated before decomposition.
 
 LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/rfc2119-language.md` — keyword semantics, positive/negative examples, decision rubric
+- `references/spec-templates.md` — protocol, API, architecture, requirements scaffolds + naming + versioning
+- `references/traceability-matrix.md` — three-way trace from source to REQ to test, drift detection
+- `references/anti-patterns.md` — ten failure modes seen in past spec drafts

package/skills/ct-spec-writer/__tests__/skill-spec-writer.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Regression test for ct-spec-writer/SKILL.md (T9643 / Epic T9629 / Saga T9625).
+ *
+ * Pins the SDK-first spec contract: specs MUST be created via
+ * `cleo docs add --type spec --slug <name>` so they auto-attach to the
+ * parent task and are retrievable by slug. The Output Location section
+ * may still mention `docs/specs/{{SPEC_NAME}}.md` as the published path,
+ * but the canonical write surface is the SDK.
+ *
+ * @task T9643
+ * @epic T9629
+ * @saga T9625
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const thisFile = fileURLToPath(import.meta.url);
+const skillRoot = resolve(dirname(thisFile), '..');
+const skillPath = join(skillRoot, 'SKILL.md');
+const skillContent = readFileSync(skillPath, 'utf-8');
+
+describe('ct-spec-writer SKILL.md — SDK-first contract (T9643)', () => {
+  it('teaches `cleo docs add --type spec` as the canonical write path', () => {
+    expect(skillContent).toMatch(/cleo docs add[\s\S]+--type spec/);
+  });
+
+  it('shows `--slug` as the kebab-case retrieval handle', () => {
+    expect(skillContent).toContain('--slug');
+    expect(skillContent).toMatch(/kebab-case/);
+  });
+
+  it('attaches the spec to a parent task via the owner ID', () => {
+    // Owner ID example must use a T### prefix to demonstrate task linkage
+    expect(skillContent).toMatch(/cleo docs add\s+T\d+\s/);
+  });
+
+  it('shows `cleo docs publish --for ... --to docs/specs/...` for git publication', () => {
+    expect(skillContent).toMatch(/cleo docs publish[\s\S]+--for[\s\S]+--to[\s\S]+docs\/specs/);
+  });
+
+  it('shows `cleo docs fetch <slug>` for downstream retrieval', () => {
+    expect(skillContent).toContain('cleo docs fetch');
+  });
+
+  it('shows `cleo docs list --type spec` for sibling spec discovery', () => {
+    expect(skillContent).toMatch(/cleo docs list[\s\S]+--type spec/);
+  });
+
+  it('marks the old direct-filesystem write as deprecated with a migration note', () => {
+    expect(skillContent).toContain('Deprecated: Direct filesystem write');
+    expect(skillContent).toMatch(/cleo docs (add|sync)/);
+  });
+
+  it('references E_SLUG_TAKEN for collision handling', () => {
+    expect(skillContent).toContain('E_SLUG_TAKEN');
+  });
+});