cue-ai 0.3.0

package/resources/skills/skills/caveman/caveman-compress/scripts/validate.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+import re
+from pathlib import Path
+
+URL_REGEX = re.compile(r"https?://[^\s)]+")
+FENCE_OPEN_REGEX = re.compile(r"^(\s{0,3})(`{3,}|~{3,})(.*)$")
+HEADING_REGEX = re.compile(r"^(#{1,6})\s+(.*)", re.MULTILINE)
+BULLET_REGEX = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
+
+# crude but effective path detection
+# Requires either a path prefix (./ ../ / or drive letter) or a slash/backslash within the match
+PATH_REGEX = re.compile(r"(?:\./|\.\./|/|[A-Za-z]:\\)[\w\-/\\\.]+|[\w\-\.]+[/\\][\w\-/\\\.]+")
+
+
+class ValidationResult:
+    def __init__(self):
+        self.is_valid = True
+        self.errors = []
+        self.warnings = []
+
+    def add_error(self, msg):
+        self.is_valid = False
+        self.errors.append(msg)
+
+    def add_warning(self, msg):
+        self.warnings.append(msg)
+
+
+def read_file(path: Path) -> str:
+    return path.read_text(errors="ignore")
+
+
+# ---------- Extractors ----------
+
+
+def extract_headings(text):
+    return [(level, title.strip()) for level, title in HEADING_REGEX.findall(text)]
+
+
+def extract_code_blocks(text):
+    """Line-based fenced code block extractor.
+
+    Handles ``` and ~~~ fences with variable length (CommonMark: closing
+    fence must use same char and be at least as long as opening). Supports
+    nested fences (e.g. an outer 4-backtick block wrapping inner 3-backtick
+    content).
+    """
+    blocks = []
+    lines = text.split("\n")
+    i = 0
+    n = len(lines)
+    while i < n:
+        m = FENCE_OPEN_REGEX.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        fence_char = m.group(2)[0]
+        fence_len = len(m.group(2))
+        open_line = lines[i]
+        block_lines = [open_line]
+        i += 1
+        closed = False
+        while i < n:
+            close_m = FENCE_OPEN_REGEX.match(lines[i])
+            if (
+                close_m
+                and close_m.group(2)[0] == fence_char
+                and len(close_m.group(2)) >= fence_len
+                and close_m.group(3).strip() == ""
+            ):
+                block_lines.append(lines[i])
+                closed = True
+                i += 1
+                break
+            block_lines.append(lines[i])
+            i += 1
+        if closed:
+            blocks.append("\n".join(block_lines))
+        # Unclosed fences are silently skipped — they indicate malformed markdown
+        # and including them would cause false-positive validation failures.
+    return blocks
+
+
+def extract_urls(text):
+    return set(URL_REGEX.findall(text))
+
+
+def extract_paths(text):
+    return set(PATH_REGEX.findall(text))
+
+
+def count_bullets(text):
+    return len(BULLET_REGEX.findall(text))
+
+
+# ---------- Validators ----------
+
+
+def validate_headings(orig, comp, result):
+    h1 = extract_headings(orig)
+    h2 = extract_headings(comp)
+
+    if len(h1) != len(h2):
+        result.add_error(f"Heading count mismatch: {len(h1)} vs {len(h2)}")
+
+    if h1 != h2:
+        result.add_warning("Heading text/order changed")
+
+
+def validate_code_blocks(orig, comp, result):
+    c1 = extract_code_blocks(orig)
+    c2 = extract_code_blocks(comp)
+
+    if c1 != c2:
+        result.add_error("Code blocks not preserved exactly")
+
+
+def validate_urls(orig, comp, result):
+    u1 = extract_urls(orig)
+    u2 = extract_urls(comp)
+
+    if u1 != u2:
+        result.add_error(f"URL mismatch: lost={u1 - u2}, added={u2 - u1}")
+
+
+def validate_paths(orig, comp, result):
+    p1 = extract_paths(orig)
+    p2 = extract_paths(comp)
+
+    if p1 != p2:
+        result.add_warning(f"Path mismatch: lost={p1 - p2}, added={p2 - p1}")
+
+
+def validate_bullets(orig, comp, result):
+    b1 = count_bullets(orig)
+    b2 = count_bullets(comp)
+
+    if b1 == 0:
+        return
+
+    diff = abs(b1 - b2) / b1
+
+    if diff > 0.15:
+        result.add_warning(f"Bullet count changed too much: {b1} -> {b2}")
+
+
+# ---------- Main ----------
+
+
+def validate(original_path: Path, compressed_path: Path) -> ValidationResult:
+    result = ValidationResult()
+
+    orig = read_file(original_path)
+    comp = read_file(compressed_path)
+
+    validate_headings(orig, comp, result)
+    validate_code_blocks(orig, comp, result)
+    validate_urls(orig, comp, result)
+    validate_paths(orig, comp, result)
+    validate_bullets(orig, comp, result)
+
+    return result
+
+
+# ---------- CLI ----------
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) != 3:
+        print("Usage: python validate.py <original> <compressed>")
+        sys.exit(1)
+
+    orig = Path(sys.argv[1]).resolve()
+    comp = Path(sys.argv[2]).resolve()
+
+    res = validate(orig, comp)
+
+    print(f"\nValid: {res.is_valid}")
+
+    if res.errors:
+        print("\nErrors:")
+        for e in res.errors:
+            print(f"  - {e}")
+
+    if res.warnings:
+        print("\nWarnings:")
+        for w in res.warnings:
+            print(f"  - {w}")

package/resources/skills/skills/caveman/caveman-help/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: caveman-help
+description: >-
+  Use when user says "caveman help" or "caveman commands". Quick reference for Caveman modes, triggers, levels.
+---
+
+# Caveman Help
+
+Display this reference card when invoked. One-shot — do NOT change mode, write flag files, or persist anything. Output in caveman style.
+
+## Modes
+
+| Mode | Trigger | What change |
+|------|---------|-------------|
+| **Lite** | `/caveman lite` | Drop filler. Keep sentence structure. |
+| **Full** | `/caveman` | Drop articles, filler, pleasantries, hedging. Fragments OK. Default. |
+| **Ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Tables over prose. |
+| **Wenyan-Lite** | `/caveman wenyan-lite` | Classical Chinese style, light compression. |
+| **Wenyan-Full** | `/caveman wenyan` | Full 文言文. Maximum classical terseness. |
+| **Wenyan-Ultra** | `/caveman wenyan-ultra` | Extreme. Ancient scholar on a budget. |
+
+Mode stick until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it do |
+|-------|---------|-----------|
+| **caveman-commit** | `/caveman-commit` | Terse commit messages. Conventional Commits. ≤50 char subject. |
+| **caveman-review** | `/caveman-review` | One-line PR comments: `L42: bug: user null. Add guard.` |
+| **caveman-compress** | `/caveman:compress <file>` | Compress .md files to caveman prose. Saves ~46% input tokens. |
+| **caveman-help** | `/caveman-help` | This card. |
+
+## Deactivate
+
+Say "stop caveman" or "normal mode". Resume anytime with `/caveman`.
+
+## Configure Default Mode
+
+Default mode = `full`. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export CAVEMAN_DEFAULT_MODE=ultra
+```
+
+**Config file** (`~/.config/caveman/config.json`):
+```json
+{ "defaultMode": "lite" }
+```
+
+Set `"off"` to disable auto-activation on session start. User can still activate manually with `/caveman`.
+
+Resolution: env var > config file > `full`.
+
+## More
+
+Full docs: https://github.com/JuliusBrussee/caveman

package/resources/skills/skills/caveman/caveman-review/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: caveman-review
+description: >-
+  Use when user says "review this PR", "code review", or "/caveman-review". One-line PR comments: location, problem, fix.
+---
+
+# Caveman Review
+Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
+
+## Rules
+
+**Format:** `L<line>: <problem>. <fix>.` — or `<file>:L<line>: ...` when reviewing multi-file diffs.
+
+**Severity prefix (optional, when mixed):**
+- `🔴 bug:` — broken behavior, will cause incident
+- `🟡 risk:` — works but fragile (race, missing null check, swallowed error)
+- `🔵 nit:` — style, naming, micro-optim. Author can ignore
+- `❓ q:` — genuine question, not a suggestion
+
+**Drop:**
+- "I noticed that...", "It seems like...", "You might want to consider..."
+- "This is just a suggestion but..." — use `nit:` instead
+- "Great work!", "Looks good overall but..." — say it once at the top, not per comment
+- Restating what the line does — the reviewer can read the diff
+- Hedging ("perhaps", "maybe", "I think") — if unsure use `q:`
+
+**Keep:**
+- Exact line numbers
+- Exact symbol/function/variable names in backticks
+- Concrete fix, not "consider refactoring this"
+- The *why* if the fix isn't obvious from the problem statement
+
+## Examples
+
+❌ "I noticed that on line 42 you're not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here."
+
+✅ `L42: 🔴 bug: user can be null after .find(). Add guard before .email.`
+
+❌ "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
+
+✅ `L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.`
+
+❌ "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
+
+✅ `L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).`
+
+## Auto-Clarity
+
+Drop terse mode for: security findings (CVE-class bugs need full explanation + reference), architectural disagreements (need rationale, not just a one-liner), and onboarding contexts where the author is new and needs the "why". In those cases write a normal paragraph, then resume terse for the rest.
+
+## Boundaries
+
+Reviews only — does not write the code fix, does not approve/request-changes, does not run linters. Output the comment(s) ready to paste into the PR. "stop caveman-review" or "normal mode": revert to verbose review style.

package/resources/skills/skills/colony/colony/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: colony
+description: >-
+  Use when user says "Colony", "Colony plan", or "Colony task". Colony workflow: live plans, lanes, handoffs, completion evidence.
+---
+
+# Colony
+
+Colony is a **local-first coordination substrate** that makes multi-agent
+coding runs safe through shared file claims, compact memory, and durable
+handoffs. Agents see ownership and prior decisions before editing files —
+parallel work goes from risky to reliable.
+
+> Inline `/CLAUDE.md` already injects a short version of the operating
+> contract every session. This skill is the full version: triggers, the
+> MCP tool surface, the startup/shutdown loops, and progressive-disclosure
+> patterns for memory. When you have this skill loaded you don't need the
+> inline copy.
+
+## When to use
+
+Direct triggers:
+- "hand this off", "handoff", "pass work to <agent>"
+- "claim this file", "claim the file before editing", "who owns <file>"
+- "check the inbox", "what needs me", "see active lanes"
+- "post a decision", "save this for the next agent", "share ownership"
+- "what's blocking me", "what's stalled", "rescue stranded"
+- `/colony`, `/task`, `/handoff`, `/claim`, `/inbox`
+
+Indirect — implies Colony first:
+- "two agents are editing the same file" → claim before edit
+- "I started this, another agent should finish" → handoff or relay
+- "what did we decide about X?" → search → get_observations
+- "is anyone working on this?" → hivemind_context
+- "this task has history we need to remember" → task_post (not OMX notepad)
+- "agent stopped mid-task" → rescue_stranded_scan
+
+## When NOT to use
+
+- Single-agent work with no file contention (just edit).
+- One-line typos, version bumps, comment fixes (claims add noise).
+- Reading to understand — only claim when about to mutate.
+- Local scratch notes that won't affect another agent (use OMX `/note`).
+- "Just merge this PR" with no concurrent worker (no coordination needed).
+
+If a prompt sounds like Colony but actually has no other agent involved, skip
+the contract and do the work directly.
+
+## Startup contract — run before any work
+
+```
+1. hivemind_context     → live lanes, file ownership, memory hits, warnings
+2. attention_inbox      → pending handoffs, unread messages, blockers, stale lanes
+3. task_ready_for_agent → pick claimable work matched to this agent (auto-claims)
+   ┌─ accept a pending handoff:  task_accept_handoff
+   └─ accept a pending relay:    task_accept_relay
+4. (queen-plan flow) task_plan_claim_subtask  ← if working from a published plan
+5. task_claim_file <path> ← claim each touched file BEFORE editing it
+6. task_note_working { branch, task, blocker, next, evidence }
+```
+
+Skip this loop only if you are 100% solo and there is no shared task scope.
+
+## During work
+
+- Update `task_note_working` after meaningful progress. Keep `next` explicit
+  so a handoff in 30 seconds would be safe.
+- Use `task_post` for decisions / blockers / answers other agents will need.
+- Run focused verification (tests, type-check, lint) for the touched behavior
+  — not the whole repo.
+- If you start touching a file you didn't claim, run `task_claim_file` first.
+  `task_drift_check` reports overlap if you forget.
+
+## Shutdown / finish contract
+
+Before stopping (whether complete, blocked, or out of quota):
+
+```
+1. git status                      ← identify dirty files
+2. If dirty: commit finished work, hand off unfinished work, or revert
+                                     intentionally abandoned edits
+3. task_note_working {
+     branch, task, dirty files, blocker, next step, evidence
+   }
+4. Release or weaken claims before abandoning work so stale strong
+   ownership does not block the next agent
+```
+
+## Quota-safe handoff (before session/turn cap)
+
+When you may disappear (rate-limit, quota, turn-cap):
+
+```
+task_relay {
+  to:     <agent-or-queue>,
+  task:   <task-id>,
+  files:  [<claimed paths>],
+  dirty:  [<git status output>],
+  branch: <name>,
+  last_verification: <what passed>,
+  next:   <one explicit next action>
+}
+# OR a normal handoff if the receiver is already known
+task_hand_off { to, task, files, summary, next }
+```
+
+Mark claims `handoff-pending` or release them before exit — no strong claims
+should be left without an active handoff or TTL.
+
+If unsure, run the coordination sweep guidance first
+(`rescue_stranded_scan` + `task_claim_quota_release_expired`) and follow
+its release/handoff recommendation.
+
+## MCP tool surface (grouped by lifecycle)
+
+### Startup & navigation
+- `hivemind_context` — live lanes, ownership, memory hits, warnings
+- `attention_inbox` — handoffs, unread messages, blockers, stale lanes
+- `task_ready_for_agent` — pick + auto-claim work for this agent
+- `startup_panel` — compact all-in-one resume card
+
+### Memory & search (use progressive disclosure — IDs first, bodies later)
+- `search` — find compact observation IDs by query
+- `get_observations(ids)` — fetch full bodies AFTER selecting IDs
+- `timeline` — chronological observation IDs for one session
+- `list_sessions` → `recall_session` — find and audit prior sessions
+
+### Task threads (per-task coordination)
+- `task_list` — browse only; NOT the work picker (use task_ready_for_agent)
+- `task_timeline` — compact activity IDs for one task
+- `task_post` — decisions, blockers, answers, notes
+- `task_note_working` — resumable state (branch, task, blocker, next, evidence)
+- `task_claim_file` — claim before editing; visible to other agents
+- `task_message` / `task_messages` / `task_message_claim` /
+  `task_message_mark_read` / `task_message_retract` — agent-to-agent comms
+- `task_drift_check` — edits-vs-claims overlap detection
+- `task_link` / `task_unlink` / `task_links` — relate task threads
+- `task_updates_since` — incremental fetch since a checkpoint
+
+### Handoffs & relays
+- `task_hand_off` — transfer work + optional file claims
+- `task_accept_handoff` / `task_decline_handoff`
+- `task_relay` — quota-safe handoff (sender may disappear)
+- `task_accept_relay` / `task_decline_relay`
+- `task_claim_quota_accept` / `task_claim_quota_decline` /
+  `task_claim_quota_release_expired` — half-claim management after quota
+
+### Proposals & foraging
+- `task_propose` — weak future-work candidate
+- `task_reinforce` — promote / reinforce
+- `task_foraging_report` — pending + promoted proposals
+- `agent_get_profile` / `agent_upsert_profile` — agent capability weights
+
+### Queen plans (multi-agent wave work)
+- `queen_plan_goal` — decompose goal into a wave plan
+- `task_plan_publish` — publish spec-backed plan + subtasks
+- `task_plan_validate` — preflight overlaps / wave errors
+- `task_plan_list` — list plans + next available subtasks
+- `task_plan_claim_subtask` — claim one subtask + file scope
+- `task_plan_complete_subtask` — finish + release claims
+- `task_plan_status_for_spec_row` — has this spec row a subtask?
+- `task_autopilot_tick` — stateless one-action next decision
+
+### OpenSpec integration
+- `spec_read` — parsed SPEC.md + hash
+- `spec_change_open` → `spec_change_add_delta` → `spec_archive` — durable change
+- `spec_build_context` — task-scoped spec context
+- `spec_build_record_failure` — record failures, maybe promote invariants
+- `openspec_sync_status` — drift report between tasks and spec artifacts
+
+### Examples & suggestions
+- `examples_list` / `examples_query` — search indexed patterns
+- `examples_integrate_plan` — deterministic integration guidance
+- `task_suggest_approach` — similarity-backed guidance from past tasks
+
+### Rescue & health
+- `rescue_stranded_scan` — dry-run identify stalled lanes
+- `rescue_stranded_run` — emit rescue relays, release orphan claims
+- `savings_report` — live MCP receipts + reference token savings
+- `bridge_status` — bridge health & lifecycle state
+
+## Progressive disclosure pattern (memory)
+
+Don't hydrate everything upfront. The cheap calls return IDs only:
+
+```
+search("auth refresh flow")     →  [obs_a1, obs_b9, obs_c2]   # compact, ~50 tok
+↓ pick the 1-3 that look right
+get_observations([obs_b9])      →  full body                  # ~300 tok each
+```
+
+Same shape for tasks: `task_timeline(task_id)` → IDs → `get_observations(ids)`
+on the few you actually need. Avoid `task_list` as a "what should I work on"
+picker — use `task_ready_for_agent` so claims are atomic.
+
+## RTK command policy (token-optimized shells)
+
+When running shell commands inside Colony work, prefix with `rtk` for
+token-optimized output: `rtk ls`, `rtk read`, `rtk grep`, `rtk git status`,
+`rtk gh pr view`, `rtk pytest`, `rtk tsc`, `rtk lint`. Use `rtk err <cmd>`
+or `rtk test <cmd>` for failure-only output. Use `rtk proxy <cmd>` for raw
+passthrough. If `rtk` isn't installed in the active env, note that and run
+the underlying command compactly.
+
+## Pointers — Colony repo docs
+
+Repo: `/home/deadpool/Documents/recodee/colony/`
+
+| File | Use when |
+| --- | --- |
+| `docs/mcp.md` | Looking up the exact arg shape of an MCP tool |
+| `docs/architecture.md` | Understanding write/read paths, compression, storage |
+| `docs/compression.md` | Caveman grammar / token preservation rules |
+| `docs/agentic-bridge.md` | OMX PreToolUse hook bridge contract |
+| `docs/proposal-task-threads.md` | Proposal lifecycle, reinforcement thresholds |
+| `docs/QUEEN.md` | Wave plan decomposition, gating, claimable subtasks |
+| `docs/ruflo-sidecar.md` | Ruflo browser/security tool integration boundary |
+| `docs/development.md` | Dev workflow, performance budgets |
+| `SPEC.md` | Source of truth for invariants & change deltas |