codex-arsenal 0.1.0 → 0.2.0

package/CODEX.md

@@ -1,121 +1,121 @@
-# CODEX.md
-
-> Behavioral guidelines to reduce common LLM coding mistakes.  
-> Merge with project-specific instructions as needed.  
-> **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
-
----
-
-## 1. Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them — don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, **stop**. Name what's confusing. Ask.
-
----
-
-## 2. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-> Ask yourself: *"Would a senior engineer say this is overcomplicated?"*  
-> If yes — simplify.
-
----
-
-## 3. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, **mention it — don't delete it**.
-
-When your changes create orphans:
-
-- Remove imports / variables / functions that **YOUR changes** made unused.
-- Don't remove pre-existing dead code unless asked.
-
-> **The test:** Every changed line should trace directly to the user's request.
-
----
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-
-| Vague | Verifiable |
-|-------|------------|
-| "Add validation" | "Write tests for invalid inputs, then make them pass" |
-| "Fix the bug" | "Write a test that reproduces it, then make it pass" |
-| "Refactor X" | "Ensure tests pass before and after" |
-
-For multi-step tasks, state a brief plan:
-
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently.  
-Weak criteria ("make it work") require constant clarification.
-
----
-
-## 5. Agentic Execution (Codex-specific)
-
-**Codex runs with more autonomy — so guardrails matter more.**
-
-- **Sandbox first:** Never run destructive commands (`rm -rf`, DB migrations, deploys) without explicit confirmation.
-- **Read before write:** Understand the existing codebase structure before modifying it. Use `find`, `grep`, `cat` to build context.
-- **One action at a time:** In agentic loops, complete and verify each step before proceeding to the next.
-- **Fail loudly:** If a step fails, surface the error immediately. Don't try to work around it silently.
-- **Scope your shell:** Prefer relative paths over absolute. Never assume a working directory without confirming it.
-
----
-
-## 6. Context Awareness
-
-**Codex has a limited context window — use it wisely.**
-
-- Don't re-read files you've already loaded. Reference prior output instead.
-- When summarizing large codebases, compress systematically: directory tree → key files → function signatures.
-- If context is filling up, state it: *"I'm approaching context limits. Summarizing and continuing."*
-- Prefer targeted grep/search over reading entire files when looking for a specific symbol.
-
----
-
-## 7. Tool Use Discipline
-
-**Every tool call has a cost. Make them count.**
-
-- Batch related reads into a single operation where possible.
-- Don't run the same command twice to "verify" — if you need to verify, define the assertion first.
-- Avoid speculative exploration ("let me just check...") — know what you're looking for before you look.
-- If a tool fails, diagnose before retrying. Don't brute-force.
-
----
-
-## ✅ These guidelines are working if:
-
-- Diffs contain fewer unnecessary changes
-- Fewer rewrites due to overcomplication
-- Clarifying questions come **before** implementation, not after mistakes
+# CODEX.md
+
+> Behavioral guidelines to reduce common LLM coding mistakes.  
+> Merge with project-specific instructions as needed.  
+> **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+---
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, **stop**. Name what's confusing. Ask.
+
+---
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+> Ask yourself: *"Would a senior engineer say this is overcomplicated?"*  
+> If yes — simplify.
+
+---
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, **mention it — don't delete it**.
+
+When your changes create orphans:
+
+- Remove imports / variables / functions that **YOUR changes** made unused.
+- Don't remove pre-existing dead code unless asked.
+
+> **The test:** Every changed line should trace directly to the user's request.
+
+---
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+| Vague | Verifiable |
+|-------|------------|
+| "Add validation" | "Write tests for invalid inputs, then make them pass" |
+| "Fix the bug" | "Write a test that reproduces it, then make it pass" |
+| "Refactor X" | "Ensure tests pass before and after" |
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently.  
+Weak criteria ("make it work") require constant clarification.
+
+---
+
+## 5. Agentic Execution (Codex-specific)
+
+**Codex runs with more autonomy — so guardrails matter more.**
+
+- **Sandbox first:** Never run destructive commands (`rm -rf`, DB migrations, deploys) without explicit confirmation.
+- **Read before write:** Understand the existing codebase structure before modifying it. Use `find`, `grep`, `cat` to build context.
+- **One action at a time:** In agentic loops, complete and verify each step before proceeding to the next.
+- **Fail loudly:** If a step fails, surface the error immediately. Don't try to work around it silently.
+- **Scope your shell:** Prefer relative paths over absolute. Never assume a working directory without confirming it.
+
+---
+
+## 6. Context Awareness
+
+**Codex has a limited context window — use it wisely.**
+
+- Don't re-read files you've already loaded. Reference prior output instead.
+- When summarizing large codebases, compress systematically: directory tree → key files → function signatures.
+- If context is filling up, state it: *"I'm approaching context limits. Summarizing and continuing."*
+- Prefer targeted grep/search over reading entire files when looking for a specific symbol.
+
+---
+
+## 7. Tool Use Discipline
+
+**Every tool call has a cost. Make them count.**
+
+- Batch related reads into a single operation where possible.
+- Don't run the same command twice to "verify" — if you need to verify, define the assertion first.
+- Avoid speculative exploration ("let me just check...") — know what you're looking for before you look.
+- If a tool fails, diagnose before retrying. Don't brute-force.
+
+---
+
+## ✅ These guidelines are working if:
+
+- 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

package/lib/manifest.js

@@ -60,6 +60,15 @@ export const MANIFEST = [
       { src: "skills/test-gen/prompt.md", dest: "skills/test-gen/prompt.md" }
     ]
   },
+  {
+    id: "skill-publishing-npm-packages",
+    category: "Skills",
+    label: "publishing-npm-packages",
+    description: "A Codex skill for preparing, troubleshooting, and automating npm package releases.",
+    files: [
+      { src: "skills/publishing-npm-packages/SKILL.md", dest: "skills/publishing-npm-packages/SKILL.md" }
+    ]
+  },
   {
     id: "plugin-context-window-compressor",
     category: "Plugins",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-arsenal",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A practical arsenal of Codex and Claude Code plugins, skills, prompts, workflows, and configs.",
   "type": "module",
   "bin": {

package/skills/publishing-npm-packages/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: publishing-npm-packages
+description: Use when preparing, troubleshooting, or automating npm package releases, especially GitHub Actions Trusted Publishing, provenance, 2FA publish errors, version tags, npm pack checks, or npx CLI packages.
+---
+
+# Publishing npm Packages
+
+## Overview
+
+Publish npm packages through a verified release path. Prefer GitHub Actions Trusted Publishing with OIDC over long-lived `NPM_TOKEN` secrets.
+
+## Release Decision
+
+Use this order:
+
+1. Existing package with Trusted Publishing configured: release by version tag.
+2. First publish for a new package: create the package with npm 2FA or a short-lived/granular manual path, then configure Trusted Publishing.
+3. CI provider unsupported or private dependency constraints: use a granular npm token with the narrowest publish scope.
+
+## Preflight
+
+Before changing release config, inspect:
+
+- `package.json`: `name`, `version`, `bin`, `files`, `repository.url`, `publishConfig.access`
+- `package-lock.json`: present when workflow uses `npm ci`
+- `.github/workflows/*.yml`: CI and publish workflow
+- npm package state: `npm info <package-name>` when npm is available
+
+For GitHub Actions Trusted Publishing, require:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+```
+
+Use GitHub-hosted runners, Node 22.14+ or 24, npm 11.5.1+, and `actions/setup-node` with `registry-url: "https://registry.npmjs.org"`.
+
+## Package Metadata
+
+Keep npm metadata boring and exact:
+
+```json
+{
+  "type": "module",
+  "bin": {
+    "package-name": "bin/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OWNER/REPO.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+Do not use `./` in `bin` paths if npm reports that it auto-corrected the script name or path. Run `npm pkg fix` when available, or apply the equivalent minimal metadata fix.
+
+## Trusted Publishing Setup
+
+Configure on npmjs.com after the package exists:
+
+```text
+Packages -> PACKAGE -> Settings -> Trusted publishing
+Provider: GitHub Actions
+Owner: GitHub owner
+Repository: GitHub repository
+Workflow filename: publish.yml
+Environment: npm, if the workflow uses environment: npm
+```
+
+The workflow filename is only `publish.yml`, not `.github/workflows/publish.yml`.
+
+If the workflow uses `environment: npm`, ensure GitHub has an environment named `npm`.
+
+## Recommended Workflows
+
+Use separate CI and publish workflows.
+
+CI:
+
+```yaml
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          package-manager-cache: false
+      - run: npm ci
+      - run: npm test
+      - run: npm pack --dry-run
+```
+
+Publish:
+
+```yaml
+name: Publish to npm
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+          package-manager-cache: false
+      - run: npm ci
+      - run: npm test
+      - run: npm pack --dry-run
+      - run: npm publish
+```
+
+## Release Procedure
+
+1. Verify clean state: `git status --short`.
+2. Run tests: `npm test`.
+3. Inspect package contents: `npm pack --dry-run`.
+4. Bump version: `npm version patch`, `minor`, or `major`.
+5. Push commit and tag: `git push --follow-tags`.
+6. Check GitHub Actions publish job.
+7. Smoke test after publish: `npx <package-name> --help` or `npx <package-name> list`.
+
+## Failure Handling
+
+| Symptom | Root Cause | Response |
+| --- | --- | --- |
+| `E403 Two-factor authentication... required` | Manual publish without required 2FA or publish token | Enable npm 2FA and retry manual first publish, or use Trusted Publishing after package exists |
+| `ENEEDAUTH` in GitHub Actions | Trusted Publisher mismatch or missing OIDC permission | Check owner, repo, workflow filename, environment name, and `id-token: write` |
+| npm auto-corrects `package.json` | Metadata is publishable but not canonical | Run `npm pkg fix` or make the exact minimal metadata change |
+| `npm ci` fails in CI | Missing or stale lockfile | Generate/update `package-lock.json` with the intended npm version |
+| Package name unavailable | Name already exists or scope mismatch | Rename to a scoped package such as `@owner/name` and set public access |
+
+## Guardrails
+
+- Never publish without reading the `npm pack --dry-run` file list.
+- Never add `NPM_TOKEN` when Trusted Publishing works for the project.
+- Never reuse a version after a failed or partial publish; check `npm info <name> versions`.
+- Never claim a package is published until npm or `npx` confirms the released version.