pluribus-context 0.2.0 → 0.3.3

package/docs/quickstart.md

@@ -0,0 +1,141 @@
+# Quickstart
+
+Use this when you want to try Pluribus without touching a real project yet.
+
+Pluribus takes one intentional context file (`pluribus.md`) and generates the tool-specific files your AI tools expect: `CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, Windsurf/Continue rules, and Zed `.rules`.
+
+Already have one or more of those files? Start with a read-only inventory before replacing anything:
+
+```bash
+npx --yes pluribus-context@latest audit
+```
+
+Without `pluribus.md`, audit lists existing AI context surfaces so you can decide what to migrate. Then see [Migrate Existing AI Context Files](migrate-existing-context.md).
+
+## What Pluribus writes
+
+The safest path is audit → validate → `sync --dry-run` → `sync`. The first three steps are read-only. `init` writes only `pluribus.md`, and `sync` writes only generated AI context files for the tools you selected (`CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, Windsurf/Continue rules, or Zed `.rules`). Generated files include a `Generated by Pluribus ... do not edit manually` header, so direct edits show up as drift in `pluribus audit`.
+
+Remote imports do not refresh silently; Pluribus writes `pluribus.lock.json` and `.pluribus/cache/remote/` only when you explicitly pass `--update-imports`.
+
+## 1. Create a disposable demo project
+
+```bash
+mkdir pluribus-demo
+cd pluribus-demo
+```
+
+## 2. Preview and scaffold context
+
+Start read-only so you can see the template before writing a file. `init --dry-run` is prepared for `pluribus-context@0.3.3`; until that patch is published, use the GitHub tag install command for the preview:
+
+```bash
+npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus init --dry-run \
+  --name "Ana" \
+  --description "A Node.js service" \
+  --tools claude,cursor,copilot
+```
+
+When the scaffold looks right, create it from the published npm package:
+
+```bash
+npx --yes pluribus-context@latest init \
+  --name "Ana" \
+  --description "A Node.js service" \
+  --tools claude,cursor,copilot
+```
+
+This creates `pluribus.md`, the single source-of-truth file Pluribus reads. Open it and replace the scaffolded notes with real project context when you are ready. If you later need team/org reuse, keep the local project sections in `pluribus.md` and import shared Markdown with `# @import ./shared/team-context.md`.
+
+Choose the comma-separated `--tools` list that matches your repo. The built-in adapters are:
+
+| Tool id | Generated file |
+| --- | --- |
+| `claude` | `CLAUDE.md` |
+| `cursor` | `.cursorrules` |
+| `copilot` | `.github/copilot-instructions.md` |
+| `openclaw` | `AGENTS.md` |
+| `windsurf` | `.windsurf/rules/pluribus.md` |
+| `continue` | `.continue/rules/pluribus.md` |
+| `zed` | `.rules` |
+
+You can also run `npx --yes pluribus-context@latest --help` to see the current supported tool ids from the CLI itself.
+
+## 3. Validate before writing generated files
+
+```bash
+npx --yes pluribus-context@latest validate
+```
+
+Validation checks for missing required sections, duplicate top-level sections, broken imports, and unsupported tool names.
+
+## 4. Preview generated outputs
+
+```bash
+npx --yes pluribus-context@latest sync --dry-run
+```
+
+You should see previews for the selected tools. For the command above, Pluribus targets:
+
+| Tool | Generated file |
+| --- | --- |
+| Claude Code | `CLAUDE.md` |
+| Cursor | `.cursorrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+## 5. Audit before writing or in CI
+
+```bash
+npx --yes pluribus-context@latest audit
+```
+
+Before generated files exist, audit reports them as missing. After sync, it becomes a read-only drift check. Use `--strict` in CI when you want missing or drifted generated files to fail the build.
+
+## 6. Write the files when the preview looks right
+
+```bash
+npx --yes pluribus-context@latest sync
+```
+
+Commit `pluribus.md` as the source of truth. Commit generated files if your team wants each tool to work immediately after clone; otherwise regenerate them in local setup/CI.
+
+## 7. Keep files fresh while editing
+
+```bash
+npx --yes pluribus-context@latest watch
+```
+
+`watch` re-runs `sync` after edits to `pluribus.md` with a small debounce, so tool-specific files do not drift during normal work.
+
+## Using shared or org-level context
+
+For reusable team conventions, import shared Markdown before local project sections:
+
+```markdown
+# @import ./shared/team-context.md
+# @import ./shared/security-constraints.md
+
+# Identity
+I am Ana, building Conduit — a Node.js job runner.
+```
+
+Local sections apply after imports, so project-specific context can override shared context. See [Composable Contexts](composable-contexts.md) for local and remote import details.
+
+## Common friction
+
+- **`pluribus` command not found after `npx`:** use `npx --yes pluribus-context@latest ...` for one-off runs, or install globally with `npm install -g pluribus-context@latest` and then run `pluribus ...`.
+- **Remote imports fail without `--update-imports`:** network refresh is explicit. Run `npx --yes pluribus-context@latest sync --update-imports` to refresh and pin remote content, then normal `sync` uses the lock/cache offline.
+- **Private GitHub imports fail:** set `GH_TOKEN`/`GITHUB_TOKEN` or log in with `gh auth login`. Pluribus never writes tokens to `pluribus.lock.json` or cache files.
+- **Generated files look wrong:** edit `pluribus.md`, run `validate`, then use `audit` and `sync --dry-run` before writing files.
+
+## Feedback wanted
+
+If the quickstart fails or the generated files do not match how your team actually uses AI tools, open a [quickstart feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=quickstart-feedback.yml) with:
+
+1. the command you ran;
+2. which tool file felt wrong;
+3. what you expected Pluribus to generate instead.
+
+If the read-only audit was the confusing step, open an [audit feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=audit-feedback.yml) instead and summarize what it missed, flagged, or made unclear.
+
+That feedback is more useful than generic feature requests because it shows where the context format or adapters are not matching real workflows.

package/docs/release-checklist.md

@@ -17,13 +17,23 @@ This checklist keeps Pluribus releases reproducible and avoids accidentally publ
 - Update `CHANGELOG.md` with user-facing changes, migration notes, and verification commands.
 - Confirm README install commands use the package name `pluribus-context` and that the binary remains `pluribus`.
 
-## 2. Local checks
+## 2. Local release gate
 
-Run from the repo root:
+Run the consolidated release gate from the repo root:
 
 ```bash
+npm run release:verify
+```
+
+The verifier requires a clean `main...origin/main` checkout, reports the local package version versus npm latest, classifies the npm auth state from `npm whoami` (logged in, missing auth, or invalid/stale token), smokes the currently published npm package when one exists, then runs `npm test`, `git diff --check`, `npm run release:smoke`, `npm pack --dry-run`, and `npm publish --dry-run`. If npm auth is missing or stale, the verifier still proves the package is technically ready and names the auth/2FA action left before publish.
+
+If you need to debug an individual step, run it directly:
+
+```bash
+npm run published:smoke
 npm test
 git diff --check
+npm run release:smoke
 npm pack --dry-run
 npm publish --dry-run
 ```
@@ -47,30 +57,54 @@ Before publishing, install the exact tarball that `npm pack` creates into a temp
 npm run release:smoke
 ```
 
-The script packs the current checkout, installs that tarball into a temporary project, runs `pluribus --version`, `--help`, `init`, `validate`, `sync --dry-run`, and a real `sync`, then checks that generated output includes the package version from `package.json`. It also removes the temporary project and generated tarball on exit.
+The script packs the current checkout, installs that tarball into a temporary project, runs `pluribus --version`, `--help`, `init`, `validate`, `audit`, `sync --dry-run`, a real `sync`, and `audit --strict`, then checks that generated output includes the package version from `package.json`. It also removes the temporary project and generated tarball on exit.
 
 Expected results:
 
 - `pluribus --version` matches `package.json`.
 - `pluribus --help` shows the same version.
 - generated files mention the same Pluribus version.
-- `validate` and `sync --dry-run` work from the installed package, not the repo checkout.
+- `validate`, `audit`, and `sync --dry-run` work from the installed package, not the repo checkout.
+- `audit --strict` passes after generated files are written.
 
 ## 4. Publish
 
-Only publish after npm auth is active and the dry run is clean:
+Only publish after npm auth is active and the dry run is clean. If `npm run release:verify` reports an invalid/stale token, clear it with `npm logout` before logging in again or using a fresh temporary publish token; do not paste tokens into the repo, docs, logs, or shell history.
+
+Use the guarded publish command so the same release gate runs immediately before publishing, then the published npm smoke runs immediately after:
 
 ```bash
-npm publish --access public
+npm run release:publish
 ```
 
-Then verify:
+For a no-publish rehearsal, run:
+
+```bash
+npm run release:publish -- --dry-run
+```
+
+This rehearsal runs the full release verifier and confirms `HEAD` matches the local Git tag `v<package.json version>` before the OTP window. Use it before asking for or entering a live OTP so tag drift is caught without touching npm.
+
+If npm asks for OTP, use a short live OTP window and pass it through npm's normal `--otp` flag; do not paste tokens into the repo, docs, logs, or shell history. Avoid raw `_authToken`/token arguments — the guarded script refuses credential-like CLI arguments.
+
+```bash
+npm run release:publish -- --otp <one-time-code>
+```
+
+If a GitHub release or tag was created before npm publish succeeds, pause distribution. If `HEAD` still matches `v<package.json version>`, finish the npm publish with OTP/token and verify that npm `latest` matches the tagged version before posting publicly. If commits landed after the GitHub release/tag while npm was blocked, do **not** publish the same version from the newer commit. Reconcile first by publishing from the tagged commit, cutting a new patch version/tag, or intentionally updating the GitHub release/tag, then rerun the guarded publish.
+
+Before any real npm publish, `release:publish` verifies that `HEAD` matches `v<package.json version>`; the dry-run rehearsal verifies the same alignment without publishing.
+
+Then verify the registry entry and the install path users will see:
 
 ```bash
 npm view pluribus-context version dist.tarball
-npx pluribus-context --help
+npm view pluribus-context readme | grep -E 'npx --yes pluribus-context|60-second smoke test|Published to npm'
+npm run published:smoke
 ```
 
+The npm README is captured at publish time. If the GitHub README changed after the previous publish, confirm the npm package page no longer contains stale pre-release markers such as `once published` before starting distribution.
+
 ## 5. GitHub release
 
 After npm publish succeeds:

package/docs/when-to-use-pluribus.md

@@ -0,0 +1,95 @@
+# When to use Pluribus
+
+Pluribus is for keeping intentional AI context in sync across tools.
+
+Use it when you already have, or expect to have, more than one context surface for the same project:
+
+- `CLAUDE.md` for Claude Code
+- `.cursorrules` or `.cursor/rules/*.mdc` for Cursor
+- `.github/copilot-instructions.md` for GitHub Copilot
+- `AGENTS.md` for OpenClaw or Codex-style agents
+- Windsurf, Continue, Zed, or other workspace rule files
+
+The core bet is simple: if multiple AI tools need the same project facts, conventions, and constraints, those facts should be reviewed once and generated many times.
+
+## Use Pluribus if
+
+- You use two or more AI coding tools in the same repo.
+- You maintain project conventions by copy-pasting between context files.
+- You want context changes to be visible in git review.
+- You want a dry-run before overwriting generated tool files.
+- Your team has shared conventions that should apply across many repos.
+- You want remote/shared context pinned with a lockfile before syncing.
+
+## You may not need it if
+
+- You only use one AI tool and one context file.
+- Your context is entirely tool-specific and should not be shared.
+- You need chat memory, retrieval, vector search, or agent orchestration.
+- You want a one-time migration and do not plan to keep files synchronized.
+
+## Pluribus vs rules sync tools
+
+There are useful adjacent tools for applying or managing AI rules across editors and agents. If you are comparing packages such as Ruler, vibe-rules, or ai-rules-sync, start with the workflow you want rather than the package name.
+
+Pluribus is a good fit when the source of truth should be reviewed as project context in git, regenerated into several tool-native files, and audited later for drift. It is less useful when you only need to push prompts into one tool's own rules format.
+
+| Need | Better fit |
+|---|---|
+| Apply the same simple rules to several coding agents with minimal ceremony | A rules sync tool may be enough |
+| Manage Cursor/Windsurf prompt snippets without adopting a shared source file | A tool-native rules manager may be enough |
+| Keep Claude, Cursor, Copilot, OpenClaw, Windsurf, Continue, Zed, and AGENTS-style context aligned over time | Pluribus |
+| Review shared project context in PRs and regenerate generated files | Pluribus |
+| Share org/team conventions across repos with pinned imports and a lockfile | Pluribus |
+| Fail CI when generated context files drift from the reviewed source | Pluribus `audit --strict` |
+
+## Pluribus vs one-way converters
+
+A one-way converter is useful when you want to translate one tool's rule format into another tool's file once.
+
+Pluribus is different: it treats `pluribus.md` as the source of truth and regenerates the tool files from that source whenever the context changes.
+
+| Need | Better fit |
+|---|---|
+| Convert existing Cursor rules into `CLAUDE.md` once | One-way converter |
+| Keep Claude, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed context aligned over time | Pluribus |
+| Preserve tool-specific metadata exactly as-is | Tool-native files or a converter |
+| Review shared project context in PRs and regenerate generated files | Pluribus |
+| Share org/team conventions across repos with pinned imports | Pluribus |
+
+## Pluribus vs context linters and drift auditors
+
+A context linter or drift auditor is useful when you want to inspect existing files and catch stale paths, dead commands, oversized instructions, risky content, or conflicting guidance.
+
+Pluribus now includes a small read-only `pluribus audit` command, but its main job is not to be the deepest possible linter. Its main job is to prevent one specific class of drift: generated AI context files no longer matching the intentional source in `pluribus.md`.
+
+Use both layers when they help:
+
+| Need | Better fit |
+|---|---|
+| Find dead file references, stale commands, token bloat, or unsafe instructions inside context files | Dedicated context linter |
+| Check whether `CLAUDE.md`, `.cursorrules`, Copilot instructions, and `AGENTS.md` match the same source of truth | `pluribus audit` |
+| Auto-slim or rewrite arbitrary existing context files | Dedicated linter/fixer |
+| Diagnose why a correct `CLAUDE.md` is ignored after compaction or summarization | Tool-specific runtime diagnostics/hooks |
+| Generate aligned context files after review | `pluribus sync` |
+| Enforce “generated files are up to date” in CI | `pluribus audit --strict` |
+
+## Recommended migration path
+
+1. Inventory your existing context files.
+2. Move shared project facts and conventions into `pluribus.md`.
+3. Keep genuinely tool-specific behavior in tool-native files or custom skills.
+4. Run `pluribus sync --dry-run` and inspect the output.
+5. Commit `pluribus.md`, generated files, and `pluribus.lock.json` if remote imports are used.
+
+For the step-by-step version, see [Migrate Existing AI Context Files](migrate-existing-context.md).
+
+## Mental model
+
+Pluribus is not trying to make every AI tool identical.
+
+It is trying to keep the stable, intentional parts of your project context from drifting while still letting each tool keep its own interface and strengths.
+
+That means Pluribus handles file-level alignment. Runtime precedence problems — for example, a tool loading a compacted summary above a correct context file — are real, but they belong in the tool's load-order, hooks, or context-priority settings rather than in Pluribus' sync layer.
+
+For a sharper split of the overloaded term "context drift", see the [Context Drift Taxonomy](context-drift-taxonomy.md).

package/examples/context-drift-audit/.cursorrules

@@ -0,0 +1,30 @@
+# Cursor Rules — generated by Pluribus 0.3.3 on 2026-05-13
+# Source: pluribus.md
+# Do not edit manually.
+
+
+## Project
+I am Mina, maintaining **RelayKit** — a small TypeScript SDK for webhook delivery.
+
+
+
+## Stack
+- TypeScript 5.4
+- Node.js 22 LTS
+- Node's built-in test runner
+
+
+## Conventions
+- Prefer explicit return types for exported SDK functions
+- Keep public API examples copy-pasteable
+- Use small modules with clear error boundaries
+
+## Goals
+1. Keep webhook retries deterministic
+2. Preserve backwards compatibility for public SDK APIs
+3. Make production failure modes visible in logs and tests
+
+## Constraints
+- Do not add external queue infrastructure
+- Do not break existing webhook payload shapes
+- Do not hide delivery failures behind silent retries

package/examples/context-drift-audit/.github/copilot-instructions.md

@@ -0,0 +1,28 @@
+<!-- Generated by Pluribus 0.3.3 on 2026-05-13 — do not edit manually -->
+<!-- Source: pluribus.md -->
+
+
+## Project
+I am Mina, maintaining **RelayKit** — a small TypeScript SDK for webhook delivery.
+
+
+## Stack
+- TypeScript 5.4
+- Node.js 22 LTS
+- Node's built-in test runner
+
+## Conventions
+- Prefer explicit return types for exported SDK functions
+- Keep public API examples copy-pasteable
+- Use small modules with clear error boundaries
+
+## Constraints
+- Do not add external queue infrastructure
+- Do not break existing webhook payload shapes
+- Do not hide delivery failures behind silent retries
+
+
+## Goals
+1. Keep webhook retries deterministic
+2. Preserve backwards compatibility for public SDK APIs
+3. Make production failure modes visible in logs and tests

package/examples/context-drift-audit/CLAUDE.md

@@ -0,0 +1,55 @@
+<!-- Generated by Pluribus 0.3.3 on 2026-05-13 — do not edit manually -->
+<!-- Source: pluribus.md -->
+
+# Project Context for Claude
+
+## Identity
+
+I am Mina, maintaining **RelayKit** — a small TypeScript SDK for webhook delivery.
+
+---
+
+## Tech Stack
+
+- TypeScript 5.4
+- Node.js 20 LTS
+- Node's built-in test runner
+
+---
+
+## Conventions
+
+- Prefer explicit return types for exported SDK functions
+- Keep public API examples copy-pasteable
+- Use small modules with clear error boundaries
+
+---
+
+## Goals
+
+1. Keep webhook retries deterministic
+2. Preserve backwards compatibility for public SDK APIs
+3. Make production failure modes visible in logs and tests
+
+---
+
+## Constraints
+
+> These are non-negotiable. Do not deviate from these under any circumstances.
+
+- Do not add external queue infrastructure
+- Do not break existing webhook payload shapes
+- Do not hide delivery failures behind silent retries
+
+
+
+
+
+
+---
+
+## Workflow
+
+- Run `npm test` before committing
+- Keep generated AI context files in sync with `pluribus.md`
+- Review context changes like code changes

package/examples/context-drift-audit/README.md

@@ -0,0 +1,31 @@
+# Context drift audit example
+
+This fixture shows the safest first Pluribus workflow for an existing repo: audit generated AI context before writing anything.
+
+`pluribus.md` is the source of truth. `CLAUDE.md` is intentionally drifted: it says `Node.js 20 LTS` while `pluribus.md` says `Node.js 22 LTS`. Cursor and Copilot outputs are current.
+
+Run from this directory:
+
+```bash
+npx --yes --package ../.. pluribus audit --strict
+```
+
+Expected result:
+
+```text
+⚠️  [claude] CLAUDE.md differs from generated output
+✅ [cursor] .cursorrules is current
+✅ [copilot] .github/copilot-instructions.md is current
+```
+
+Preview the fix without writing files:
+
+```bash
+npx --yes --package ../.. pluribus sync --dry-run
+```
+
+Then apply it when the diff is acceptable:
+
+```bash
+npx --yes --package ../.. pluribus sync
+```

package/examples/context-drift-audit/pluribus.md

@@ -0,0 +1,35 @@
+<!-- pluribus:tools: claude,cursor,copilot -->
+
+# Identity
+
+I am Mina, maintaining **RelayKit** — a small TypeScript SDK for webhook delivery.
+
+# Stack
+
+- TypeScript 5.4
+- Node.js 22 LTS
+- Node's built-in test runner
+
+# Conventions
+
+- Prefer explicit return types for exported SDK functions
+- Keep public API examples copy-pasteable
+- Use small modules with clear error boundaries
+
+# Goals
+
+1. Keep webhook retries deterministic
+2. Preserve backwards compatibility for public SDK APIs
+3. Make production failure modes visible in logs and tests
+
+# Constraints
+
+- Do not add external queue infrastructure
+- Do not break existing webhook payload shapes
+- Do not hide delivery failures behind silent retries
+
+# Workflow
+
+- Run `npm test` before committing
+- Keep generated AI context files in sync with `pluribus.md`
+- Review context changes like code changes

package/examples/git-hooks/pre-commit

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+set -eu
+
+# Keep generated AI context files aligned with pluribus.md before committing.
+# Install by copying this file to .git/hooks/pre-commit and running chmod +x.
+
+if [ ! -f pluribus.md ]; then
+  exit 0
+fi
+
+npx --yes pluribus-context@latest audit --strict

package/examples/github-actions/pluribus-audit.yml

@@ -0,0 +1,26 @@
+name: Pluribus context audit
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22.x
+
+      - name: Audit AI context drift
+        # Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm.
+        run: npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --ci

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pluribus-context",
-  "version": "0.2.0",
-  "description": "Intentional context across every AI tool you use.",
+  "version": "0.3.3",
+  "description": "Sync intentional AI context and rules across Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",
   "repository": {
@@ -20,29 +20,44 @@
     "src/",
     "docs/",
     "spec/",
+    "schemas/",
     "examples/",
     "CHANGELOG.md"
   ],
   "scripts": {
     "start": "node bin/pluribus.js",
     "test": "node --test",
-    "release:smoke": "node scripts/release-smoke.js"
+    "release:smoke": "node scripts/release-smoke.js",
+    "published:smoke": "node scripts/published-smoke.js",
+    "release:verify": "node scripts/release-verify.js",
+    "release:publish": "node scripts/release-publish.js"
   },
   "keywords": [
+    "agent-rules",
+    "agents",
+    "agents-md",
     "ai",
-    "cli",
-    "context",
-    "context-engineering",
+    "ai-coding-agents",
+    "ai-context",
     "ai-tools",
+    "aider",
     "claude",
     "claude-code",
-    "cursor",
-    "copilot",
-    "windsurf",
+    "cli",
+    "codex",
+    "context",
+    "context-drift",
+    "context-engineering",
     "continue",
-    "zed",
+    "copilot",
+    "cursor",
+    "cursor-rules",
+    "developer-tools",
+    "drift-detection",
     "openclaw",
-    "developer-tools"
+    "rules",
+    "windsurf",
+    "zed"
   ],
   "author": "Caio Ribeiro",
   "license": "MIT",