orbit-thread 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 1.1.0 — 7 October 2026
+
+- Rename the product from **Orbit Handoff** to **Orbit Thread**.
+- Publish the feature release under the new npm package name `orbit-thread`; keep historical `orbit-handoff` releases immutable.
+- Add `orbit-setup` for Codex and Claude Code.
+- Add `npx orbit-thread setup`; keep `init` as an alias.
+- Create only missing lightweight PRODUCT, DESIGN, ARCHITECTURE, SECURITY and ROADMAP living docs while preserving existing equivalents.
+- Add selective context-loading, in-place living-doc updates, fresh-context recovery and bounded-subagent rules.
+- Add `configure` for project-specific subagent model/reasoning preferences stored in `.orbit-thread/config.json`.
+- Add `doctor` for full continuity/config/document-health checks; keep `check` as the lightweight legacy managed-skill installation check.
+- Allow Handoff to be invoked implicitly at meaningful verified checkpoints and completed coding tasks.
+- Keep `HANDOFF-STATE.md` overwrite-only, evidence-only and capped at 50 lines.
+- Migrate compatible Orbit Handoff project state to Orbit Thread while preserving locally edited managed files.
+- Reduce CI noise by running feature work on pull requests, main on push, and package/release checks once after the cross-platform test matrix.
+
+## 1.0.1 — 5 October 2026
+
+- Confirm successful public npm publication and make `npx orbit-handoff install` the primary installation route.
+- Remove stale pre-publication claims and record public package smoke testing.
+- Update release and submission artifact references; directory submissions remain pending.
+- Keep the installer, canonical skill and handoff writer unchanged.
+
+## 1.0.0 — 5 October 2026
+
+- Publish the proven handoff workflow as Orbit Handoff for Codex and Claude Code.
+- Add interactive installation and ownership-aware init, check, update and uninstall.
+- Package one canonical skill for Claude marketplaces and portable Agent Plugins.
+- Preserve validated atomic handoffs, the 50-line limit and the local-only runtime.
+- Add macOS and Linux tests, release packaging and directory submission guidance.

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for helping improve Orbit Thread. Open an issue for a bug/focused proposal, or send a pull request with a clear explanation and relevant tests. Use synthetic repositories and credentials in reproductions.
+
+Requirements: Node.js 20+, Python 3 for packaging, Git and a POSIX shell. The project has no npm runtime dependencies.
+
+```sh
+npm test
+npm run validate
+npm run scan:public
+npm run build:plugin
+npm pack
+npm run smoke:pack
+```
+
+Keep canonical skills under:
+
+```text
+plugin/skills/handoff/
+plugin/skills/orbit-setup/
+```
+
+Do not create divergent Codex and Claude implementations.
+
+Handoff changes must preserve the 50-line cap, overwrite-only current state, validation before atomic replacement, secret backstop, failed-write preservation, no temporary residue, no network calls and no Git mutation.
+
+Setup/configuration changes must preserve existing project docs and unrelated instructions, avoid duplicate root/docs files, stay idempotent, keep living docs as current truth rather than changelogs, and keep user-configured subagent preferences inside the managed Orbit Thread block.
+
+Installer/update tests must cover migration from compatible Orbit Handoff installations, edited-file preservation and user-owned content.
+
+Packaging changes should also be validated with current Claude Code:
+
+```sh
+claude plugin validate ./plugin --strict
+claude plugin validate . --strict
+```
+
+Public-directory validation is separate from provider approval.
+
+Use British English in documentation.

package/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/PRIVACY.md

@@ -0,0 +1,9 @@
+# Privacy
+
+Orbit Thread has no telemetry, remote service, external account or MCP server.
+
+The Handoff writer processes input locally and saves `HANDOFF-STATE.md`. Orbit Setup writes local/project documentation, managed agent instructions, a small project configuration file and local ownership state. The CLI records hashes and the exact managed instruction blocks it adds.
+
+Installation through npm or a plugin marketplace uses the relevant registry or Git host. Your coding agent's model calls and privacy settings remain governed by its provider. Orbit Thread's local writer and setup/configuration scripts do not send repository content anywhere.
+
+Keep secrets, credentials, personal data and sensitive production data out of handoffs and living docs. Pattern checks are limited and are not a data-loss-prevention system. `HANDOFF-STATE.md` and Orbit Thread's local ownership state are Git-ignored by setup; ignoring a previously tracked file does not untrack it.

package/README.md

@@ -1,3 +1,320 @@
-# Temporary Holding Version
+# Orbit Thread
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Keep coding agents aligned across long projects without carrying a huge conversation forever.**
+
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/shab1h-gh/orbit-thread/actions/workflows/ci.yml/badge.svg)](https://github.com/shab1h-gh/orbit-thread/actions/workflows/ci.yml)
+
+Orbit Thread is a small local continuity layer for Codex and Claude Code. It has two reusable skills:
+
+- **Orbit Setup** prepares a project with lightweight living documentation and token-efficient agent rules.
+- **Handoff** keeps one short `HANDOFF-STATE.md` current so a fresh session can resume from verified state instead of replaying a large chat history.
+
+Tracked source, Git history and living project docs remain authoritative. The handoff is current execution state, not a changelog.
+
+## Quick start
+
+From the project you want to configure:
+
+```sh
+npx orbit-thread install
+npx orbit-thread setup
+```
+
+Choose Codex, Claude Code or both when prompted.
+
+Non-interactive:
+
+```sh
+npx orbit-thread install --agent both --scope project --yes
+npx orbit-thread setup --agent both --yes
+```
+
+Then use the skills directly:
+
+| Agent | Setup | Handoff |
+| --- | --- | --- |
+| Codex standalone | `$orbit-setup` | `$handoff` |
+| Claude Code standalone | `/orbit-setup` | `/handoff` |
+| Claude plugin | `/orbit-thread:orbit-setup` | `/orbit-thread:handoff` |
+
+## What Orbit Setup creates
+
+Orbit Setup is designed to run before the first substantial coding prompt, or later to upgrade an existing project.
+
+If equivalent files do not already exist, it creates:
+
+```text
+project/
+├── AGENTS.md
+├── CLAUDE.md                 # when Claude is selected
+├── .orbit-thread/
+│   └── config.json           # tracked project preferences
+└── docs/
+    ├── PRODUCT.md
+    ├── DESIGN.md
+    ├── ARCHITECTURE.md
+    ├── SECURITY.md
+    └── ROADMAP.md
+```
+
+At the first meaningful checkpoint, Handoff creates:
+
+```text
+HANDOFF-STATE.md              # local, Git-ignored, overwrite-only
+```
+
+Orbit Thread also keeps its small internal ownership state local and Git-ignored.
+
+Existing product/design/architecture/security/roadmap files at either the repository root or under `docs/` are preserved instead of duplicated.
+
+### Living-doc rules
+
+The generated project instructions tell the agent to:
+
+- load only the docs relevant to the current task;
+- inspect only the source files it actually needs;
+- keep `PRODUCT.md`, `DESIGN.md`, `ARCHITECTURE.md`, `SECURITY.md` and `ROADMAP.md` as current truth;
+- update affected sections **in place** after verified changes;
+- never append session diaries or duplicate superseded sections;
+- keep Git as history;
+- never rewrite an applied migration;
+- run the smallest relevant verification before claiming completion.
+
+The document-routing rules are deliberately selective:
+
+- product behaviour, copy or scope → `PRODUCT.md`
+- UI/UX → `DESIGN.md`
+- runtime, data flow, infrastructure or integrations → `ARCHITECTURE.md`
+- auth, tenancy, secrets or other security-sensitive work → `SECURITY.md`
+- future planning only → `ROADMAP.md`
+
+This keeps routine tasks from loading every project document into context.
+
+## Checkpoints and fresh-context recovery
+
+Orbit Thread asks the coding agent to run Handoff:
+
+- after a meaningful verified milestone that changed repository state or durable project truth;
+- after a completed coding task with such changes, before the final reply;
+- before `/clear`, session end, or a usage/context stop when the agent receives warning.
+
+It intentionally skips read-only questions and trivial edits.
+
+Each successful checkpoint **overwrites** the previous `HANDOFF-STATE.md`. It does not grow into a development diary.
+
+After a fresh, cleared or recovered session, the generated project rules tell the agent to recover in this order:
+
+1. read `HANDOFF-STATE.md` once if present;
+2. inspect current branch/status/diff/recent Git log;
+3. load only relevant living docs;
+4. inspect only source needed for the recorded next action;
+5. preserve valid uncommitted work and continue from the highest verified milestone.
+
+## Handoff format
+
+A handoff is normally about 30 lines and has a hard cap of 50:
+
+```markdown
+# Handoff State
+
+Updated: 07-10-2026 00:30
+
+## Current objective
+- Finish account-security settings.
+
+## Completed milestones
+- Added the settings route.
+- Connected password change and session revocation.
+
+## In progress
+- Passkey-management UI.
+
+## Open issues / risks
+- Passkey removal still needs a browser test.
+
+## Immediate next steps
+1. Finish passkey management.
+2. Run the authentication suite.
+
+## Verification
+- Typecheck passed.
+- Unit tests passed: 42/42.
+```
+
+The writer validates before replacing the previous handoff, rejects obvious secret-like content, writes atomically, makes no network calls and does not mutate Git.
+
+## Subagent configuration
+
+Orbit Thread defaults to **no subagents unless they genuinely help**, with a maximum of two and no recursive subagents.
+
+You can save project-specific model/reasoning preferences without hand-editing `AGENTS.md`:
+
+```sh
+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
+```
+
+Change the maximum:
+
+```sh
+npx orbit-thread configure --max-subagents 1
+```
+
+Disable subagents:
+
+```sh
+npx orbit-thread configure --max-subagents 0
+```
+
+Show configuration:
+
+```sh
+npx orbit-thread configure --show
+```
+
+Reset saved subagent preferences:
+
+```sh
+npx orbit-thread configure --agent claude --reset-subagents
+```
+
+Preferences are stored in `.orbit-thread/config.json` and reflected in Orbit Thread's managed section of `AGENTS.md`. They are preferences rather than hard dependencies: an unavailable exact model setting should not block useful work.
+
+## Project doctor
+
+Run:
+
+```sh
+npx orbit-thread doctor
+```
+
+It checks the managed skill installation and project continuity setup, including living docs, config, managed agent blocks, Git-ignore rules, duplicate root/docs files and handoff size.
+
+`npx orbit-thread check` remains the lightweight managed-skill installation check kept for Orbit Handoff compatibility; use `doctor` for the full project health check.
+
+## Installation
+
+Requirements:
+
+- Node.js 20+
+- Git for normal repository workflows
+- a POSIX shell and standard Unix utilities for the handoff writer
+
+macOS and Linux are supported. Native Windows is not currently supported; WSL is the expected route.
+
+### npm / standalone Codex and Claude Code
+
+```sh
+npx orbit-thread install
+```
+
+Project installs use:
+
+| Agent | Project location |
+| --- | --- |
+| Codex | `.agents/skills/handoff/` and `.agents/skills/orbit-setup/` |
+| Claude Code | `.claude/skills/handoff/` and `.claude/skills/orbit-setup/` |
+
+User/global installs use the equivalent `~/.agents/skills/` or `~/.claude/skills/` locations.
+
+### Claude GitHub marketplace
+
+Inside Claude Code:
+
+```text
+/plugin marketplace add shab1h-gh/orbit-thread
+/plugin install orbit-thread@orbit-thread
+```
+
+Equivalent shell commands:
+
+```sh
+claude plugin marketplace add shab1h-gh/orbit-thread
+claude plugin install orbit-thread@orbit-thread
+```
+
+The GitHub marketplace route is separate from Anthropic's official public directory.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `npx orbit-thread install` | Install both skills for selected agent(s). |
+| `npx orbit-thread setup` | Prepare/upgrade the current project workflow and living docs. |
+| `npx orbit-thread configure` | Configure project subagent preferences. |
+| `npx orbit-thread doctor` | Check installation and project continuity health. |
+| `npx orbit-thread@latest update` | Upgrade unchanged managed skill files. |
+| `npx orbit-thread uninstall` | Remove managed skills/instruction blocks while preserving project-owned docs/config/state. |
+| `npx orbit-thread init` | Backwards-compatible alias for `setup`. |
+| `npx orbit-thread check` | Check managed skill installation (kept for Orbit Handoff compatibility). |
+
+Common options:
+
+```text
+--agent codex|claude|both
+--scope project|user
+--yes
+```
+
+## Migrating from Orbit Handoff 1.0.x
+
+Orbit Thread is the successor to **Orbit Handoff**.
+
+Existing npm-managed users should install/update through the new package name:
+
+```sh
+npx orbit-thread@latest update --agent both --scope project --yes
+npx orbit-thread@latest setup --agent both --yes
+npx orbit-thread doctor --agent both --scope project
+```
+
+The v1.1 CLI recognises the managed Orbit Handoff installation/state and migrates it without intentionally overwriting local edits. The old `orbit-handoff` binary name remains an alias inside the Orbit Thread package for compatibility.
+
+The historical `orbit-handoff` npm releases remain immutable.
+
+For Claude GitHub-marketplace users, update/reinstall from the renamed repository and run:
+
+```text
+/orbit-thread:orbit-setup
+```
+
+## Updating Orbit Thread
+
+```sh
+npx orbit-thread@latest update --agent both --scope project --yes
+npx orbit-thread@latest setup --agent both --yes
+```
+
+The first command updates unchanged managed skill files. The second updates the project-managed rules and creates only missing living docs.
+
+Locally edited managed skill files are never force-overwritten.
+
+## Security and privacy
+
+Orbit Thread is local-first.
+
+The handoff writer makes no network calls and does not mutate Git. Secret detection is a backstop, not a data-loss-prevention system, so never place credentials, personal data or sensitive production information in handoffs or project docs.
+
+The installer refuses unmanaged skill collisions and protects locally modified managed files. Setup preserves unrelated instructions and existing project docs.
+
+There is no Orbit Thread telemetry. npm, GitHub, Claude and OpenAI still operate under their own service/privacy policies.
+
+See [SECURITY.md](SECURITY.md) and [PRIVACY.md](PRIVACY.md).
+
+## Provider directories
+
+The repository includes a portable skills-only plugin ZIP suitable for OpenAI's plugin upload flow and a Claude plugin manifest suitable for Anthropic/GitHub distribution.
+
+Public OpenAI and Anthropic directory approval is separate from npm/GitHub installation. See [docs/SUBMISSION.md](docs/SUBMISSION.md).
+
+## Contributing
+
+Issues and focused pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Licence
+
+[MIT](LICENSE) — Shabih Anwar.

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security
+
+Orbit Thread keeps handoff and project-continuity state local.
+
+The Handoff writer makes no network requests and does not mutate Git. It validates a temporary file before replacing the previous handoff with a same-directory atomic rename. Failed validation leaves the previous file intact and removes temporary residue. New handoffs inherit `mktemp`'s restrictive permissions.
+
+The secret check is a backstop for recognisable credential/private-key patterns, not a complete DLP system. Rejection messages include line numbers rather than matched content.
+
+The npm CLI copies the same canonical skills to supported agents. It records file hashes, refuses unmanaged skill collisions or locally edited managed installations, preserves edited files during uninstall and rejects symlinked destinations. Setup uses ownership-tracked instruction blocks, preserves unrelated instructions and existing living docs, and writes project subagent preferences only into Orbit Thread's managed AGENTS.md block.
+
+There are no runtime npm dependencies or postinstall hooks.
+
+`npx` and plugin installation may access their registries or GitHub. Your coding agent uses its own provider and permissions; Orbit Thread does not expand those permissions or sandbox the host agent.
+
+Please report vulnerabilities privately through the repository security advisory form after the repository rename:
+`https://github.com/shab1h-gh/orbit-thread/security/advisories/new`
+
+Use synthetic data in reports. Never put live secrets or private project state in public issues.

package/bin/orbit-handoff.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../lib/cli.mjs';
+try {
+  await main(process.argv.slice(2));
+} catch (error) {
+  console.error(`Orbit Thread: ${error.message}`);
+  process.exitCode = 1;
+}

package/bin/orbit-thread.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../lib/cli.mjs';
+try {
+  await main(process.argv.slice(2));
+} catch (error) {
+  console.error(`Orbit Thread: ${error.message}`);
+  process.exitCode = 1;
+}

package/docs/PUBLISHING.md

@@ -0,0 +1,113 @@
+# npm publication and releases
+
+Orbit Thread v1.1.0 is the successor to Orbit Handoff v1.0.x.
+
+Historical `orbit-handoff@1.0.0` and `orbit-handoff@1.0.1` releases are immutable. Do not republish, unpublish or move their release tags.
+
+The new primary package is:
+
+```text
+orbit-thread
+```
+
+## Release checks
+
+Before publication:
+
+```sh
+npm test
+npm run validate
+npm run scan:public
+npm run build:plugin
+npm pack
+npm run smoke:pack
+```
+
+Also validate the Claude plugin with the currently installed Claude Code release:
+
+```sh
+claude plugin validate ./plugin --strict
+claude plugin validate . --strict
+```
+
+Inspect:
+
+```text
+orbit-thread-1.1.0.tgz
+dist/orbit-thread-plugin-1.1.0.zip
+```
+
+Confirm both canonical skills are present:
+
+```text
+plugin/skills/handoff/
+plugin/skills/orbit-setup/
+```
+
+and that the packed CLI can install, setup, configure, doctor, update and uninstall in a disposable repository.
+
+## Publish
+
+After release checks pass:
+
+```sh
+npm publish ./orbit-thread-1.1.0.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.
+
+If interactive authentication is unavailable to the release agent, stop with the verified tarball and give the publisher the exact command above.
+
+## Verify public distribution
+
+After publication:
+
+```sh
+npm view orbit-thread@latest version repository --registry https://registry.npmjs.org/
+mkdir /tmp/orbit-thread-public-smoke
+cd /tmp/orbit-thread-public-smoke
+git init
+npx orbit-thread@latest install --agent both --scope project --yes
+npx orbit-thread@latest setup --agent both --yes
+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`.
+
+## Existing Orbit Handoff users
+
+Because the npm package name changes, users should migrate through the new package explicitly:
+
+```sh
+npx orbit-thread@latest update --agent both --scope project --yes
+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.
+
+After Orbit Thread is publicly verified, the old package may be deprecated with a migration message, but must not be unpublished:
+
+```sh
+npm deprecate 'orbit-handoff@<=1.0.1' 'Renamed to orbit-thread. Install orbit-thread@latest.'
+```
+
+That command also requires publisher authentication and is optional.
+
+## Claude GitHub-marketplace users
+
+After the repository is renamed:
+
+```sh
+claude plugin marketplace add shab1h-gh/orbit-thread
+claude plugin install orbit-thread@orbit-thread
+```
+
+Then run:
+
+```text
+/orbit-thread:orbit-setup
+```
+
+Public OpenAI and Anthropic directory publication is separate from npm/GitHub distribution. See [SUBMISSION.md](SUBMISSION.md).

package/docs/SUBMISSION.md

@@ -0,0 +1,72 @@
+# Directory submission
+
+Updated 7 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:
+
+```text
+dist/orbit-thread-plugin-1.1.0.zip
+```
+
+Build it with:
+
+```sh
+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.
+
+### Submission flow
+
+1. Complete release validation and build the final v1.1.0 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`.
+4. Complete automated checks and resolve genuine findings.
+5. Review listing metadata and required policy/data-handling declarations.
+6. Choose **Submit for review**.
+7. Track **Review status** in the same dashboard.
+8. After approval, choose **Publish plugin** when ready.
+
+Changing bundled skills or plugin metadata requires a newly uploaded ZIP; changing GitHub alone does not update an already uploaded package.
+
+Only advertise public availability after the dashboard says the plugin is published.
+
+## Anthropic / Claude public directory
+
+The GitHub marketplace route and Anthropic's public Claude directory are separate.
+
+After the repository rename, direct GitHub installation is:
+
+```text
+/plugin marketplace add shab1h-gh/orbit-thread
+/plugin install orbit-thread@orbit-thread
+```
+
+or:
+
+```sh
+claude plugin marketplace add shab1h-gh/orbit-thread
+claude plugin install orbit-thread@orbit-thread
+```
+
+For public-directory publication, use Anthropic's developer directory submission portal. Anthropic announced that developers on paid Claude plans can submit plugins, track review and see usage after publication.
+
+Before submission:
+
+```sh
+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.
+
+A successful GitHub marketplace installation does not mean the plugin is approved for Anthropic's public directory.
+
+## General rule
+
+Provider dashboard state wins over repository documentation. Update these instructions in place if either provider changes its submission flow; Git history already records the old process.