@cleocode/skills 2.0.0

package/skills/ct-grade-v2-1/scripts/token_tracker.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+token_tracker.py — Aggregate token usage stats from a completed A/B run.
+
+Usage:
+    python token_tracker.py --run-dir ./ab_results/run-001
+
+Reads all timing.json files in the run directory and produces token-summary.json
+with per-arm statistics.
+
+Output: <run-dir>/token-summary.json
+"""
+
+import argparse
+import json
+import os
+import sys
+import math
+from pathlib import Path
+
+
+def find_timing_files(run_dir):
+    """Find all timing.json files under run_dir."""
+    return list(Path(run_dir).rglob("timing.json"))
+
+
+def load_timing(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"  WARN: Could not read {path}: {e}", file=sys.stderr)
+        return None
+
+
+def mean(values):
+    return sum(values) / len(values) if values else 0
+
+
+def stddev(values):
+    if len(values) < 2:
+        return 0
+    m = mean(values)
+    return math.sqrt(sum((x - m) ** 2 for x in values) / (len(values) - 1))
+
+
+def stats(values):
+    if not values:
+        return {"mean": None, "stddev": None, "min": None, "max": None, "count": 0}
+    return {
+        "mean": round(mean(values), 1),
+        "stddev": round(stddev(values), 1),
+        "min": min(values),
+        "max": max(values),
+        "count": len(values),
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Aggregate token stats from ct-grade A/B run")
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument("--output", default=None, help="Output path (default: <run-dir>/token-summary.json)")
+    args = parser.parse_args()
+
+    run_dir = args.run_dir
+    if not os.path.isdir(run_dir):
+        print(f"ERROR: Run dir not found: {run_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    timing_files = find_timing_files(run_dir)
+    if not timing_files:
+        print(f"ERROR: No timing.json files found in {run_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Found {len(timing_files)} timing.json files")
+
+    # Group by arm
+    by_arm = {}
+    by_interface = {}
+    missing_tokens = []
+
+    for tpath in timing_files:
+        data = load_timing(tpath)
+        if data is None:
+            continue
+
+        arm = data.get("arm", "unknown")
+        iface = data.get("interface", "unknown")
+        tokens = data.get("total_tokens")
+        duration = data.get("duration_ms")
+
+        if arm not in by_arm:
+            by_arm[arm] = {"tokens": [], "duration_ms": [], "interface": iface, "files": []}
+        if iface not in by_interface:
+            by_interface[iface] = {"tokens": [], "duration_ms": [], "files": []}
+
+        by_arm[arm]["files"].append(str(tpath))
+
+        if tokens is not None:
+            by_arm[arm]["tokens"].append(tokens)
+            by_interface[iface]["tokens"].append(tokens)
+        else:
+            missing_tokens.append(str(tpath))
+
+        if duration is not None:
+            by_arm[arm]["duration_ms"].append(duration)
+            by_interface[iface]["duration_ms"].append(duration)
+
+    # Build summary
+    arm_stats = {}
+    for arm, data in sorted(by_arm.items()):
+        arm_stats[arm] = {
+            "interface": data["interface"],
+            "file_count": len(data["files"]),
+            "total_tokens": stats(data["tokens"]),
+            "duration_ms": stats(data["duration_ms"]),
+        }
+
+    iface_stats = {}
+    for iface, data in sorted(by_interface.items()):
+        iface_stats[iface] = {
+            "file_count": len(data["files"]),
+            "total_tokens": stats(data["tokens"]),
+            "duration_ms": stats(data["duration_ms"]),
+        }
+
+    # Compute delta between arms (A vs B)
+    delta = {}
+    if "arm-A" in arm_stats and "arm-B" in arm_stats:
+        a_mean = arm_stats["arm-A"]["total_tokens"].get("mean") or 0
+        b_mean = arm_stats["arm-B"]["total_tokens"].get("mean") or 0
+        if b_mean > 0:
+            delta = {
+                "mean_tokens": round(a_mean - b_mean, 1),
+                "percent": f"{((a_mean - b_mean) / b_mean * 100):+.1f}%",
+                "note": f"Arm A uses {abs(a_mean - b_mean):.0f} {'more' if a_mean > b_mean else 'fewer'} tokens on average",
+            }
+
+    summary = {
+        "run_dir": os.path.abspath(run_dir),
+        "timing_files_found": len(timing_files),
+        "timing_files_missing_tokens": len(missing_tokens),
+        "by_arm": arm_stats,
+        "by_interface": iface_stats,
+        "delta_A_vs_B": delta,
+        "warnings": (
+            [f"MISSING total_tokens in {len(missing_tokens)} files — fill these from task notifications"]
+            if missing_tokens else []
+        ),
+    }
+
+    output_path = args.output or os.path.join(run_dir, "token-summary.json")
+    with open(output_path, "w") as f:
+        json.dump(summary, f, indent=2)
+
+    # Print summary
+    print(f"\nToken Summary")
+    print(f"{'='*50}")
+    for arm, s in arm_stats.items():
+        t = s["total_tokens"]
+        if t["mean"] is not None:
+            print(f"  {arm} ({s['interface']}): {t['mean']:.0f} tokens (±{t['stddev']:.0f}, n={t['count']})")
+        else:
+            print(f"  {arm} ({s['interface']}): NO TOKEN DATA (fill timing.json from task notifications)")
+    if delta:
+        print(f"\n  Delta (A-B): {delta['percent']} ({delta['mean_tokens']:+.0f} tokens)")
+        print(f"  {delta['note']}")
+    if missing_tokens:
+        print(f"\n  WARNING: {len(missing_tokens)} files missing total_tokens")
+        print(f"  These must be filled from Claude Code task notification data.")
+    print(f"\nWritten: {output_path}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/ct-memory/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: ct-memory
+version: 1.0.0
+description: Brain memory protocol with progressive disclosure for anti-hallucination and context recall
+triggers:
+  - memory
+  - brain
+  - recall
+  - remember
+  - anti-hallucination
+---
+
+# ct-memory -- Brain Memory Protocol
+
+## Purpose
+
+Ensures LLM agents never start conversations with amnesia. Provides structured memory access through CLEO's brain system using progressive disclosure.
+
+## Tier 0: Session Start (ALWAYS run on first interaction)
+
+1. The memory bridge (.cleo/memory-bridge.md) is already loaded via CLEO-INJECTION.md @-reference
+2. If the bridge content feels stale (>2 hours old), refresh:
+   - `query memory brain.search {query: "session task decision", limit: 10}`
+3. Check for anti-patterns to avoid:
+   - `query memory brain.search {query: "mistake error avoid warning", limit: 5}`
+4. If results are relevant, fetch details:
+   - `query memory brain.fetch {ids: ["O-xxx", "O-yyy"]}`
+
+## Tier 1: During Work (run when topic-relevant)
+
+### Before Making Decisions
+
+- `query memory brain.search {query: "decision ADR architecture", limit: 5}`
+- Check if a similar decision was already made
+
+### Before Repeating Work
+
+- `query memory brain.search {query: "{current-topic}", limit: 10}`
+- Avoid re-doing work that's already been completed
+
+### After Completing Significant Work
+
+- `mutate memory brain.observe {text: "Completed X using approach Y. Key learning: Z", title: "Work completion"}`
+
+### Anti-Hallucination Protocol
+
+Before stating facts about the codebase or project:
+
+1. Search brain: `query memory brain.search {query: "{claim-topic}", limit: 5}`
+2. If results exist, verify your claim matches stored knowledge
+3. If no results, state your uncertainty clearly
+
+## Tier 2: Deep Recall (run when specifically needed)
+
+### Full Timeline
+
+- `query memory brain.timeline {anchor: "O-xxx", depthBefore: 5, depthAfter: 5}`
+- Understand chronological context around a specific observation
+
+### Cross-Project Knowledge (via NEXUS)
+
+- `query nexus search {query: "pattern", scope: "global"}`
+- Search across all CLEO-managed projects
+
+## MCP Resources (Alternative to search)
+
+For providers that support MCP resources:
+
+- `ReadResource("cleo://memory/recent")` -- last 15 observations
+- `ReadResource("cleo://memory/learnings")` -- active learnings with confidence
+- `ReadResource("cleo://memory/patterns")` -- patterns to follow/avoid
+- `ReadResource("cleo://memory/handoff")` -- last session handoff
+
+## Token Budget Guidelines
+
+| Operation | ~Tokens | When |
+|-----------|---------|------|
+| memory-bridge.md (auto-loaded) | 200-400 | Always (free) |
+| brain.search | 50/hit | Discovery |
+| brain.fetch | 500/entry | Details |
+| brain.timeline | 200-500 | Context |
+| MCP resources | 200-500 | On-demand |
+
+Stay within LAFS MVI budget: start minimal, escalate only when needed.

package/skills/ct-orchestrator/INSTALL.md

@@ -0,0 +1,61 @@
+# Installing the Orchestrator Skill
+
+## For Claude Code Plugin Projects
+
+1. Copy `skills/ct-orchestrator/` directory to your project's skills directory
+2. Skill will be auto-discovered by Claude Code plugin system
+3. Invoke via `/ct-orchestrator` command or Skill tool
+
+## Manual Invocation
+
+Use the Skill tool directly:
+
+```
+Skill: ct-orchestrator
+```
+
+Or natural language triggers:
+- "activate orchestrator mode"
+- "run as orchestrator"
+- "orchestrate this workflow"
+- "delegate to subagents"
+
+## Verification
+
+After activation, you should see the Orchestrator Protocol constraints loaded.
+Test by asking Claude to explain ORC-001 through ORC-005:
+
+```
+What are the ORC constraints for orchestrator mode?
+```
+
+Expected response should include:
+- ORC-001: Stay high-level
+- ORC-002: Delegate ALL work
+- ORC-003: No full file reads
+- ORC-004: Dependency order
+- ORC-005: Context budget
+
+## Why Skill-Based Delivery?
+
+The skill approach is preferred over CLAUDE.md injection because:
+
+1. **Selective Activation**: Only the HITL orchestrator agent receives the protocol
+2. **Subagent Isolation**: Subagents spawn without orchestrator constraints
+3. **On-Demand Loading**: Reduces context overhead when not in orchestrator mode
+4. **Clean Separation**: Orchestrator vs worker roles are architecturally distinct
+
+## Directory Structure
+
+```
+skills/
+  ct-orchestrator/
+    SKILL.md      # Main skill definition with frontmatter
+    INSTALL.md    # This file
+```
+
+## Dependencies
+
+- CLEO task management (`cleo` CLI)
+- Agent manifest system (`claudedocs/agent-outputs/MANIFEST.jsonl`)
+- Task tool for subagent spawning

package/skills/ct-orchestrator/README.md

@@ -0,0 +1,69 @@
+# Orchestrator Skill
+
+Activate orchestrator mode for managing complex multi-agent workflows.
+
+## Quick Start
+
+1. **Activate**: Say "activate orchestrator mode" or use Skill tool
+2. **Operate**: Follow ORC-001 through ORC-005 constraints
+3. **Delegate**: Use Task tool to spawn subagents for all work
+
+## Installation
+
+### Option A: On-Demand (Recommended)
+
+Simply invoke the skill when needed:
+```
+# Natural language
+"activate orchestrator mode"
+"run as orchestrator"
+"orchestrate this workflow"
+
+# Or Skill tool
+Skill: orchestrator
+```
+
+### Option B: Project Installation
+
+Install to your project for persistent availability:
+```bash
+cleo orchestrator skill --install    # Copy to .cleo/skills/
+cleo orchestrator skill --verify     # Verify installation
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Main skill definition (loaded by Claude Code) |
+| `INSTALL.md` | Detailed installation instructions |
+| `README.md` | This file |
+| `references/` | Additional documentation and templates |
+
+## Key Principle
+
+**Only YOU (the HITL-facing session) become an orchestrator.**
+
+Your subagents do NOT inherit this skill and operate normally as task executors.
+This is the critical difference from CLAUDE.md injection, which affected all agents.
+
+## Constraints (ORC)
+
+See [SKILL.md](SKILL.md) for quick reference or [ORCHESTRATOR-PROTOCOL-SPEC.md](../../docs/specs/ORCHESTRATOR-PROTOCOL-SPEC.md#21-core-constraints) for full specification.
+
+**Summary**: ORC-001 (high-level) | ORC-002 (delegate) | ORC-003 (no full reads) | ORC-004 (dependency order) | ORC-005 (10K budget)
+
+## Why Skill-Based?
+
+| Problem with CLAUDE.md injection | Skill-based solution |
+|----------------------------------|---------------------|
+| ALL agents read CLAUDE.md | Skills load ON-DEMAND |
+| Subagents ALSO try to orchestrate | Subagents do NOT inherit skills |
+| Breaks delegation pattern | Only HITL session operates as orchestrator |
+| Always loaded (context overhead) | Loaded when activated |
+
+## Related Documentation
+
+- [Orchestrator Protocol Guide](../../docs/guides/ORCHESTRATOR-PROTOCOL.md)
+- [CLI Reference](../../docs/commands/orchestrator.md)
+- [Subagent Protocol Block](references/SUBAGENT-PROTOCOL-BLOCK.md)