orbit-thread 0.0.0-stage → 1.2.0

package/lib/cli.mjs

@@ -0,0 +1,304 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import { setupProject, checkProject, removeProjectConfig, resolveProjectRoot } from '../plugin/skills/orbit-setup/scripts/setup_project.mjs';
+import { configureProject, readProjectConfig } from '../plugin/skills/orbit-setup/scripts/project_config.mjs';
+import { resumeProject } from './resume.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+const skillsRoot = path.join(packageRoot, 'plugin/skills');
+const marker = '.orbit-thread.json';
+const legacyMarker = '.orbit-handoff.json';
+const agents = ['codex', 'claude'];
+const skills = ['handoff', 'orbit-setup', 'orbit-resume'];
+const digest = data => crypto.createHash('sha256').update(data).digest('hex');
+const exists = p => { try { fs.lstatSync(p); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } };
+
+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); }
+}
+
+function files(dir, prefix = '') {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+    const relative = path.posix.join(prefix, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`Refusing symlink: ${relative}`);
+    return entry.isDirectory() ? files(path.join(dir, entry.name), relative) : [relative];
+  }).sort();
+}
+
+function skillSource(skill) { return path.join(skillsRoot, skill); }
+function bundled(skill) { return Object.fromEntries(files(skillSource(skill)).map(name => [name, fs.readFileSync(path.join(skillSource(skill), name))])); }
+function agentSkillsRoot(agent, scope, root) { return path.join(scope === 'user' ? os.homedir() : root, agent === 'codex' ? '.agents/skills' : '.claude/skills'); }
+function location(agent, scope, root, skill) { return path.join(agentSkillsRoot(agent, scope, root), skill); }
+
+function ownershipPath(dir) {
+  safePath(dir);
+  const current = path.join(dir, marker);
+  const legacy = path.join(dir, legacyMarker);
+  if (exists(current) && exists(legacy)) throw new Error(`Both Orbit Thread and legacy Orbit Handoff ownership files exist at ${dir}; reconcile them before continuing.`);
+  if (exists(current)) return current;
+  if (exists(legacy)) return legacy;
+  return null;
+}
+
+function readOwnership(dir) {
+  const p = ownershipPath(dir);
+  if (!p) return null;
+  const state = JSON.parse(fs.readFileSync(p, 'utf8'));
+  if (!['orbit-handoff', 'orbit-thread'].includes(state.product) || state.schema !== 1 || typeof state.version !== 'string' || !state.files || typeof state.files !== 'object' || Array.isArray(state.files)) throw new Error(`Invalid ownership file: ${p}`);
+  for (const [name, hash] of Object.entries(state.files)) {
+    if (!name || name === marker || name === legacyMarker || path.posix.isAbsolute(name) || name.includes('\\') || name.split('/').some(part => ['.', '..', ''].includes(part)) || !/^[a-f0-9]{64}$/.test(hash)) throw new Error(`Invalid ownership entry: ${p}`);
+  }
+  return state;
+}
+
+function preflight(dir, skill, updating) {
+  const state = readOwnership(dir);
+  if (exists(dir) && !state) throw new Error(`An unmanaged ${skill} skill already exists at ${dir}; move it aside yourself before installing.`);
+  if (updating && !state) return true;
+  if (state) {
+    for (const [name, hash] of Object.entries(state.files)) {
+      const p = path.join(dir, name); safePath(p);
+      if (!exists(p) || digest(fs.readFileSync(p)) !== hash) throw new Error(`Managed file was edited or removed: ${p}. Preserve your changes before updating.`);
+    }
+    for (const name of Object.keys(bundled(skill))) if (exists(path.join(dir, name)) && !Object.hasOwn(state.files, name)) throw new Error(`Unrelated file conflicts with this release: ${path.join(dir, name)}`);
+  }
+  return true;
+}
+
+function installSkill(dir, skill) {
+  const previousPath = ownershipPath(dir);
+  const previous = readOwnership(dir);
+  const content = bundled(skill);
+  for (const [name, data] of Object.entries(content)) atomicWrite(path.join(dir, name), data);
+  for (const name of Object.keys(previous?.files ?? {})) if (!Object.hasOwn(content, name) && exists(path.join(dir, name))) fs.unlinkSync(path.join(dir, name));
+  atomicWrite(path.join(dir, marker), JSON.stringify({ product: 'orbit-thread', schema: 1, version: pkg.version, skill,
+    files: Object.fromEntries(Object.entries(content).map(([name, data]) => [name, digest(data)])) }, null, 2) + '\n');
+  if (previousPath && previousPath.endsWith(legacyMarker) && exists(previousPath)) fs.unlinkSync(previousPath);
+}
+
+function prune(dir, boundary) {
+  while (dir !== boundary && exists(dir) && fs.readdirSync(dir).length === 0) { fs.rmdirSync(dir); dir = path.dirname(dir); }
+}
+
+function uninstallSkill(dir) {
+  const ownerFile = ownershipPath(dir);
+  const state = readOwnership(dir);
+  if (!state) { if (exists(dir)) console.log(`Unmanaged skill preserved: ${dir}`); return; }
+  const retained = {};
+  for (const [name, hash] of Object.entries(state.files)) {
+    const p = path.join(dir, name); safePath(p);
+    if (!exists(p)) continue;
+    if (digest(fs.readFileSync(p)) === hash) { fs.unlinkSync(p); prune(path.dirname(p), dir); }
+    else { retained[name] = hash; console.log(`Preserved edited file: ${p}`); }
+  }
+  if (Object.keys(retained).length) atomicWrite(ownerFile, JSON.stringify({ ...state, files: retained }, null, 2) + '\n');
+  else if (ownerFile && exists(ownerFile)) fs.unlinkSync(ownerFile);
+  prune(dir, path.dirname(dir));
+}
+
+function skillStatus(root, selected, scope) {
+  let complete = true;
+  for (const agent of selected) {
+    for (const skill of skills) {
+      const dir = location(agent, scope, root, skill);
+      const state = readOwnership(dir);
+      let label = exists(dir) ? 'unmanaged skill' : 'not installed';
+      if (state) {
+        const contents = bundled(skill);
+        const intact = Object.entries(state.files).every(([name, hash]) => { const p = path.join(dir, name); return exists(p) && digest(fs.readFileSync(p)) === hash; });
+        const current = intact && Object.keys(state.files).length === Object.keys(contents).length && Object.entries(contents).every(([name, data]) => state.files[name] === digest(data));
+        label = !intact ? `v${state.version}, locally modified` : current ? `v${state.version}, current` : `v${state.version}, update available in this package`;
+        if (!current) complete = false;
+      } else complete = false;
+      console.log(`${agent}/${skill} (${scope}): ${label} — ${dir}`);
+    }
+  }
+  return complete;
+}
+
+const help = `Orbit Thread ${pkg.version}
+
+Usage: orbit-thread <command> [options]
+
+Commands:
+  install       Install the Orbit Thread skills.
+  setup         Prepare/upgrade the current project workflow and living docs.
+  resume        Show concise project continuity and current Git state (read-only).
+  configure     Set project subagent preferences.
+  doctor        Check installed skills and project continuity health.
+  update        Upgrade unchanged managed skill files to this package version.
+  uninstall     Remove managed skills and instruction blocks.
+  init          Alias for setup.
+  check         Check managed skill installation (legacy-compatible).
+
+Common options:
+  --agent codex|claude|both
+  --scope project|user
+  --yes, -y
+
+Configure options:
+  --model, --subagent-model <name>
+  --reasoning, --effort <level>
+  --max-subagents 0|1|2
+  --reset-subagents
+  --show
+
+Examples:
+  npx orbit-thread install
+  npx orbit-thread setup
+  npx orbit-thread configure --agent claude --model "Claude Sonnet 5.5" --effort low
+  npx orbit-thread configure --agent codex --model "GPT-6.1 Sol" --reasoning high
+  npx orbit-thread doctor
+  npx orbit-thread@latest update --agent both --scope project --yes
+`;
+
+function parseOptions(rest) {
+  const options = { yes: false, show: false, resetSubagents: false };
+  for (let i = 0; i < rest.length; i++) {
+    const flag = rest[i];
+    const take = () => {
+      const value = rest[++i];
+      if (value === undefined) throw new Error(`Missing value for ${flag}`);
+      return value;
+    };
+    if (flag === '--yes' || flag === '-y') options.yes = true;
+    else if (flag === '--agent') options.agent = take();
+    else if (flag === '--scope') options.scope = take();
+    else if (flag === '--model' || flag === '--subagent-model') options.model = take();
+    else if (flag === '--reasoning' || flag === '--effort') options.reasoning = take();
+    else if (flag === '--max-subagents') options.maxSubagents = take();
+    else if (flag === '--reset-subagents') options.resetSubagents = true;
+    else if (flag === '--show') options.show = true;
+    else throw new Error(`Unknown option: ${flag}`);
+  }
+  return options;
+}
+
+function selectedAgents(value = 'both') {
+  if (!['codex', 'claude', 'both'].includes(value)) throw new Error('Agent must be codex, claude or both');
+  return value === 'both' ? agents : [value];
+}
+
+export async function main(argv) {
+  if (argv.includes('--help') || argv.includes('-h') || !argv.length) { console.log(help); return; }
+  if (argv.includes('--version') || argv.includes('-v')) { console.log(pkg.version); return; }
+
+  let [command, ...rest] = argv;
+  if (command === 'init') command = 'setup';
+  if (!['install', 'setup', 'resume', 'configure', 'check', 'doctor', 'update', 'uninstall'].includes(command)) throw new Error(`Unknown command: ${command}`);
+
+  const options = parseOptions(rest);
+  const scope = options.scope ?? 'project';
+  if (!['project', 'user'].includes(scope)) throw new Error('Scope must be project or user');
+  if (['setup', 'configure'].includes(command) && scope !== 'project') throw new Error(`${command} configures the current project; use --scope project`);
+  if (process.platform === 'win32') throw new Error('Use a Linux environment in WSL; native Windows is not supported');
+
+  let selected = selectedAgents(options.agent);
+  const root = resolveProjectRoot(process.cwd());
+
+  if (command === 'resume') {
+    if (rest.length) throw new Error('resume does not accept options');
+    resumeProject(root);
+    return;
+  }
+
+  if (command === 'configure') {
+    if (options.show) { console.log(JSON.stringify(readProjectConfig(root), null, 2)); return; }
+    if ((options.model !== undefined || options.reasoning !== undefined) && selected.length !== 1) {
+      throw new Error('Choose exactly one --agent when setting a subagent model or reasoning/effort preference.');
+    }
+    const config = configureProject(root, {
+      agent: selected.length === 1 ? selected[0] : undefined,
+      maxSubagents: options.maxSubagents,
+      model: options.model,
+      reasoning: options.reasoning,
+      resetSubagents: options.resetSubagents,
+    });
+    console.log(`Orbit Thread: project subagent configuration updated (max ${config.subagents.max}).`);
+    return;
+  }
+
+  if (command === 'check') {
+    if (!skillStatus(root, selected, scope)) process.exitCode = 1;
+    return;
+  }
+
+  if (command === 'doctor') {
+    const installed = skillStatus(root, selected, scope);
+    let healthy = installed;
+    if (scope === 'project') {
+      const result = checkProject(root, selected);
+      result.messages.forEach(message => console.log(message));
+      healthy = healthy && result.ok;
+    }
+    if (!healthy) process.exitCode = 1;
+    return;
+  }
+
+  const interactive = !options.yes;
+  if (interactive && !process.stdin.isTTY) throw new Error('Non-interactive input: pass --yes (and optionally --agent / --scope)');
+  const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+  try {
+    let effectiveScope = scope;
+    if (!options.agent && rl) {
+      const answer = (await rl.question('Choose agent: 1) Codex  2) Claude Code  3) Both [3]: ')).trim() || '3';
+      const chosen = { '1':'codex', '2':'claude', '3':'both' }[answer];
+      if (!chosen) throw new Error('Choose 1, 2 or 3');
+      selected = selectedAgents(chosen);
+    }
+    if (!options.scope && rl && command !== 'setup') {
+      const answer = (await rl.question('Choose scope: 1) Current project  2) User/global [1]: ')).trim() || '1';
+      effectiveScope = { '1':'project', '2':'user' }[answer];
+      if (!effectiveScope) throw new Error('Choose 1 or 2');
+    }
+
+    if (command === 'setup') {
+      console.log(`Will configure Orbit Thread project continuity in ${root}. Existing docs and unrelated instructions are preserved.`);
+      if (rl && !['y','yes'].includes((await rl.question('Continue? [y/N]: ')).trim().toLowerCase())) { console.log('Cancelled.'); return; }
+      const result = setupProject(root, selected);
+      for (const item of [...result.managed, ...result.docs]) console.log(`${item.action}: ${item.name}`);
+      console.log('Orbit Thread: setup complete. HANDOFF-STATE.md will be created at the first meaningful checkpoint.');
+      return;
+    }
+
+    const targets = selected.flatMap(a => skills.map(skill => ({ agent:a, skill, dir:location(a, effectiveScope, root, skill) })));
+    let eligible;
+    if (command === 'install' || command === 'update') {
+      if (command === 'update' && !targets.some(t => readOwnership(t.dir))) throw new Error('No managed Orbit Thread/legacy Orbit Handoff installation found; run install first');
+      eligible = targets.map(t => preflight(t.dir, t.skill, command === 'update'));
+    } else targets.forEach(t => readOwnership(t.dir));
+
+    console.log(`Will ${command} Orbit Thread ${pkg.version} (${effectiveScope}):\n${targets.map(t => t.dir).join('\n')}`);
+    if (rl && !['y','yes'].includes((await rl.question('Continue? [y/N]: ')).trim().toLowerCase())) { console.log('Cancelled.'); return; }
+
+    if (command === 'uninstall') {
+      targets.forEach(t => uninstallSkill(t.dir));
+      if (effectiveScope === 'project') removeProjectConfig(root, selected);
+    } else {
+      targets.forEach((t, i) => { if (command === 'install' || eligible[i]) installSkill(t.dir, t.skill); });
+    }
+    const suffix = command === 'install' && effectiveScope === 'project' ? '\nRun `npx orbit-thread setup` to prepare this project.' : '';
+    console.log(`Orbit Thread: ${command} complete.${suffix}`);
+  } finally { rl?.close(); }
+}

package/lib/resume.mjs

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const handoffPath = root => path.join(root, 'HANDOFF-STATE.md');
+const secret = /\b(api[_ -]?key|access[_ -]?token|refresh[_ -]?token|password|secret|authorization|bearer)\b\s*[:=]\s*[^\s,;]+/gi;
+
+function scrub(value) {
+  const safe = value.slice(0, 500)
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/\u009b[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '');
+  if (/\b(?:password|passphrase|token|secret|credential|private\s+key|api[_ -]?key|authorization|bearer)\b/i.test(safe)) {
+    return '[redacted sensitive-looking handoff line]';
+  }
+  return safe.replace(secret, '$1=[redacted]');
+}
+
+function readHandoff(root) {
+  const file = handoffPath(root);
+  try {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) return { state: 'invalid', reason: 'not a regular local file' };
+    if (stat.size > 32768) return { state: 'invalid', reason: 'larger than the 32 KB safety limit' };
+    const text = fs.readFileSync(file, 'utf8');
+    const lines = text.split(/\r?\n/);
+    if (lines.length > 51) return { state: 'invalid', reason: 'over the 50-line limit' };
+    if (!/^# Handoff State\s*$/m.test(text)) return { state: 'invalid', reason: 'missing the Handoff State heading' };
+    const updated = text.match(/^Updated:\s*(\d{2})-(\d{2})-(\d{4})(?:\s+\d{2}:\d{2})?\s*$/m);
+    const objective = section(text, 'Current objective');
+    if (!updated || !objective.length) return { state: 'invalid', reason: 'missing a valid update date or current objective' };
+    const date = new Date(Number(updated[3]), Number(updated[2]) - 1, Number(updated[1]));
+    if (Number.isNaN(date.valueOf()) || date.getDate() !== Number(updated[1]) || date.getMonth() !== Number(updated[2]) - 1) {
+      return { state: 'invalid', reason: 'invalid update date' };
+    }
+    return {
+      state: 'valid', text, updated: `${updated[3]}-${updated[2]}-${updated[1]}`,
+      fields: {
+        objective,
+        completed: section(text, 'Completed milestones'),
+        unfinished: section(text, 'In progress'),
+        risks: section(text, 'Open issues / risks'),
+        verification: section(text, 'Verification'),
+        next: section(text, 'Immediate next steps'),
+      },
+    };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'missing' };
+    throw error;
+  }
+}
+
+function section(text, title) {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = text.match(new RegExp(`^##\\s+${escaped}\\s*\\r?\\n([\\s\\S]*?)(?=^##\\s+|\\s*$)`, 'm'));
+  if (!match) return [];
+  return match[1].split(/\r?\n/).map(line => line.trim()).filter(line => line && !/^<!--/.test(line)).slice(0, 6).map(line => scrub(line));
+}
+
+function git(root, args) {
+  try {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 }).trim();
+  } catch { return null; }
+}
+
+function currentGit(root) {
+  const branch = git(root, ['symbolic-ref', '--short', '-q', 'HEAD']) ?? (git(root, ['rev-parse', '--short', 'HEAD']) ? 'detached HEAD' : null);
+  const status = git(root, ['status', '--short', '--untracked-files=normal']);
+  const commitDate = git(root, ['log', '-1', '--format=%cs']);
+  const changed = (status ?? '').split(/\r?\n/).filter(Boolean);
+  const safeChanged = changed.filter(line => !/(^|\s)(?:\.env(?:\.|\s|$)|\.dev\.vars(?:\s|$)|.*(?:secret|credential|private[_-]?key|id_rsa|id_ed25519|\.pem|\.key|\.netrc|\.npmrc|\.pypirc).*)/i.test(line));
+  return { branch, status, changed: safeChanged.slice(0, 8), count: changed.length, commitDate };
+}
+
+function relevantDocs(text, root) {
+  const topics = [
+    ['PRODUCT.md', /product|workflow|scope|user-facing|feature/i],
+    ['DESIGN.md', /ui|ux|design|layout|visual|accessibility/i],
+    ['ARCHITECTURE.md', /architecture|runtime|data flow|integration|database|storage|deploy/i],
+    ['SECURITY.md', /auth|security|permission|secret|tenant|trust|privacy/i],
+    ['ROADMAP.md', /roadmap|plan|milestone|later|defer/i],
+  ];
+  const matches = [];
+  for (const [name, pattern] of topics) {
+    if (!pattern.test(text)) continue;
+    for (const file of [path.join(root, name), path.join(root, 'docs', name)]) {
+      try {
+        if (fs.lstatSync(file).isFile() && !fs.lstatSync(file).isSymbolicLink()) { matches.push(path.relative(root, file)); break; }
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+  }
+  return [...new Set(matches)].slice(0, 3);
+}
+
+function printLines(label, lines, fallback) {
+  console.log(`${label}:`);
+  if (!lines.length) console.log(`  ${fallback}`);
+  else lines.forEach(line => console.log(`  ${line}`));
+}
+
+export function resumeProject(root) {
+  root = path.resolve(root);
+  const handoff = readHandoff(root);
+  const gitState = currentGit(root);
+  let status = handoff.state;
+  let reason = handoff.reason;
+  const recordedBranch = handoff.state === 'valid' ? handoff.text.match(/^(?:current\s+)?branch:\s*([^\s]+)/im)?.[1] : null;
+  if (recordedBranch && gitState.branch) {
+    if (recordedBranch !== gitState.branch) { status = 'possibly outdated'; reason = `recorded branch ${recordedBranch} differs from current branch`; }
+  }
+  const today = new Date();
+  const todayDate = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}`;
+  if (handoff.state === 'valid' && handoff.updated && handoff.updated > todayDate) {
+    status = 'possibly outdated';
+    reason = 'handoff date is in the future';
+  }
+  if (handoff.state === 'valid' && gitState.commitDate && handoff.updated && gitState.commitDate > handoff.updated) {
+    status = 'possibly outdated';
+    reason = `Git has a commit dated ${gitState.commitDate}, after the handoff date`;
+  }
+
+  console.log('Orbit Resume (read-only)');
+  console.log(`Project: ${scrub(path.basename(root))}`);
+  console.log(`Handoff: ${status}${reason ? ` — ${scrub(reason)}` : ''}`);
+  if (handoff.state === 'valid') {
+    const usable = status === 'valid';
+    printLines('Objective', usable ? handoff.fields.objective : [], usable ? 'Not recorded.' : 'Treat the handoff as a lead; current repository evidence takes precedence.');
+    printLines('Completed milestones', usable ? handoff.fields.completed : [], 'No verified milestones recorded.');
+    printLines('Unfinished work', usable ? handoff.fields.unfinished : [], 'No in-progress work recorded.');
+    printLines('Risks', usable ? handoff.fields.risks : [], 'No risks recorded.');
+    printLines('Verification', usable ? handoff.fields.verification : [], 'No verification recorded.');
+  } else {
+    printLines('Objective', [], 'Unknown; do not infer it from an absent or invalid handoff.');
+    printLines('Completed milestones', [], 'No reliable handoff evidence.');
+    printLines('Unfinished work', [], 'Check the current task and Git changes before proceeding.');
+    printLines('Risks', [], handoff.state === 'invalid' ? 'Handoff was not used because it is invalid.' : 'No handoff exists yet.');
+    printLines('Verification', [], 'No reliable handoff evidence.');
+  }
+
+  console.log('Git status:');
+  if (!gitState.branch && gitState.status === null) console.log('  Git repository unavailable.');
+  else {
+    console.log(`  Branch: ${scrub(gitState.branch ?? 'unknown')}`);
+    console.log(`  Working tree: ${gitState.count ? `dirty (${gitState.count} change${gitState.count === 1 ? '' : 's'})` : 'clean'}`);
+    gitState.changed.forEach(line => console.log(`  ${scrub(line)}`));
+    if (gitState.count > gitState.changed.length) console.log(`  ${gitState.count - gitState.changed.length} sensitive-looking path(s) omitted.`);
+  }
+
+  const trustedNext = handoff.state === 'valid' && status === 'valid' ? handoff.fields.next : [];
+  const docs = relevantDocs([...(trustedNext.length ? trustedNext : []), ...(handoff.state === 'valid' ? handoff.fields.objective : [])].join(' '), root);
+  printLines('Next steps', trustedNext, handoff.state === 'valid' && status === 'valid' ? 'No next step recorded; inspect current changes and choose one from repository evidence.' : 'Inspect current Git changes, then identify the next action from the user request and tracked project docs.');
+  printLines('Relevant living docs', docs, 'None identified from the handoff; load a living doc only if the next action needs it.');
+  console.log('Keep unfinished working changes. Do not reset or clean the repository. Current Git and tracked docs override stale handoff details.');
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "orbit-thread",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "Token-efficient project setup, checkpoints and coding-session continuity for Codex and Claude Code.",
+  "type": "module",
+  "bin": {
+    "orbit-thread": "bin/orbit-thread.mjs",
+    "orbit-handoff": "bin/orbit-thread.mjs"
+  },
+  "engines": { "node": ">=20" },
+  "os": ["darwin", "linux"],
+  "license": "MIT",
+  "author": "Shabih Anwar",
+  "repository": { "type": "git", "url": "git+https://github.com/shab1h-gh/orbit-thread.git" },
+  "homepage": "https://github.com/shab1h-gh/orbit-thread#readme",
+  "bugs": { "url": "https://github.com/shab1h-gh/orbit-thread/issues" },
+  "keywords": ["codex", "claude-code", "agent-skills", "continuity", "project-setup", "handoff", "resume", "context-efficiency"],
+  "files": ["bin/", "lib/", "plugin/", "docs/", "README.md", "LICENSE", "SECURITY.md", "PRIVACY.md", "CONTRIBUTING.md", "CHANGELOG.md"],
+  "scripts": {
+    "test": "node --test",
+    "validate": "node scripts/validate.mjs",
+    "build:plugin": "python3 scripts/package_plugin.py",
+    "scan:public": "node scripts/scan-public.mjs",
+    "smoke:pack": "node scripts/smoke-pack.mjs"
+  },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "orbit-thread",
+  "displayName": "Orbit Thread",
+  "version": "1.2.0",
+  "description": "Token-efficient project setup, checkpoints and coding-session continuity.",
+  "author": { "name": "Shabih Anwar", "url": "https://github.com/shab1h-gh" },
+  "homepage": "https://github.com/shab1h-gh/orbit-thread",
+  "repository": "https://github.com/shab1h-gh/orbit-thread",
+  "license": "MIT",
+  "icon": "./assets/icon.png",
+  "documentationUrl": "https://github.com/shab1h-gh/orbit-thread#readme",
+  "supportUrl": "https://github.com/shab1h-gh/orbit-thread/issues",
+  "privacyPolicyUrl": "https://github.com/shab1h-gh/orbit-thread/blob/main/PRIVACY.md",
+  "keywords": ["continuity", "handoff", "resume", "project-setup", "developer-tools"],
+  "skills": "./skills/"
+}

package/plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shabih Anwar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugin/README.md

@@ -0,0 +1,28 @@
+# Orbit Thread
+
+Orbit Thread provides three local coding skills:
+
+- **Orbit Setup** prepares a project with lightweight living docs, selective context rules and configurable subagent preferences.
+- **Handoff** overwrites a compact, evidence-only `HANDOFF-STATE.md` so a fresh coding session can resume from Git + current project truth rather than a large old conversation.
+- **Resume** reconstructs concise project context from the latest usable handoff, current Git state and task-relevant living docs.
+
+Standalone commands:
+
+- Codex: `$orbit-setup`, `$handoff` and `$orbit-resume`
+- Claude Code: `/orbit-setup`, `/handoff` and `/orbit-resume`
+
+Claude plugin commands:
+
+- `/orbit-thread:orbit-setup`
+- `/orbit-thread:handoff`
+- `/orbit-thread:orbit-resume`
+
+Setup creates only missing PRODUCT, DESIGN, ARCHITECTURE, SECURITY and ROADMAP templates, preserves existing equivalents, manages a concise Orbit Thread section in AGENTS.md/CLAUDE.md, and keeps local handoff/tool state Git-ignored.
+
+Start each coding task in a fresh chat and run Resume once at session start, automatically where supported or manually as a fallback. The project rules update living docs in place, load only relevant context, default to no subagents with a maximum of two, and request Handoff after meaningful verified milestones/completed coding tasks.
+
+Handoff is overwrite-only, capped at 50 lines, secret-checked before atomic replacement and makes no network calls or Git mutations. Resume and `npx orbit-thread resume` are read-only and preserve unfinished work.
+
+There is no MCP server, telemetry or external account.
+
+See the project README for installation, migration and update instructions.

package/plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "orbit-thread",
+  "version": "1.2.0",
+  "description": "Token-efficient project setup, checkpoints and coding-session continuity.",
+  "author": { "name": "Shabih Anwar", "url": "https://github.com/shab1h-gh" },
+  "homepage": "https://github.com/shab1h-gh/orbit-thread",
+  "repository": "https://github.com/shab1h-gh/orbit-thread",
+  "license": "MIT",
+  "keywords": ["handoff", "resume", "codex", "claude-code", "continuity", "project-setup", "developer-tools"],
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "Orbit Thread",
+        "shortDescription": "Lean coding continuity",
+        "longDescription": "Orbit Thread gives coding agents a small, durable continuity layer. Orbit Setup creates only missing PRODUCT, DESIGN, ARCHITECTURE, SECURITY and ROADMAP living docs, adds selective context-loading and bounded-subagent rules, and keeps local execution state separate from tracked project truth. Handoff overwrites a compact HANDOFF-STATE.md at verified checkpoints. Resume starts a fresh chat from the current handoff, read-only Git state and only the living docs needed for the task, reducing repeated context while preserving unfinished changes. Handoffs are capped at 50 lines, validated before atomic replacement, and the writer makes no network calls or Git mutations. Existing project docs and unrelated instructions are preserved.",
+        "developerName": "Shabih Anwar",
+        "category": "Developer Tools",
+        "capabilities": ["Prepare project continuity", "Save verified coding checkpoints", "Resume coding sessions"],
+        "websiteURL": "https://github.com/shab1h-gh/orbit-thread",
+        "supportURL": "https://github.com/shab1h-gh/orbit-thread/issues",
+        "privacyPolicyURL": "https://github.com/shab1h-gh/orbit-thread/blob/main/PRIVACY.md",
+        "defaultPrompt": ["Prepare this coding project for efficient continuity, resume a fresh coding session, or save verified current state at a meaningful checkpoint."],
+        "brandColor": "#4338CA",
+        "composerIcon": "./assets/icon.png",
+        "logo": "./assets/icon.png"
+      },
+      "onboardingSkill": "./skills/orbit-setup/SKILL.md",
+      "publication": {
+        "release_notes": "Orbit Thread v1.1 adds project setup, living docs, configurable subagent preferences, automatic meaningful checkpoints, fresh-context recovery and Orbit Handoff migration support."
+      }
+    }
+  }
+}

package/plugin/skills/handoff/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: handoff
+description: Use Orbit Thread to overwrite HANDOFF-STATE.md with a compact, secret-free checkpoint of verified coding state. Invoke when the user asks for a handoff, when Orbit Thread project instructions require a meaningful checkpoint, before a fresh/cleared session, or before finalising a completed coding task whose repository state or durable project truth changed.
+---
+
+# Orbit Thread Handoff
+
+Write concise current operational state for the next session, not a changelog or transcript.
+
+## Workflow
+
+1. Gather state once: `date '+%d-%m-%Y %H:%M'; git status --short --branch; git diff --stat HEAD; git log -1 --oneline`. If Git is unavailable, record that fact and use only current-session evidence. Reuse a handoff already read this session; otherwise read it once. Consult only files changed or discussed for the current work.
+2. Reconcile previous state with current evidence. Keep only facts still true and work still relevant. Drop resolved, superseded or duplicated history. Repository state and relevant tracked docs override stale handoff content.
+3. Pipe the new Markdown to this skill's `scripts/write_handoff.sh`, resolving the script relative to the loaded skill directory. In Claude Code, `${CLAUDE_SKILL_DIR}/scripts/write_handoff.sh` resolves that location; in Codex, use the loaded skill directory. Quote the path and run it with `sh`.
+4. The writer overwrites repo-root `HANDOFF-STATE.md` atomically, rejects empty/over-50-line/obviously secret-bearing content, and prints the line count. Do not re-read after a successful write.
+5. If this is an intermediate checkpoint and the current request still has unfinished work, continue. If the task is complete, return the normal final response.
+
+## Format
+
+```markdown
+# Handoff State
+
+Updated: DD-MM-YYYY HH:MM
+
+## Current objective
+## Completed milestones
+## In progress
+## Current state
+## Decisions
+## Open issues / risks
+## Immediate next steps
+## Verification
+```
+
+Omit empty sections. Aim for about 30 lines; hard cap 50. State each fact once. Immediate next steps must be genuinely outstanding.
+
+## Rules
+
+- Checkpoint after meaningful verified milestones and completed coding tasks when the configured project rules require it; skip read-only questions and trivial edits.
+- Use read-only Git inspection only. Never commit, stage, amend, push, reset or otherwise mutate Git.
+- Evidence only. Never claim a test, deployment, commit, push or external action happened without evidence.
+- Never include secrets, credentials, tokens, private keys, recovery codes, `.env`/`.dev.vars` values, personal data or sensitive production data.
+- Do not record the current HEAD SHA; it becomes stale easily. Exact SHAs are allowed only for immutable earlier revisions such as releases, deployments or rollback points.
+- When Git is available, record the current branch as `Branch: <name>` under `Current state` so a later Resume can detect a branch change. Never record the current HEAD SHA.
+- `HANDOFF-STATE.md` is local current state, intended to be Git-ignored. Never append history or make committing it a next step.
+- Durable product, design, architecture, security or roadmap truth belongs in tracked living docs. Handoff does not replace those files.
+- At an intermediate checkpoint, do not stop merely because the handoff was written.

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