orbit-thread 0.0.0-stage → 1.1.0

package/plugin/skills/handoff/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Orbit Thread Handoff"
+  short_description: "Save verified coding state"
+  default_prompt: "Use $handoff to save the verified current state and immediate next steps."
+policy:
+  allow_implicit_invocation: true

package/plugin/skills/handoff/scripts/write_handoff.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Replace HANDOFF-STATE.md (repo root by default) with stdin after validation.
+set -eu
+
+target="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)/HANDOFF-STATE.md}"
+tmp="$(mktemp "$(dirname "$target")/.handoff.XXXXXX")"
+trap 'rm -f "$tmp"' EXIT HUP INT TERM
+
+cat > "$tmp"
+
+if [ ! -s "$tmp" ]; then
+  echo "handoff rejected: content is empty" >&2
+  exit 1
+fi
+
+# awk also counts a final line without a trailing newline.
+lines="$(awk 'END { print NR }' "$tmp")"
+if [ "$lines" -gt 50 ]; then
+  echo "handoff rejected: $lines lines; maximum is 50" >&2
+  exit 1
+fi
+
+# Backstop for obvious secrets. Report line numbers only, never the matched text.
+secret_re='-----BEGIN [A-Z ]*PRIVATE KEY-----|AKIA[0-9A-Z]{16}|(sk|rk)_(live|test)_[0-9A-Za-z]{10,}|whsec_[0-9A-Za-z]{10,}|gh[pousr]_[0-9A-Za-z]{20,}|github_pat_[0-9A-Za-z_]{20,}|xox[abprs]-[0-9A-Za-z-]{10,}|eyJ[0-9A-Za-z_-]{10,}\.[0-9A-Za-z_-]{10,}\.|(secret|token|passw(or)?d|api[_-]?key)[a-z_]*["'\'']?[[:space:]]*[:=][[:space:]]*["'\'']?[^[:space:]"'\''`]{12,}'
+hits="$(grep -Ein -e "$secret_re" "$tmp" | cut -d: -f1 | tr '\n' ' ' || true)"
+if [ -n "$hits" ]; then
+  echo "handoff rejected: possible secret on line(s) ${hits% }" >&2
+  exit 1
+fi
+
+mv "$tmp" "$target"
+trap - EXIT HUP INT TERM
+printf 'wrote %s (%s lines)\n' "$target" "$lines"

package/plugin/skills/orbit-setup/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: orbit-setup
+description: Set up or upgrade a coding project for token-efficient long-running work with Orbit Thread. Use when the user invokes orbit-setup, asks to initialise project continuity, wants lightweight living project docs and agent rules before development, or asks to configure Orbit Thread project workflow.
+---
+
+# Orbit Thread Setup
+
+Prepare the current project for efficient Codex and Claude Code sessions without overwriting existing project knowledge.
+
+## Workflow
+
+1. Resolve this skill's directory and run `scripts/setup_project.mjs` with Node from inside the user's project:
+   - Claude standalone: `node "${CLAUDE_SKILL_DIR}/scripts/setup_project.mjs" setup --agent both`
+   - Codex: resolve the loaded skill directory and run the same script from there.
+2. The script creates only missing living-document templates, preserves equivalent root/docs files, updates the managed Orbit Thread blocks in `AGENTS.md` and `CLAUDE.md`, creates `.orbit-thread/config.json`, and ensures local handoff/tool state is Git-ignored.
+3. Do not create `HANDOFF-STATE.md` during setup. The handoff skill creates it at the first meaningful checkpoint.
+4. If the conversation already contains clear durable project facts, fill only relevant TODOs in newly created docs. Do not broadly scan the repository or invent product, architecture, security or design decisions.
+5. Report created, updated and preserved files concisely.
+
+## Project shape
+
+Orbit Thread prefers these living docs under `docs/` when no equivalent root/docs file already exists:
+
+- `PRODUCT.md` — product purpose, workflows, scope and constraints.
+- `DESIGN.md` — durable visual/interaction rules.
+- `ARCHITECTURE.md` — system shape, boundaries, persistence and operations.
+- `SECURITY.md` — trust boundaries, controls and known risks.
+- `ROADMAP.md` — forward-looking current plan only.
+
+These are living current-state documents, not changelogs. Update affected sections in place as implementation truth changes; Git is the history.
+
+## Rules
+
+- Preserve existing files and unrelated instructions. Never replace project docs merely to standardise layout or create duplicate root/docs copies.
+- Keep setup token-efficient: inspect only target files and facts needed for setup.
+- Do not read secret files or write credentials, personal data or sensitive production data into project docs.
+- Do not commit, push, merge, initialise Git or make other Git writes.
+- Setup may run before Git is initialised; then the current directory is the project root.
+- Setup-created living docs and `.orbit-thread/config.json` are project-owned and are preserved on uninstall.
+- For subagent preferences, use the npm CLI after setup, for example:
+  `npx orbit-thread configure --agent claude --model "Claude Sonnet 5.5" --effort low`
+  or `npx orbit-thread configure --agent codex --model "GPT-6.1 Sol" --reasoning high`.

package/plugin/skills/orbit-setup/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Orbit Thread Setup"
+  short_description: "Prepare efficient coding continuity"
+  default_prompt: "Use $orbit-setup to prepare this project with lightweight living docs and Orbit Thread workflow rules."
+policy:
+  allow_implicit_invocation: true

package/plugin/skills/orbit-setup/scripts/project_config.mjs

@@ -0,0 +1,168 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const PRODUCT = 'orbit-thread';
+const SCHEMA = 1;
+const agents = ['codex', 'claude'];
+const start = '<!-- orbit-thread:subagents:start -->';
+const end = '<!-- orbit-thread:subagents:end -->';
+
+const exists = p => {
+  try { fs.lstatSync(p); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+};
+
+function safePath(p) {
+  let cursor = path.resolve(p);
+  while (true) {
+    if (exists(cursor) && fs.lstatSync(cursor).isSymbolicLink()) throw new Error(`Refusing symlink: ${cursor}`);
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+}
+
+function atomicWrite(p, content) {
+  safePath(p);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const temporary = path.join(path.dirname(p), `.orbit-thread-${crypto.randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, content, { flag: 'wx', mode: exists(p) ? fs.statSync(p).mode & 0o777 : 0o644 });
+    fs.renameSync(temporary, p);
+  } finally {
+    if (exists(temporary)) fs.unlinkSync(temporary);
+  }
+}
+
+const configPath = root => path.join(root, '.orbit-thread/config.json');
+const statePath = root => path.join(root, '.orbit-thread/state.json');
+const defaultConfig = () => ({
+  product: PRODUCT,
+  schema: SCHEMA,
+  subagents: {
+    max: 2,
+    codex: { model: null, reasoning: null },
+    claude: { model: null, reasoning: null },
+  },
+});
+
+function validate(config, source = 'Orbit Thread config') {
+  if (!config || config.product !== PRODUCT || config.schema !== SCHEMA ||
+      !config.subagents || !Number.isInteger(config.subagents.max) ||
+      config.subagents.max < 0 || config.subagents.max > 2) {
+    throw new Error(`Invalid ${source}`);
+  }
+  for (const agent of agents) {
+    const pref = config.subagents[agent];
+    if (!pref || !Object.hasOwn(pref, 'model') || !Object.hasOwn(pref, 'reasoning')) throw new Error(`Invalid ${source}`);
+    for (const key of ['model', 'reasoning']) {
+      const value = pref[key];
+      const limit = key === 'model' ? 100 : 40;
+      if (value !== null && (typeof value !== 'string' || !value.trim() || value.includes('\n') || value.length > limit)) {
+        throw new Error(`Invalid ${source}: ${agent}.${key}`);
+      }
+    }
+  }
+  return config;
+}
+
+export function readProjectConfig(root) {
+  const p = configPath(path.resolve(root));
+  if (!exists(p)) return defaultConfig();
+  return validate(JSON.parse(fs.readFileSync(p, 'utf8')), p);
+}
+
+export function ensureProjectConfig(root) {
+  root = path.resolve(root);
+  const config = readProjectConfig(root);
+  if (!exists(configPath(root))) atomicWrite(configPath(root), JSON.stringify(config, null, 2) + '\n');
+  return config;
+}
+
+export function renderSubagentBlock(config) {
+  validate(config);
+  const lines = [start];
+  if (config.subagents.max === 0) {
+    lines.push('- Subagents are disabled for this project.');
+  } else {
+    lines.push(`- Subagents: default to none. Use at most ${config.subagents.max} total/concurrently, only for genuinely separable work where isolated context materially helps. Give each subagent a narrow scope, avoid duplicate repository reads, and require concise findings. No recursive subagents. The main agent owns integration and final decisions.`);
+    for (const agent of agents) {
+      const pref = config.subagents[agent];
+      if (!pref.model && !pref.reasoning) continue;
+      const details = [
+        pref.model ? `model ${pref.model}` : null,
+        pref.reasoning ? `reasoning/effort ${pref.reasoning}` : null,
+      ].filter(Boolean).join(', ');
+      lines.push(`- Preferred ${agent === 'codex' ? 'Codex' : 'Claude'} subagent setting when the host supports it: ${details}. Treat this as a preference, not a reason to block work if the exact setting is unavailable.`);
+    }
+  }
+  lines.push(end);
+  return lines.join('\n');
+}
+
+function clean(value, label, max) {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  const text = String(value).trim();
+  if (!text || text.includes('\n') || text.length > max) throw new Error(`Invalid ${label}`);
+  return text;
+}
+
+function replaceManagedSubagentBlock(text, replacement) {
+  const first = text.indexOf(start);
+  const last = text.indexOf(end);
+  if (first < 0 || last < first || text.indexOf(start, first + start.length) >= 0 || text.indexOf(end, last + end.length) >= 0) {
+    throw new Error('Orbit Thread subagent block is missing or malformed; run setup before configure.');
+  }
+  return text.slice(0, first) + replacement + text.slice(last + end.length);
+}
+
+export function configureProject(root, { agent, maxSubagents, model, reasoning, resetSubagents = false } = {}) {
+  root = path.resolve(root);
+  const stateFile = statePath(root);
+  const agentsFile = path.join(root, 'AGENTS.md');
+  if (!exists(stateFile) || !exists(agentsFile)) throw new Error('Orbit Thread project setup is not configured; run `npx orbit-thread setup` first.');
+
+  const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  const owned = state?.additions?.['AGENTS.md'];
+  if (!owned || typeof owned.inserted !== 'string') throw new Error('Orbit Thread AGENTS.md ownership state is missing; run setup first.');
+
+  let config = readProjectConfig(root);
+  if (resetSubagents) {
+    if (agent && agents.includes(agent)) {
+      config.subagents[agent] = { model: null, reasoning: null };
+    } else {
+      for (const name of agents) config.subagents[name] = { model: null, reasoning: null };
+    }
+  }
+  if (maxSubagents !== undefined) {
+    const value = Number(maxSubagents);
+    if (!Number.isInteger(value) || value < 0 || value > 2) throw new Error('max-subagents must be 0, 1 or 2');
+    config.subagents.max = value;
+  }
+  const cleanModel = clean(model, 'subagent model', 100);
+  const cleanReasoning = clean(reasoning, 'subagent reasoning/effort', 40);
+  if (cleanModel !== undefined || cleanReasoning !== undefined) {
+    if (!agents.includes(agent)) throw new Error('Choose --agent codex or --agent claude when setting a model or reasoning/effort preference.');
+    if (cleanModel !== undefined) config.subagents[agent].model = cleanModel;
+    if (cleanReasoning !== undefined) config.subagents[agent].reasoning = cleanReasoning;
+  }
+  validate(config);
+
+  const before = fs.readFileSync(agentsFile, 'utf8');
+  const index = before.indexOf(owned.inserted);
+  if (index < 0 || index !== before.lastIndexOf(owned.inserted)) {
+    throw new Error('Managed Orbit Thread AGENTS.md block was edited or duplicated; reconcile it before configure.');
+  }
+
+  const replacement = renderSubagentBlock(config);
+  const nextInserted = replaceManagedSubagentBlock(owned.inserted, replacement);
+  const nextFile = before.slice(0, index) + nextInserted + before.slice(index + owned.inserted.length);
+  state.additions['AGENTS.md'].inserted = nextInserted;
+
+  atomicWrite(configPath(root), JSON.stringify(config, null, 2) + '\n');
+  atomicWrite(agentsFile, nextFile);
+  atomicWrite(stateFile, JSON.stringify(state, null, 2) + '\n');
+  return config;
+}