@cleocode/skills 2.0.0

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

@@ -0,0 +1,422 @@
+#!/usr/bin/env python3
+"""
+CLEO Skill Validator — Full compliance gauntlet.
+Validates a skill directory against the complete CLEO skill standard.
+
+Usage:
+    validate.py <skill-directory>
+    validate.py <skill-directory> --manifest path/to/manifest.json
+    validate.py <skill-directory> --manifest path/to/manifest.json --dispatch-config path/to/dispatch-config.json
+    validate.py <skill-directory> --provider-map path/to/provider-skills-map.json
+    validate.py <skill-directory> --json
+"""
+import sys
+import re
+import json
+import yaml
+import argparse
+from pathlib import Path
+
+V2_STANDARD = {
+    "name", "description", "argument-hint", "disable-model-invocation",
+    "user-invocable", "allowed-tools", "model", "context", "agent", "hooks",
+    "license",
+}
+CLEO_ONLY = {
+    "version", "tier", "core", "category", "protocol",
+    "dependencies", "sharedResources", "compatibility",
+    "token_budget", "capabilities", "constraints",
+    "metadata", "tags", "triggers", "mvi_scope", "requires_tiers",
+}
+
+MANIFEST_REQUIRED_FIELDS = [
+    "name", "version", "description", "path", "status",
+    "tier", "token_budget", "capabilities", "constraints",
+]
+
+
+def validate_skill(skill_path, manifest_path=None, dispatch_config_path=None, provider_map_path=None):
+    """Run the full v2 validation gauntlet on a skill directory.
+
+    Returns (results, errors, warnings) where results is a list of
+    (tier, severity, message) tuples.
+    """
+    skill_dir = Path(skill_path).resolve()
+    skill_name = skill_dir.name
+    errors = 0
+    warnings = 0
+    results = []
+
+    def error(tier, msg):
+        nonlocal errors
+        errors += 1
+        results.append((tier, "ERROR", msg))
+
+    def warn(tier, msg):
+        nonlocal warnings
+        warnings += 1
+        results.append((tier, "WARN", msg))
+
+    def ok(tier, msg):
+        results.append((tier, "OK", msg))
+
+    # ── Tier 1 — Structure ──────────────────────────────────────────────
+    tier = 1
+    skill_md = skill_dir / "SKILL.md"
+
+    if not skill_md.exists():
+        error(tier, "SKILL.md does not exist")
+        return results, errors, warnings
+
+    ok(tier, "SKILL.md exists")
+
+    raw_content = skill_md.read_text(encoding="utf-8")
+
+    if not raw_content.startswith("---"):
+        error(tier, "SKILL.md does not start with '---' (no frontmatter block)")
+        return results, errors, warnings
+
+    ok(tier, "Content starts with '---'")
+
+    fm_match = re.match(r"^---\n(.*?)\n---", raw_content, re.DOTALL)
+    if not fm_match:
+        error(tier, "Could not extract frontmatter (missing closing '---')")
+        return results, errors, warnings
+
+    ok(tier, "Frontmatter block extracted")
+
+    raw_frontmatter = fm_match.group(1)
+    try:
+        frontmatter = yaml.safe_load(raw_frontmatter)
+    except yaml.YAMLError as e:
+        error(tier, f"Frontmatter is not valid YAML: {e}")
+        return results, errors, warnings
+
+    ok(tier, "Frontmatter is valid YAML")
+
+    if not isinstance(frontmatter, dict):
+        error(tier, "Frontmatter is not a dictionary (key: value pairs expected)")
+        return results, errors, warnings
+
+    ok(tier, "Frontmatter is a dict")
+
+    for key in frontmatter:
+        if key in CLEO_ONLY:
+            error(tier, f"Move '{key}' to manifest.json (CLEO-only field)")
+        else:
+            pass  # valid or unknown keys checked in tier 2
+
+    if not any(r[1] == "ERROR" and "CLEO-only" in r[2] for r in results):
+        ok(tier, "No CLEO-only fields in frontmatter")
+
+    # ── Tier 2 — Frontmatter Quality ────────────────────────────────────
+    tier = 2
+
+    # name checks
+    name_val = frontmatter.get("name")
+    if name_val is None:
+        error(tier, "'name' field is missing")
+    else:
+        if not isinstance(name_val, str):
+            error(tier, "'name' must be a string")
+        else:
+            if not re.match(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", name_val):
+                error(tier, f"'name' must be hyphen-case (got: '{name_val}')")
+            if "--" in name_val:
+                error(tier, "'name' must not contain consecutive hyphens")
+            if name_val.startswith("-") or name_val.endswith("-"):
+                error(tier, "'name' must not start or end with a hyphen")
+            if len(name_val) > 64:
+                error(tier, f"'name' exceeds 64 characters (got: {len(name_val)})")
+            if name_val != skill_name:
+                warn(tier, f"'name' field ('{name_val}') does not match directory name ('{skill_name}')")
+            if not any(r[1] == "ERROR" and "'name'" in r[2] for r in results if r[0] == 2):
+                ok(tier, "'name' is valid")
+
+    # description checks
+    desc_val = frontmatter.get("description")
+    if desc_val is None:
+        error(tier, "'description' field is missing")
+    else:
+        if not isinstance(desc_val, str):
+            error(tier, "'description' must be a string")
+        else:
+            if "<" in desc_val or ">" in desc_val:
+                error(tier, "'description' must not contain '<' or '>' characters")
+            if len(desc_val) > 1024:
+                error(tier, f"'description' exceeds 1024 characters (got: {len(desc_val)})")
+            if len(desc_val) < 50:
+                warn(tier, f"'description' is shorter than 50 characters (got: {len(desc_val)})")
+            trigger_indicators = ["when", "use when", "use for"]
+            has_trigger = any(ind in desc_val.lower() for ind in trigger_indicators)
+            if not has_trigger:
+                warn(tier, "'description' should contain a trigger indicator ('when', 'use when', 'use for')")
+            if desc_val.startswith("I "):
+                warn(tier, "'description' should not start with 'I ' (use third person)")
+            if not any(r[1] == "ERROR" and "'description'" in r[2] for r in results if r[0] == 2):
+                ok(tier, "'description' is valid")
+
+    # YAML multiline pitfall check
+    if "description: >" in raw_frontmatter or "description: |" in raw_frontmatter:
+        warn(tier, "'description' uses YAML multiline syntax (> or |) which can cause unexpected whitespace")
+
+    # context checks
+    context_val = frontmatter.get("context")
+    if context_val is not None:
+        if context_val != "fork":
+            error(tier, f"'context' must be 'fork' if present (got: '{context_val}')")
+        else:
+            if "agent" not in frontmatter:
+                warn(tier, "'context' is 'fork' but no 'agent' field specified")
+            ok(tier, "'context' is valid")
+
+    # boolean field checks
+    dmi_val = frontmatter.get("disable-model-invocation")
+    if dmi_val is not None and not isinstance(dmi_val, bool):
+        error(tier, "'disable-model-invocation' must be a boolean")
+
+    ui_val = frontmatter.get("user-invocable")
+    if ui_val is not None and not isinstance(ui_val, bool):
+        error(tier, "'user-invocable' must be a boolean")
+
+    # contradictory flags
+    if (isinstance(dmi_val, bool) and dmi_val is True and
+            isinstance(ui_val, bool) and ui_val is False):
+        error(tier, "Contradictory: 'disable-model-invocation' is true AND 'user-invocable' is false (skill cannot be invoked at all)")
+
+    # argument-hint checks
+    ah_val = frontmatter.get("argument-hint")
+    if ah_val is not None:
+        if not isinstance(ah_val, str):
+            error(tier, "'argument-hint' must be a string")
+        elif len(ah_val) > 100:
+            error(tier, f"'argument-hint' exceeds 100 characters (got: {len(ah_val)})")
+
+    # allowed-tools checks
+    at_val = frontmatter.get("allowed-tools")
+    if at_val is not None:
+        if not isinstance(at_val, (str, list)):
+            error(tier, "'allowed-tools' must be a string or list")
+
+    # model checks
+    model_val = frontmatter.get("model")
+    if model_val is not None and not isinstance(model_val, str):
+        error(tier, "'model' must be a string")
+
+    # agent checks
+    agent_val = frontmatter.get("agent")
+    if agent_val is not None and not isinstance(agent_val, str):
+        error(tier, "'agent' must be a string")
+
+    # hooks checks
+    hooks_val = frontmatter.get("hooks")
+    if hooks_val is not None and not isinstance(hooks_val, dict):
+        error(tier, "'hooks' must be a dict")
+
+    # ── Tier 3 — Body Quality ───────────────────────────────────────────
+    tier = 3
+
+    # Extract body (content after second ---)
+    parts = raw_content.split("---", 2)
+    body = parts[2].strip() if len(parts) >= 3 else ""
+
+    if not body:
+        warn(tier, "Body is empty (no content after frontmatter)")
+    else:
+        ok(tier, "Body is present")
+
+        body_lines = body.split("\n")
+        line_count = len(body_lines)
+
+        if line_count >= 600:
+            error(tier, f"Body is too long: {line_count} lines (max 600)")
+        elif line_count >= 400:
+            warn(tier, f"Body is getting long: {line_count} lines (warn threshold: 400)")
+        else:
+            ok(tier, f"Body length OK ({line_count} lines)")
+
+        # Placeholder scan — case-sensitive to avoid matching "todo app", "replace with X", etc.
+        placeholders = [r"\[Required:", r"\bTODO\b", r"\bREPLACE\b", r"\[Add content", r"\bFIXME\b", r"\bTBD\b"]
+        for pattern in placeholders:
+            matches = re.findall(pattern, body)
+            if matches:
+                clean_pattern = re.sub(r"[\\(?\[\])]", "", pattern).strip("\\b")
+                warn(tier, f"Placeholder text found: '{clean_pattern}' ({len(matches)} occurrence(s))")
+
+        # Section headers check for long bodies
+        if line_count > 200:
+            section_headers = re.findall(r"^## ", body, re.MULTILINE)
+            if not section_headers:
+                warn(tier, "Body exceeds 200 lines but has no '## ' section headers")
+            else:
+                ok(tier, f"Body has {len(section_headers)} section header(s)")
+
+        # File reference existence checks
+        # Strip fenced code blocks first — paths inside ``` are examples, not live references
+        body_no_fences = re.sub(r"```[\s\S]*?```", "", body)
+        refs = re.findall(r"(?:references|scripts)/[\w./-]+", body_no_fences)
+        for ref in refs:
+            # Skip cross-skill paths (preceded by / or ${ anywhere in the body)
+            escaped = re.escape(ref)
+            if re.search(r"[/$]" + escaped, body_no_fences):
+                continue
+            # Skip example prose: line contains illustrative markers
+            ref_line = next((l for l in body_no_fences.split("\n") if ref in l), "")
+            if re.search(r"\b(examples?|e\.g\.|such as|like `|would be|illustrat)\b", ref_line, re.IGNORECASE):
+                continue
+            ref_path = skill_dir / ref
+            if not ref_path.exists():
+                warn(tier, f"Referenced file does not exist: {ref}")
+
+    # ── Tier 4 — CLEO Integration ──────────────────────────────────────
+    tier = 4
+
+    if manifest_path:
+        manifest_file = Path(manifest_path).resolve()
+        if not manifest_file.exists():
+            error(tier, f"Manifest file not found: {manifest_path}")
+        else:
+            try:
+                manifest_data = json.loads(manifest_file.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as e:
+                error(tier, f"Manifest is not valid JSON: {e}")
+                manifest_data = None
+
+            if manifest_data is not None:
+                skills_list = manifest_data.get("skills", [])
+                matching = [s for s in skills_list if s.get("name") == skill_name]
+
+                if not matching:
+                    warn(tier, f"Skill '{skill_name}' not found in manifest.json skills[]")
+                else:
+                    ok(tier, f"Skill '{skill_name}' found in manifest.json")
+                    entry = matching[0]
+                    for field in MANIFEST_REQUIRED_FIELDS:
+                        if field not in entry:
+                            warn(tier, f"Manifest entry missing required field: '{field}'")
+
+        if dispatch_config_path:
+            dc_file = Path(dispatch_config_path).resolve()
+            if not dc_file.exists():
+                error(tier, f"Dispatch config file not found: {dispatch_config_path}")
+            else:
+                try:
+                    dc_data = json.loads(dc_file.read_text(encoding="utf-8"))
+                except json.JSONDecodeError as e:
+                    error(tier, f"Dispatch config is not valid JSON: {e}")
+                    dc_data = None
+
+                if dc_data is not None:
+                    overrides = dc_data.get("skill_overrides", {})
+                    if skill_name not in overrides:
+                        warn(tier, f"Skill '{skill_name}' not found in dispatch-config.json skill_overrides")
+                    else:
+                        ok(tier, f"Skill '{skill_name}' found in dispatch-config.json")
+
+    # ── Tier 5 — Provider Compatibility ─────────────────────────────────
+    tier = 5
+
+    if provider_map_path:
+        pm_file = Path(provider_map_path).resolve()
+        if not pm_file.exists():
+            error(tier, f"Provider map file not found: {provider_map_path}")
+        else:
+            try:
+                pm_data = json.loads(pm_file.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as e:
+                error(tier, f"Provider map is not valid JSON: {e}")
+                pm_data = None
+
+            if pm_data is not None:
+                # Check if skill is referenced anywhere in the provider map
+                pm_text = json.dumps(pm_data)
+                if skill_name not in pm_text:
+                    warn(tier, f"Skill '{skill_name}' not referenced in provider-skills-map.json")
+                else:
+                    ok(tier, f"Skill '{skill_name}' found in provider-skills-map.json")
+
+    return results, errors, warnings
+
+
+def _print_report(skill_name, results, errors, warnings):
+    """Print the structured validation report."""
+    print(f"\n=== CLEO Skill Validator: {skill_name} ===\n")
+
+    tier_names = {
+        1: "Tier 1 — Structure",
+        2: "Tier 2 — Frontmatter Quality",
+        3: "Tier 3 — Body Quality",
+        4: "Tier 4 — CLEO Integration",
+        5: "Tier 5 — Provider Compatibility",
+    }
+
+    current_tier = None
+    for tier_num, severity, msg in results:
+        if tier_num != current_tier:
+            current_tier = tier_num
+            print(f"{tier_names.get(tier_num, f'Tier {tier_num}')}")
+
+        if severity == "OK":
+            print(f"  \u2705 {msg}")
+        elif severity == "ERROR":
+            print(f"  \u274c ERROR: {msg}")
+        elif severity == "WARN":
+            print(f"  \u26a0\ufe0f  WARN: {msg}")
+
+    print(f"\n=== SUMMARY ===")
+    print(f"Errors:   {errors}")
+    print(f"Warnings: {warnings}")
+
+    if errors > 0:
+        print(f"Result:   FAIL")
+    elif warnings > 0:
+        print(f"Result:   PASS (with warnings)")
+    else:
+        print(f"Result:   PASS")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="CLEO Skill Validator — Full compliance gauntlet"
+    )
+    parser.add_argument("skill_dir", help="Path to the skill directory to validate")
+    parser.add_argument("--manifest", help="Path to manifest.json for CLEO integration check")
+    parser.add_argument("--dispatch-config", help="Path to dispatch-config.json for dispatch override check")
+    parser.add_argument("--provider-map", help="Path to provider-skills-map.json for provider compatibility check")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON instead of human-readable text")
+
+    args = parser.parse_args()
+
+    skill_path = Path(args.skill_dir).resolve()
+    if not skill_path.is_dir():
+        print(f"Error: '{args.skill_dir}' is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    skill_name = skill_path.name
+    results, errors, warnings = validate_skill(
+        skill_path,
+        manifest_path=args.manifest,
+        dispatch_config_path=args.dispatch_config,
+        provider_map_path=args.provider_map,
+    )
+
+    if getattr(args, "json"):
+        output = {
+            "skill_name": skill_name,
+            "results": [
+                {"tier": t, "severity": s, "message": m}
+                for t, s, m in results
+            ],
+            "errors": errors,
+            "warnings": warnings,
+            "passed": errors == 0,
+        }
+        print(json.dumps(output, indent=2))
+    else:
+        _print_report(skill_name, results, errors, warnings)
+
+    sys.exit(1 if errors > 0 else 0)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,189 @@
+---
+name: ct-spec-writer
+description: Technical specification writing using RFC 2119 language for clear, unambiguous requirements. Creates protocol specifications, technical requirements, API specifications, and architecture documents with testable requirements and compliance criteria. Use when writing specifications, defining protocols, documenting requirements, or creating API contracts. Triggers on specification tasks, protocol definition needs, or requirement documentation.
+version: 2.0.0
+tier: 2
+core: false
+category: recommended
+protocol: specification
+dependencies: []
+sharedResources:
+  - subagent-protocol-base
+  - task-system-integration
+compatibility:
+  - claude-code
+  - cursor
+  - windsurf
+  - gemini-cli
+license: MIT
+---
+
+# Specification Writer Context Injection
+
+**Protocol**: @src/protocols/specification.md
+**Type**: Context Injection (cleo-subagent)
+**Version**: 2.0.0
+
+---
+
+## Purpose
+
+Context injection for specification writing tasks spawned via cleo-subagent. Provides domain expertise for creating clear, unambiguous technical specifications using RFC 2119 language.
+
+---
+
+## Capabilities
+
+1. **Protocol Specifications** - Define behavior rules with RFC 2119 keywords
+2. **Technical Requirements** - Document system requirements with constraints
+3. **API Specifications** - Define interfaces, schemas, and contracts
+4. **Architecture Documents** - Document system design decisions
+
+---
+
+## RFC 2119 Keywords (MANDATORY)
+
+Use these keywords with their precise meanings:
+
+| Keyword | Meaning | Compliance |
+|---------|---------|------------|
+| **MUST** | Absolute requirement | 95-98% |
+| **MUST NOT** | Absolute prohibition | 93-97% |
+| **SHOULD** | Recommended unless good reason exists | 75-85% |
+| **SHOULD NOT** | Discouraged unless good reason exists | 75-85% |
+| **MAY** | Truly optional | 40-60% |
+
+---
+
+## Specification Structure
+
+### Standard Layout
+
+```markdown
+# {Specification Title} v{X.Y.Z}
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document
+are to be interpreted as described in RFC 2119.
+
+---
+
+## Overview
+
+{2-3 sentence summary of what this spec defines}
+
+---
+
+## Definitions
+
+| Term | Definition |
+|------|------------|
+| {term} | {definition} |
+
+---
+
+## Requirements
+
+### {Category 1}
+
+**REQ-001**: {Requirement description}
+- Rationale: {Why this requirement exists}
+- Verification: {How to verify compliance}
+
+### {Category 2}
+
+**REQ-002**: {Requirement description}
+...
+
+---
+
+## Constraints
+
+| ID | Constraint | Enforcement |
+|----|------------|-------------|
+| CON-001 | {constraint} | {how enforced} |
+
+---
+
+## Compliance
+
+A system is compliant if:
+1. {condition 1}
+2. {condition 2}
+3. {condition 3}
+
+Non-compliant implementations SHOULD {remediation}.
+```
+
+---
+
+## Writing Guidelines
+
+### Be Precise
+- Every requirement MUST be testable
+- Avoid ambiguous terms ("appropriate", "reasonable", "adequate")
+- Use specific values, not ranges when possible
+
+### Be Complete
+- Define all terms that might be misunderstood
+- Cover error cases and edge conditions
+- Specify what happens when requirements conflict
+
+### Be Organized
+- Group related requirements
+- Use consistent numbering (REQ-XXX, CON-XXX)
+- Cross-reference related sections
+
+---
+
+## Output Location
+
+Specifications go in: `docs/specs/{{SPEC_NAME}}.md`
+
+---
+
+## Task System Integration
+
+@skills/_shared/task-system-integration.md
+
+### Execution Sequence
+
+1. Read task: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
+2. Start task: `{{TASK_START_CMD}} {{TASK_ID}}` (if not already started by orchestrator)
+3. Write specification to `docs/specs/{{SPEC_NAME}}.md`
+4. Append manifest entry to `{{MANIFEST_PATH}}`
+5. Complete task: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
+6. Return summary message
+
+---
+
+## Subagent Protocol
+
+@skills/_shared/subagent-protocol-base.md
+
+### Output Requirements
+
+1. MUST write specification to: `docs/specs/{{SPEC_NAME}}.md`
+2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+3. MUST return ONLY: "Specification complete. See MANIFEST.jsonl for summary."
+4. MUST NOT return specification content in response
+
+### Manifest Entry Format
+
+```json
+{"id":"spec-{{SPEC_NAME}}-{{DATE}}","file":"{{DATE}}_spec-{{SPEC_NAME}}.md","title":"Specification: {{TITLE}}","date":"{{DATE}}","status":"complete","agent_type":"specification","topics":["specification","{{DOMAIN}}"],"key_findings":["Defined N requirements in M categories","Established X constraints with enforcement rules","Compliance criteria: summary"],"actionable":true,"needs_followup":["{{IMPLEMENTATION_TASK_IDS}}"],"linked_tasks":["{{TASK_ID}}"]}
+```
+
+---
+
+## Completion Checklist
+
+- [ ] Task started via `{{TASK_START_CMD}}` (if not already started)
+- [ ] RFC 2119 header included
+- [ ] All requirements numbered (REQ-XXX)
+- [ ] All constraints numbered (CON-XXX)
+- [ ] Compliance section defines pass/fail
+- [ ] Specification written to docs/specs/
+- [ ] Manifest entry appended
+- [ ] Task completed via `{{TASK_COMPLETE_CMD}}`
+- [ ] Return summary message only

package/skills/ct-stickynote/README.md

@@ -0,0 +1,14 @@
+# ct-stickynote
+
+Enhanced sticky note workflows for CLEO.
+
+## Features
+
+- Templates for common note types
+- Visual board view
+- Batch operations
+- Weekly digest
+
+## Usage
+
+See SKILL.md for full documentation.

package/skills/ct-stickynote/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ct-stickynote
+description: Quick ephemeral sticky notes for project-wide capture before formal classification
+version: 1.0.0
+category: productivity
+tier: 0
+protocol: null
+tags: [sticky, notes, capture, quick, ephemeral]
+triggers: [note, sticky, jot, capture]
+compatibility: [claude-code, gemini-cli, codex-cli, opencode]
+dependencies: []
+sharedResources: []
+license: MIT
+---
+
+# Sticky Notes Skill
+
+Quick capture ephemeral notes that fill the gap between session notes and formal tasks.
+
+## When to Use
+
+Use sticky notes for:
+- Quick thoughts that don't fit a formal task yet
+- Temporary reminders
+- Ideas that need refinement before becoming tasks
+- Notes that span multiple sessions
+
+## Operations
+
+| Operation | Usage | Example |
+|-----------|-------|---------|
+| `sticky.add` | Create sticky | `cleo sticky add "Refactor auth middleware" --tag bug --color red` |
+| `sticky.list` | List active | `cleo sticky list --tag bug` |
+| `sticky.show` | Show details | `cleo sticky show SN-001` |
+| `sticky.convert` | Promote to task/memory | `cleo sticky convert SN-001 --to-task` |
+| `sticky.archive` | Archive | `cleo sticky archive SN-001` |
+
+## Installation
+
+```bash
+cleo skill install library:ct-stickynote
+```
+
+## Auto-Archive
+
+Stickies auto-archive after 30 days if not converted.