orbit-thread 1.1.0 → 1.2.1

package/docs/PUBLISHING.md

@@ -1,8 +1,10 @@
 # npm publication and releases
 
-Orbit Thread v1.1.0 is the successor to Orbit Handoff v1.0.x.
+Orbit Thread v1.2.1 is a compatibility patch for Orbit Resume (v1.2.0 added Resume to the Orbit Thread line, which succeeded Orbit Handoff v1.0.x in v1.1.0).
 
-Historical `orbit-handoff@1.0.0` and `orbit-handoff@1.0.1` releases are immutable. Do not republish, unpublish or move their release tags.
+`orbit-thread@1.2.0` is already published. v1.2.1 is a new version.
+
+Historical `orbit-handoff@1.0.0`, `orbit-handoff@1.0.1`, `orbit-thread@1.1.0` and `orbit-thread@1.2.0` releases are immutable. Do not republish, unpublish or move their release tags.
 
 The new primary package is:
 
@@ -33,15 +35,18 @@ claude plugin validate . --strict
 Inspect:
 
 ```text
-orbit-thread-1.1.0.tgz
-dist/orbit-thread-plugin-1.1.0.zip
+orbit-thread-1.2.1.tgz
+dist/orbit-thread-plugin-1.2.1.zip
 ```
 
-Confirm both canonical skills are present:
+The npm tarball should contain 28 files (version 1.2.1, including `lib/resume.mjs` and `plugin/skills/orbit-resume/`). The plugin ZIP should contain the portable `plugin.json`, the three canonical skills and the listing icon. Neither should contain tests, `dist/`, credentials or other build residue.
+
+Confirm all three canonical skills are present:
 
 ```text
 plugin/skills/handoff/
 plugin/skills/orbit-setup/
+plugin/skills/orbit-resume/
 ```
 
 and that the packed CLI can install, setup, configure, doctor, update and uninstall in a disposable repository.
@@ -51,7 +56,7 @@ and that the packed CLI can install, setup, configure, doctor, update and uninst
 After release checks pass:
 
 ```sh
-npm publish ./orbit-thread-1.1.0.tgz --access public --registry https://registry.npmjs.org/
+npm publish ./orbit-thread-1.2.1.tgz --access public --registry https://registry.npmjs.org/
 ```
 
 Complete npm's normal browser/2FA challenge if prompted. Never weaken npm account security to automate publication.
@@ -73,7 +78,7 @@ npx orbit-thread@latest doctor --agent both --scope project
 npx orbit-thread@latest uninstall --agent both --scope project --yes
 ```
 
-Verify `latest` resolves to `1.1.0` and package metadata points to `shab1h-gh/orbit-thread`.
+Also confirm `npx orbit-thread@latest resume` runs read-only in the disposable repository. Verify `latest` resolves to `1.2.1` and package metadata points to `shab1h-gh/orbit-thread`.
 
 ## Existing Orbit Handoff users
 
@@ -85,7 +90,7 @@ npx orbit-thread@latest setup --agent both --yes
 npx orbit-thread doctor --agent both --scope project
 ```
 
-The v1.1 CLI accepts compatible Orbit Handoff ownership/project state and migrates it while refusing locally edited managed files.
+The v1.1 and later CLI accepts compatible Orbit Handoff ownership/project state and migrates it while refusing locally edited managed files.
 
 After Orbit Thread is publicly verified, the old package may be deprecated with a migration message, but must not be unpublished:
 

package/docs/SUBMISSION.md

@@ -1,15 +1,15 @@
 # Directory submission
 
-Updated 7 October 2026.
+Updated 12 October 2026.
 
 Provider-directory review is separate from npm, GitHub and standalone installation.
 
 ## OpenAI / ChatGPT Plugins Directory
 
-Orbit Thread v1.1.0 is submitted as:
+Orbit Thread v1.2.1 is submitted as:
 
 ```text
-dist/orbit-thread-plugin-1.1.0.zip
+dist/orbit-thread-plugin-1.2.1.zip
 ```
 
 Build it with:
@@ -18,14 +18,14 @@ Build it with:
 npm run build:plugin
 ```
 
-The ZIP contains portable `plugin.json`, both canonical skills, OpenAI interface metadata, the Orbit Setup onboarding skill, listing icon and compatibility metadata. Orbit Thread needs no MCP server or external account.
+The ZIP contains portable `plugin.json`, all three canonical skills, OpenAI interface metadata, the Orbit Setup onboarding skill, listing icon and compatibility metadata. Orbit Thread needs no MCP server or external account.
 
 ### Submission flow
 
-1. Complete release validation and build the final v1.1.0 ZIP from the release commit/tag.
+1. Complete release validation and build the final v1.2.1 ZIP from the release commit/tag.
 2. Open the OpenAI Plugins publisher dashboard:
    `https://platform.openai.com/plugins`
-3. Upload `orbit-thread-plugin-1.1.0.zip`.
+3. Upload `orbit-thread-plugin-1.2.1.zip`.
 4. Complete automated checks and resolve genuine findings.
 5. Review listing metadata and required policy/data-handling declarations.
 6. Choose **Submit for review**.
@@ -63,7 +63,7 @@ claude plugin validate ./plugin --strict
 claude plugin validate . --strict
 ```
 
-Then use the directory management/submission surface in Claude, connect the GitHub account that owns `shab1h-gh/orbit-thread`, select the repository/plugin, complete the listing details and submit it for review. Use the immutable v1.1.0 release/tag once created.
+Then use the directory management/submission surface in Claude, connect the GitHub account that owns `shab1h-gh/orbit-thread`, select the repository/plugin, complete the listing details and submit it for review. Use the immutable v1.2.1 release/tag once created.
 
 A successful GitHub marketplace installation does not mean the plugin is approved for Anthropic's public directory.
 

package/docs/VALIDATION.md

@@ -177,3 +177,75 @@ Those native CLIs are not part of GitHub CI, so CI success does not claim those
 
 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.
 
+## Orbit Resume v1.2.0 validation
+
+Release validation completed on 12 October 2026 on the `feature/orbit-resume` branch (PR #3) for v1.2.0. `orbit-thread@1.1.0` was confirmed published on the public npm registry before the version bump; v1.2.0 has not been tagged, published or merged.
+
+### Verified locally for the v1.2.0 release candidate
+
+- All 43 automated tests passed, including Codex and Claude project installation,
+  reinstall, update, Doctor, missing/invalid/stale handoffs, branch changes,
+  future dates, terminal-control sanitisation, secret redaction, and preservation
+  of dirty working trees.
+- `npm run validate`, `npm run scan:public`, `npm run build:plugin` and
+  `git diff --check` passed.
+- `claude plugin validate ./plugin --strict` and `claude plugin validate . --strict` passed.
+- `npm pack` produced `orbit-thread-1.2.0.tgz` (28 files, including `lib/resume.mjs` and
+  `plugin/skills/orbit-resume/`), and `npm run smoke:pack` passed against it in a disposable
+  Git project: `resume`, install, setup, configure, Doctor, update and uninstall.
+- `dist/orbit-thread-plugin-1.2.0.zip` contains 16 files: portable and Claude manifests,
+  all three skills, icon, licence, privacy and security documents. Both archives report
+  version 1.2.0 throughout, with no private paths or build residue.
+- Release metadata (`package.json`, `plugin/plugin.json`, `plugin/.claude-plugin/plugin.json`
+  and `.claude-plugin/marketplace.json`) is consistent at 1.2.0; `npm run validate` enforces this.
+
+### Compatibility with v1.1.0 installations
+
+Using the published `orbit-thread@1.1.0` from the npm registry, a disposable project was installed
+and set up with `handoff` and `orbit-setup` only, then updated with the packed 1.2.0 CLI.
+Update added `orbit-resume` for Codex and Claude, kept the existing `handoff` and `orbit-setup`
+skills, `.orbit-thread/config.json`, local edits to living docs and user content in `AGENTS.md`, and
+Doctor reported all three skills current at v1.2.0. A locally edited managed skill file was still
+refused with an instruction to preserve changes. The 1.2.0 `resume` command ran read-only,
+and uninstall preserved project docs and configuration.
+
+### Reported native agent testing (not CI)
+
+The maintainer reported successful authenticated native testing of the feature-branch skills in fresh
+Codex and Claude Code sessions, using a disposable Git project: Setup, Doctor, handoff
+validation and Resume recovery scenarios passed, and both automatic and explicit manual Resume
+invocation worked in each agent. This was an interactive local test recorded from the
+maintainer's report; it is not part of GitHub CI and was not re-run during release preparation.
+Codex emitted macOS temporary-cache warnings during Git reads but still reported branch,
+status and commit.
+
+### Verified in GitHub CI
+
+GitHub CI covers the macOS and Linux Node.js matrix, the test suite, package validation, the
+public-source scan, plugin ZIP generation, `npm pack` and the packed-tarball smoke test. CI does not run
+authenticated Codex or Claude sessions or `claude plugin validate`. The PR #3 CI run on the
+previous commit passed; CI for the release commit is checked on the pull request after push.
+
+### Security review
+
+A security review identified a low-risk terminal-control injection through branch metadata in a
+local handoff. Resume strips terminal control sequences from displayed repository and handoff text; a
+regression test confirms they do not reach terminal output.
+
+### Remaining release-gate checks
+
+- Merge PR #3, then tag v1.2.0 from the merged release commit.
+- Publish `orbit-thread@1.2.0` and repeat the public-registry smoke test described in
+  [PUBLISHING.md](PUBLISHING.md).
+
+## Orbit Resume v1.2.1 validation
+
+Compatibility patch (`fix/resume-completed-heading`): Resume now accepts `## Completed this session` as an alias of the canonical `## Completed milestones`. The canonical section takes precedence when both exist; the handoff format is unchanged. The v1.2.0 section above is a historical record and is unchanged.
+
+### Verified locally
+
+Results are recorded in the release PR and final report; the checks run were `npm test` (including regression tests for both headings, precedence, missing sections and redaction under the legacy heading), `npm run validate`, `npm run scan:public`, `npm run build:plugin`, `npm pack`, `npm run smoke:pack`, `claude plugin validate ./plugin --strict`, `claude plugin validate . --strict` and `git diff --check`.
+
+### Compatibility with v1.2.0 installations
+
+A project installed with the published `orbit-thread@1.2.0` is updated in place by the 1.2.1 CLI; installed skills, `.orbit-thread/config.json`, living docs and existing handoffs are preserved.

package/lib/cli.mjs

@@ -6,6 +6,7 @@ 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'));
@@ -13,7 +14,7 @@ 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 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; } };
 
@@ -143,6 +144,7 @@ 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.
@@ -204,7 +206,7 @@ export async function main(argv) {
 
   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}`);
+  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';
@@ -215,6 +217,12 @@ export async function main(argv) {
   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) {

package/lib/resume.mjs

@@ -0,0 +1,164 @@
+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: firstSection(text, ['Completed milestones', 'Completed this session']),
+        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\\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));
+}
+
+// Canonical heading first; legacy alias only used when the canonical section is absent or empty.
+function firstSection(text, titles) {
+  for (const title of titles) {
+    const lines = section(text, title);
+    if (lines.length) return lines;
+  }
+  return [];
+}
+
+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,6 @@
 {
   "name": "orbit-thread",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Token-efficient project setup, checkpoints and coding-session continuity for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   "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"],
+  "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",

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

@@ -1,7 +1,7 @@
 {
   "name": "orbit-thread",
   "displayName": "Orbit Thread",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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",
@@ -11,6 +11,6 @@
   "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"],
+  "keywords": ["continuity", "handoff", "resume", "project-setup", "developer-tools"],
   "skills": "./skills/"
 }

package/plugin/README.md

@@ -1,25 +1,27 @@
 # Orbit Thread
 
-Orbit Thread provides two local coding skills:
+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` and `$handoff`
-- Claude Code: `/orbit-setup` and `/handoff`
+- 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.
 
-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.
+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.
+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.
 

package/plugin/plugin.json

@@ -1,26 +1,26 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "orbit-thread",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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"],
+  "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 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.",
+        "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"],
+        "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, or save verified current state at a meaningful checkpoint."],
+        "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"

package/plugin/skills/handoff/SKILL.md

@@ -41,6 +41,7 @@ Omit empty sections. Aim for about 30 lines; hard cap 50. State each fact once.
 - 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/orbit-resume/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: orbit-resume
+description: Recover essential project context at the start of a fresh Codex or Claude Code conversation from the latest usable handoff, current Git state and only the living docs needed for the current task. Use once per new coding session, or when the user explicitly asks to resume project work.
+---
+
+# Orbit Thread Resume
+
+Recover the current project state once at the beginning of a fresh coding conversation. Keep the context small and preserve unfinished changes.
+
+## Workflow
+
+1. If the user already supplied output from `npx orbit-thread resume` in this conversation, use it. Otherwise inspect `HANDOFF-STATE.md` once if it exists, then run read-only `git status --short --branch`, `git diff --stat HEAD`, and `git log -1 --oneline` from the project root. Do not invoke npm, install tools, or search the repository broadly.
+2. Treat the handoff as a lead. Current Git state and tracked project docs override stale or conflicting handoff details. A missing or malformed handoff is not a reason to invent the objective or completed work; use the user's current request and state what remains unknown.
+3. Preserve all dirty and untracked work. Never reset, clean, stash, stage, commit, checkout, deploy, or otherwise change repository state.
+4. Read only the living doc that directly informs the current requested task: PRODUCT for scope or behaviour, DESIGN for UI, ARCHITECTURE for runtime/data flow, SECURITY for trust/auth/secrets, ROADMAP for planning. Use its existing root or `docs/` location. Do not load unrelated docs or repeat facts already clear from the handoff.
+5. Give the user a compact summary of the objective, verified milestones, unfinished work, risks, verification, Git state, and immediate next action. Separate facts from unknowns. End with one clear next action grounded in the current request and repository evidence.
+
+Run this skill once per fresh conversation. Do not repeat it during the same session unless the user asks for a fresh recovery. If the host cannot invoke it automatically, the reliable fallback is `$orbit-resume` in Codex, `/orbit-resume` in Claude Code, or `/orbit-thread:orbit-resume` from the Claude marketplace plugin.
+
+## Safety
+
+- Read only the handoff, Git summaries, and task-relevant living docs. Never read `.env`, `.dev.vars`, credentials, private keys, or unrelated files.
+- Do not echo secret-looking values or sensitive local file paths. Keep the user's unfinished work intact.
+- The `npx orbit-thread resume` CLI command is read-only and can be run by the developer for a concise terminal summary. Do not run `npx` from this skill because it can download packages when the CLI is unavailable.
+- Do not claim a check, test, deployment, commit, or external action unless current evidence confirms it.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Orbit Thread Resume"
+  short_description: "Recover concise project context"
+  default_prompt: "Use $orbit-resume once to recover the verified project state and next action for this fresh coding session."
+policy:
+  allow_implicit_invocation: true

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

@@ -28,8 +28,9 @@ const agentsBlock = config => `${begin}
 - Inspect only source files needed for the task. Do not broadly scan generated, vendor, dependency, build, coverage or cache directories, and do not reread unchanged context without a reason.
 - Living docs describe CURRENT truth. After verified work changes that truth, update affected existing sections in place during the same milestone. Never append session diaries or duplicate superseded sections; Git is history. Never rewrite an applied migration.
 - Run the smallest relevant verification before claiming a milestone or task complete. Never claim a test, deployment, commit, push or external action that did not run.
+- Start each new coding task in a fresh chat and invoke \`$orbit-resume\` once at session start. Do this automatically where the host supports it; otherwise the reliable fallback is to invoke it manually. Do not repeat Resume in the same session unless the user asks for a fresh recovery.
 - Run the installed \`handoff\` skill after a meaningful verified milestone that changed repository state or durable project truth, and after each completed coding task with such changes before the final reply. Also checkpoint before \`/clear\`, session end, or a usage/context stop when warning is available. Skip read-only questions and trivial edits. Intermediate checkpoints must not stop unfinished work.
-- Each checkpoint overwrites \`HANDOFF-STATE.md\`. After a fresh/cleared/recovered session: read the handoff once if present, inspect branch/status/diff/recent log, read only relevant living docs, then inspect only source needed for the exact next action. Do not reconstruct old conversation history or repeat completed work.
+- Each checkpoint overwrites \`HANDOFF-STATE.md\`. Resume reads the handoff once if present, checks current Git state, then reads only task-relevant living docs and source. Do not reconstruct old conversation history or repeat completed work.
 ${renderSubagentBlock(config)}
 - Read-only Git inspection is allowed. Commit, push, merge, rebase, reset, branch deletion or other Git writes require explicit authority in the current request. Never force-push or destructively clean without explicit authority.
 - Never place secrets, credentials, environment values, private keys, recovery codes, personal data or sensitive production data in living docs or \`HANDOFF-STATE.md\`.
@@ -39,7 +40,7 @@ ${end}
 const claudeBlock = `${begin}
 ## Orbit Thread
 
-Read and follow \`AGENTS.md\` for project workflow, selective context loading, subagents and checkpoints. On a fresh or recovered session, resume from \`HANDOFF-STATE.md\` + current Git state + only the relevant living docs instead of reconstructing old conversation history.
+Read and follow \`AGENTS.md\` for project workflow, selective context loading, subagents and checkpoints. Start each new coding task in a fresh chat and invoke \`/orbit-resume\` once at session start, automatically where supported. If automatic invocation is unavailable, manually run \`/orbit-resume\` (or \`/orbit-thread:orbit-resume\` from the marketplace plugin). Do not repeat Resume in the same session unless the user asks for a fresh recovery.
 ${end}
 `;
 const templates = {