pluribus-context 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to Pluribus are documented here.
+
+## 0.2.0 — Package-ready CLI release
+
+Pluribus 0.2.0 is the first npm-ready release of the CLI for keeping intentional AI context in one versioned source and syncing it to the files each tool expects. It supersedes the earlier GitHub-only v0.1.0 alpha release from March.
+
+### Added
+
+- `pluribus init` to scaffold a project `pluribus.md` context file.
+- `pluribus validate` to catch missing sections, unresolved imports, duplicated top-level sections, and invalid tool names before syncing.
+- `pluribus sync` to generate tool-specific context files.
+- `pluribus watch` to debounce edits to `pluribus.md` and keep generated files fresh during local development.
+- Built-in adapters for:
+  - Claude Code (`CLAUDE.md`)
+  - Cursor (`.cursorrules`)
+  - GitHub Copilot (`.github/copilot-instructions.md`)
+  - OpenClaw (`AGENTS.md`)
+  - Zed (`.rules`)
+  - Windsurf (`.windsurf/rules/pluribus.md`)
+  - Continue (`.continue/rules/pluribus.md`)
+- Local composable contexts via `# @import ./relative-file.md`.
+- Explicit remote imports via `github:owner/repo/path.md[@ref]` and HTTPS URLs when running with `--update-imports`.
+- Deterministic remote import lock/cache support through `pluribus.lock.json` and `.pluribus/cache/remote/`.
+- Optional GitHub authentication for private GitHub imports through `GH_TOKEN`, `GITHUB_TOKEN`, or the logged-in GitHub CLI.
+- Specs, examples, and docs for context format, adapter behavior, and composable contexts.
+
+### Notes
+
+- The npm package name is `pluribus-context` because `pluribus` is already occupied on npm by an unrelated package.
+- The installed binary is still `pluribus`.
+- Remote imports never fetch during normal `sync`/`validate`; network refresh is explicit via `--update-imports`.
+- Tokens are never written to the lockfile or cache.
+
+### Verification
+
+- Local test suite: `npm test`.
+- Package check: `npm pack --dry-run`.
+- Publish check before release: `npm publish --dry-run`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caio Ribeiro
+
+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/README.md

@@ -0,0 +1,294 @@
+# Pluribus
+
+[![Building in Public](https://img.shields.io/badge/building-in%20public-orange?style=flat-square)](https://x.com/RibeiroCaioCLW)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+> Intentional context across every AI tool you use.
+
+Pluribus keeps project instructions, conventions, constraints, and team context in one versioned source of truth, then syncs that context into the formats each AI tool expects.
+
+It is **not** a persistent memory layer, retrieval system, agent orchestrator, or agent-merging framework. Think `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `AGENTS.md` — one intentional context, multiple generated outputs.
+
+---
+
+## The Problem
+
+You use Claude, Copilot, Cursor, Windsurf, Continue, Zed, ChatGPT, and whatever ships next Tuesday.
+
+Each one has its own way of understanding your project:
+- `CLAUDE.md` for Claude Code
+- `copilot-instructions.md` for GitHub Copilot
+- `.cursorrules` for Cursor
+- `AGENTS.md` for OpenClaw
+- `.windsurf/rules/pluribus.md` for Windsurf Cascade
+- `.continue/rules/pluribus.md` for Continue
+- `.rules` for Zed
+
+You end up maintaining **5+ files** that say roughly the same thing — your project's architecture, conventions, tech stack, who you are, what matters. Copy-paste across files. They drift. They rot. You forget to update one. Your AI gives you wrong answers because it's reading stale context.
+
+**This is a multiplying problem.** Every new AI tool = another context file = more maintenance = more drift.
+
+## The Vision
+
+**Pluribus** is a universal format for intentional context in AI-assisted development.
+
+Write your project context **once**, in simple `.md` files. Pluribus syncs it to every tool you use — formatted exactly how each tool expects it.
+
+```
+pluribus/
+├── context.md        # Your project: stack, architecture, conventions
+├── identity.md       # Who you are, your preferences, tone
+├── skills.md         # What your AI should be good at
+└── rules.md          # Guardrails and constraints
+```
+
+Then:
+
+```bash
+npx pluribus-context sync
+```
+
+And it generates the right files for each tool:
+- `CLAUDE.md` ← for Claude Code
+- `.github/copilot-instructions.md` ← for Copilot
+- `.cursorrules` ← for Cursor
+- `AGENTS.md` ← for OpenClaw
+- `.windsurf/rules/pluribus.md` ← for Windsurf Cascade
+- `.continue/rules/pluribus.md` ← for Continue
+- `.rules` ← for Zed
+
+**One source of truth. Zero drift.**
+
+## Why `.md`?
+
+- It's **human-readable** — you can review it, version it, PR it
+- It's **universal** — every tool already parses markdown
+- It's **composable** — import shared contexts across projects
+- It's **versionable** — git diff your AI context like you diff your code
+- It's **simple** — no YAML schemas, minimal JSON only when you opt into locked remote imports
+
+## Getting Started
+
+### Install
+
+```bash
+# From npm (once published)
+npm install -g pluribus-context
+
+# Or run directly with npx
+npx pluribus-context
+
+# Or clone and link locally
+git clone https://github.com/caioribeiroclw-pixel/pluribus.git
+cd pluribus
+npm link
+```
+
+### Usage
+
+**1. Initialize your context file**
+
+```bash
+cd your-project/
+pluribus init
+```
+
+This creates `pluribus.md` with all required sections scaffolded. Fill in your project context.
+
+You can also use flags for non-interactive init:
+
+```bash
+pluribus init --name "Ana" --description "A background job runner" --tools claude,cursor,openclaw
+```
+
+**2. Edit `pluribus.md`**
+
+Fill in your context once:
+
+```markdown
+# Identity
+I am Ana, building **Conduit** — a background job runner for Node.js.
+
+# Stack
+- Language: TypeScript 5.4
+- Runtime: Node.js 22 LTS
+- ...
+
+# Conventions
+- async/await everywhere — no .then()/.catch()
+- ...
+
+# Goals
+1. Zero external infrastructure
+2. Type safety end-to-end
+...
+
+# Constraints
+- Never introduce native-compile dependencies
+- ...
+```
+
+**3. Compose shared context when needed**
+
+For team or org-wide conventions, import shared Markdown files before your local project sections:
+
+```markdown
+# @import ./shared/team-context.md
+# @import ./shared/security-constraints.md
+
+# Identity
+I am Ana, building **Conduit** — a background job runner for Node.js.
+```
+
+Local sections are applied after imported sections, so project-specific context can override shared context. See [Composable Contexts](docs/composable-contexts.md) for details.
+
+**4. Validate before syncing**
+
+```bash
+pluribus validate
+```
+
+This checks that `pluribus.md` exists, imports resolve, required sections are present, top-level sections are not duplicated, and any `pluribus:tools` comment uses supported tool names.
+
+If you use remote imports and want to refresh the lock/cache while validating:
+
+```bash
+pluribus validate --update-imports
+```
+
+**5. Sync to all your tools**
+
+```bash
+pluribus sync
+```
+
+If you use remote imports, refresh and pin them explicitly:
+
+```bash
+pluribus sync --update-imports
+```
+
+That writes `pluribus.lock.json` plus a local `.pluribus/cache/remote/` content cache. Future plain `pluribus sync` runs resolve those remote imports from the lock/cache without network access, and fail if cached bytes no longer match the recorded digest.
+
+Private `github:` imports use existing GitHub credentials only during `--update-imports`: `GH_TOKEN`/`GITHUB_TOKEN` if set, otherwise the logged-in GitHub CLI (`gh auth token`). Tokens are never stored in the lockfile or cache. Commit `pluribus.lock.json`; treat `.pluribus/cache/remote/` as local, regenerable cache.
+
+Output:
+```
+🔄 Syncing pluribus.md → claude, cursor, openclaw
+
+   ✅ [claude]   → CLAUDE.md
+   ✅ [cursor]   → .cursorrules
+   ✅ [openclaw] → AGENTS.md
+
+✅ Sync complete — 3 file(s) written.
+```
+
+**Preview without writing (dry run):**
+
+```bash
+pluribus sync --dry-run
+```
+
+**Sync specific tools only:**
+
+```bash
+pluribus sync --tools claude,openclaw
+```
+
+**Keep tool files fresh while editing:**
+
+```bash
+pluribus watch
+```
+
+`watch` monitors `pluribus.md`, debounces rapid editor saves, and re-runs `sync` automatically. It accepts the same `--source`, `--tools`, and `--update-imports` options as `sync`.
+
+For scripts/hooks that should exit after the first detected change-triggered sync:
+
+```bash
+pluribus watch --once --tools claude,cursor
+```
+
+### Supported Tools
+
+| Flag | Output file | AI Tool |
+|---|---|---|
+| `claude` | `CLAUDE.md` | Claude Code (Anthropic) |
+| `cursor` | `.cursorrules` | Cursor AI editor |
+| `openclaw` | `AGENTS.md` | OpenClaw agent runner |
+| `copilot` | `.github/copilot-instructions.md` | GitHub Copilot |
+| `zed` | `.rules` | Zed Editor |
+| `windsurf` | `.windsurf/rules/pluribus.md` | Windsurf Cascade workspace rules |
+| `continue` | `.continue/rules/pluribus.md` | Continue workspace rules |
+
+### Custom Skills
+
+Add a `pluribus/skills/<tool>.md` file to override or extend any built-in skill.
+See `spec/skills-format.md` for the skill file format.
+
+---
+
+## Status
+
+🚧 **Early development** — the spec and CLI are being built in public.
+
+### Roadmap
+
+- [x] Problem definition & vision
+- [x] Context format spec (`pluribus.md` flat format)
+- [x] Skills format spec (extensible adapter system)
+- [x] CLI: `pluribus init` — scaffold your context
+- [x] CLI: `pluribus sync` — generate tool-specific files
+- [x] OpenClaw integration (built-in skill)
+- [x] Cursor integration (built-in skill)
+- [x] Copilot integration (built-in skill)
+- [x] Claude Code integration (built-in skill)
+- [x] Zed Editor integration (built-in skill)
+- [ ] Custom skill overrides (local `pluribus/skills/`)
+- [x] Windsurf integration (built-in workspace rule)
+- [x] Continue integration (built-in workspace rule)
+- [x] `pluribus validate` command
+- [x] `pluribus watch` command (debounced auto-sync on context changes)
+- [x] Composable contexts MVP (local `# @import ./file.md`)
+- [x] Remote composable contexts MVP (explicit `--update-imports`, public GitHub/HTTPS, safety limits)
+- [x] Remote imports hardening (lockfile/cache/digest offline mode, optional GitHub auth, and CI coverage)
+- [ ] CI/CD: auto-sync on commit
+- [ ] Published to npm
+
+## Building in Public
+
+I'm documenting every step of building Pluribus — the decisions, the trade-offs, the mistakes.
+
+Follow along: [@RibeiroCaioCLW](https://x.com/RibeiroCaioCLW)
+
+If you've felt this pain, [open an issue](https://github.com/caioribeiroclw-pixel/pluribus/issues) and tell me about your setup. What tools do you use? How do you manage context today? What's broken?
+
+## Docs
+
+- [OpenClaw Integration](docs/openclaw-integration.md) — how Pluribus generates `AGENTS.md` for OpenClaw
+- [Composable Contexts](docs/composable-contexts.md) — local/remote imports, merge behavior, and safety rules
+- [Remote Composable Context Imports](docs/remote-composable-context-imports.md) — design notes for lockfile/cache/auth hardening
+- [Context Format Spec](spec/context-format.md) — the `pluribus.md` format reference
+- [Skills Format Spec](spec/skills-format.md) — how adapters work and how to write custom skills
+- [Release Checklist](docs/release-checklist.md) — reproducible npm/GitHub release steps
+- [Changelog](CHANGELOG.md) — user-facing release notes
+
+---
+
+## Contributing
+
+This project is just getting started. The best way to help right now:
+
+1. ⭐ Star the repo if the problem resonates
+2. 🗣️ [Open an issue](https://github.com/caioribeiroclw-pixel/pluribus/issues) describing your context management pain
+3. 📣 Share with someone who maintains 3+ AI context files
+
+Looking for first contributions? Check out the [open issues](https://github.com/caioribeiroclw-pixel/pluribus/issues). The next good contributions are release polish, CI/CD workflow examples, and real-world adapter feedback.
+
+## License
+
+[MIT](LICENSE) — use it, fork it, build on it.
+
+---
+
+*"E pluribus unum" — out of many, one.*

package/bin/pluribus.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+/**
+ * Pluribus CLI — Write your AI context once. Sync it to every tool.
+ * Entry point: bin/pluribus.js
+ */
+
+import { runInit } from '../src/commands/init.js'
+import { runSync } from '../src/commands/sync.js'
+import { runValidate } from '../src/commands/validate.js'
+import { runWatch } from '../src/commands/watch.js'
+import { parseArgs } from '../src/utils/args.js'
+import { VERSION } from '../src/utils/version.js'
+
+const HELP = `
+Pluribus v${VERSION} — Write your AI context once. Sync it to every tool.
+
+USAGE
+  pluribus <command> [options]
+
+COMMANDS
+  init      Create a pluribus.md file in the current directory
+  sync      Read pluribus.md and generate tool-specific output files
+  validate  Validate pluribus.md before syncing
+  watch     Watch pluribus.md and auto-sync after changes
+  help      Show this help message
+
+OPTIONS (init)
+  --name          Project/author name
+  --description   One-line project description
+  --tools         Comma-separated list of tools to enable (claude,cursor,openclaw)
+
+OPTIONS (sync)
+  --dry-run       Preview output without writing files
+  --tools         Override which tools to sync (comma-separated)
+  --source        Path to pluribus.md (default: ./pluribus.md)
+  --update-imports  Explicitly allow fetching remote github:/https:// imports
+
+OPTIONS (validate)
+  --source        Path to pluribus.md (default: ./pluribus.md)
+  --update-imports  Refresh remote github:/https:// imports before validating
+
+OPTIONS (watch)
+  --source        Path to pluribus.md (default: ./pluribus.md)
+  --tools         Override which tools to sync (comma-separated)
+  --update-imports  Explicitly allow fetching remote github:/https:// imports
+  --once          Exit after the first change-triggered sync
+  --debounce      Debounce delay in ms (minimum 300, default 400)
+
+EXAMPLES
+  pluribus init
+  pluribus init --name "Ana" --description "A task manager" --tools claude,cursor
+  pluribus sync
+  pluribus sync --dry-run
+  pluribus sync --tools claude,openclaw
+  pluribus sync --update-imports
+  pluribus validate
+  pluribus watch --tools claude,cursor
+
+DOCS
+  https://github.com/caioribeiroclw-pixel/pluribus
+`
+
+async function main() {
+  const args = process.argv.slice(2)
+
+  if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+    console.log(HELP)
+    process.exit(0)
+  }
+
+  if (args[0] === '--version' || args[0] === '-v') {
+    console.log(VERSION)
+    process.exit(0)
+  }
+
+  const command = args[0]
+  const parsedArgs = parseArgs(args.slice(1))
+
+  try {
+    switch (command) {
+      case 'init':
+        await runInit(parsedArgs)
+        break
+      case 'sync':
+        await runSync(parsedArgs)
+        break
+      case 'validate':
+        await runValidate(parsedArgs)
+        break
+      case 'watch':
+        await runWatch(parsedArgs)
+        break
+      default:
+        console.error(`❌ Unknown command: "${command}"`)
+        console.log(`Run \`pluribus help\` for usage.`)
+        process.exit(1)
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message || err}`)
+    if (process.env.DEBUG) {
+      console.error(err)
+    }
+    process.exit(1)
+  }
+}
+
+main()

package/docs/composable-contexts.md

@@ -0,0 +1,124 @@
+# Composable Contexts
+
+Pluribus supports context imports so teams can share a base context and let each project add or override what is specific to that repo.
+
+Use this when you have one set of org/team conventions that should be inherited by multiple projects, but each project still needs its own stack, goals, constraints, or examples.
+
+## Import syntax
+
+Add import directives near the top of `pluribus.md`:
+
+```markdown
+# @import ./shared/team-context.md
+# @import ./shared/security-constraints.md
+
+# Identity
+I am Ana, building **Conduit** — a background job runner for Node.js.
+
+# Goals
+1. Ship a small, reliable CLI first
+2. Keep runtime dependencies minimal
+```
+
+Import paths are resolved relative to the file that contains the directive.
+
+## Merge behavior
+
+Imported files are expanded before the local file content. That means local sections win when a section appears in both places:
+
+```markdown
+# @import ./shared/base-context.md
+
+# Conventions
+Project-specific conventions override the shared `# Conventions` section.
+```
+
+This keeps the inheritance model simple:
+
+1. shared/org context first
+2. team context next
+3. project-local context last
+
+## Safety rules
+
+Local imports are deterministic by default:
+
+- ✅ `# @import ./relative/path.md`
+- ✅ nested imports up to depth `5`
+- ✅ cycle detection
+- ✅ path-escape protection outside the project root
+- ❌ shell execution during import resolution
+
+Remote imports are explicit opt-in via `pluribus sync --update-imports`:
+
+- ✅ `github:owner/repo/path.md[@ref]` public raw imports
+- ✅ optional private `github:` imports via existing `GH_TOKEN`/`GITHUB_TOKEN` or logged-in `gh`
+- ✅ direct `https://...` Markdown/text imports
+- ✅ HTTPS only; `http://` is rejected
+- ✅ request timeout, redirect limit, UTF-8/text content checks, per-file and merged-size limits
+- ✅ credential-bearing URLs are rejected/redacted in errors
+- ✅ nested relative imports inside `github:` resources stay in the same repo/ref
+- ✅ `pluribus sync --update-imports` writes `pluribus.lock.json` and `.pluribus/cache/remote/`
+- ✅ later plain `pluribus sync` runs reuse the locked cache offline with SHA-256 verification
+- ❌ relative imports from arbitrary HTTPS documents
+- ❌ inline tokens in import specs, CLI flags, lockfiles, cache metadata, logs, or errors
+
+Remote imports are deliberately disabled unless `--update-imports` is passed so normal sync runs do not perform silent network access. Once a remote import is locked, normal sync runs read it from the local cache instead of the network. If a remote import has no lock entry/cache yet, sync fails closed and asks you to refresh with `--update-imports`. GitHub credentials are used only while refreshing private `github:` imports; tokens are never written to `pluribus.lock.json` or `.pluribus/cache/remote/`. Commit the lockfile for deterministic CI/offline syncs; treat the cache as local and regenerable.
+
+## Example layout
+
+```text
+my-project/
+├── pluribus.md
+└── shared/
+    ├── team-context.md
+    └── security-constraints.md
+```
+
+`pluribus.md`:
+
+```markdown
+# @import ./shared/team-context.md
+# @import ./shared/security-constraints.md
+
+# Identity
+I am Ana, building **Conduit** — a background job runner for Node.js.
+
+# Stack
+- Node.js 22 LTS
+- TypeScript strict mode
+
+# Goals
+1. Ship the CLI first
+2. Keep install size small
+```
+
+`shared/team-context.md`:
+
+```markdown
+# Conventions
+- Prefer small, explicit functions
+- Use named exports only
+- Tests live next to the source file
+```
+
+`shared/security-constraints.md`:
+
+```markdown
+# Constraints
+- Never execute shell commands from context files
+- Never write outside the project root
+- Never add network calls without explicit review
+```
+
+Then run:
+
+```bash
+pluribus sync --dry-run
+```
+
+Pluribus resolves the imports, parses the merged context, and generates the selected tool files from the resolved content.
+
+## Current limitation
+
+The current parser treats top-level section names as unique, and the later section wins if a duplicate appears after imports. Use duplicate sections deliberately for overrides; if you want additive behavior, put shared and local details under different section names such as `# Team` and `# Workflow`.