@oneie/claude 0.5.0 → 0.6.0

package/skills/rag-triangulate/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: rag-triangulate
+description: Pattern 3 of the RAG query library - run the SAME question against all 3 vaults (oo-brain / agency-operator / personal-brain) plus a cross-vault pass, then compare what each surfaces. A vault that hits where another is silent = a knowledge/SOP/skill gap. Triggers when Donal says "triangulate this", "check all vaults for", "do we have an SOP for X", or when a single-vault search returns weak hits and the gap is unclear.
+model: claude-sonnet-4-6
+source: oo-internal
+---
+
+# Skill: /rag-triangulate - Cross-Vault Triangulation
+
+**Purpose:** Ask one question of every vault and compare coverage. The output is both an answer AND a gap signal: if `oo-brain` (intel/courses) knows something `agency-operator` (our SOPs/skills) doesn't, that delta is a skill/SOP we should build. Pattern 3 of `docs/rag-query-pattern-library.md`.
+**Output:** A 3-column coverage comparison + synthesized answer + explicit gap list, with per-vault `mark_retrieval` closing the loop.
+**Time to run:** 1-3 min.
+**Cost:** Tier 1 (in-chat, $0). Scripted: ~$0.50 (4 searches + Sonnet compare). Hard-cap $2.
+
+---
+
+## HARD RULES
+
+- **Closed-loop non-negotiable.** Each of the (up to 4) `search_notes` calls gets its own `mark_retrieval(query_id, outcome)` before the skill returns. No orphan queries.
+- **Same query string to every vault.** The whole point is a controlled comparison - do NOT re-word the query per vault. Vary the vault, hold the query constant.
+- **personal-brain may be empty.** It currently holds 0 chunks. A zero-hit there is expected, not a gap - note it as "vault unpopulated" not "knowledge gap".
+- **A gap is directional.** "oo-brain hits, agency-operator silent" = we have the intel but no operational asset = BUILD candidate. "agency-operator hits, oo-brain silent" = our SOP isn't backed by external intel = fine, or a research candidate. Always state the direction.
+- **W1-W4 routing:** W1 (frame query) Haiku · W2/W3 (compare + synthesize) Sonnet · W4 (close loop) Haiku.
+
+---
+
+## When to use
+
+- "Do we actually have an SOP / skill for <X>, or just intel about it?"
+- A single-vault search returned weak hits and you can't tell if it's a query problem or a real gap
+- Pre-build gap check before authoring a new skill (confirms the gap is real, not just mis-queried)
+- Reconciling "the course says X" against "what our SOPs actually do"
+
+**Not for:** broad multi-angle research (use `/rag-fanout`); narrow factual lookup (Pattern 1 single query); persona questions (`/persona-council`).
+
+## Input
+
+**Required:** `<question>` - the single query string to triangulate.
+**Optional:**
+- `--k <N>` chunks per vault (default 5, max 8)
+- `--vaults <list>` override the default 3 (e.g. `oo-brain,agency-operator`)
+- `--out <path>` write report to file
+- `--dry-run` print the plan (query + vaults) without firing
+
+## Process
+
+### Step 1 (W1, Haiku): Lock the query
+Take the question verbatim as the search string (lightly normalize to keywords if it's a long sentence - search_notes is hybrid vector+BM25, not Q&A). Confirm it's the SAME string for all vaults.
+
+### Step 2 (W3): Fire one search per vault
+For each vault in {oo-brain, agency-operator, personal-brain (skip if known-empty unless `--vaults` forces it), null/cross-vault}:
+1. `mcp__search_notes(query=<q>, k=<k>, vault=<vault>)`
+2. Capture query_id + top-k chunks (file_path, excerpt, score).
+
+**Acceptance:** one query_id per vault attempted; zero-hits recorded explicitly.
+
+### Step 3 (W2/W3, Sonnet): Compare + synthesize
+Build the comparison:
+
+```markdown
+# Triangulation: "<question>"
+
+## Coverage by vault
+| Vault | Top hit (file) | Score | Verdict |
+|---|---|---|---|
+| oo-brain | <file> | <score> | strong / weak / silent |
+| agency-operator | <file> | <score> | strong / weak / silent |
+| personal-brain | - | - | unpopulated |
+| cross-vault | <file> | <score> | strong / weak / silent |
+
+## Synthesized answer
+<the answer, citing which vault each claim came from>
+
+## Gaps surfaced (directional)
+- [BUILD] oo-brain has <X> but agency-operator is silent → candidate skill/SOP: <name>
+- [RESEARCH] agency-operator has <Y> but no external backing in oo-brain
+- [OK] both cover <Z>
+```
+
+**Acceptance:** every claim cites its source vault + file; every gap states direction + a candidate action.
+
+### Step 4 (W4, Haiku): Close the loop
+`mark_retrieval` per vault query: `mark` if a chunk fed the synthesis, `warn` if hits were useless, `unsure` if ambiguous. personal-brain zero-hit on an empty vault = `unsure` with note "vault unpopulated".
+
+**Acceptance:** mark_retrieval count == search_notes count.
+
+### Step 5: Emit
+`--out` writes to file else stdout. Always print:
+```
+TRIANGULATE: <q> | vaults hit: <list> | gaps: <n> BUILD / <n> RESEARCH | closed-loop <m>/<m>.
+```
+
+## Quality Checks
+- [ ] Same query string used for every vault
+- [ ] One mark_retrieval per search_notes
+- [ ] Each claim cites source vault + file
+- [ ] Gaps are directional (BUILD vs RESEARCH vs OK) with a candidate action
+- [ ] Empty-vault zero-hits labelled "unpopulated" not "gap"
+
+## Escalation rules
+Escalate to Donal if: vaults return CONTRADICTORY answers (oo-brain says X, agency-operator says not-X) - flag the contradiction, don't auto-resolve; all vaults silent (query or RAG-quality problem - try `/rag-fanout` to widen); a [BUILD] gap looks high-value (feed to `/rag-skill-discovery` + sub-plan 12 catalog).
+
+## Cost note (Rule 15)
+4 searches × k=5 + one Sonnet compare ≈ $0.50. Hard-cap $2. Tier 1 in-chat = $0.
+
+## Composition
+`composes_with_sesh: false`. Single-shot comparison. If a [BUILD] gap warrants a real build, run `/sesh new <slug>` separately.
+
+## Cross-references
+
+- Cost levers (sub-token / API): `docs/rag-cost-optimization.md` (Haiku cache floor ~4k empirical; dedup sub-queries + chunks; OpenAI-embedding vs Anthropic-synthesis surfaces)
+- Pattern source: `docs/rag-query-pattern-library.md` (Pattern 3)
+- Closed-loop: CLAUDE.md "OO-Brain MCP - Closed-Loop Retrieval Contract"
+- Sibling: `/rag-fanout` (Pattern 2), `/rag-skill-discovery` (Pattern 6 - consumes the gaps this surfaces)
+- Rules: 08 (routing), 15 (cost)
+- Sub-plan: `Plans/2026-05-28/big-skill-overhaul/15-rag-query-pattern-library.md`
+
+## Pickup Prompt
+```
+/rag-triangulate "do we have an SOP for Hostinger to CF Pages cutover"
+/rag-triangulate "<question>" --k 8 --out /tmp/triangulate-<topic>.md
+/rag-triangulate "<question>" --dry-run
+```

package/skills/react19/SKILL.md

@@ -0,0 +1,491 @@
+---
+name: react19
+description: React 19 patterns including Actions, use() hook, transitions, ref as prop, and optimistic updates for the Envelope System
+user-invocable: true
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# React 19 Development
+
+Modern React 19 patterns for building interactive components in the Envelope System.
+
+## Works With
+
+| Skill        | Load when                                                                        |
+|--------------|----------------------------------------------------------------------------------|
+| `/signal`    | Any `onClick` — every click emits `ui:<surface>:<action>` via `emitClick()`. See `.claude/rules/ui.md`. |
+| `/astro`     | The component lives in an Astro page — hydration directives (`client:load`, `client:only`) decide worker bundle size. |
+| `/shadcn`    | Using Cards, Tabs, Badges, Dialog — shadcn components are React components with ref-as-prop. |
+| `/ai-ui`     | Agent reasoning UIs, tool-call visualization, generative components composed from shadcn. |
+| `/reactflow` | Graph visualizations — ColonyGraph, PheromoneGraph read substrate highways.       |
+
+Auto-loads on `*.tsx`: `rules/react.md` + `rules/ui.md` (per `.claude/settings.json`).
+
+## When to Use This Skill
+
+- Build React components in `src/components/`
+- Implement form handling with Actions
+- Use the new `use()` hook for promises/context
+- Apply transitions for non-blocking updates
+- Implement optimistic UI patterns
+
+## Key React 19 Features
+
+### 1. Actions (Form Handling)
+
+Actions replace manual form handling. They work with `<form action={...}>`:
+
+```tsx
+// src/components/envelopes/EnvelopeSubmitter.tsx
+import { useActionState } from 'react';
+
+interface EnvelopeFormState {
+  success: boolean;
+  error?: string;
+  envelopeId?: string;
+}
+
+async function submitEnvelope(
+  prevState: EnvelopeFormState,
+  formData: FormData
+): Promise<EnvelopeFormState> {
+  const action = formData.get('action') as string;
+  const target = formData.get('target') as string;
+
+  try {
+    // Process envelope
+    const envelope = createEnvelope({ action, target });
+    return { success: true, envelopeId: envelope.id };
+  } catch (e) {
+    return { success: false, error: (e as Error).message };
+  }
+}
+
+export function EnvelopeSubmitter() {
+  const [state, formAction, isPending] = useActionState(
+    submitEnvelope,
+    { success: false }
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="action" placeholder="Action name" disabled={isPending} />
+      <input name="target" placeholder="Target agent" disabled={isPending} />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Sending...' : 'Send Envelope'}
+      </button>
+      {state.error && <p className="text-red-500">{state.error}</p>}
+      {state.success && <p className="text-green-500">Sent: {state.envelopeId}</p>}
+    </form>
+  );
+}
+```
+
+### 2. use() Hook
+
+Read promises and context directly with `use()`:
+
+```tsx
+// Reading a promise
+import { use, Suspense } from 'react';
+
+interface RuntimeState {
+  agents: Agent[];
+  promises: AgentPromise[];
+}
+
+function RuntimeDisplay({ runtimePromise }: { runtimePromise: Promise<RuntimeState> }) {
+  const runtime = use(runtimePromise); // Suspends until resolved
+
+  return (
+    <div>
+      <h2>Agents: {runtime.agents.length}</h2>
+      <h2>Promises: {runtime.promises.length}</h2>
+    </div>
+  );
+}
+
+// Wrap with Suspense
+export function RuntimeContainer() {
+  const runtimePromise = fetchRuntimeState();
+
+  return (
+    <Suspense fallback={<div>Loading runtime...</div>}>
+      <RuntimeDisplay runtimePromise={runtimePromise} />
+    </Suspense>
+  );
+}
+```
+
+```tsx
+// Reading context conditionally
+import { use, createContext } from 'react';
+
+const RuntimeContext = createContext<Runtime | null>(null);
+
+function AgentCard({ agentId }: { agentId: string }) {
+  const runtime = use(RuntimeContext);
+  if (!runtime) return null;
+
+  const agent = runtime.getAgent(agentId);
+  return <div>{agent.name}</div>;
+}
+```
+
+### 3. Transitions
+
+Non-blocking state updates with `useTransition`:
+
+```tsx
+import { useState, useTransition } from 'react';
+
+interface Agent {
+  id: string;
+  name: string;
+  envelopes: Envelope[];
+}
+
+export function AgentTabs({ agents }: { agents: Agent[] }) {
+  const [selectedAgent, setSelectedAgent] = useState(agents[0]?.id);
+  const [isPending, startTransition] = useTransition();
+
+  const handleTabChange = (agentId: string) => {
+    startTransition(() => {
+      setSelectedAgent(agentId);
+    });
+  };
+
+  const agent = agents.find(a => a.id === selectedAgent);
+
+  return (
+    <div>
+      <div className="tabs">
+        {agents.map(a => (
+          <button
+            key={a.id}
+            onClick={() => handleTabChange(a.id)}
+            className={a.id === selectedAgent ? 'active' : ''}
+          >
+            {a.name}
+          </button>
+        ))}
+      </div>
+      <div className={isPending ? 'opacity-50' : ''}>
+        {agent && <AgentContent agent={agent} />}
+      </div>
+    </div>
+  );
+}
+```
+
+### 4. Optimistic Updates
+
+Show expected state before server confirms:
+
+```tsx
+import { useOptimistic } from 'react';
+
+interface Envelope {
+  id: string;
+  status: 'pending' | 'resolved' | 'rejected';
+}
+
+export function EnvelopeList({ envelopes: initialEnvelopes }: { envelopes: Envelope[] }) {
+  const [optimisticEnvelopes, addOptimisticEnvelope] = useOptimistic(
+    initialEnvelopes,
+    (state, newEnvelope: Envelope) => [...state, newEnvelope]
+  );
+
+  async function sendEnvelope(formData: FormData) {
+    const tempEnvelope: Envelope = {
+      id: `temp-${Date.now()}`,
+      status: 'pending',
+    };
+
+    // Show optimistically
+    addOptimisticEnvelope(tempEnvelope);
+
+    // Actually send
+    await submitEnvelope(formData);
+  }
+
+  return (
+    <div>
+      <form action={sendEnvelope}>
+        <input name="action" />
+        <button type="submit">Send</button>
+      </form>
+      <ul>
+        {optimisticEnvelopes.map(env => (
+          <li key={env.id} className={env.id.startsWith('temp-') ? 'opacity-50' : ''}>
+            {env.id}: {env.status}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### 5. ref as Prop
+
+No more `forwardRef` needed in React 19:
+
+```tsx
+// Before (React 18)
+const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => (
+  <input ref={ref} {...props} />
+));
+
+// After (React 19)
+interface InputProps {
+  ref?: React.Ref<HTMLInputElement>;
+  placeholder?: string;
+}
+
+function Input({ ref, ...props }: InputProps) {
+  return <input ref={ref} {...props} />;
+}
+
+// Usage
+function Form() {
+  const inputRef = useRef<HTMLInputElement>(null);
+  return <Input ref={inputRef} placeholder="Enter action" />;
+}
+```
+
+### 6. Document Metadata
+
+Render `<title>` and `<meta>` anywhere:
+
+```tsx
+function AgentPage({ agent }: { agent: Agent }) {
+  return (
+    <div>
+      <title>{agent.name} | Envelope System</title>
+      <meta name="description" content={`Agent ${agent.name} details`} />
+      <h1>{agent.name}</h1>
+    </div>
+  );
+}
+```
+
+## Project-Specific Patterns
+
+### Runtime Context Provider
+
+```tsx
+// src/components/providers/RuntimeProvider.tsx
+import { createContext, useState, useCallback, ReactNode } from 'react';
+import { Runtime } from '@/engine/Runtime';
+
+interface RuntimeContextValue {
+  runtime: Runtime;
+  refresh: () => void;
+  uiSchema: object;
+}
+
+export const RuntimeContext = createContext<RuntimeContextValue | null>(null);
+
+export function RuntimeProvider({ children }: { children: ReactNode }) {
+  const [runtime] = useState(() => new Runtime());
+  const [uiSchema, setUiSchema] = useState(() => runtime.toUISchema());
+
+  const refresh = useCallback(() => {
+    setUiSchema(runtime.toUISchema());
+  }, [runtime]);
+
+  return (
+    <RuntimeContext.Provider value={{ runtime, refresh, uiSchema }}>
+      {children}
+    </RuntimeContext.Provider>
+  );
+}
+```
+
+### Envelope Form with Actions
+
+```tsx
+// src/components/envelopes/CreateEnvelopeForm.tsx
+import { useActionState } from 'react';
+import { use } from 'react';
+import { RuntimeContext } from '@/components/providers/RuntimeProvider';
+import { createEnvelope } from '@/engine/Envelope';
+
+export function CreateEnvelopeForm() {
+  const { runtime, refresh } = use(RuntimeContext)!;
+
+  async function handleSubmit(prevState: any, formData: FormData) {
+    const envelope = createEnvelope({
+      action: formData.get('action') as string,
+      inputs: JSON.parse(formData.get('inputs') as string || '{}'),
+      sender: 'user',
+      receiver: formData.get('receiver') as string,
+    });
+
+    await runtime.send(envelope);
+    refresh();
+
+    return { success: true, envelopeId: envelope.id };
+  }
+
+  const [state, formAction, isPending] = useActionState(handleSubmit, {});
+
+  return (
+    <form action={formAction} className="space-y-4">
+      <input name="action" placeholder="Action" className="input" />
+      <input name="receiver" placeholder="Target Agent" className="input" />
+      <textarea name="inputs" placeholder='{"key": "value"}' className="textarea" />
+      <button type="submit" disabled={isPending} className="btn">
+        {isPending ? 'Sending...' : 'Send Envelope'}
+      </button>
+    </form>
+  );
+}
+```
+
+### Promise Tracker with Transitions
+
+```tsx
+// src/components/promises/PromiseTracker.tsx
+import { useState, useTransition } from 'react';
+import { AgentPromise } from '@/engine/types';
+
+interface Props {
+  promises: AgentPromise[];
+}
+
+export function PromiseTracker({ promises }: Props) {
+  const [filter, setFilter] = useState<'all' | 'pending' | 'resolved'>('all');
+  const [isPending, startTransition] = useTransition();
+
+  const filtered = promises.filter(p =>
+    filter === 'all' || p.status === filter
+  );
+
+  return (
+    <div>
+      <div className="flex gap-2 mb-4">
+        {(['all', 'pending', 'resolved'] as const).map(f => (
+          <button
+            key={f}
+            onClick={() => startTransition(() => setFilter(f))}
+            className={filter === f ? 'btn-active' : 'btn'}
+          >
+            {f}
+          </button>
+        ))}
+      </div>
+      <ul className={isPending ? 'opacity-50' : ''}>
+        {filtered.map(promise => (
+          <li key={promise.id} className="flex items-center gap-2">
+            <span className={`status-dot status-${promise.status}`} />
+            <span>{promise.label}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## TypeScript Patterns
+
+### Event Handlers
+
+```tsx
+// Type-safe event handlers
+function handleClick(e: React.MouseEvent<HTMLButtonElement>) {
+  e.preventDefault();
+}
+
+function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+  const value = e.target.value;
+}
+
+function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+  e.preventDefault();
+}
+```
+
+### Component Props
+
+```tsx
+// Prefer interfaces for props
+interface AgentCardProps {
+  agent: Agent;
+  onSelect?: (id: string) => void;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+// Use PropsWithChildren for components with children
+import { PropsWithChildren } from 'react';
+
+interface PanelProps {
+  title: string;
+}
+
+function Panel({ title, children }: PropsWithChildren<PanelProps>) {
+  return (
+    <div>
+      <h2>{title}</h2>
+      {children}
+    </div>
+  );
+}
+```
+
+## State Management Patterns
+
+### Local state for UI
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+const [selectedTab, setSelectedTab] = useState('agent-a');
+```
+
+### useReducer for complex state
+
+```tsx
+type Action =
+  | { type: 'SELECT_AGENT'; agentId: string }
+  | { type: 'ADD_ENVELOPE'; envelope: Envelope }
+  | { type: 'UPDATE_PROMISE'; promiseId: string; status: string };
+
+interface State {
+  selectedAgent: string;
+  envelopes: Envelope[];
+  promises: AgentPromise[];
+}
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'SELECT_AGENT':
+      return { ...state, selectedAgent: action.agentId };
+    case 'ADD_ENVELOPE':
+      return { ...state, envelopes: [...state.envelopes, action.envelope] };
+    case 'UPDATE_PROMISE':
+      return {
+        ...state,
+        promises: state.promises.map(p =>
+          p.id === action.promiseId ? { ...p, status: action.status } : p
+        ),
+      };
+  }
+}
+```
+
+## Best Practices
+
+1. **Use Actions for forms**: Cleaner than manual `onSubmit`
+2. **Wrap async with Suspense**: When using `use()` with promises
+3. **Use transitions for tabs/filters**: Keeps UI responsive
+4. **Optimistic updates for UX**: Show expected state immediately
+5. **Type everything**: No `any` types
+6. **Prefer `interface` over `type`**: For props and objects
+
+---
+
+**Version**: 1.0.0
+**Tech**: React 19.1