pluribus-context 0.2.0

package/spec/context-format.md

@@ -0,0 +1,356 @@
+# Pluribus Context Format Spec
+
+**Version:** 0.1.0-draft
+**Status:** Draft
+**Date:** 2026-03-08
+
+---
+
+## Overview
+
+The Pluribus context format defines a single, human-readable Markdown file — `pluribus.md` — that serves as the authoritative source of truth for AI tool context in a project. From this one file, Pluribus generates all tool-specific files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) without duplication or drift.
+
+This spec defines the structure, sections, parsing rules, and conventions for `pluribus.md`.
+
+---
+
+## File Location
+
+**Primary (flat):** `pluribus.md` in the project root.
+**Structured (multi-file):** `pluribus/context.md`, `pluribus/identity.md`, `pluribus/skills.md`, `pluribus/rules.md`
+
+When both exist, the structured form takes precedence. The flat form is recommended for single-developer projects; the structured form for teams with complex contexts.
+
+This spec covers the flat form. The structured form follows the same section rules, distributed across files.
+
+---
+
+## Composable Contexts
+
+A `pluribus.md` file may import other local Markdown context files with `# @import` directives:
+
+```markdown
+# @import ./shared/team-context.md
+# @import ./shared/security-constraints.md
+```
+
+Imports are resolved during `pluribus sync` before the file is parsed into sections.
+
+### Import Rules
+
+- Import paths are resolved relative to the file containing the directive.
+- Imports are expanded before the importing file's own local content.
+- Later duplicate top-level sections override earlier ones through the existing parser behavior, so project-local sections win over shared imported sections.
+- Nested imports are allowed up to depth `5`.
+- Cycles are rejected with the import path chain.
+- Imports cannot escape the project/source root.
+- Remote imports are refreshed only when sync is run with explicit network refresh (`pluribus sync --update-imports`).
+- `github:owner/repo/path.md[@ref]` resolves to raw GitHub content; nested relative imports stay within the same repo/ref.
+- Private `github:` imports may use existing `GH_TOKEN`/`GITHUB_TOKEN` or logged-in GitHub CLI credentials during explicit refresh only.
+- Direct `https://...` Markdown/text imports are supported; `http://` and credential-bearing URLs are rejected.
+- Remote fetches enforce timeout, redirect, UTF-8/text content, per-file size, and merged-size limits.
+- Refresh writes `pluribus.lock.json` plus `.pluribus/cache/remote/<sha256>.md` entries for each fetched remote document.
+- Tokens are never stored in lockfile or cache entries; the lockfile may be committed and the cache is local/regenerable.
+- Later sync runs resolve remote imports from that lock/cache without network access and verify the cached bytes against the recorded SHA-256 digest.
+- If a remote import is referenced but not yet locked/cached, sync fails closed and asks for `--update-imports`.
+- Context files are never executed; imports only read Markdown text.
+
+### Example
+
+```markdown
+# @import ./shared/base-context.md
+
+# Goals
+1. Project-specific goals override the shared `# Goals` section.
+```
+
+---
+
+## Canonical Sections
+
+A `pluribus.md` file is composed of top-level Markdown headings. Each heading is a **section**. Sections are case-sensitive and must be level-1 headings (`#`).
+
+### Required Sections
+
+| Section | Purpose |
+|---|---|
+| `# Identity` | Who the project owner is; the agent/AI persona if applicable |
+| `# Stack` | Technology stack: language, framework, tooling, infrastructure |
+| `# Conventions` | Code style, patterns, naming rules, workflow expectations |
+| `# Goals` | What this project is trying to achieve; what matters most |
+| `# Constraints` | Hard rules — what the AI must never do |
+
+All five required sections must be present for a valid `pluribus.md`.
+
+### Optional Sections
+
+| Section | Purpose |
+|---|---|
+| `# Examples` | Concrete code snippets or interaction examples |
+| `# Anti-patterns` | Patterns that look reasonable but should be avoided in this project |
+| `# Workflow` | Development workflow: branching, PRs, testing, deployment |
+| `# Context` | Background the AI needs to understand the project domain |
+| `# Team` | Team members, roles, areas of ownership |
+
+Optional sections may appear in any order after the required sections.
+
+---
+
+## Section Specification
+
+### `# Identity`
+
+Who you are, what the project is, and (if applicable) the AI persona to adopt.
+
+**Guidelines:**
+- Keep this concise — 3–10 lines
+- Include: your name or team name, the project name, the project's purpose in one sentence
+- If the project uses an AI agent with a defined persona, describe it here
+
+**Example:**
+```markdown
+# Identity
+
+I am Carlos, a solo developer building **Velo** — a lightweight task manager for developers who live in the terminal.
+
+Velo is a TypeScript CLI tool. Users are developers. They value speed and simplicity over features.
+```
+
+---
+
+### `# Stack`
+
+The full technical picture of the project.
+
+**Guidelines:**
+- List language + version, frameworks, key libraries, test tools, linter/formatter, infrastructure
+- Be specific — "TypeScript 5.4" is better than "TypeScript"
+- Include what is intentionally excluded (e.g., "no ORM — raw SQL via `postgres` driver")
+
+**Example:**
+```markdown
+# Stack
+
+- **Language:** TypeScript 5.4 (strict mode)
+- **Runtime:** Node.js 22 LTS
+- **Framework:** None — pure Node CLI
+- **Testing:** Jest 29 + ts-jest
+- **Linting:** ESLint (flat config) + Prettier
+- **Package manager:** pnpm
+- **CI:** GitHub Actions
+- **No ORM** — raw SQL via `postgres` driver
+```
+
+---
+
+### `# Conventions`
+
+How code is written in this project. This section directly shapes AI behavior during code generation and review.
+
+**Guidelines:**
+- Be opinionated and explicit
+- Cover: async patterns, error handling, naming conventions, file structure, forbidden patterns
+- Prefer positive rules ("always X") over vague ones ("use good naming")
+
+**Example:**
+```markdown
+# Conventions
+
+- Always use `async/await` — never `.then()/.catch()` chains
+- No class-based code — use plain functions and closures
+- Error handling: never swallow errors silently; always propagate or log
+- File naming: `kebab-case.ts`
+- Exports: named exports only — no default exports
+- Tests: one `describe` block per module; test file lives next to the source file
+- No `any` — use `unknown` and narrow types explicitly
+- Prefer `const` over `let`; never `var`
+```
+
+---
+
+### `# Goals`
+
+What this project is optimizing for. Helps the AI make trade-off decisions.
+
+**Guidelines:**
+- List 3–7 goals in priority order
+- Be specific to this project — not generic engineering virtues
+- Include product goals, not just technical goals
+
+**Example:**
+```markdown
+# Goals
+
+1. Ship fast — the project is pre-launch; velocity matters more than perfection
+2. Keep the codebase small and readable — a new contributor should understand the whole codebase in 30 minutes
+3. Zero runtime dependencies where possible — this is a CLI tool; bloat matters
+4. 100% type coverage — TypeScript strict mode, no escape hatches
+5. Developer experience over user customizability
+```
+
+---
+
+### `# Constraints`
+
+Hard rules. What the AI must never do, regardless of context.
+
+**Guidelines:**
+- State constraints clearly and firmly
+- Include security, architectural, and process constraints
+- These map directly to AI tool guardrails
+
+**Example:**
+```markdown
+# Constraints
+
+- Never introduce new dependencies without explicit confirmation
+- Never use `eval`, `Function()`, or dynamic `require()`
+- Never write to the filesystem outside of designated output directories
+- Never delete or overwrite files without a dry-run option
+- Never use class-based patterns — not even for error types (use plain objects + type guards)
+- Do not modify `package.json` or lock files autonomously
+```
+
+---
+
+### `# Examples` (optional)
+
+Concrete code that shows what "good" looks like in this project. The AI uses these as style references.
+
+**Guidelines:**
+- Include 1–3 representative examples
+- Show the pattern, not just the syntax
+- Label each example clearly
+
+---
+
+### `# Anti-patterns` (optional)
+
+Patterns that look acceptable but should be avoided in this specific project.
+
+**Guidelines:**
+- Each entry: name the pattern, explain why it's banned here
+- Keep it short — this is a warning list, not a tutorial
+
+---
+
+## Parsing Rules
+
+Pluribus parses `pluribus.md` using the following rules:
+
+1. **Section detection:** A section starts at any level-1 heading (`# Heading`) and ends at the next level-1 heading or EOF.
+2. **Section content:** Everything between the heading and the next `#` heading is the section body. Subheadings (`##`, `###`) within a section are preserved as-is.
+3. **Unknown sections:** Any section not in the canonical list is preserved and passed to skills as `extra.<section-slug>`.
+4. **Whitespace:** Leading and trailing whitespace within a section body is trimmed.
+5. **No execution:** Pluribus never executes code blocks inside `pluribus.md`. They are treated as literal text.
+6. **Encoding:** UTF-8. Files with BOM are supported but the BOM is stripped.
+7. **Imports:** `# @import ./path.md` directives are resolved before section parsing. The directive itself is not preserved in generated tool output.
+
+---
+
+## Validation
+
+A valid `pluribus.md` must:
+
+- [ ] Contain all 5 required sections
+- [ ] Have each required section non-empty (at least one non-whitespace line)
+- [ ] Be valid UTF-8
+- [ ] Have no duplicate top-level section names
+
+Run `pluribus validate` to check your file.
+
+---
+
+## Full Example
+
+Below is a complete, realistic `pluribus.md` for a Node.js TypeScript project.
+
+```markdown
+# Identity
+
+I am Ana, building **Conduit** — a background job runner for Node.js applications.
+
+Conduit lets you schedule, retry, and monitor background jobs without a Redis dependency.
+Target users: backend developers who want a simple, reliable job queue without infrastructure overhead.
+
+# Stack
+
+- **Language:** TypeScript 5.4 (strict mode, no `any`)
+- **Runtime:** Node.js 22 LTS
+- **Framework:** Fastify 4 (HTTP API for the dashboard)
+- **Database:** SQLite via `better-sqlite3` (embedded; no external DB required)
+- **Testing:** Jest 29 + ts-jest + Supertest
+- **Linting:** ESLint (flat config) + Prettier (2-space indent, single quotes)
+- **Package manager:** pnpm 9
+- **CI:** GitHub Actions — lint + test on every PR
+- **No Redis, no RabbitMQ, no external message broker**
+
+# Conventions
+
+- Always `async/await` — no `.then()/.catch()`
+- No classes — all logic is plain functions; data is plain objects with explicit types
+- Error handling: create typed error objects (`{ code, message, cause }`); never throw strings
+- File structure: `src/core/` for domain logic, `src/api/` for HTTP handlers, `src/db/` for DB layer
+- Named exports only — no default exports
+- Test files: `*.test.ts` co-located with source; each test file has one top-level `describe`
+- Database access: only through functions in `src/db/` — no raw SQL in core or API layers
+- No `process.exit()` in library code — only in the CLI entrypoint
+
+# Goals
+
+1. Zero external infrastructure — Conduit should work with just Node.js and a file path
+2. Type safety end-to-end — every public API is fully typed
+3. Readable codebase — optimized for new contributors to get up to speed in < 1 hour
+4. Reliable job delivery — retry logic and failure tracking are first-class, not afterthoughts
+5. Minimal API surface — fewer methods, more composable
+
+# Constraints
+
+- Never introduce a dependency that requires native compilation (no native addons)
+- Never write to disk outside of the configured data directory
+- Never skip tests for a PR — CI must pass; no `--no-verify`
+- Do not use `any` — use `unknown` with type narrowing
+- Do not use class syntax — not even for custom errors
+- Never auto-migrate the database schema — migrations are explicit and versioned
+
+# Examples
+
+## Defining a job handler
+
+```typescript
+import type { JobHandler } from '../types.js'
+
+export const sendWelcomeEmail: JobHandler<{ userId: string }> = async (job) => {
+  const user = await getUser(job.data.userId)
+  await emailService.send({
+    to: user.email,
+    template: 'welcome',
+  })
+}
+```
+
+## Scheduling a job
+
+```typescript
+const jobId = await queue.enqueue('send-welcome-email', {
+  data: { userId: 'usr_123' },
+  runAt: new Date(Date.now() + 5000),
+  maxRetries: 3,
+})
+```
+
+# Anti-patterns
+
+- **God functions:** Functions > 50 lines are a sign something should be extracted
+- **Implicit any via `JSON.parse`:** Always assert the shape with a type guard after parsing
+- **Shared mutable state:** No module-level variables that accumulate state across requests
+- **Catching and re-throwing without context:** Always add `cause` when wrapping errors
+```
+
+---
+
+## Changelog
+
+| Version | Date | Notes |
+|---|---|---|
+| 0.1.0-draft | 2026-03-08 | Initial draft |

package/spec/skills-format.md

@@ -0,0 +1,325 @@
+# Pluribus Skills Format Spec
+
+**Version:** 0.1.0-draft
+**Status:** Draft
+**Date:** 2026-03-08
+
+---
+
+## Overview
+
+A **skill** is a Pluribus adapter that defines how to transform a `pluribus.md` context into a tool-specific output file. Skills are what make Pluribus extensible: adding support for a new AI tool means writing a new skill — a single Markdown file with a defined structure.
+
+This spec defines the skills file format, the built-in skills, and how to write a custom skill.
+
+---
+
+## Skills Directory
+
+Skills live in the `pluribus/skills/` directory of the project:
+
+```
+pluribus/
+└── skills/
+    ├── claude.md        ← built-in (can be overridden)
+    ├── cursor.md        ← built-in (can be overridden)
+    ├── copilot.md       ← built-in (can be overridden)
+    ├── openclaw.md      ← built-in (can be overridden)
+    └── my-custom.md     ← custom skill
+```
+
+**Override behavior:** If a skill file exists in `pluribus/skills/`, it overrides the built-in with the same name. This allows teams to customize how their context is rendered for a specific tool without forking Pluribus.
+
+**Built-in skills** ship with the Pluribus CLI and are used if no local override exists.
+
+---
+
+## Skill File Structure
+
+A skill file is a Markdown file with three required top-level sections and one optional section.
+
+```
+# Output
+# Template
+# Sections
+```
+
+### `# Output`
+
+Declares what file(s) this skill generates. Each line is a target file path relative to the project root.
+
+**Format:**
+```markdown
+# Output
+
+CLAUDE.md
+```
+
+Multiple outputs are supported (e.g., when a tool expects files in multiple locations):
+
+```markdown
+# Output
+
+.github/copilot-instructions.md
+.github/copilot-instructions-workspace.md
+```
+
+**Rules:**
+- Paths are relative to the project root
+- Directories are created automatically if they don't exist
+- Existing files are overwritten on each `pluribus sync` run
+- File paths must be valid for the operating system
+
+---
+
+### `# Template`
+
+Defines how the output file is rendered. The template uses **Pluribus Template Syntax (PTS)** — a minimal, Mustache-inspired syntax embedded in Markdown.
+
+#### Variables
+
+| Variable | Resolves to |
+|---|---|
+| `{{identity}}` | Full content of the `# Identity` section |
+| `{{stack}}` | Full content of the `# Stack` section |
+| `{{conventions}}` | Full content of the `# Conventions` section |
+| `{{goals}}` | Full content of the `# Goals` section |
+| `{{constraints}}` | Full content of the `# Constraints` section |
+| `{{examples}}` | Full content of the `# Examples` section (empty string if absent) |
+| `{{anti-patterns}}` | Full content of the `# Anti-patterns` section (empty string if absent) |
+| `{{<section-slug>}}` | Content of any section, referenced by its slug (lowercase, hyphens) |
+| `{{pluribus.version}}` | The Pluribus CLI version used to generate the file |
+| `{{pluribus.date}}` | ISO 8601 date when the file was generated |
+| `{{pluribus.source}}` | The source file path (`pluribus.md` or `pluribus/context.md`) |
+
+#### Conditional Blocks
+
+Optional sections can be conditionally included using `{{#if}}` blocks:
+
+```
+{{#if examples}}
+## Examples
+
+{{examples}}
+{{/if}}
+```
+
+The block renders only if the section is non-empty.
+
+#### Literal Text
+
+Everything outside of `{{ }}` tags is emitted literally into the output file. This includes any preamble, headings, or formatting that the tool expects.
+
+#### Example Template
+
+```markdown
+# Template
+
+<!-- Generated by Pluribus {{pluribus.version}} on {{pluribus.date}} — do not edit manually -->
+<!-- Source: {{pluribus.source}} -->
+
+# Project Context
+
+## Who I Am
+
+{{identity}}
+
+## Tech Stack
+
+{{stack}}
+
+## How We Write Code
+
+{{conventions}}
+
+## What We're Building Toward
+
+{{goals}}
+
+## Hard Rules
+
+{{constraints}}
+
+{{#if examples}}
+## Code Examples
+
+{{examples}}
+{{/if}}
+
+{{#if anti-patterns}}
+## What to Avoid
+
+{{anti-patterns}}
+{{/if}}
+```
+
+---
+
+### `# Sections`
+
+Declares which sections from `pluribus.md` this skill uses, and in what order. This serves as both documentation and validation input — Pluribus can warn if a required section is missing.
+
+**Format:**
+```markdown
+# Sections
+
+required: identity, stack, conventions, goals, constraints
+optional: examples, anti-patterns
+```
+
+**Rules:**
+- `required` sections must all be present in `pluribus.md` for the skill to render
+- `optional` sections are included if present; silently omitted if absent
+- The order listed here is the recommended rendering order (but the Template controls actual order)
+
+---
+
+### `# Meta` (optional)
+
+Optional metadata about the skill.
+
+```markdown
+# Meta
+
+name: Claude Code
+tool: claude
+description: Generates CLAUDE.md for use with Claude Code (Anthropic)
+version: 1.0.0
+author: Pluribus contributors
+```
+
+---
+
+## Built-in Skills
+
+Pluribus ships with seven built-in skills. Their behavior is defined below. The full template source is available in the Pluribus source repository under `src/skills/`.
+
+### `claude`
+
+- **Output:** `CLAUDE.md`
+- **Target tool:** Claude Code (Anthropic)
+- **Format:** A single Markdown file. Claude Code reads the full file before every session. Optimized for verbosity — Claude benefits from detailed conventions and constraints.
+- **Sections used:** all required + examples + anti-patterns
+
+### `cursor`
+
+- **Output:** `.cursorrules`
+- **Target tool:** Cursor AI editor
+- **Format:** Plain text rules file. Cursor reads this as AI instructions. More concise than Claude — strip headings, emit bullet points.
+- **Sections used:** conventions, constraints, goals (identity and stack are condensed into a single preamble)
+
+### `copilot`
+
+- **Output:** `.github/copilot-instructions.md`
+- **Target tool:** GitHub Copilot
+- **Format:** Markdown. Copilot uses this for inline code suggestions. Focus on conventions and stack; omit identity and goals (Copilot is suggestion-oriented, not context-oriented).
+- **Sections used:** stack, conventions, constraints
+
+### `openclaw`
+
+- **Output:** `AGENTS.md`
+- **Target tool:** OpenClaw AI agent runner
+- **Format:** Markdown with specific sections OpenClaw expects: `## Identity`, `## Role`, `## Stack`, `## Conventions`, `## Constraints`. OpenClaw also reads `SOUL.md` for tone — skills can optionally generate `SOUL.md` as a second output.
+- **Sections used:** all required + examples
+
+### `windsurf`
+
+- **Output:** `.windsurf/rules/pluribus.md`
+- **Target tool:** Windsurf Cascade workspace rules
+- **Format:** Markdown workspace rule with `trigger: always_on` frontmatter. Windsurf currently discovers workspace rules from `.windsurf/rules/*.md`; this keeps the generated Pluribus context version-controlled and shared with the project.
+- **Sections used:** conventions, constraints + optional identity, stack, goals, workflow, anti-patterns, context
+
+### `continue`
+
+- **Output:** `.continue/rules/pluribus.md`
+- **Target tool:** Continue workspace rules
+- **Format:** Markdown local rule with frontmatter (`name`, `alwaysApply: true`). Continue discovers project-specific rules from `.continue/rules/*.md` and includes always-apply rules in Agent, Chat, and Edit mode requests.
+- **Sections used:** conventions, constraints + optional identity, stack, goals, workflow, anti-patterns, context
+
+### `zed`
+
+- **Output:** `.rules`
+- **Target tool:** Zed Editor
+- **Format:** Markdown-style rules file for Zed AI. Focuses on conventions and constraints, with optional project identity, stack, goals, and anti-patterns when present.
+- **Sections used:** conventions, constraints + optional identity, stack, goals, anti-patterns
+
+---
+
+## Writing a Custom Skill
+
+To add support for a new AI tool:
+
+1. Create `pluribus/skills/<tool-name>.md` in your project.
+2. Add the three required sections: `# Output`, `# Template`, `# Sections`.
+3. Run `pluribus sync` — Pluribus will include your custom skill automatically.
+
+**Example: a custom skill for a team-specific review bot**
+
+```markdown
+# Meta
+
+name: Review Bot
+tool: reviewbot
+description: Generates REVIEWBOT.md for a team-specific review assistant
+
+# Output
+
+REVIEWBOT.md
+
+# Template
+
+You are an expert reviewer for the following project.
+
+**Stack:** {{stack}}
+
+**Conventions:**
+{{conventions}}
+
+**Constraints:**
+{{constraints}}
+
+{{#if goals}}
+**Goals:**
+{{goals}}
+{{/if}}
+
+# Sections
+
+required: stack, conventions, constraints
+optional: goals, identity
+```
+
+4. Commit `pluribus/skills/reviewbot.md` to your repo. All team members get the same output on next sync.
+
+---
+
+## Skill Resolution Order
+
+When `pluribus sync` runs, skill resolution follows this order:
+
+1. **Local skill file** in `pluribus/skills/<tool>.md` — if found, use it
+2. **Built-in skill** shipped with the CLI — if found, use it
+3. **Error** — skill not found; log a warning and skip
+
+This allows overriding built-in skills without modifying the CLI.
+
+---
+
+## Validation
+
+A valid skill file must:
+
+- [ ] Contain `# Output` with at least one non-empty file path
+- [ ] Contain `# Template` with at least one `{{variable}}` reference
+- [ ] Contain `# Sections` with at least one `required:` entry
+- [ ] Use only known variable names in the template (unknown variables emit a warning, not an error)
+
+Skill-file validation is planned as a future extension to `pluribus validate`. The current `validate` command checks `pluribus.md` source/import health before sync.
+
+---
+
+## Changelog
+
+| Version | Date | Notes |
+|---|---|---|
+| 0.1.0-draft | 2026-03-08 | Initial draft |