orbit-thread 0.0.0-stage → 1.1.0

package/docs/VALIDATION.md

@@ -0,0 +1,179 @@
+# Release validation record
+
+Checks performed on 5 October 2026, using disposable Git repositories.
+
+## Original v1.0.0 checks
+
+### Automated tests
+
+All 26 tests passed locally on macOS with Node.js 24. Tests cover first creation,
+overwrite, exactly 50 lines, 51-line rejection, final lines with and without a
+newline, empty and synthetic secret/private-key rejection, preservation of the
+old file, paths with spaces, cleanup after validation and rename failures, and
+unchanged Git index/refs with network-command guards.
+
+CLI tests cover Codex, Claude and both-agent project installs, identical copies,
+reinstall, check, update across package versions, uninstall, user-scope locations
+in a disposable home, init idempotency and block upgrades, ignore rules, existing
+instructions, edited files/blocks, unrelated files/directories, symlinks and
+invalid ownership paths. No live user installation is altered by these tests.
+
+CI ran the suite, local package validation, source scan, ZIP build and npm pack
+on macOS/Linux with Node.js 20 and 24. All four jobs passed in the
+[initial public CI run](https://github.com/shab1h-gh/orbit-handoff/actions/runs/37254076291).
+
+### Native discovery and packaging
+
+- Codex CLI 0.160.0 returned the installed `handoff` from its native `skills/list`
+  API, with display name Orbit Handoff and a `$handoff` default prompt.
+- Claude Code 2.1.289 passed `claude plugin validate ./plugin --strict` and
+  `claude plugin validate . --strict`.
+- A local marketplace install succeeded. `claude plugin details orbit-handoff`
+  reported one `handoff` skill, zero agents/hooks/MCP/LSP servers.
+- A second isolated configuration installed `orbit-handoff@orbit-handoff` from
+  `shab1h-gh/orbit-handoff` on GitHub and reported version 1.0.0 enabled.
+- Claude startup's `slash_commands` and `skills` arrays contained
+  `orbit-handoff:handoff`; its plugin metadata reported version 1.0.0.
+- A standalone Claude project install registered and loaded `handoff`, confirming
+  the `/handoff` command independently of the plugin namespace.
+- The attempted Claude model run ended with **Not logged in**. Registration and
+  installation are verified; an authenticated agent-driven handoff is untested.
+- The portable manifest passed the official Agent Plugins 1.0.0 JSON Schema
+  using Ajv's draft-2020 validator. Local checks cover OpenAI listing limits,
+  real PNG assets, skill metadata and the absence of MCP/hooks.
+- `npm pack` was inspected and the packed CLI installed both agents through
+  `npx --package` in a clean disposable project.
+- The interactive installer was exercised in a terminal: agent selection,
+  project scope selection, destination preview and confirmation all completed.
+- Public-source scans passed. Archives are inspected separately for unwanted
+  paths, credentials, test output and build residue before release.
+
+## Publication limits
+
+`orbit-handoff@1.0.0` was successfully published manually. Public registry
+verification on 5 October 2026 confirmed version 1.0.0, `latest` resolving to
+1.0.0 before the patch release, and repository/homepage/issue metadata pointing
+to `shab1h-gh/orbit-handoff`. The previous failed publication attempt is stale
+history; the registry package is available.
+
+Neither OpenAI nor Anthropic public directory submission has been made.
+Provider review, identity verification and portal checks remain publisher steps.
+Native Windows, WSL-specific operation and ordinary ChatGPT execution are
+unverified; the supported runtime is macOS/Linux with a POSIX shell.
+
+## v1.0.1 patch verification
+
+The patch changes documentation and release version metadata only. No installer,
+canonical skill, writer, tests or packaging logic changed.
+
+### Public v1.0.0 smoke test
+
+Downloaded the actual public package with an isolated npm cache and ran
+`npx orbit-handoff@1.0.0 install --agent both --scope project --yes` in a disposable
+Git repository on macOS with Node.js 24.16.0 and npm 12.0.2. Verified:
+
+- Codex and Claude installs contain byte-identical skill files and ownership metadata.
+- The npm CLI has executable permissions. Installed writers are mode 0644 and
+  execute through `sh`, matching the canonical skill's invocation contract.
+- `check` succeeds after install; `init` preserves existing AGENTS.md, CLAUDE.md
+  and .gitignore content, records ownership and ignores HANDOFF-STATE.md.
+- Reinstall and repeated init preserve bytes and add no duplicate blocks.
+- Init creates no handoff. The writer creates and atomically replaces the file
+  with restrictive permissions; empty and 51-line inputs preserve the valid file.
+- No writer temporary files remain. Uninstall restores original configuration,
+  removes unchanged owned skills, and preserves unrelated files and the handoff.
+- Edited skills and continuity blocks survive uninstall; check and reinstall
+  report edited files with failure status rather than overwriting them.
+
+This smoke test exercises the CLI and shell workflow. It does not claim a new
+native agent discovery test or an authenticated agent-driven handoff.
+
+### Local checks and packed v1.0.1 smoke test
+
+- All 26 existing tests passed on macOS with Node.js 24.16.0.
+- `npm run validate`, `npm run scan:public` and `npm run build:plugin` passed.
+- Claude Code 2.1.289 passed both `claude plugin validate ./plugin --strict` and
+  `claude plugin validate . --strict` for the updated manifests.
+- The portable manifest passed the official Agent Plugins 1.0.0 JSON Schema
+  with Ajv's draft-2020 validator and format checks.
+- `npm pack --dry-run` and `npm pack` succeeded using a disposable cache.
+  The tarball contains 20 intended files, an executable CLI, version 1.0.1 and
+  the corrected README. No dependencies, credentials or build residue are included.
+- The submission ZIP passed its integrity check and both extracted archives
+  passed the public/privacy scanner. No private paths or unwanted files were found.
+- The packed 1.0.1 CLI passed the same disposable-repository install, check,
+  init, reinstall, handoff and uninstall smoke test described above, including
+  edited-content preservation and executable permissions.
+- Complete diff review confirmed that runtime code and canonical skill bytes
+  are unchanged. The v1.0.0 tag and release remain untouched.
+
+These are pre-publication checks. After publication, verify `latest` resolves to
+1.0.1 and repeat the public-registry smoke test; report its result in the GitHub
+release. The original CI result above covers v1.0.0; it is not a new 1.0.1 CI claim.
+
+
+## v1.1.0 feature validation
+
+Validation completed on 7 October 2026 for the Orbit Thread feature release.
+
+### Verified in GitHub CI
+
+The final feature-branch workflow passed on macOS and Linux with Node.js 20 and 24.
+
+The workflow verified:
+
+- the complete Node test suite;
+- package/manifest validation;
+- public/privacy source scanning;
+- deterministic OpenAI/plugin ZIP generation;
+- `npm pack`;
+- a packed-tarball smoke test in a disposable Git repository.
+
+The packed smoke test exercised the actual `orbit-thread-1.1.0.tgz` through:
+
+- install for Codex and Claude;
+- setup;
+- Claude and Codex subagent configuration;
+- doctor;
+- update;
+- uninstall;
+- preservation of living project docs/config after uninstall.
+
+It also verified both canonical skills, the expected living-document templates, `.orbit-thread/config.json`, and that setup does not create `HANDOFF-STATE.md`.
+
+### Behaviour verified by tests
+
+Coverage includes:
+
+- Orbit Setup creation/idempotency and preservation of existing project docs/instructions;
+- selective project state and Git-ignore management;
+- Orbit Handoff → Orbit Thread project-state migration;
+- managed skill ownership/update/uninstall safeguards;
+- subagent model/reasoning configuration and AGENTS.md reflection;
+- doctor detection of duplicate root/docs living documents;
+- Handoff atomic overwrite, 50-line limit, secret-pattern rejection, failure preservation and no Git/network mutation.
+
+### Invocation policy
+
+The canonical Handoff skill intentionally omits Claude's former
+`disable-model-invocation: true` restriction and keeps OpenAI metadata
+`allow_implicit_invocation: true`.
+
+Configured Orbit Thread projects therefore permit proactive checkpoints after meaningful verified milestones and completed coding tasks, while manual `$handoff` / `/handoff` invocation remains supported.
+
+Orbit Setup remains separately exposed as `$orbit-setup` / `/orbit-setup`.
+
+### Remaining release-gate checks
+
+Before publishing/tagging v1.1.0:
+
+- validate the final plugin with a current Claude Code installation using `claude plugin validate`;
+- verify native Claude and Codex skill discovery against the final package where those CLIs are available;
+- publish `orbit-thread@1.1.0` and repeat the public-registry smoke test.
+
+Those native CLIs are not part of GitHub CI, so CI success does not claim those checks.
+
+### Provider directories
+
+OpenAI and Anthropic public-directory review is separate from npm/GitHub distribution. Their publisher dashboards are authoritative after submission; local validation does not imply approval.
+

package/lib/cli.mjs

@@ -0,0 +1,296 @@
+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';
+
+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'];
+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.
+  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', '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 === '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/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.1.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", "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.1.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", "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,26 @@
+# Orbit Thread
+
+Orbit Thread provides two 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.
+
+Standalone commands:
+
+- Codex: `$orbit-setup` and `$handoff`
+- Claude Code: `/orbit-setup` and `/handoff`
+
+Claude plugin commands:
+
+- `/orbit-thread:orbit-setup`
+- `/orbit-thread:handoff`
+
+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.
+
+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.
+
+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.1.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", "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 then overwrites a compact HANDOFF-STATE.md at meaningful verified checkpoints and completed coding tasks so a fresh session can resume from Git, current docs and the exact next action instead of carrying a large chat history. 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"],
+        "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, 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,46 @@
+---
+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.
+- `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.