codex-arsenal 0.2.1 → 0.3.0

package/CODEX.md

@@ -91,7 +91,20 @@ Weak criteria ("make it work") require constant clarification.
 
 ---
 
-## 6. Context Awareness
+## 6. Token Budgeting
+
+**Spend context only where it changes the decision.**
+
+- Start with filenames, symbols, and short snippets before reading full files.
+- Prefer `rg` and targeted search over broad recursive reads.
+- Summarize long outputs immediately: key facts, file paths, line numbers, open questions.
+- Do not paste large logs back to the user. Quote only the failing line or smallest useful excerpt.
+- Reuse already-loaded context instead of re-reading the same files.
+- When handing off, compress to: goal, changed files, commands run, verification status, next risk.
+
+---
+
+## 7. Context Awareness
 
 **Codex has a limited context window — use it wisely.**
 
@@ -102,7 +115,7 @@ Weak criteria ("make it work") require constant clarification.
 
 ---
 
-## 7. Tool Use Discipline
+## 8. Tool Use Discipline
 
 **Every tool call has a cost. Make them count.**
 
@@ -118,4 +131,4 @@ Weak criteria ("make it work") require constant clarification.
 - Diffs contain fewer unnecessary changes
 - Fewer rewrites due to overcomplication
 - Clarifying questions come **before** implementation, not after mistakes
-- Agentic runs complete tasks end-to-end without silent failures or scope creep
+- Agentic runs complete tasks end-to-end without silent failures or scope creep

package/README.md

@@ -1,8 +1,8 @@
 # Codex-Arsenal
 
-Practical building blocks for working with OpenAI Codex, Claude Code, and other coding agents.
+Practical building blocks for working with OpenAI Codex.
 
-Codex-Arsenal is not an awesome list. It is a small, installable collection of agent guidelines, skills, prompts, workflows, configs, and plugin sketches that can be copied into real projects.
+Codex-Arsenal is not an awesome list. It is a small, installable collection of Codex guidelines, skills, prompts, workflows, configs, and plugin sketches that can be copied into real projects.
 
 ## Install
 
@@ -39,14 +39,15 @@ npm exec --yes --package=codex-arsenal -- codex-arsenal list
 ## CLI
 
 ```bash
-codex-arsenal init [--yes] [--dir <path>]
+codex-arsenal init [--yes] [--force] [--dir <path>]
 codex-arsenal list
-codex-arsenal get <id...> [--dir <path>]
+codex-arsenal get <id...> [--force] [--dir <path>]
 ```
 
 - `init` opens a small selector. With `--yes`, it installs default items without prompting.
 - `list` prints all installable manifest entries grouped by category.
 - `get` installs one or more manifest entries by id.
+- Existing files are skipped by default. Add `--force` to overwrite them intentionally.
 
 The package is published on npm as [`codex-arsenal`](https://www.npmjs.com/package/codex-arsenal).
 
@@ -57,7 +58,6 @@ The package is published on npm as [`codex-arsenal`](https://www.npmjs.com/packa
 | ID | Installs | Purpose |
 | --- | --- | --- |
 | `codex-md` | `CODEX.md` | Project-local behavioral guardrails for Codex-style agents. |
-| `claude-md` | `CLAUDE.md` | Project-local behavioral guardrails for Claude Code. |
 
 ### Configs
 
@@ -153,6 +153,19 @@ git push --follow-tags
 
 The publish workflow runs on `v*` tags and publishes with OIDC, so it does not require a long-lived `NPM_TOKEN`.
 
+## Codex Plugin Distribution
+
+The npm package is the current public distribution channel. Codex plugin library publishing is separate from npm and currently does not expose a general public submission flow in the public docs.
+
+For now, use one of these paths:
+
+- publish reusable files through `codex-arsenal` on npm;
+- keep plugin sketches under `plugins/`;
+- create a local or team marketplace file at `.agents/plugins/marketplace.json` when you want Codex app users to install a repo plugin from a local marketplace;
+- track OpenAI's Codex plugin documentation for an official public marketplace submission path.
+
+See `docs/codex-plugin-distribution.md` for the current assessment.
+
 ## Contribution Guidelines
 
 Good additions should be:

package/bin/cli.js

@@ -6,9 +6,11 @@ function printHelp() {
   console.log(`codex-arsenal
 
 Usage:
-  codex-arsenal init [--yes] [--dir <path>]
+  codex-arsenal init [--yes] [--force] [--dir <path>]
   codex-arsenal list
-  codex-arsenal get <id...> [--dir <path>]
+  codex-arsenal get <id...> [--force] [--dir <path>]
+
+By default, existing files are skipped. Use --force to overwrite them.
 `);
 }
 
@@ -28,7 +30,7 @@ function nonOptionArgs(args) {
       index += 1;
       continue;
     }
-    if (arg === "--yes" || arg === "-y") {
+    if (arg === "--yes" || arg === "-y" || arg === "--force") {
       continue;
     }
     result.push(arg);
@@ -51,6 +53,7 @@ function printList() {
 async function main(argv) {
   const [command = "init", ...args] = argv;
   const dir = readOption(args, "--dir", readOption(args, "-d", process.cwd()));
+  const force = args.includes("--force");
 
   if (command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -67,12 +70,12 @@ async function main(argv) {
     if (!ids.length) {
       throw new Error("get requires at least one item id");
     }
-    await runInit({ preSelected: findManifestItems(ids), skipPrompt: true, dir });
+    await runInit({ preSelected: findManifestItems(ids), skipPrompt: true, dir, force });
     return;
   }
 
   if (command === "init") {
-    await runInit({ yes: args.includes("--yes") || args.includes("-y"), dir });
+    await runInit({ yes: args.includes("--yes") || args.includes("-y"), dir, force });
     return;
   }
 

package/docs/codex-plugin-distribution.md

@@ -0,0 +1,54 @@
+# Codex Plugin Distribution
+
+## Current Assessment
+
+As of May 23, 2026, the practical public distribution path for Codex-Arsenal is npm. OpenAI's public Codex material says Codex users can browse the plugins library and create plugins in the Codex app, but it does not document a general public submission process for third-party plugins.
+
+Relevant OpenAI pages:
+
+- [Plugins and skills](https://openai.com/academy/codex-plugins-and-skills/)
+- [Codex](https://openai.com/codex/)
+- [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540/)
+
+## Recommended Path
+
+1. Keep publishing installable skills, prompts, configs, and workflow files through `codex-arsenal` on npm.
+2. Keep plugin ideas in `plugins/<name>/` until they become real Codex plugins.
+3. When a plugin is ready for Codex app testing, convert it to a Codex plugin structure with `.codex-plugin/plugin.json`.
+4. Add a repo-local marketplace entry in `.agents/plugins/marketplace.json` for team/local installation.
+5. If OpenAI opens a formal public marketplace submission path, package the plugin manifest, documentation, permission model, and test notes for review.
+
+## Repo Marketplace Shape
+
+Use this shape for local or team discovery:
+
+```json
+{
+  "name": "codex-arsenal",
+  "interface": {
+    "displayName": "Codex-Arsenal"
+  },
+  "plugins": [
+    {
+      "name": "context-window-compressor",
+      "source": {
+        "source": "local",
+        "path": "./plugins/context-window-compressor"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Before Submitting Anywhere
+
+- Define exactly what external systems the plugin touches.
+- Keep permissions narrow and explain authentication.
+- Provide a small demo workflow and screenshots if the plugin has UI.
+- Include test notes for install, auth, failure states, and uninstall.
+- Avoid bundling broad arsenals into one plugin. Publish focused plugins that solve one job well.

package/docs/npm-publishing.md

@@ -0,0 +1,35 @@
+# npm Publishing
+
+This package is set up for npm Trusted Publishing from GitHub Actions.
+
+## One-time npm setup
+
+1. Create or claim the `codex-arsenal` package on npm.
+2. On npmjs.com, open the package settings and add a Trusted Publisher:
+   - Provider: GitHub Actions
+   - Owner: `citron03`
+   - Repository: `Codex-Arsenal`
+   - Workflow filename: `publish.yml`
+   - Environment: `npm`
+3. After the first trusted publish works, set publishing access to require 2FA and disallow tokens.
+
+## Release process
+
+1. Ensure `main` is green.
+2. Update the version:
+
+   ```bash
+   npm version patch
+   ```
+
+3. Push the commit and tag:
+
+   ```bash
+   git push --follow-tags
+   ```
+
+GitHub Actions will run tests, perform a package dry run, and publish to npm from the `v*` tag.
+
+## Why Trusted Publishing
+
+Trusted Publishing uses short-lived OIDC credentials from GitHub Actions instead of a long-lived `NPM_TOKEN`. For public packages published from public repositories, npm also creates provenance attestations automatically.

package/lib/installer.js

@@ -2,12 +2,15 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { BASE_URL, MANIFEST } from "./manifest.js";
 import { fetchFile } from "./fetcher.js";
 
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
 async function readSourceFile(src) {
   try {
-    return await readFile(src, "utf8");
+    return await readFile(path.join(PACKAGE_ROOT, src), "utf8");
   } catch (error) {
     if (error.code !== "ENOENT") {
       throw error;
@@ -21,13 +24,27 @@ export async function installItems(items, targetDir, opts = {}) {
   let installed = 0;
   let failed = 0;
   const successes = [];
+  const skipped = [];
   const failures = [];
   const readSource = opts.readSourceFile || readSourceFile;
+  const force = !!opts.force;
 
   for (const item of items) {
     for (const file of item.files) {
       const destination = path.join(resolvedTarget, file.dest);
       try {
+        if (!force) {
+          try {
+            await readFile(destination, "utf8");
+            skipped.push(file.dest);
+            continue;
+          } catch (error) {
+            if (error.code !== "ENOENT") {
+              throw error;
+            }
+          }
+        }
+
         const content = await readSource(file.src);
         await mkdir(path.dirname(destination), { recursive: true });
         await writeFile(destination, content, "utf8");
@@ -40,7 +57,7 @@ export async function installItems(items, targetDir, opts = {}) {
     }
   }
 
-  return { installed, failed, successes, failures, targetDir: resolvedTarget };
+  return { installed, failed, successes, skipped, failures, targetDir: resolvedTarget };
 }
 
 function defaultItems() {
@@ -78,18 +95,24 @@ export async function runInit(opts = {}) {
 
   if (!selected.length) {
     console.log("No items selected.");
-    return { installed: 0, failed: 0, successes: [], failures: [], targetDir: path.resolve(opts.dir || ".") };
+    return { installed: 0, failed: 0, successes: [], skipped: [], failures: [], targetDir: path.resolve(opts.dir || ".") };
   }
 
   const result = await installItems(selected, opts.dir || process.cwd(), {
-    readSourceFile: opts.readSourceFile
+    readSourceFile: opts.readSourceFile,
+    force: opts.force
   });
   for (const file of result.successes) {
     console.log(`installed ${file}`);
   }
+  for (const file of result.skipped) {
+    console.log(`skipped ${file} (already exists; use --force to overwrite)`);
+  }
   for (const failure of result.failures) {
     console.log(`failed ${failure.dest} (${failure.error})`);
   }
-  console.log(`\nDone: ${result.installed} installed${result.failed ? `, ${result.failed} failed` : ""}.`);
+  console.log(
+    `\nDone: ${result.installed} installed${result.skipped.length ? `, ${result.skipped.length} skipped` : ""}${result.failed ? `, ${result.failed} failed` : ""}.`
+  );
   return result;
 }

package/lib/manifest.js

@@ -11,13 +11,6 @@ export const MANIFEST = [
     files: [{ src: "CODEX.md", dest: "CODEX.md" }],
     default: true
   },
-  {
-    id: "claude-md",
-    category: "Behavior Guidelines",
-    label: "CLAUDE.md",
-    description: "Behavior guidelines adapted for Claude Code agents.",
-    files: [{ src: "CLAUDE.md", dest: "CLAUDE.md" }]
-  },
   {
     id: "config-codex",
     category: "Configs",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-arsenal",
-  "version": "0.2.1",
-  "description": "A practical arsenal of Codex and Claude Code plugins, skills, prompts, workflows, and configs.",
+  "version": "0.3.0",
+  "description": "A practical arsenal of Codex plugins, skills, prompts, workflows, and configs.",
   "type": "module",
   "bin": {
     "codex-arsenal": "bin/cli.js"
@@ -22,9 +22,10 @@
   },
   "files": [
     "bin/",
+    "docs/codex-plugin-distribution.md",
+    "docs/npm-publishing.md",
     "lib/",
     "CODEX.md",
-    "CLAUDE.md",
     "configs/",
     "plugins/",
     "prompts/",
@@ -36,7 +37,6 @@
   },
   "keywords": [
     "codex",
-    "claude-code",
     "ai-agent",
     "developer-tools",
     "prompt-engineering"

package/CLAUDE.md

@@ -1,15 +0,0 @@
-# CLAUDE.md
-
-Use this file as a project-local behavior guide for Claude Code agents.
-
-## Operating Principles
-
-- Read the repository instructions before editing.
-- Keep changes small and directly tied to the task.
-- Prefer tests before behavior changes.
-- Explain uncertainty instead of guessing silently.
-- Do not overwrite user work unless explicitly asked.
-
-## Completion Criteria
-
-Before reporting completion, run the smallest command that proves the change works and summarize the result.