From 2200860865032ada45b5316da67645cf9cb519c6 Mon Sep 17 00:00:00 2001 From: Zack Whitson Date: Thu, 6 Aug 2026 22:29:48 -0500 Subject: [PATCH] Ship the Claude Code plugin listing artifact (v0.1.6) Make this repository the canonical, marketplace-conformant Claude Code distribution artifact instead of standing up a second plugin repo. The existing layout already matches the documented multi-plugin marketplace pattern and both manifests pass `claude plugin validate --strict`, so the work was content, not structure. - README leads with the settled positioning, documents the exact in-session install (`/plugin marketplace add DeliriumPulse/codetruss-plugins` then `/plugin install codetruss@codetruss`), shows a verbatim excerpt of a real `codetruss report latest` receipt, and separates what runs locally from what is hosted so no reader can infer local injection analysis. - Plugin and marketplace descriptions carry the same positioning, which is what the `/plugin` browser actually renders. - Skill instructions were re-checked command by command against the shipped CLI v0.2.30 tarball; every command and flag the skill uses exists in its `--help`. The v0.2.24 minimum is unchanged. - PLUGIN-SUBMISSION.md holds paste-ready answers for the Console community submission and the awesome-claude-code issue form, both of which are humans-only filings. - validate.mjs now pins the positioning line, the install commands, the 0.2.30 verification claim, the analyzer-count line, and the absence of bundled hooks or an MCP server in the Claude manifest. Verified: `npm test` green, `claude plugin validate . --strict` green, `claude plugin validate ./plugins/codetruss-claude --strict` green, and a clean-HOME `marketplace add` plus `install` against the public repo and against this working tree both succeed on Claude Code 2.1.218. Co-Authored-By: Claude Opus 5 --- .claude-plugin/marketplace.json | 8 +- .codex-plugin/plugin.json | 2 +- .codexignore | 1 + PLUGIN-SUBMISSION.md | 133 +++++++++++++++++ README.md | 135 +++++++++++++++--- package-lock.json | 4 +- package.json | 2 +- .../.claude-plugin/plugin.json | 4 +- plugins/codetruss-claude/README.md | 30 +++- plugins/codetruss/.codex-plugin/plugin.json | 2 +- scripts/validate.mjs | 27 ++++ 11 files changed, 315 insertions(+), 33 deletions(-) create mode 100644 PLUGIN-SUBMISSION.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9c966c5..9bc3288 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,10 +1,10 @@ { "$schema": "https://json.schemastore.org/claude-code-marketplace.json", "name": "codetruss", - "description": "Verify the acceptance contract for coding-agent changes locally", - "version": "0.1.5", + "description": "The deterministic first-pass verification gate for AI-written code", + "version": "0.1.6", "metadata": { - "description": "Verify the acceptance contract for coding-agent changes locally" + "description": "The deterministic first-pass verification gate for AI-written code" }, "owner": { "name": "CodeTruss", @@ -14,7 +14,7 @@ { "name": "codetruss", "source": "./plugins/codetruss-claude", - "description": "Enforce approved scope and checks with the separately installed free CodeTruss CLI", + "description": "Bind each agent task to an approved file boundary, run the repository's own checks, and read the signed receipt. Requires the separately installed free CodeTruss CLI.", "category": "development", "tags": ["acceptance-gate", "scope-drift", "verification", "local-first", "coding-agents"] } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 9665419..89443ad 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "codetruss", - "version": "0.1.5", + "version": "0.1.6", "description": "Verify the acceptance contract for coding-agent changes locally.", "author": { "name": "CodeTruss", diff --git a/.codexignore b/.codexignore index 3a2ba46..bd731c4 100644 --- a/.codexignore +++ b/.codexignore @@ -1,5 +1,6 @@ .git/ .github/ +PLUGIN-SUBMISSION.md .claude-plugin/ dist/ node_modules/ diff --git a/PLUGIN-SUBMISSION.md b/PLUGIN-SUBMISSION.md new file mode 100644 index 0000000..3dadf20 --- /dev/null +++ b/PLUGIN-SUBMISSION.md @@ -0,0 +1,133 @@ +# Plugin submission answers + +Paste-ready answers for the two submissions that a human has to file. Both +target audiences forbid or discourage agent-filed submissions, so an agent +prepared this file and a person files the forms. Budget about 10 minutes total. + +Everything below is already true of the repository at HEAD. Nothing here needs +to be built first. + +## Preflight, already done + +- `claude plugin validate . --strict` passes on the marketplace manifest. +- `claude plugin validate ./plugins/codetruss-claude --strict` passes on the + plugin manifest. +- `npm test` passes. +- The self-hosted marketplace is live and installable today: + `/plugin marketplace add DeliriumPulse/codetruss-plugins` then + `/plugin install codetruss@codetruss`. Verified end to end against the public + repository on 2026-08-06 with Claude Code 2.1.218. +- Installed component inventory, as Claude Code reports it: Skills 1, Agents 0, + Hooks 0, MCP servers 0, LSP servers 0. Always-on cost about 108 tokens. + +## 1. Community marketplace, Console form + +Form: + +Use the Console form, not the claude.ai form. The claude.ai form requires a Team +or Enterprise organization; the Console form works for individual authors. + +The form is behind a login, so the exact field labels could not be captured +here. The answer bank below covers what a plugin submission asks for. Match each +value to the closest field and skip what is not asked. + +| Topic | Value to paste | +|---|---| +| Repository | `https://github.com/DeliriumPulse/codetruss-plugins` | +| Marketplace name | `codetruss` | +| Plugin name | `codetruss` | +| Plugin path in repo | `plugins/codetruss-claude` | +| Version | `0.1.6` | +| Category | `development` | +| License | MIT for the plugin wrappers | +| Homepage | `https://codetruss.com/cli` | +| Author | Zack Whitson, `zack@codetruss.com` | +| Issue tracker | `https://github.com/DeliriumPulse/codetruss-plugins/issues` | +| Security contact | `zack@codetruss.com`, policy in `SECURITY.md` | + +Short description, one line: + +> Bind each agent task to an approved file boundary, run the repository's own +> checks, and read the signed receipt. Requires the separately installed free +> CodeTruss CLI. + +Long description, if the form has a larger field: + +> CodeTruss is the deterministic first-pass verification gate for AI-written +> code. This plugin adds one skill that teaches Claude Code to operate the +> separately installed CodeTruss CLI: propose a narrow allow and deny boundary +> for the task, run the repository's own verification commands, and interpret +> the signed receipt the CLI writes for the session. Analysis is deterministic +> and local. The 13 registry analyzers, scope classification, secret detection +> on changed files, and the verification commands all run on the developer's +> machine with no account and no network. Security static analysis and the +> cross-file symbol graph are hosted and run only for an explicitly requested +> full-codebase audit, so a local receipt never contains injection or taint +> analysis and states that in its own "What did not run" section. The plugin +> ships no analyzer, no bundled hook, no MCP server, and no upload path; hook +> installation is delegated to the CLI's own tested installer after the +> developer confirms it. + +If the form asks what the plugin does that could concern a reviewer: + +> The skill invokes a separately installed CLI with the agent's local +> permissions. It never installs software, authenticates, enables +> provider-backed review, or syncs a receipt without explicit developer +> confirmation. It writes only inside the developer's repository. The wrapper +> contains no executable code of its own. + +## 2. awesome-claude-code + +Form: the repository's "Recommend a Resource" issue form at +. +Do not open a pull request; the maintainer only accepts the form. The +CONTRIBUTING file states that coding agents must not file these, so this one has +to be filed by hand. + +Eligibility check, already satisfied: the repository's first commit to the +default branch was on 2026-07-14, which is more than 14 days of active +development. Only one resource may be submitted at a time. + +Field by field: + +- **Title** (prefilled `[Resource]: `): + `[Resource]: CodeTruss` +- **Display Name**: `CodeTruss` +- **Category**: `Skills` +- **Link**: `https://github.com/DeliriumPulse/codetruss-plugins` +- **Author Name**: `Zack Whitson` +- **Author Link**: `https://github.com/DeliriumPulse` +- **Description** (10 to 500 characters, descriptive not promotional, do not + address the reader): + +> A skills-only plugin that drives the CodeTruss CLI as a deterministic +> first-pass gate on agent-written changes. It binds a session to an approved +> file boundary, runs the repository's own verification commands, and reads the +> signed receipt the CLI writes, which records what ran and what did not. The +> CLI is free, needs no account, and analyzes locally; the plugin wrappers are +> MIT licensed. + +That last sentence is deliberate. The list's screening notes treat closed-source +resources that require signup or payment as blockers, so the description states +plainly that the plugin is MIT, the CLI is free, and no account is involved. + +- **Checklist**: check the first five boxes after actually doing them. Leave the + sixth box unchecked. It is a trap that reads "Do not check the following box" + and checking it flags the submission as unread. + +Variant if you would rather list the CLI, which is what the acquisition plan +originally named: change **Link** to +`https://github.com/DeliriumPulse/codetruss-cli`, change **Display Name** to +`CodeTruss Boundary`, and replace "A skills-only plugin that drives the +CodeTruss CLI" with "A local CLI". Everything else stands. The plugin +repository is the recommended entry because the list requires resources specific +to Claude Code and the plugin repository is both Claude Code specific and fully +MIT licensed. + +## Not submitted here, and why + +The GitHub Marketplace listing, the MCP registry publish, and the +`claude-plugins-official` curation request are separate tracks with their own +prerequisites. The official marketplace has no application process; it is a +partner conversation, and the CLI hint protocol is the concrete ask to bring to +it. diff --git a/README.md b/README.md index e0cdf3f..04eeacb 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,45 @@ # CodeTruss agent plugins -Open integration wrappers that teach Claude Code, Codex, and other Agent Skills -clients to use the local-first CodeTruss CLI as an acceptance gate for -AI-generated changes. +CodeTruss is the deterministic first-pass verification gate for AI-written code. +This repository is the open wrapper that puts that gate inside Claude Code and +Codex: a skill that teaches the agent to operate the separately installed +CodeTruss CLI, bind each task to an approved file boundary, run the repository's +own verification commands, and read the signed receipt the CLI writes for every +change. The analysis is deterministic and runs on the developer's machine, the +receipt records exactly what ran and what did not, and anyone can re-verify a +receipt offline. Nothing here calls a model, uploads source, or scores a repo by +vibes. + +The wrappers contain no analyzer, no bundled hook, no MCP server, and no upload +path. They invoke the separately installed CLI, keep deterministic analysis +local, and require explicit consent before installation, provider-backed `--llm` +review, authentication, or receipt `sync`. + +## Install for Claude Code + +Inside a Claude Code session: + +```text +/plugin marketplace add DeliriumPulse/codetruss-plugins +/plugin install codetruss@codetruss +``` + +Or from a shell: -The integrations do not contain an analyzer, upload source code, or call a -CodeTruss service. They invoke the separately installed CLI, keep deterministic -analysis on the developer's machine, and require explicit consent before -installation, provider-backed `--llm` review, authentication, or receipt -`sync`. +```bash +claude plugin marketplace add DeliriumPulse/codetruss-plugins +claude plugin install codetruss@codetruss +``` + +Then ask Claude to `Set up CodeTruss for this repository`. The skill proposes an +allow/deny boundary and verification commands, waits for your confirmation, and +runs the CLI's own guided `codetruss setup` with `--hooks claude` so the tested +CLI installer owns hook installation. From then on the gate runs on the agent's +lifecycle events and writes a receipt per session. + +The owned marketplace is live now. CodeTruss is not currently listed in +Anthropic's reviewed community catalog or its separately curated official +marketplace. ## Prerequisites @@ -16,19 +47,84 @@ installation, provider-backed `--llm` review, authentication, or receipt - Node.js 20.9 or newer - CodeTruss CLI v0.2.24 or newer from -The skill can explain the official installer when the CLI is missing, but it -must not install software without the developer's confirmation. +Skill instructions in this repository are verified against the shipped CLI +v0.2.30. The skill can explain the official installer when the CLI is missing, +but it must not install software without the developer's confirmation. -## Claude Code +## What a receipt looks like -```bash -claude plugin marketplace add DeliriumPulse/codetruss-plugins -claude plugin install codetruss@codetruss +Verbatim excerpt from `codetruss report latest` after a review where the agent +also touched a denied path and committed a live key: + +```markdown +# CodeTruss receipt — FAILED + +- **Session:** `20260807T032401919Z-42bd50` +- **Task:** Add a SESSION_TTL constant to src/auth.ts +- **Starting commit:** `decff98665b27d53ec643546829342bbb1b4c878` +- **Policy SHA-256:** `d13f4367129bb7683c486d4d4e8e876bc1e9a7f541cd0e539945743b16d95a03` + +## Verdict: FAILED + +- 1 high/critical security or dependency finding(s) affect changed files +- 1 file(s) changed in denied paths: infra/deploy.sh +- 1 file(s) changed outside approved scope: .codetruss.yml + +## Changed files (3) + +| Path | Change | Scope | Sensitive | Lines | +|---|---|---|---|---:| +| `.codetruss.yml` | added | unexpected | policy | +16/−0 | +| `infra/deploy.sh` | added | denied | — | +3/−0 | +| `src/auth.ts` | modified | allowed | — | +2/−0 | + +## Introduced or worsened analyzer findings (1) + +| Severity | Analyzer | Location | Finding | +|---|---|---|---| +| HIGH | secrets | `infra/deploy.sh:2` | Possible Stripe live secret key committed in deploy.sh | + +## Analysis profile + +The 13 deterministic registry analyzers ran locally on this machine. + +### What did not run + +- **Security static analysis (SAST).** No injection or taint analysis was + performed. SQL injection, command injection, code injection, path traversal, + SSRF, open redirect, XSS and insecure deserialization were never checked, so + this receipt says nothing either way about those classes. ``` -The owned marketplace is live now. CodeTruss is not currently listed in -Anthropic's reviewed community catalog or its separately curated official -marketplace. +`codetruss verify latest` re-checks the signature over those bytes and prints +`verified 20260807T032401919Z-42bd50 (FAILED)`. + +## What runs where + +Local and deterministic, with no account and no network required: + +- the 13 registry analyzers listed in the receipt's analysis profile; +- scope classification of every changed file against the approved allow/deny + boundary, including untracked and sensitive-surface detection; +- secret detection on changed files; +- the repository's own verification commands, executed against a fresh + materialization of the final Git tree; +- receipt signing and offline `codetruss verify`. + +Hosted, and only when the developer explicitly asks for it: + +- security static analysis and the cross-file symbol graph, which back the + full-codebase audit and the Health scores; +- receipt `sync` to a CodeTruss account. + +A local receipt never contains injection or taint analysis, and it says so in +its own "What did not run" section. Optional provider-backed `--llm` review is +force-disabled under agent hooks, so a hook receipt is always deterministic +evidence only. + +Measured behaviour on public repositories is published at +. CLI downloads, checksums, and the SBOM are at +. ## Codex @@ -50,7 +146,7 @@ npx --yes skills add DeliriumPulse/codetruss-plugins \ --skill codetruss --agent claude-code codex -y ``` -For an immutable install, pin the current reviewed release: +For an immutable install, pin the most recent published release: ```bash npx --yes skills add \ @@ -82,7 +178,8 @@ self-contained. ```bash npm test -claude plugin validate ./plugins/codetruss-claude +claude plugin validate . --strict +claude plugin validate ./plugins/codetruss-claude --strict python3 /path/to/plugin-creator/scripts/validate_plugin.py ./plugins/codetruss npm run release:verify ``` diff --git a/package-lock.json b/package-lock.json index c79a5fe..c5dbd52 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "codetruss-agent-plugins", - "version": "0.1.5", + "version": "0.1.6", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "codetruss-agent-plugins", - "version": "0.1.5", + "version": "0.1.6", "license": "MIT", "engines": { "node": ">=20.9" diff --git a/package.json b/package.json index 6f786cc..56554da 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codetruss-agent-plugins", - "version": "0.1.5", + "version": "0.1.6", "private": true, "description": "Open Claude Code, Codex, and Agent Skills wrappers for the CodeTruss CLI", "license": "MIT", diff --git a/plugins/codetruss-claude/.claude-plugin/plugin.json b/plugins/codetruss-claude/.claude-plugin/plugin.json index 4513060..6c2e6da 100644 --- a/plugins/codetruss-claude/.claude-plugin/plugin.json +++ b/plugins/codetruss-claude/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "codetruss", - "version": "0.1.5", - "description": "Verify coding-agent changes locally with the separately installed free CodeTruss CLI.", + "version": "0.1.6", + "description": "The deterministic first-pass verification gate for AI-written code. Binds each agent task to an approved file boundary, runs the repository's own checks, and reads the signed receipt. Requires the separately installed free CodeTruss CLI.", "author": { "name": "CodeTruss", "email": "zack@codetruss.com", diff --git a/plugins/codetruss-claude/README.md b/plugins/codetruss-claude/README.md index 649f0a8..78eb08d 100644 --- a/plugins/codetruss-claude/README.md +++ b/plugins/codetruss-claude/README.md @@ -1,7 +1,19 @@ # CodeTruss for Claude Code +CodeTruss is the deterministic first-pass verification gate for AI-written code. This plugin teaches Claude Code to operate the separately installed free -CodeTruss CLI as a local acceptance gate for coding-agent changes. +CodeTruss CLI as that gate: bind the task to an approved file boundary, run the +repository's own verification commands, and read the signed receipt the CLI +writes for every change. + +Install: + +```text +/plugin marketplace add DeliriumPulse/codetruss-plugins +/plugin install codetruss@codetruss +``` + +Then ask Claude to `Set up CodeTruss for this repository`. Prerequisites: @@ -9,10 +21,17 @@ Prerequisites: - Node.js 20.9 or newer - CodeTruss CLI v0.2.24 or newer from +Skill instructions are verified against the shipped CLI v0.2.30. + The plugin contains no analyzer, bundled hook, MCP server, background service, or upload path. It delegates hook installation to the tested CLI after developer -confirmation. Deterministic checks stay local. Provider-backed review, -authentication, and receipt sync require separate explicit developer actions. +confirmation. Deterministic checks stay local: the 13 registry analyzers, scope +classification, secret detection on changed files, and the repository's own +verification commands. Security static analysis and the cross-file symbol graph +are hosted and run only for an explicitly requested full-codebase audit, so a +local receipt never contains injection or taint analysis and states that in its +own "What did not run" section. Provider-backed review, authentication, and +receipt sync require separate explicit developer actions. Troubleshooting: @@ -22,6 +41,8 @@ Troubleshooting: and hook flow. Do not replace it with hand-edited setup steps. - Run `codetruss hooks status claude` and `codetruss hooks doctor claude` before changing or reinstalling Claude settings. +- Run `codetruss report latest` to read the newest receipt and + `codetruss verify latest` to re-check its signature offline. - Exit 1 means `REVIEW_REQUIRED`, exit 2 means `FAILED`, and both still produce a receipt. Exit 3 is a usage or environment failure. - Report wrapper problems at @@ -29,6 +50,9 @@ Troubleshooting: - Follow for private vulnerability reporting and the current product security boundary. +Measured behaviour on public repositories is published at +. + The wrapper files in this package are MIT licensed. The separately installed CLI is source-visible and free to use under the CodeTruss CLI Proprietary License and CodeTruss Terms of Service. diff --git a/plugins/codetruss/.codex-plugin/plugin.json b/plugins/codetruss/.codex-plugin/plugin.json index 8f2b463..382fc0b 100644 --- a/plugins/codetruss/.codex-plugin/plugin.json +++ b/plugins/codetruss/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "codetruss", - "version": "0.1.5", + "version": "0.1.6", "description": "Verify the acceptance contract for coding-agent changes locally.", "author": { "name": "CodeTruss", diff --git a/scripts/validate.mjs b/scripts/validate.mjs index 202cbee..ae3100f 100644 --- a/scripts/validate.mjs +++ b/scripts/validate.mjs @@ -62,6 +62,11 @@ for (const manifest of [claudeManifest, codexManifest, rootManifest]) { assert.equal(manifest.skills, './skills/') assert.match(manifest.homepage, /^https:\/\/codetruss\.com\//) } +assert.ok(!('hooks' in claudeManifest), 'plugin must delegate hooks to the tested CLI installer') +assert.ok(!('mcpServers' in claudeManifest), 'local-first wrapper must not add an MCP server') +for (const manifest of [claudeManifest, codexManifest, rootManifest]) { + assert.doesNotMatch(manifest.description, /proof layer/i) +} for (const manifest of [codexManifest, rootManifest]) { assert.equal(manifest.interface.privacyPolicyURL, 'https://codetruss.com/privacy') assert.equal(manifest.interface.termsOfServiceURL, 'https://codetruss.com/terms') @@ -170,6 +175,16 @@ assert.match(readme, /codetruss-plugins\/tree\/v0\.1\.5/) assert.doesNotMatch(readme, /official listing remains pending review/) assert.match(readme, /not currently listed in\s+Anthropic's reviewed community catalog/) assert.match(readme, /not currently listed in\s+OpenAI's public Plugin Directory/) +assert.match( + readme, + /CodeTruss is the deterministic first-pass verification gate for\s+AI-written code\./, +) +assert.match(readme, /\/plugin marketplace add DeliriumPulse\/codetruss-plugins/) +assert.match(readme, /\/plugin install codetruss@codetruss/) +assert.match(readme, /verified against the shipped CLI\s+v0\.2\.30/) +assert.match(readme, /The 13 deterministic registry analyzers ran locally on this machine\./) +assert.match(readme, /https:\/\/codetruss\.com\/benchmark/) +assert.match(readme, /https:\/\/codetruss\.com\/cli/) for (const path of [ 'plugins/codetruss/README.md', @@ -180,4 +195,16 @@ for (const path of [ assert.match(pluginReadme, /Run `codetruss setup` for the guided local policy/) } +const claudePluginReadme = await read('plugins/codetruss-claude/README.md') +assert.match(claudePluginReadme, /\/plugin install codetruss@codetruss/) +assert.match(claudePluginReadme, /verified against the shipped CLI v0\.2\.30/) + +const submission = await read('PLUGIN-SUBMISSION.md') +assert.match(submission, /platform\.claude\.com\/plugins\/submit/) +assert.match(submission, /DeliriumPulse\/codetruss-plugins/) + +for (const prose of [readme, claudePluginReadme, submission]) { + assert.doesNotMatch(prose, /proof layer/i) +} + process.stdout.write('CodeTruss Claude, Codex, and Agent Skills packages validated.\n')