@oneie/claude 0.4.0 → 0.6.0

package/skills/writer/references/structures.md

@@ -0,0 +1,285 @@
+# Structures: templates for common pieces
+
+Practical scaffolds for the formats that come up most often. These are starting points, not rules. Bend them when the piece calls for it.
+
+## Essay / blog post
+
+### Opening
+
+Three openings that work, in rough order of preference:
+
+1. **The strongest sentence.** State the thesis or the most striking observation in the first sentence. Then back it up.
+2. **A concrete scene.** Drop the reader into a specific moment, then pull back to the general point.
+3. **A genuine question.** Not a rhetorical one. A question you are actually going to answer in the piece.
+
+Three openings to avoid:
+
+- Definition ("Productivity, defined as…")
+- Throat-clearing ("In today's world…", "It's no secret that…")
+- Restating the title in prose form
+
+### Middle
+
+- One idea per paragraph. If a paragraph contains two ideas, split it.
+- Each paragraph picks up from where the last one left off (old information first), then introduces something new.
+- Use concrete examples liberally. Abstractions need anchors.
+- Section headers only if the piece is long enough that a reader might skim or return.
+
+### Closing
+
+The closing should leave the reader with something to carry. Options:
+
+- A reframe — show the topic in a new light now that the piece has done its work.
+- A specific implication — what should change for the reader as a result?
+- An open question — the kind that keeps working in the reader's head after they close the tab.
+
+Avoid:
+
+- Summary of what you just said. The reader was there.
+- "In conclusion…"
+- Calls to action that weren't earned by the piece.
+- Hopeful platitudes ("The future is bright").
+
+## Founder update / investor email
+
+A monthly or quarterly update to investors, advisors, or close supporters.
+
+```
+Subject: [Company] — [Month] update
+
+TL;DR: [one or two sentences. The headline.]
+
+## Numbers
+- [Metric 1]: [number] ([change vs. last period])
+- [Metric 2]: [number] ([change])
+- [Metric 3]: [number] ([change])
+
+## What worked
+[2-4 sentences. Specifics: shipped X, signed Y, hired Z.]
+
+## What didn't
+[2-4 sentences. Honest. The thing you'd rather not say is usually the thing they most need to hear.]
+
+## What's next
+[2-4 sentences. Concrete plans for next period.]
+
+## Asks
+- [Specific intro to a person]
+- [Specific advice on a decision]
+- [Specific help with a hire]
+
+Thanks,
+[Name]
+```
+
+The discipline: numbers up top, problems named honestly, asks specific. Investors trust founders who tell the truth and know what they want.
+
+## Landing page
+
+A landing page is a sales pitch with three parts: hook, proof, action.
+
+### Above the fold
+
+- **Headline.** Names the audience's problem or desired outcome in their words. Not your product's features.
+- **Subhead.** Says how you deliver it. Adds the specificity the headline left out.
+- **Primary CTA.** One action. Not three.
+- **Hero image or demo.** Shows the product, not a stock photo.
+
+### Proof section
+
+Show, don't tell. Options:
+
+- Specific customer outcomes ("Acme reduced X from Y to Z").
+- Named customer logos (only if recognisable to the audience).
+- A short demo video or GIF.
+- Numbers ("12,000 teams", "98% retention").
+
+Avoid the "trusted by industry leaders" line with no specifics.
+
+### How it works
+
+Three or four steps, each one a single sentence with a verb. Not a wall of text.
+
+### Objection handling
+
+The two or three reasons the visitor might not buy, and your honest answer to each. Often a FAQ.
+
+### Closing CTA
+
+Same action as the top. Don't introduce a new one.
+
+## Cold email
+
+```
+Subject: [specific reason for emailing, 5-7 words]
+
+[Name],
+
+[One sentence: who you are and the specific reason you're emailing this person, not anyone else.]
+
+[One sentence: what you want.]
+
+[Optional: one sentence of proof or context that earns the reply.]
+
+[One sentence: easy yes-or-no question.]
+
+[Name]
+```
+
+Total length: 4-5 sentences. Longer cold emails get worse response rates, not better.
+
+The discipline: the email is about the recipient, not you. The first sentence proves you've done the work to know who they are. The ask is specific and easy.
+
+## LinkedIn post
+
+```
+[Hook line — earns the click on "see more". One sentence.]
+
+[Set up: the situation. 1-2 short paragraphs.]
+
+[Turn: what changed, what you learned, the surprise. 1-2 short paragraphs.]
+
+[Lesson or takeaway: one or two lines.]
+
+[Optional: a question to invite comments.]
+```
+
+- Paragraphs are usually one or two sentences.
+- White space matters; LinkedIn rewards readability on mobile.
+- One idea per post. If you have three things to say, that's three posts.
+- Avoid hashtag spam. Two or three relevant tags is enough.
+
+## Twitter / X thread
+
+```
+1/ [Hook tweet. The most interesting claim or question. Earns the click.]
+
+2/ [Context: why this matters, who it's for.]
+
+3-N/ [The actual content, one idea per tweet.]
+
+N+1/ [The strongest specific example or moment.]
+
+Last/ [The takeaway. Often calls back to the opening.]
+```
+
+- Each tweet should stand alone. People scroll into the middle.
+- The first tweet is 80% of the work. If it doesn't hook, the thread dies.
+- Numbering is optional; some good threads don't use it.
+
+## Push notification / SMS
+
+You have one sentence. Sometimes half a sentence.
+
+- Lead with the value or the news, not the brand.
+- Specific over general ("Sho liked your photo" beats "You have a new notification").
+- No emoji unless the brand uses them consistently.
+- Avoid "Hey!" and other throat-clearing.
+
+## Technical documentation
+
+### Per-feature page
+
+```
+# [Feature name]
+
+[One-paragraph summary: what it is, who it's for, what problem it solves. 2-4 sentences max.]
+
+## When to use it
+
+[A few concrete situations.]
+
+## How it works
+
+[Plain-English explanation. Diagram if useful.]
+
+## Example
+
+[Working code, not pseudocode. The shortest example that actually does something.]
+
+## Reference
+
+[API surface, parameters, return values. Tables work here.]
+
+## Common pitfalls
+
+[2-4 specific things that trip people up.]
+```
+
+- Lead with what the thing is. Don't bury it under history or motivation.
+- Concrete examples before abstractions.
+- If a reader can copy-paste your example and have it work, you've done your job.
+
+### README
+
+```
+# [Project name]
+
+[One sentence: what it is.]
+[One sentence: who it's for.]
+
+## Install
+
+[The shortest install instructions that work.]
+
+## Usage
+
+[The shortest example that demonstrates the value.]
+
+## Documentation
+
+[Links to longer docs.]
+
+## License
+```
+
+- Optimise for the reader who landed here from a search and has 30 seconds to decide if your project is worth their time.
+
+## Apology / hard message
+
+When the message is genuinely difficult — an apology, bad news, a no — the structure matters more than usual.
+
+```
+[The hard thing, named directly. One sentence. No softeners.]
+
+[Why it happened, briefly. Honest. No blame-shifting.]
+
+[What you're doing about it. Specific. Not vague reassurance.]
+
+[Optional: what you owe the recipient. An offer, a refund, a follow-up.]
+```
+
+- Don't bury the hard thing in paragraph three.
+- Don't apologise for things that aren't the issue ("sorry for the delay" when the issue is the mistake itself).
+- Don't promise what you can't deliver.
+
+## Decision document / proposal
+
+A short document arguing for a specific decision. Common in startups and engineering teams.
+
+```
+# [Title: the decision being proposed]
+
+## Recommendation
+[One paragraph: what you propose, in plain English.]
+
+## Context
+[Why this is on the table now. What changed.]
+
+## Options considered
+[2-4 options, including the recommended one and the do-nothing option.]
+
+## Trade-offs
+[Honest costs of the recommended option.]
+
+## Open questions
+[What you don't know yet. Where you need input.]
+```
+
+- Lead with the recommendation. Senior readers will skip the rest if they trust your reasoning.
+- Always include "do nothing" as an option. It clarifies the cost of action.
+- Name the trade-offs. Pretending there are none destroys credibility.
+
+## A note on templates
+
+Templates are crutches. They help you start. Once you know the form, ignore it when the piece calls for something different. The best writing in any of these formats often breaks the template at one or two points — and that break is usually what makes it memorable.

package/skills/youtube-subs/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: youtube-subs
+description: Download clean text transcripts from YouTube videos, playlists, or full channels. Use when a user wants to learn from / summarize / extract knowledge out of YouTube talks, lectures, or podcasts — especially when refining a Claude Code skill from video content. Requires yt-dlp (brew install yt-dlp).
+---
+
+# YouTube Subtitles → Clean Transcripts
+
+A reusable skill for pulling subtitles out of YouTube and converting them to plain-text transcripts suitable for LLM ingestion.
+
+## When to invoke
+
+Use this skill whenever the user says anything like:
+- "read the YouTube videos from X channel"
+- "download the subtitles / transcripts / captions"
+- "summarize this talk / lecture / podcast"
+- "refine skill Y from video content"
+- "what did <speaker> say in that conference talk"
+
+Do **not** use it for:
+- Short single clips where a WebFetch of the transcript panel is enough
+- Paywalled or age-gated content (fails)
+- Live streams (no captions until VOD)
+
+## Prerequisites
+
+```bash
+brew install yt-dlp           # ~200 MB including deno + python@3.14
+yt-dlp --version              # should print YYYY.MM.DD
+```
+
+## Usage
+
+### One video
+
+```bash
+bash .claude/skills/youtube-subs/scripts/fetch.sh <video-id-or-url> <out-dir>
+```
+
+Produces `<out-dir>/<id>.txt` (plain text, no timestamps) plus the raw `.vtt` file for reference.
+
+### Playlist
+
+```bash
+bash .claude/skills/youtube-subs/scripts/fetch.sh "https://www.youtube.com/playlist?list=..." <out-dir>
+```
+
+### Whole channel (last N videos)
+
+```bash
+bash .claude/skills/youtube-subs/scripts/fetch.sh "https://www.youtube.com/c/vaticle/videos" <out-dir> 20
+```
+
+The third argument caps how many videos to pull (default: unlimited — be careful on large channels).
+
+### Selected video IDs
+
+```bash
+bash .claude/skills/youtube-subs/scripts/fetch.sh "ID1 ID2 ID3" <out-dir>
+```
+
+Pass space-separated IDs as one argument and the script loops them.
+
+## Output layout
+
+```
+<out-dir>/
+  raw/
+    20240115-LMzZoq6fUqg-Intro_to_TypeDB.en.vtt    # original WebVTT
+    20240115-LMzZoq6fUqg-Intro_to_TypeDB.info.json # metadata (title, uploader, duration, views)
+  text/
+    LMzZoq6fUqg.txt                                 # clean text, one sentence per line
+  index.tsv                                         # id <TAB> title <TAB> duration <TAB> lang
+```
+
+The clean text files are what you feed to the LLM — they strip timestamps, deduplicate the rolling-captions overlap, and collapse the caption lines into paragraphs.
+
+## How the conversion works
+
+WebVTT auto-captions have three problems:
+1. **Timestamps interleaved with text** — noise for an LLM
+2. **Rolling overlap** — the same phrase appears in consecutive cues as new words arrive
+3. **No sentence boundaries** — caption breaks don't match spoken sentences
+
+`scripts/vtt-to-text.py` handles all three:
+- strips timestamp lines (`^\d+:\d+:\d+\.\d+`)
+- dedupes adjacent cues using longest-common-suffix detection
+- reflows into sentences on `.!?` boundaries
+
+## Quota / rate limit
+
+`yt-dlp` hits YouTube's public endpoints; no API key, no quota. But at >50 videos in a burst, add `--sleep-interval 2` (already wired into `fetch.sh`) to avoid the soft-rate-limit that returns empty playlists.
+
+## Known caveats
+
+- **Auto-captions vs manual**: The script prefers manual subs (`--write-subs`) over auto (`--write-auto-subs`). If only auto is present, quality drops on technical jargon — expect "TypeQL" transcribed as "type ql" or "type cul".
+- **Multi-language**: Defaults to `en`. Override with `SUBS_LANG=es bash scripts/fetch.sh ...`.
+- **Title sanitization**: Filenames replace `/:?*` with `_`; Unicode is preserved.
+- **Age-restricted / members-only**: Require cookies — out of scope for this skill.
+
+## See also
+
+- yt-dlp docs: https://github.com/yt-dlp/yt-dlp
+- WebVTT spec: https://www.w3.org/TR/webvtt1/
+- TypeDB skill refinement example (the pass that produced this skill): `.claude/skills/typedb/`

package/skills/youtube-subs/scripts/fetch.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# youtube-subs/fetch.sh — download subtitles for a video, playlist, channel, or list of IDs
+#
+# Usage:
+#   fetch.sh <url-or-ids> <out-dir> [max-videos]
+#
+# Env:
+#   SUBS_LANG=en     (override subtitle language, default en)
+#   PREFER_AUTO=0    (if 1, accept auto-generated even when manual exists)
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  cat >&2 <<EOF
+Usage: $0 <url-or-space-separated-ids> <out-dir> [max-videos]
+
+Examples:
+  $0 dQw4w9WgXcQ ./out
+  $0 "https://www.youtube.com/c/vaticle/videos" ./out 20
+  $0 "ID1 ID2 ID3" ./out
+EOF
+  exit 1
+fi
+
+TARGET="$1"
+OUT_DIR="$2"
+MAX="${3:-0}"
+LANG="${SUBS_LANG:-en}"
+
+mkdir -p "$OUT_DIR/raw" "$OUT_DIR/text"
+
+# If TARGET is a space-separated list of IDs, turn them into URLs
+if [[ "$TARGET" =~ ^[A-Za-z0-9_-]{11}([[:space:]]+[A-Za-z0-9_-]{11})*$ ]]; then
+  URLS=()
+  for id in $TARGET; do
+    URLS+=("https://www.youtube.com/watch?v=$id")
+  done
+else
+  URLS=("$TARGET")
+fi
+
+# Build yt-dlp args
+COMMON_ARGS=(
+  --skip-download
+  --write-subs
+  --write-auto-subs
+  --sub-langs "$LANG"
+  --sub-format "vtt"
+  --write-info-json
+  --no-warnings
+  --sleep-interval 1
+  --ignore-errors
+  -o "$OUT_DIR/raw/%(upload_date>%Y%m%d)s-%(id)s-%(title).80s.%(ext)s"
+)
+
+if [[ "$MAX" != "0" ]]; then
+  COMMON_ARGS+=(--playlist-end "$MAX")
+fi
+
+echo "→ Fetching subtitles for ${#URLS[@]} target(s) into $OUT_DIR/raw/"
+for url in "${URLS[@]}"; do
+  yt-dlp "${COMMON_ARGS[@]}" "$url" || echo "  ⚠ partial failure on $url (continuing)"
+done
+
+echo "→ Converting VTT to clean text"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+python3 "$SCRIPT_DIR/vtt-to-text.py" "$OUT_DIR/raw" "$OUT_DIR/text"
+
+echo "→ Building index"
+INDEX="$OUT_DIR/index.tsv"
+printf "id\ttitle\tduration\tupload_date\tview_count\n" > "$INDEX"
+for info in "$OUT_DIR"/raw/*.info.json; do
+  [[ -e "$info" ]] || continue
+  jq -r '[.id, .title, (.duration // 0), (.upload_date // "NA"), (.view_count // 0)] | @tsv' "$info" >> "$INDEX"
+done
+
+# Summary
+RAW_COUNT=$(find "$OUT_DIR/raw" -name "*.vtt" 2>/dev/null | wc -l | tr -d ' ')
+TXT_COUNT=$(find "$OUT_DIR/text" -name "*.txt" 2>/dev/null | wc -l | tr -d ' ')
+echo
+echo "✓ $RAW_COUNT VTT files, $TXT_COUNT text files"
+echo "  Index: $INDEX"
+echo "  Feed text/ to an LLM for synthesis"

package/skills/youtube-subs/scripts/vtt-to-text.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Convert WebVTT files to clean plain-text transcripts.
+
+Handles YouTube's auto-caption quirks:
+  - Timestamps on their own lines (stripped)
+  - Inline cue timing tags like <00:00:01.500> (stripped)
+  - Rolling-window overlap between adjacent cues (de-duplicated)
+  - HTML entities + positioning metadata (stripped)
+
+Usage:
+    vtt-to-text.py <input-dir> <output-dir>
+
+Each `<id>-<title>.en.vtt` → `<id>.txt` (one sentence per line where detectable).
+"""
+
+from __future__ import annotations
+
+import html
+import re
+import sys
+from pathlib import Path
+
+# Line-start timestamp: "00:00:05.000 --> 00:00:08.000" and variations
+TS_LINE = re.compile(r"^\d+:\d+:\d+\.\d+\s*-->\s*\d+:\d+:\d+\.\d+.*$")
+# Inline timing tags: <00:00:01.500>
+INLINE_TS = re.compile(r"<\d+:\d+:\d+\.\d+>")
+# Positioning tags: <c>, </c>, <c.colorFFFFFF>
+INLINE_TAG = re.compile(r"</?c[^>]*>")
+# WebVTT header + cue-ids + positioning lines
+META_LINE = re.compile(r"^(WEBVTT|NOTE|Kind:|Language:|X-TIMESTAMP|\d+)(\s|$)")
+
+EXTRACT_ID = re.compile(r"-([A-Za-z0-9_-]{11})-")
+
+
+def parse_vtt(text: str) -> list[str]:
+    """Return ordered list of cue lines with timing/tags stripped."""
+    cues: list[str] = []
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        if TS_LINE.match(line):
+            continue
+        if META_LINE.match(line):
+            continue
+        # Strip inline tags
+        line = INLINE_TS.sub("", line)
+        line = INLINE_TAG.sub("", line)
+        line = html.unescape(line).strip()
+        if line:
+            cues.append(line)
+    return cues
+
+
+def dedupe_rolling(cues: list[str]) -> list[str]:
+    """YouTube auto-captions repeat each phrase as the rolling window advances.
+
+    Strategy: if cue N fully starts with cue N-1, keep only the new suffix.
+    Otherwise look for the longest suffix of cue N-1 that is a prefix of cue N
+    and drop that overlap.
+    """
+    out: list[str] = []
+    prev = ""
+    for cur in cues:
+        if not prev:
+            out.append(cur)
+            prev = cur
+            continue
+        if cur == prev:
+            continue
+        if cur.startswith(prev):
+            suffix = cur[len(prev) :].strip()
+            if suffix:
+                out.append(suffix)
+            prev = cur
+            continue
+        # Find longest overlap: prev's suffix == cur's prefix
+        overlap = 0
+        max_k = min(len(prev), len(cur))
+        for k in range(max_k, 0, -1):
+            if prev.endswith(cur[:k]):
+                overlap = k
+                break
+        trimmed = cur[overlap:].strip()
+        if trimmed:
+            out.append(trimmed)
+        prev = cur
+    return out
+
+
+def reflow_sentences(pieces: list[str]) -> str:
+    """Join cue fragments into flowing text, break on sentence-end punctuation."""
+    joined = " ".join(pieces)
+    joined = re.sub(r"\s+", " ", joined).strip()
+    # Insert newlines after sentence-ending punctuation
+    joined = re.sub(r"([.!?])\s+(?=[A-Z0-9])", r"\1\n", joined)
+    return joined
+
+
+def convert(vtt_path: Path) -> str:
+    raw = vtt_path.read_text(encoding="utf-8", errors="replace")
+    cues = parse_vtt(raw)
+    cues = dedupe_rolling(cues)
+    return reflow_sentences(cues)
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("usage: vtt-to-text.py <input-dir> <output-dir>", file=sys.stderr)
+        return 2
+    in_dir = Path(sys.argv[1])
+    out_dir = Path(sys.argv[2])
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    count = 0
+    for vtt in sorted(in_dir.glob("*.vtt")):
+        m = EXTRACT_ID.search(vtt.name)
+        if m:
+            out_name = f"{m.group(1)}.txt"
+        else:
+            out_name = vtt.stem + ".txt"
+        text = convert(vtt)
+        (out_dir / out_name).write_text(text + "\n", encoding="utf-8")
+        count += 1
+    print(f"  converted {count} VTT → txt")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/template-agent.md

@@ -1,10 +1,18 @@
 ---
+# TEMPLATE — AGENT DEFINITION → one.ie/ai/agents/<name>.md. Fill, then
+# delete these comment lines. Spawned at BUILD when the promise's
+# world.agents names an agent that doesn't exist (the presence-check
+# gap); reconciles upward to the promise (text/<slug>.md).
 name: {kebab-name}
 description: {One sentence — what this agent does and when to spawn it}
 tools: {comma-separated tool list}
 model: {haiku | sonnet | opus}
 effort: {none | low | medium | high | xhigh}
 skills: {comma-separated skill list}
+subscribes: [{tag}, {tag}]  # the agent's stake — these tags route matching
+                            # world signals to it AND define its inbox Space
+                            # at /u/<slug>/in; registered via
+                            # subscriptions:register on sync/provision
 ---
 
 You are the {name} agent. {One sentence role statement.}
@@ -15,6 +23,8 @@ You are the {name} agent. {One sentence role statement.}
 
 **Output:** {format of the result — structured, bounded, cited}
 
+**Escalate, don't guess.** Ambiguous or under-specified input → return a `needs: {what}` receipt and stop. Never assume a missing value.
+
 ## Model · Effort dial
 
 | Model | Effort | Use when |
@@ -45,6 +55,17 @@ You are the {name} agent. {One sentence role statement.}
 
 {json signal receiver and shape}
 
+## Example (one filled pass — the shape to copy)
+
+**Input:** `{ targets: ["src/lib/foo.ts", "src/lib/bar.ts"], mode: "RECON" }`
+
+**Output:**
+```json
+{ "receiver": "recon:done", "files": 2,
+  "findings": [{ "file": "src/lib/foo.ts", "exports": ["fooClient"], "relevance": 0.8 }],
+  "receipt": "2 files · 1 high-signal · bar.ts filtered (relevance 0.3)" }
+```
+
 ## Out of scope
 
 - {what this agent never does}