From 70bb0d23443114f76553a20a2e57da596654d9df Mon Sep 17 00:00:00 2001 From: Masoud Golchin Date: Mon, 7 Sep 2026 10:45:46 +0300 Subject: [PATCH] feat: add Codex support with shared toolkit skills --- .agents/plugins/marketplace.json | 116 ++++++++++++++++ .claude-plugin/marketplace.json | 20 +-- .github/workflows/validate-plugins.yml | 25 ++++ AGENTS.md | 54 ++++++++ CLAUDE.md | 130 +----------------- README.md | 91 +++++++++--- docs/change-log.md | 16 +++ docs/codex.md | 129 +++++++++++++++++ examples/codex/disable-refact.toml | 28 ++++ plugins/base/.claude-plugin/plugin.json | 5 +- plugins/base/.codex-plugin/plugin.json | 32 +++++ plugins/base/commands/refact.md | 61 +------- .../hooks/{hooks.json => claude-hooks.json} | 0 .../base/hooks/preflight-refact-config.mjs | 2 +- plugins/base/references/plugin-runtime.md | 43 ++++++ plugins/base/skills/asana/SKILL.md | 2 + plugins/base/skills/code-development/SKILL.md | 2 + .../base/skills/extract-learnings/SKILL.md | 2 + plugins/base/skills/git-workflow/SKILL.md | 2 + plugins/base/skills/manage-plugins/SKILL.md | 15 +- .../skills/manage-plugins/references/codex.md | 72 ++++++++++ plugins/base/skills/refact-toolkit/SKILL.md | 44 ++++++ .../setup-refact-control-mcp-server/SKILL.md | 8 +- .../references/codex.md | 35 +++++ plugins/base/skills/sync-env-vars/SKILL.md | 6 +- .../skills/sync-env-vars/scripts/sync-env.sh | 4 +- .../skills/update-project-config/SKILL.md | 2 + .../base/skills/verify-visual-change/SKILL.md | 2 + .../skills/writing-client-updates/SKILL.md | 2 + plugins/client/.claude-plugin/plugin.json | 11 +- plugins/client/.codex-plugin/plugin.json | 28 ++++ plugins/client/references/plugin-runtime.md | 43 ++++++ .../skills/draft-discovery-proposal/SKILL.md | 2 + .../client/skills/render-deliverable/SKILL.md | 2 + plugins/insights/.claude-plugin/plugin.json | 15 +- plugins/insights/.codex-plugin/plugin.json | 32 +++++ plugins/insights/references/plugin-runtime.md | 43 ++++++ plugins/insights/skills/ahrefs/SKILL.md | 2 + plugins/insights/skills/ga4/SKILL.md | 2 + plugins/insights/skills/gsc/SKILL.md | 2 + plugins/insights/skills/gtm/SKILL.md | 2 + plugins/insights/skills/pagespeed/SKILL.md | 10 +- plugins/memory/.claude-plugin/plugin.json | 7 +- plugins/memory/.codex-plugin/plugin.json | 30 ++++ .../hooks/{hooks.json => claude-hooks.json} | 0 plugins/memory/references/plugin-runtime.md | 43 ++++++ plugins/memory/skills/close-ticket/SKILL.md | 2 + plugins/memory/skills/ingest-input/SKILL.md | 2 + plugins/memory/skills/log-entry/SKILL.md | 2 + plugins/memory/skills/open-ticket/SKILL.md | 2 + plugins/memory/skills/process-docs/SKILL.md | 2 + plugins/memory/skills/project-status/SKILL.md | 2 + .../skills/update-canonical-record/SKILL.md | 2 + plugins/migrate/.claude-plugin/plugin.json | 13 +- plugins/migrate/.codex-plugin/plugin.json | 28 ++++ plugins/migrate/references/plugin-runtime.md | 43 ++++++ .../skills/migrate-to-marketplace/SKILL.md | 14 ++ plugins/nextjs/.claude-plugin/plugin.json | 11 +- plugins/nextjs/.codex-plugin/plugin.json | 28 ++++ plugins/nextjs/references/plugin-runtime.md | 43 ++++++ plugins/nextjs/skills/nextjs-dev/SKILL.md | 2 + .../skills/setup-netlify-deploy/SKILL.md | 2 + .../nextjs/skills/setup-nextjs-app/SKILL.md | 2 + .../skills/setup-vercel-deploy/SKILL.md | 2 + plugins/ops/.claude-plugin/plugin.json | 12 +- plugins/ops/.codex-plugin/plugin.json | 29 ++++ plugins/ops/references/plugin-runtime.md | 43 ++++++ plugins/ops/skills/cloudflare/SKILL.md | 2 + plugins/ops/skills/sentry/SKILL.md | 2 + plugins/testing/.claude-plugin/plugin.json | 12 +- plugins/testing/.codex-plugin/plugin.json | 29 ++++ plugins/testing/references/plugin-runtime.md | 43 ++++++ .../testing/skills/backfill-tests/SKILL.md | 2 + .../testing/skills/integration-tests/SKILL.md | 2 + .../skills/red-green-refactor/SKILL.md | 2 + plugins/testing/skills/tdd-plan/SKILL.md | 2 + plugins/testing/skills/tdd/SKILL.md | 2 + plugins/wordpress/.claude-plugin/plugin.json | 14 +- plugins/wordpress/.codex-plugin/plugin.json | 30 ++++ .../hooks/{hooks.json => claude-hooks.json} | 0 .../wordpress/references/plugin-runtime.md | 43 ++++++ .../skills/install-wp-skills/SKILL.md | 11 ++ .../wordpress/skills/plugin-update/SKILL.md | 2 + .../skills/setup-kinsta-deploy/SKILL.md | 2 + .../skills/setup-wpengine-deploy/SKILL.md | 2 + plugins/wordpress/skills/wp-env/SKILL.md | 2 + requirements-dev.txt | 1 + scripts/check-plugins.py | 76 ++++++++++ scripts/sync-codex.mjs | 81 +++++++++++ shared/plugin-runtime.md | 41 ++++++ tests/plugin-support.test.mjs | 82 +++++++++++ 91 files changed, 1754 insertions(+), 241 deletions(-) create mode 100644 .agents/plugins/marketplace.json create mode 100644 .github/workflows/validate-plugins.yml create mode 100644 AGENTS.md create mode 100644 docs/codex.md create mode 100644 examples/codex/disable-refact.toml create mode 100644 plugins/base/.codex-plugin/plugin.json rename plugins/base/hooks/{hooks.json => claude-hooks.json} (100%) create mode 100644 plugins/base/references/plugin-runtime.md create mode 100644 plugins/base/skills/manage-plugins/references/codex.md create mode 100644 plugins/base/skills/refact-toolkit/SKILL.md create mode 100644 plugins/base/skills/setup-refact-control-mcp-server/references/codex.md create mode 100644 plugins/client/.codex-plugin/plugin.json create mode 100644 plugins/client/references/plugin-runtime.md create mode 100644 plugins/insights/.codex-plugin/plugin.json create mode 100644 plugins/insights/references/plugin-runtime.md create mode 100644 plugins/memory/.codex-plugin/plugin.json rename plugins/memory/hooks/{hooks.json => claude-hooks.json} (100%) create mode 100644 plugins/memory/references/plugin-runtime.md create mode 100644 plugins/migrate/.codex-plugin/plugin.json create mode 100644 plugins/migrate/references/plugin-runtime.md create mode 100644 plugins/nextjs/.codex-plugin/plugin.json create mode 100644 plugins/nextjs/references/plugin-runtime.md create mode 100644 plugins/ops/.codex-plugin/plugin.json create mode 100644 plugins/ops/references/plugin-runtime.md create mode 100644 plugins/testing/.codex-plugin/plugin.json create mode 100644 plugins/testing/references/plugin-runtime.md create mode 100644 plugins/wordpress/.codex-plugin/plugin.json rename plugins/wordpress/hooks/{hooks.json => claude-hooks.json} (100%) create mode 100644 plugins/wordpress/references/plugin-runtime.md create mode 100644 requirements-dev.txt create mode 100644 scripts/check-plugins.py create mode 100644 scripts/sync-codex.mjs create mode 100644 shared/plugin-runtime.md create mode 100644 tests/plugin-support.test.mjs diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..583c93e --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,116 @@ +{ + "name": "refact-os", + "interface": { + "displayName": "Refact Toolkit" + }, + "plugins": [ + { + "name": "base", + "source": { + "source": "local", + "path": "./plugins/base" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "client", + "source": { + "source": "local", + "path": "./plugins/client" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "ops", + "source": { + "source": "local", + "path": "./plugins/ops" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "insights", + "source": { + "source": "local", + "path": "./plugins/insights" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "nextjs", + "source": { + "source": "local", + "path": "./plugins/nextjs" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "wordpress", + "source": { + "source": "local", + "path": "./plugins/wordpress" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "testing", + "source": { + "source": "local", + "path": "./plugins/testing" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "migrate", + "source": { + "source": "local", + "path": "./plugins/migrate" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "memory", + "source": { + "source": "local", + "path": "./plugins/memory" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6446dd0..eef7f09 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,6 +1,6 @@ { "name": "refact-os", - "version": "2.12.1", + "version": "2.13.0", "owner": { "name": "Refact Developer", "email": "dev@refact.co" @@ -8,7 +8,7 @@ "plugins": [ { "name": "base", - "version": "1.7.0", + "version": "1.9.0", "source": "./plugins/base", "description": "Base toolkit: git workflow, code-dev gates, Asana, env sync, learnings, client updates, slim project config, Refact Control MCP setup + the /base:refact command + TS/JS LSP.", "author": { @@ -30,7 +30,7 @@ }, { "name": "client", - "version": "1.1.2", + "version": "1.2.0", "source": "./plugins/client", "description": "Client deliverables: discovery-first proposals and branded print-ready PDF rendering.", "author": { @@ -48,7 +48,7 @@ }, { "name": "ops", - "version": "1.1.0", + "version": "1.2.0", "source": "./plugins/ops", "description": "Ops integrations: Cloudflare client-zone operations and Sentry backlog triage.", "author": { @@ -67,7 +67,7 @@ }, { "name": "insights", - "version": "1.1.0", + "version": "1.2.0", "source": "./plugins/insights", "description": "Site insights: SEO (Ahrefs, Search Console), web analytics (GA4), tag management (GTM), and PageSpeed/Core Web Vitals.", "author": { @@ -89,7 +89,7 @@ }, { "name": "nextjs", - "version": "1.0.2", + "version": "1.1.0", "source": "./plugins/nextjs", "description": "Next.js: scaffold or adopt an app, run/diagnose it, and set up Vercel or Netlify deploys.", "author": { @@ -107,7 +107,7 @@ }, { "name": "wordpress", - "version": "1.1.0", + "version": "1.2.0", "source": "./plugins/wordpress", "description": "WordPress: local wp-env stack, safe plugin updates with QA + rollback, Kinsta/WP Engine deploy workflows + PHP LSP.", "author": { @@ -127,7 +127,7 @@ }, { "name": "testing", - "version": "1.2.0", + "version": "1.3.0", "source": "./plugins/testing", "description": "Testing: TDD harness (plan -> red-green-refactor) plus WordPress characterization and real-plugin integration tests.", "author": { @@ -146,7 +146,7 @@ }, { "name": "migrate", - "version": "1.1.0", + "version": "1.2.0", "source": "./plugins/migrate", "description": "One-time migration: move a refact-os-scaffolded project off the npm scaffold and onto this plugin marketplace — detect, back up, remove the generated trees, slim the config, and print the pack install commands.", "author": { @@ -164,7 +164,7 @@ }, { "name": "memory", - "version": "1.0.0", + "version": "1.1.0", "source": "./plugins/memory", "description": "Memory workflows on the refact-memory mount: ingest evidence, tracker entries, canonical-record edits, ticket anchor + outcome, status scan — plus a SessionStart hook that keeps the local clone fresh.", "author": { diff --git a/.github/workflows/validate-plugins.yml b/.github/workflows/validate-plugins.yml new file mode 100644 index 0000000..8e65ee8 --- /dev/null +++ b/.github/workflows/validate-plugins.yml @@ -0,0 +1,25 @@ +name: Validate plugins + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '22' + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: python -m pip install -r requirements-dev.txt + - run: node scripts/sync-codex.mjs --check + - run: python scripts/check-plugins.py + - run: node --test tests/plugin-support.test.mjs diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..be20fff --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,54 @@ +# Refact Toolkit + +Use simple English, short sentences, and common words. Keep exact commands and +file names accurate. Explain a required technical term in plain English. + +This repository is a plugin marketplace for Claude Code and Codex. It has nine +packs under `plugins/`, with shared skills and helper files. It is not a web app. + +## Source files + +- Edit each skill once in `plugins//skills//SKILL.md`. +- Keep its `name` equal to its folder name. Preserve the project's custom + workflow metadata; the native loaders use `name` and `description`. +- Every skill links to its pack's `references/plugin-runtime.md`. Edit the + common source at `shared/plugin-runtime.md`, then regenerate the copies. +- Keep support files inside the plugin root so installed copies are complete. +- Reusable agent briefs live under `plugins//agents/`. +- This marketplace is the source of truth for skills. Do not restore old + scaffold assumptions such as `agent/skills/`, `refact:sync`, or `.cursor` adapters. +- Keep `next_skills` links within the same pack. Cross-pack workflows must check + whether the needed skill is available in the current task. +- `.refact-os.json` holds optional project structure and stack information. + Keep secrets in the project's environment or credential store. +- Claude hooks are declared explicitly in `.claude-plugin/plugin.json` and live + at `hooks/claude-hooks.json`. Do not add a default `hooks/hooks.json`: Codex + would load it too. Claude language servers remain in `.lsp.json`. + +## Releases and generated files + +The version in each pack's `.claude-plugin/plugin.json` is the version source. +Bump changed packs and the Claude marketplace's top-level version for a release. +Run `node scripts/sync-codex.mjs` to sync catalog versions, native Codex manifests, +the Codex marketplace, and shared runtime copies. Commit those generated files +so installation from Git needs no build step. Do not edit them independently. + +Native manifests live at `plugins//.codex-plugin/plugin.json`. +The root `.agents/plugins/marketplace.json` points to the same pack directories +as `.claude-plugin/marketplace.json`. + +## Validation + +Use a temporary Python environment and install `requirements-dev.txt`, then run: + +```bash +node scripts/sync-codex.mjs --check +python scripts/check-plugins.py +node --test tests/plugin-support.test.mjs +``` + +For installation changes, verify catalog discovery and installation with Codex. +For project settings, test the actual skill list in a trusted project. A CLI +catalog list alone does not prove which skills a task will load. + +Read `docs/codex.md` for installation, updates, and project-specific enablement. diff --git a/CLAUDE.md b/CLAUDE.md index e01783b..671f65a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,126 +1,8 @@ -# CLAUDE.md +# Claude Code repository instructions -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Read and follow [AGENTS.md](AGENTS.md). It is the shared repository guide for +Claude Code and Codex, including writing style, source files, releases, and checks. -## How to write your responses - -Always answer in plain, simple English at about A2 (basic / elementary) level. Easy to understand. - -- Use short sentences. One idea per sentence. -- Use common, everyday words. Avoid jargon (special hard words) and idioms. -- Keep exact technical names, file names, commands, and code accurate — never simplify those. -- If a word must stay as its exact technical term, keep the word and put its meaning in - parentheses right after it. Example: "Edit the manifest (the settings file) ...". -- Prefer a small, concrete example over an abstract explanation. -- Short headings, bullets, and small tables are fine. - -This rule is about the prose you write for the reader. It does not change code, file names, -commands, or exact technical names. - -## What this repository is - -This is a **Claude Code plugin marketplace**, not an application. It has no build step, no -package manager, and no test runner. It ships declarative JSON manifests, markdown skills, a -slash command, and hooks that Claude Code loads at runtime. "Building" here means editing -these files and bumping versions. - -It ships **9 plugins** ("skill packs"), so a project installs only the capabilities it needs. - -## Layout - -``` -.claude-plugin/marketplace.json # marketplace manifest — lists all 9 plugins -plugins/ - base/ git-workflow, code-development, extract-learnings, asana, - sync-env-vars, update-project-config, setup-refact-control-mcp-server, - writing-client-updates - .claude-plugin/plugin.json .lsp.json (TS/JS) - commands/refact.md # the /base:refact slash command (router) - hooks/hooks.json + check-vtsls.sh (SessionStart, auto-install TS/JS LSP) - + claude-transcript-send-to-remote.py (Stop/SessionEnd) - + preflight-refact-config.mjs (UserPromptSubmit) - client/ draft-discovery-proposal, render-deliverable - ops/ cloudflare, sentry - insights/ ahrefs, ga4, gsc, gtm, pagespeed - nextjs/ setup-nextjs-app, nextjs-dev, setup-vercel-deploy, setup-netlify-deploy - wordpress/ wp-env, install-wp-skills, plugin-update, setup-kinsta-deploy, - setup-wpengine-deploy - .lsp.json (PHP) + hooks/check-intelephense.sh (SessionStart) - testing/ tdd, tdd-plan, red-green-refactor, backfill-tests, integration-tests - migrate/ migrate-to-marketplace - memory/ ingest-input, process-docs, log-entry, open-ticket, close-ticket, - project-status, update-canonical-record - hooks/hooks.json + refresh-memory-mount.mjs (SessionStart, pull the - refact-memory clone when stale + warn on unpushed local commits) -docs/plugin-marketplace-plan.md # the full plan + the 50-skill triage decision -docs/change-log.md # running change log -``` - -Each plugin has its own `.claude-plugin/plugin.json` **with a `version` field**. Skills with -support files keep them in `references/`, `assets/`, `scripts/`, `workflows/` next to `SKILL.md`. - -## How the pieces wire together - -- **Marketplace → plugins**: `marketplace.json` lists each plugin and points at its - `./plugins/` folder via `source`. Adding a plugin means a new entry here plus a new - folder under `plugins/`. -- **Skills**: Claude Code auto-discovers every `skills//SKILL.md`. The folder name must - equal the `name:` in the frontmatter. Frontmatter fields in use: `name`, `description`, - `pattern` (`procedure` | `orchestrator`), `when_to_use`, `when_not_to_use`, `next_skills`, - `sub_agents`, and optionally `references`, `requires_approval`, `disable-model-invocation`. - `next_skills` must reference only skills **in the same plugin** (cross-pack links are - optional prose). -- **`/base:refact` is a slash command, not a skill**: `plugins/base/commands/refact.md` is a menu - router. It maps a typed action (`/base:refact config`, `/base:refact sync asana`, `/base:refact wp-env`, …) - to the skill that handles it, and tells the user to `/plugin install @refact-os` when - that pack is not installed. -- **`.refact-os.json` (slim)**: an optional, non-secret project file holding only the - canonical **project structure + tech stack**. Skills may **read** it; `update-project-config` - (base) **writes** it; the `preflight-refact-config.mjs` hook **warns** when it is missing - before a `/base:refact` action. Secrets never go here — they stay in env / 1Password. -- **Hooks**: `base/hooks/hooks.json` registers `check-vtsls.sh` on `SessionStart`, - `preflight-refact-config.mjs` on `UserPromptSubmit`, and `claude-transcript-send-to-remote.py` - on `Stop` + `SessionEnd` (POSTs the chat transcript to `REMOTE_API_URL`). - `wordpress/hooks/hooks.json` registers `check-intelephense.sh` on `SessionStart`. All - `check-*.sh` exit `0` even on failure so they never block a session. -- **LSP**: `base/.lsp.json` binds `vtsls` to TS/JS/JSX/MJS/CJS; `wordpress/.lsp.json` binds - `intelephense` to PHP/`.phtml`. - -## This marketplace is canonical (it is NOT synced from a scaffold) - -The skills were **lifted out of the `@refactco/refact-os` npm scaffolder once and rewritten** -to stand alone here. This repo is now the **single source of truth** — there is no -`agent/skills/` source, no `npm run refact:sync` / `refact:validate`, no `.cursor` adapters, -and no on-install scaffold. To change a skill, edit its `SKILL.md` (and support files) -directly. A skill body may still **read a slim `.refact-os.json`** for the project's structure -and tech stack, but nothing regenerates anything. - -See `docs/plugin-marketplace-plan.md` for the full design and the 50-skill triage decision -(which refact-os skills were kept, fixed, dropped, or rebuilt). - -## Authoring or editing a skill - -1. Keep the folder name and frontmatter `name:` identical. -2. `pattern: orchestrator` (e.g. `tdd`) routes to other skills via `next_skills`; `procedure` - skills declare `next_skills: []` if terminal. `next_skills` must stay within the same plugin. -3. Put any counting/scanning/parsing in a script the skill invokes (e.g. - `plugins/client/skills/render-deliverable/render.mjs`), not in prose. Reference a bundled - script as `${CLAUDE_PLUGIN_ROOT}/skills//scripts/`. -4. Do not reintroduce scaffold assumptions: no `agent/skills/` paths, no `refact:sync`, no - `.cursor`. Read non-secret config from `.refact-os.json`; never expect secrets there. -5. After adding or removing a skill, bump the changed plugin's `version` (in both its - `plugin.json` and `marketplace.json`) and the top-level marketplace `version`. - -## Testing the marketplace locally - -Add the marketplace from this checkout, then install whichever packs you want: - -``` -/plugin marketplace add /Users/masoudgolchin/Documents/Refact Projects/new-plugin -/plugin install base@refact-os -/plugin install wordpress@refact-os -/plugin install insights@refact-os -``` - -`.claude/settings.local.json` (git-ignored) enables packs for this working copy. After editing -a skill, hook, or manifest, restart the session so Claude Code re-reads it. +Claude-specific package hooks are declared in each `.claude-plugin/plugin.json`. +Keep `/base:refact` as the Claude command wrapper for the shared `refact-toolkit` +skill. Do not add default `hooks/hooks.json` files to these shared pack folders. diff --git a/README.md b/README.md index 57654a5..7b68f61 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,31 @@ -# Refact OS — Claude Code plugin marketplace +# Refact Toolkit — Claude Code and Codex -A Claude Code **plugin marketplace** that packages the Refact skills as **8 installable packs**. +A **plugin marketplace** with **9 installable packs** and **42 shared skills** for Claude Code and Codex. Install only the capabilities a project needs; turn packs on or off independently. -## Install +## Install in Codex + +```bash +codex plugin marketplace add refactco/claude-toolkit +codex plugin add base@refact-os +``` + +Start a new Codex task. Ask “Use the Refact toolkit for this project,” or select +`refact-toolkit` from the skill picker. Add `--ref ` to the marketplace +command when testing a release branch. + +For a project that should not use a pack, merge this into its `.codex/config.toml`: + +```toml +[plugins."base@refact-os"] +enabled = false +``` + +This requires a trusted project and a new task. Each pack has its own switch. +See [the Codex guide](docs/codex.md) for usage, updates, local development, and +[all nine disable settings](examples/codex/disable-refact.toml). + +## Install in Claude Code Add the marketplace once, then install the packs you want: @@ -14,16 +36,21 @@ Add the marketplace once, then install the packs you want: (Or add it from a local checkout: `/plugin marketplace add /path/to/this/repo`.) -## Keeping packs up to date +## Keeping Claude Code packs up to date + +New versions land on `main`. To enable automatic updates, open `/plugin`, choose +**Marketplaces > refact-os > Enable auto-update**. New files load after +`/reload-plugins` or a later launch. With explicit versions, every release must +bump the changed pack version. -New versions land on `main`. Refreshing the marketplace does **not** upgrade packs you already have -installed — you have to bump each one, then restart. +For manual updates, refresh the marketplace and update each installed pack you use. +Then reload the plugins or restart Claude Code. **The easy way** (needs the **base** pack): run **`/base:refact update plugins`**. It refreshes the catalog, updates every installed pack, and tells you when to restart. **`/base:refact install plugins`** does the same for installing. Both run the base **`manage-plugins`** skill. -**By hand — two steps, then a restart:** +**By hand — two steps, then reload:** ``` /plugin marketplace update refact-os # 1. refresh the catalog (learn the new versions) @@ -31,7 +58,7 @@ does the same for installing. Both run the base **`manage-plugins`** skill. /plugin update wordpress@refact-os # …repeat for the packs you have installed ``` -Then **restart Claude Code** (or run `/reload-plugins`) — plugin updates only apply after a restart. +Then run `/reload-plugins` or restart Claude Code to load the new versions. - `/plugin marketplace update refact-os` **alone** only refreshes the *catalog*; your installed packs stay on their old version until you run `/plugin update @refact-os` for each. @@ -39,7 +66,11 @@ Then **restart Claude Code** (or run `/reload-plugins`) — plugin updates only ## The packs -| Pack | Install | What you get | +In Codex, install any pack with `codex plugin add @refact-os`. +The language servers and `/base:refact` command below apply to Claude Code. +Codex uses the `refact-toolkit` entry skill. + +| Pack | Claude Code install | What you get | |---|---|---| | **base** | `/plugin install base@refact-os` | git workflow, code-dev gates, Asana, env-var sync, learnings capture, client updates, slim project config, Refact Control MCP setup, the `/base:refact` command, TS/JS language server | | **client** | `/plugin install client@refact-os` | discovery-first proposals, branded print-ready PDF rendering | @@ -49,18 +80,19 @@ Then **restart Claude Code** (or run `/reload-plugins`) — plugin updates only | **wordpress** | `/plugin install wordpress@refact-os` | local `wp-env` stack, safe plugin updates with QA + rollback, Kinsta/WP Engine deploys, PHP language server | | **testing** | `/plugin install testing@refact-os` | TDD harness (`tdd` → `tdd-plan` → `red-green-refactor`), WordPress characterization + integration tests | | **migrate** | `/plugin install migrate@refact-os` | one-time move of a refact-os-scaffolded repo (`agent/skills`, `.cursor` adapters) onto these installable packs | +| **memory** | `/plugin install memory@refact-os` | evidence, project memory, ticket records, and status scans | Start with **base** — it carries the `/base:refact` menu command and the always-useful git / env / project-config skills. ## Skills by pack -Every skill (the exact `skills//` folder), grouped by the pack that ships it. Claude Code -auto-discovers these by trigger; you don't call them by name. +Every skill (the exact `skills//` folder), grouped by the pack that ships it. +Both clients can use skills for relevant requests. You can also select a skill explicitly. | Pack | Skills | |---|---| -| **base** | `asana`, `code-development`, `extract-learnings`, `git-workflow`, `setup-refact-control-mcp-server`, `sync-env-vars`, `update-project-config`, `writing-client-updates` — plus the `/base:refact` command | +| **base** | `asana`, `code-development`, `extract-learnings`, `git-workflow`, `setup-refact-control-mcp-server`, `sync-env-vars`, `update-project-config`, `writing-client-updates`, `manage-plugins`, `verify-visual-change`, `refact-toolkit` — plus the `/base:refact` command | | **client** | `draft-discovery-proposal`, `render-deliverable` | | **ops** | `cloudflare`, `sentry` | | **insights** | `ahrefs`, `ga4`, `gsc`, `gtm`, `pagespeed` | @@ -68,8 +100,9 @@ auto-discovers these by trigger; you don't call them by name. | **wordpress** | `wp-env`, `install-wp-skills`, `plugin-update`, `setup-kinsta-deploy`, `setup-wpengine-deploy` | | **testing** | `tdd`, `tdd-plan`, `red-green-refactor`, `backfill-tests`, `integration-tests` | | **migrate** | `migrate-to-marketplace` | +| **memory** | `ingest-input`, `process-docs`, `log-entry`, `open-ticket`, `close-ticket`, `project-status`, `update-canonical-record` | -## Enable or disable a pack (per project) +## Enable or disable a Claude Code pack (per project) Each pack turns on or off independently — per project, and per person. @@ -96,9 +129,11 @@ Each pack turns on or off independently — per project, and per person. - `.claude/settings.json` — shared, committed: the team's choice. - `.claude/settings.local.json` — personal, git-ignored: your own choice; it wins over the shared file. -## Hooks +## Claude Code hooks -Two packs ship hooks. They run automatically whenever that pack is enabled: +Three packs declare Claude hooks in their Claude manifests. Codex uses the shared +skills without these automatic hooks. Memory skills prepare the mount explicitly +in Codex. The Claude hooks run when their pack is enabled: | Pack | Runs on | What it does | |---|---|---| @@ -106,6 +141,7 @@ Two packs ship hooks. They run automatically whenever that pack is enabled: | **base** | `UserPromptSubmit` | warn if `.refact-os.json` is missing | | **base** | `Stop`, `SessionEnd` | upload the session transcript to `REMOTE_API_URL` | | **wordpress** | `SessionStart` | install the PHP language server (`intelephense`) | +| **memory** | `SessionStart` | refresh the local memory mount | Claude Code has **no switch for a single plugin hook**. To control them: @@ -130,13 +166,28 @@ Skills read an optional, non-secret project file holding only the **project stru The base `update-project-config` skill writes it; run `/base:refact config` to create or update it. **Secrets never go here** — they stay in your `.env` / 1Password. -## Language servers +## Claude Code language servers `base` auto-installs the TS/JS server (`vtsls`); `wordpress` auto-installs the PHP server (`intelephense`). Both install on `SessionStart` and never block a session if `npm` is missing. -## How it is built +## Development and releases + +Edit skills and scripts once under `plugins//`. Both clients use those +files. Claude loads `.claude-plugin/plugin.json`; Codex loads +`.codex-plugin/plugin.json`. + +Bump the changed pack versions in their Claude manifests, then run: + +```bash +node scripts/sync-codex.mjs +node scripts/sync-codex.mjs --check +python scripts/check-plugins.py +node --test tests/plugin-support.test.mjs +``` -No build step. Each pack is a folder of markdown skills (`skills//SKILL.md`) plus -manifests and hooks that Claude Code loads at runtime. See `CLAUDE.md` for the layout and -`docs/plugin-marketplace-plan.md` for the design and the full 50-skill triage decision. +The Python check needs `requirements-dev.txt` in a development environment. +The sync script updates both catalog versions, Codex metadata, and shared runtime +notes. Commit the generated files. Users need no build step when installing. +See [AGENTS.md](AGENTS.md) for the source layout and [docs/codex.md](docs/codex.md) +for runtime differences. diff --git a/docs/change-log.md b/docs/change-log.md index 351a784..335c9f2 100644 --- a/docs/change-log.md +++ b/docs/change-log.md @@ -7,6 +7,22 @@ Plan: see `docs/plugin-marketplace-plan.md`. --- +## 2026-09-07 — Codex support with shared skills + +Adds native Codex manifests for all nine packs and a `.agents/plugins/marketplace.json` +with the same `refact-os` identity. Both clients load the same skill files. The new +`refact-toolkit` skill provides a common entry point; `/base:refact` is a thin Claude +wrapper. Shared runtime notes cover path resolution, skill calls, and agent briefs. + +Adds Codex-specific plugin management and Refact Control setup guidance, project +on/off examples, and a release metadata generator. Claude hooks move to explicit +`hooks/claude-hooks.json` declarations, so Codex does not run the transcript uploader +or language-server installers. Fixes the existing base catalog/version mismatch and +accepts `/base:refact` in the Claude preflight. Validation now runs in CI. + +Versions: marketplace 2.13.0; base 1.9.0; client/ops/insights/wordpress/migrate 1.2.0; +nextjs/memory 1.1.0; testing 1.3.0. Total: 9 packs, 42 skills. + ## 2026-08-04 — New `memory` pack: the 7 mount-workflow skills + the freshness hook (Phase 1 of the memory-pack rollout) Adds the ninth pack, `memory` (enabled as `memory@refact-os`). It packages the 7 memory-workflow diff --git a/docs/codex.md b/docs/codex.md new file mode 100644 index 0000000..e8890d2 --- /dev/null +++ b/docs/codex.md @@ -0,0 +1,129 @@ +# Use Refact Toolkit in Codex + +The toolkit has nine optional packs. Install `base` to get the common workflows +and the `refact-toolkit` entry skill. Add other packs when a project needs them. + +## Install from GitHub + +Run these commands in a terminal with the Codex CLI installed: + +```bash +codex plugin marketplace add refactco/claude-toolkit +codex plugin add base@refact-os +``` + +For a release on a particular branch, use +`codex plugin marketplace add refactco/claude-toolkit --ref `. +If the repository is private, Git must have permission to read it. + +Then start a **new Codex task**. In the desktop app, open Plugins and find +**Refact Toolkit** to browse its packs. In the CLI, `/plugins` opens the browser. + +Examples for optional packs: + +```bash +codex plugin add wordpress@refact-os +codex plugin add client@refact-os +codex plugin add testing@refact-os +``` + +## Use it + +Ask for an outcome, for example: + +- “Use the Refact toolkit to record this project's structure and stack.” +- “Use the Refact proposal skill to draft a discovery proposal from these notes.” +- “Use the Refact WordPress workflow to check this local environment.” + +You can also select the `refact-toolkit` skill from the skill picker, or use +`$refact-toolkit` in the CLI. The entry skill checks which other skills are +available before routing the request. A disabled pack must not be loaded by +reading its cache directly. + +## Disable a pack for one project + +Installation enables the pack in the user's Codex configuration. To override +that setting for one project, merge this into that project's `.codex/config.toml`: + +```toml +[plugins."base@refact-os"] +enabled = false + +[plugins."wordpress@refact-os"] +enabled = false +``` + +The exact key includes both the pack and marketplace: `base@refact-os`, not +just `base`. Set `enabled = true` to enable an already installed pack in the +project. Each pack is independent: turning off `base` does not turn off `client`. +Use [the full example](../examples/codex/disable-refact.toml) to disable all nine. + +Codex reads project config only for **trusted projects**. Start a new task after +changing the file. Do not rely on a note in `AGENTS.md` as a replacement for the +plugin setting. + +- For a team rule, commit the non-secret `.codex/config.toml`. +- For your own rule, keep it untracked with `.git/info/exclude`. Do not silently + remove a config file that is already tracked by the team. +- The Plugins UI switch changes user defaults. Use project config for a rule + that applies only to one project. + +To use a pack only in selected projects, keep it installed, set its user-level +`enabled = false` in `~/.codex/config.toml`, and set `enabled = true` in each +selected project's `.codex/config.toml`. Preserve all other config tables. + +The project override was tested with Codex CLI `0.153.4`: the base skill paths +were present in the rendered task input when enabled and absent when disabled. +The user-level installation remained enabled during this test. + +## Update + +For a Git marketplace, refresh it and reinstall the installed packs you want: + +```bash +codex plugin marketplace upgrade refact-os +codex plugin add base@refact-os +codex plugin list --marketplace refact-os --json +``` + +Start a new task after the update. Repeat the `plugin add` command for other +selected packs. A general update should skip disabled packs because reinstalling +can enable them. The `manage-plugins` skill includes this rule. + +`marketplace upgrade` refreshes the configured Git snapshot. A local marketplace +uses the files in its checkout; update that checkout before reinstalling. +This release does not install an automatic background updater for personal Codex. + +## Develop from a local checkout + +```bash +node scripts/sync-codex.mjs +codex plugin marketplace add /absolute/path/to/claude-toolkit +codex plugin add base@refact-os +``` + +Use one configured source for `refact-os` at a time. Keep a development checkout +separate from the Git source used by regular users. After changes, bump the +changed pack's version, run the sync script, reinstall, and start a new task. +For rapid local-only iteration, Codex's plugin-creator cachebuster helper is +also available. Do not commit those temporary version suffixes as a team release. + +## Support boundaries + +Both clients use the same skill folders, scripts, templates, and references. +Codex reads its native manifests; Claude Code reads its own manifests. + +- Claude lifecycle hooks use explicit `hooks/claude-hooks.json` declarations. + Codex does not start the Claude transcript uploader or install language servers. +- In Codex, memory skills explicitly prepare the memory mount before their work. +- Named Claude agent files are reusable briefs. Codex follows them through its + available delegation tools or carries out the same bounded work directly. +- Refact Control has a separate local Codex setup procedure. Service logins, + credentials, Node/Python, Docker, WordPress, and browser tools remain explicit + requirements of the skills that use them. +- These packages target local Codex. Installing them is not a claim that a local + WordPress stack or a local credential tool runs in ChatGPT on the web. + +Official references: [plugin packaging](https://developers.openai.com/plugins/build/plugins), +[config precedence](https://learn.chatgpt.com/docs/config-file/config-basic), +[using plugins](https://learn.chatgpt.com/docs/plugins). diff --git a/examples/codex/disable-refact.toml b/examples/codex/disable-refact.toml new file mode 100644 index 0000000..db307b3 --- /dev/null +++ b/examples/codex/disable-refact.toml @@ -0,0 +1,28 @@ +# Merge the desired tables into this project's .codex/config.toml. +# Project config loads only in trusted projects. Start a new task after editing. +[plugins."base@refact-os"] +enabled = false + +[plugins."client@refact-os"] +enabled = false + +[plugins."ops@refact-os"] +enabled = false + +[plugins."insights@refact-os"] +enabled = false + +[plugins."nextjs@refact-os"] +enabled = false + +[plugins."wordpress@refact-os"] +enabled = false + +[plugins."testing@refact-os"] +enabled = false + +[plugins."migrate@refact-os"] +enabled = false + +[plugins."memory@refact-os"] +enabled = false diff --git a/plugins/base/.claude-plugin/plugin.json b/plugins/base/.claude-plugin/plugin.json index 8432d15..1772e8a 100644 --- a/plugins/base/.claude-plugin/plugin.json +++ b/plugins/base/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "base", - "version": "1.8.0", + "version": "1.9.0", "description": "Base toolkit: git workflow, code-dev gates, Asana, env sync, learnings, client updates, slim project config, Refact Control MCP setup + the /base:refact command + TS/JS LSP.", "author": { "name": "Refact Developer", @@ -17,5 +17,6 @@ "typescript", "javascript", "lsp" - ] + ], + "hooks": "./hooks/claude-hooks.json" } diff --git a/plugins/base/.codex-plugin/plugin.json b/plugins/base/.codex-plugin/plugin.json new file mode 100644 index 0000000..4160cba --- /dev/null +++ b/plugins/base/.codex-plugin/plugin.json @@ -0,0 +1,32 @@ +{ + "name": "base", + "version": "1.9.0", + "description": "Refact base workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "git", + "workflow", + "asana", + "env", + "client-updates", + "typescript", + "javascript", + "lsp" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact Base", + "shortDescription": "Use the Refact base skill pack.", + "longDescription": "Shared Refact base skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact base skills for this project." + } +} diff --git a/plugins/base/commands/refact.md b/plugins/base/commands/refact.md index c5fa0c2..3e1269d 100644 --- a/plugins/base/commands/refact.md +++ b/plugins/base/commands/refact.md @@ -1,61 +1,10 @@ --- -description: Refact toolkit menu — route a /base:refact action to the right installed skill. -argument-hint: "[action] e.g. config | sync asana | wp-env | setup nextjs" +description: Refact toolkit menu — route a /base:refact action to the shared toolkit skill. +argument-hint: "[action] e.g. config | sync asana | wp-env | setup nextjs" --- The user invoked `/base:refact $ARGUMENTS`. -You are the **Refact router**. Your job is to map the requested action to the one skill that -handles it and hand off to that skill. This command ships in the **base** pack; the skills it -routes to may live in other packs that the user has to install separately. - -## If `$ARGUMENTS` is empty - -Show this menu (and nothing else), then stop and wait for the user to pick: - -| `/base:refact …` | Does | Pack | -|---|---|---| -| `config` | Record the project structure + tech stack in `.refact-os.json` | base (always available) | -| `sync asana` | Sync / pull / comment on Asana tasks | base (always available) | -| `setup refact-control` | Wire the Refact Control MCP server into this project | base (always available) | -| `install plugins` / `update plugins` | Install/update the refact-os **packs** — not a site's WordPress plugins (those are `/plugin-update`) | base (always available) | -| `wp-env` | Manage the local WordPress stack | wordpress | -| `install wp skills` | Vendor the WordPress/Gutenberg skills | wordpress | -| `setup kinsta` / `setup wpengine` | Create the WP auto-deploy workflows | wordpress | -| `setup nextjs` | Create or adopt a Next.js app | nextjs | -| `nextjs dev` | Run / fix an existing Next.js app | nextjs | -| `setup vercel` / `setup netlify` | Set up the Next.js deploy | nextjs | -| `migrate` | Move a refact-os-scaffolded repo onto the marketplace | migrate | - -Tell the user packs install with `/plugin install @refact-os`. - -## Otherwise — route `$ARGUMENTS` to a skill - -Match the action (case-insensitive, allow close paraphrases) to one row: - -| Action | Skill to invoke | Pack | -|---|---|---| -| config, set config, project config | `update-project-config` | base | -| sync asana, asana, asana sync | `asana` | base | -| setup refact-control, refact-control mcp, refact control mcp, add refact context | `setup-refact-control-mcp-server` | base | -| install plugins, install the plugins, install pack, install `` | `manage-plugins` | base | -| update plugins, update the plugins, update packs, latest packs, update `` | `manage-plugins` | base | -| wp-env, wp env | `wp-env` | wordpress | -| install wp skills | `install-wp-skills` | wordpress | -| setup kinsta, kinsta deploy | `setup-kinsta-deploy` | wordpress | -| setup wpengine, wpengine deploy | `setup-wpengine-deploy` | wordpress | -| setup nextjs, create nextjs, adopt nextjs | `setup-nextjs-app` | nextjs | -| nextjs dev, run nextjs | `nextjs-dev` | nextjs | -| setup vercel, vercel deploy | `setup-vercel-deploy` | nextjs | -| setup netlify, netlify deploy | `setup-netlify-deploy` | nextjs | -| migrate, migrate to marketplace, migrate scaffold, unscaffold | `migrate-to-marketplace` | migrate | - -Then: - -1. **base actions** (`config`, `sync asana`, `setup refact-control`, `install plugins`, `update plugins`) are always available — invoke the skill directly. -2. **pack actions**: if the matching skill is available in this session, invoke it. If it is - **not** installed, do not improvise — tell the user exactly: - `That action needs the pack. Install it with: /plugin install @refact-os` - and stop. -3. If the action matches **no** row, show the menu above and ask which they meant. Do not guess. -4. **"update plugins" vs "plugin update":** `/base:refact install plugins` / `/base:refact update plugins` mean the **refact-os packs** (`manage-plugins`, base). A **WordPress site's** plugins (ACF, Yoast, `wp-content/plugins/`) are the wordpress `plugin-update` skill / `/plugin-update`. If a bare "plugin update" is ambiguous on a WordPress project, ask which they mean before acting. +Read `${CLAUDE_PLUGIN_ROOT}/skills/refact-toolkit/SKILL.md` and follow it for +`$ARGUMENTS`. The shared skill owns the menu, pack selection, and routing rules. +If the arguments are empty, show its menu and wait for the user to choose. diff --git a/plugins/base/hooks/hooks.json b/plugins/base/hooks/claude-hooks.json similarity index 100% rename from plugins/base/hooks/hooks.json rename to plugins/base/hooks/claude-hooks.json diff --git a/plugins/base/hooks/preflight-refact-config.mjs b/plugins/base/hooks/preflight-refact-config.mjs index 25e66ca..5a7d0c6 100755 --- a/plugins/base/hooks/preflight-refact-config.mjs +++ b/plugins/base/hooks/preflight-refact-config.mjs @@ -22,7 +22,7 @@ process.stdin.on("end", () => { const prompt = String(payload.prompt || ""); // Only react to an explicit /refact action. - if (!/(^|\s)\/refact(\s|$)/.test(prompt)) { + if (!/(^|\s)\/(?:base:)?refact(\s|$)/.test(prompt)) { process.exit(0); } diff --git a/plugins/base/references/plugin-runtime.md b/plugins/base/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/base/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/base/skills/asana/SKILL.md b/plugins/base/skills/asana/SKILL.md index 104120b..acd2620 100644 --- a/plugins/base/skills/asana/SKILL.md +++ b/plugins/base/skills/asana/SKILL.md @@ -11,6 +11,8 @@ sub_agents: [] # Asana Skill Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this skill whenever the user invokes `/asana` or asks to: - Sync all Asana tickets locally diff --git a/plugins/base/skills/code-development/SKILL.md b/plugins/base/skills/code-development/SKILL.md index b9e25a5..50a1b5b 100644 --- a/plugins/base/skills/code-development/SKILL.md +++ b/plugins/base/skills/code-development/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Code Development Skill +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + A thin layer over the base **`git-workflow`** skill, for changes to product code. All the git — branching, commits, pushing, opening the PR, recovering from blockers — lives in `git-workflow`. This skill only adds the parts that are specific to code. diff --git a/plugins/base/skills/extract-learnings/SKILL.md b/plugins/base/skills/extract-learnings/SKILL.md index 48ea748..fe1e37c 100644 --- a/plugins/base/skills/extract-learnings/SKILL.md +++ b/plugins/base/skills/extract-learnings/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Extract Learnings +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Write down **non-obvious** things from the current chat — user preferences, project conventions, recurring mistakes, hard-won setup recipes — before they're lost. > **This skill is the project's memory of record, and it takes precedence over personal/global agent memory.** Capture durable *project* facts here, in `docs/context/learnings.md` — do **not** also write the same fact to `~/.claude/projects//memory/`. The repo is the shared brain; per-user memory is not. diff --git a/plugins/base/skills/git-workflow/SKILL.md b/plugins/base/skills/git-workflow/SKILL.md index ecdcede..eb7dc3b 100644 --- a/plugins/base/skills/git-workflow/SKILL.md +++ b/plugins/base/skills/git-workflow/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Git Workflow +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + This skill handles **all the git** for you. Say what you want in plain words — the agent does the right thing and keeps the shared project safe. Every committed change (code, docs, content, config, deliverable) passes through here. diff --git a/plugins/base/skills/manage-plugins/SKILL.md b/plugins/base/skills/manage-plugins/SKILL.md index 148f902..4171692 100644 --- a/plugins/base/skills/manage-plugins/SKILL.md +++ b/plugins/base/skills/manage-plugins/SKILL.md @@ -1,17 +1,26 @@ --- name: manage-plugins -description: "Install or update the refact-os marketplace packs — all of them, the ones this project needs, or a single named pack. Refreshes the catalog, then installs/updates via the claude plugin CLI and reminds you to restart. This is about the /refact toolkit packs, not a WordPress site's plugins." +description: "Install, update, enable, or disable refact-os toolkit packs in Claude Code or Codex. Supports one pack, selected project packs, and project-specific enablement. This is about the Refact toolkit, not a WordPress site's plugins." pattern: procedure when_to_use: "The user wants to install or update the refact-os marketplace packs (the /refact toolkit) — \"install the plugins\", \"update the plugins\", \"/refact install plugins\", \"/refact update plugins\", \"get the latest packs\", \"am I on the latest refact-os packs\", or install/update a single named pack (\"install wordpress\", \"update the base pack\")." -when_not_to_use: "Updating a WordPress SITE's plugins (ACF, Yoast, …) — use the wordpress plugin-update skill / /plugin-update. Migrating a scaffolded repo onto the marketplace — use migrate-to-marketplace. Only turning a pack on/off for this project — edit .claude/settings.json enabledPlugins (no install needed)." +when_not_to_use: "Updating a WordPress SITE's plugins (ACF, Yoast, …) — use the wordpress plugin-update skill. Migrating a scaffolded repo onto the marketplace — use migrate-to-marketplace." next_skills: [] sub_agents: [] --- # Manage plugins (refact-os packs) +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + +## Select the active host first + +For **Codex**, read and follow [the Codex procedure](references/codex.md), then +stop. It covers installation, updates, and per-project enablement. The remaining +procedure below applies to **Claude Code** only. Do not select a host merely +because its CLI happens to be installed on the computer. + Install or update the **refact-os marketplace packs** — `base`, `wordpress`, `ops`, `insights`, -`nextjs`, `client`, `testing`, `migrate`. These are Claude Code plugins from the `refact-os` +`nextjs`, `client`, `testing`, `migrate`, `memory`. These are Claude Code plugins from the `refact-os` marketplace, **not** a WordPress site's plugins (for those, use the wordpress `plugin-update` skill). > **Am I the right skill?** This manages **refact-os marketplace packs** (Claude Code plugins: diff --git a/plugins/base/skills/manage-plugins/references/codex.md b/plugins/base/skills/manage-plugins/references/codex.md new file mode 100644 index 0000000..30028c9 --- /dev/null +++ b/plugins/base/skills/manage-plugins/references/codex.md @@ -0,0 +1,72 @@ +# Manage Refact packs in Codex + +Use this procedure when the active host is Codex. Do not run the Claude planner +or change `.claude/settings.json` for a Codex request. + +## Inspect + +```bash +codex plugin marketplace list +codex plugin list --marketplace refact-os --available --json +``` + +If the marketplace is absent, add `refactco/claude-toolkit` at the release ref +the user is following. Preserve an existing marketplace's source and ref. + +```bash +codex plugin marketplace add refactco/claude-toolkit +``` + +The JSON list has `installed` and `available` arrays. Entries include `pluginId`, +`name`, `version`, `installed`, and `enabled`. Use exact IDs from this result. + +## Install or update + +Install only the requested packs. For a project without a named pack, choose +`base` and the stack pack (`wordpress` or `nextjs`) when the request calls for it. +Other packs are optional. The marketplace also includes `memory`. + +```bash +codex plugin add base@refact-os +``` + +For updates, first record the installed packs and their enabled state. Refresh +a Git-backed marketplace, then reinstall only the selected installed packs: + +```bash +codex plugin marketplace upgrade refact-os +codex plugin add base@refact-os +``` + +Reinstalling can enable a pack. Skip disabled packs during a general update; +only update and restore a disabled pack when the user asks for that pack. +Do not install missing optional packs during an update. For a local marketplace, +the source checkout must already contain the changed files; `marketplace upgrade` +does not pull a local working copy. After editing a local plugin, change its +version before reinstalling. + +List the installed versions again. Ask the user to start a new task so new +skills and files load. Do not claim the current task reloaded them. A Git refresh +alone does not prove the installed copy changed. + +## Enable or disable for one project + +Plugin IDs include the marketplace name. In the target project's +`.codex/config.toml`, merge a table such as: + +```toml +[plugins."base@refact-os"] +enabled = false +``` + +Use one table per pack. Preserve the rest of the file. Use `true` to enable an +already installed pack for the project. Project config loads only in a trusted +project and overrides user defaults. A new task picks up the change. + +For a personal rule in that project, exclude `.codex/config.toml` through +`.git/info/exclude`. For a team rule, commit the non-secret config file. Do not +remove or ignore a file already shared with the team without the user's request. + +Do not bypass disabled skills by reading the plugin cache. If the user wants +all Refact packs disabled, write an `enabled = false` table for each of the nine +pack IDs, not a wildcard key. diff --git a/plugins/base/skills/refact-toolkit/SKILL.md b/plugins/base/skills/refact-toolkit/SKILL.md new file mode 100644 index 0000000..6b8db3c --- /dev/null +++ b/plugins/base/skills/refact-toolkit/SKILL.md @@ -0,0 +1,44 @@ +--- +name: refact-toolkit +description: Choose and run a Refact toolkit workflow for this project, including project config, Git, Asana, plugin installation, WordPress, Next.js, testing, client proposals, and memory. Use when the user asks for the Refact toolkit menu or a Refact action. +--- + +# Refact toolkit + +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + +Match the requested outcome to an installed skill: + +| Outcome | Skill | Pack | +|---|---|---| +| Record project structure and stack | update-project-config | base | +| Git branch, commit, or PR workflow | git-workflow | base | +| Sync or work with Asana tasks | asana | base | +| Connect Refact Control | setup-refact-control-mcp-server | base | +| Install or update toolkit packs | manage-plugins | base | +| Run a WordPress development environment | wp-env | wordpress | +| Install WordPress reference skills | install-wp-skills | wordpress | +| Update a site's WordPress plugins | plugin-update | wordpress | +| Set up Kinsta or WP Engine deployment | setup-kinsta-deploy / setup-wpengine-deploy | wordpress | +| Create or run a Next.js app | setup-nextjs-app / nextjs-dev | nextjs | +| Set up Vercel or Netlify deployment | setup-vercel-deploy / setup-netlify-deploy | nextjs | +| Test-driven development | tdd | testing | +| Draft a client proposal | draft-discovery-proposal | client | +| Render a client deliverable | render-deliverable | client | +| Review project memory/status | project-status | memory | +| Move an old scaffold to marketplace packs | migrate-to-marketplace | migrate | + +Read and follow the selected skill. Its prerequisites, approval rules, and +verification steps apply. Check `.refact-os.json` when that workflow needs project +structure or stack information; ask `update-project-config` to create it if needed. + +If no action was supplied, show the relevant choices from the table. If a plugin +update request is ambiguous, ask whether it means toolkit packs or the site's +WordPress plugins. + +If a skill is absent from the current available-skills list, do not bypass a +disabled pack by reading its cached files. Explain which pack is needed. In +Codex, install it with `codex plugin add @refact-os`, then start a new task. +In Claude Code, use `/plugin install @refact-os` and reload plugins. +An installed pack may be disabled for the project; explain that setting before +suggesting an installation. Respect an intentional project-level disable. diff --git a/plugins/base/skills/setup-refact-control-mcp-server/SKILL.md b/plugins/base/skills/setup-refact-control-mcp-server/SKILL.md index d9b1cf8..8561957 100644 --- a/plugins/base/skills/setup-refact-control-mcp-server/SKILL.md +++ b/plugins/base/skills/setup-refact-control-mcp-server/SKILL.md @@ -1,6 +1,6 @@ --- name: setup-refact-control-mcp-server -description: Wire the Refact Control MCP server (@refactco/refact-control-mcp-server, private on GitHub Packages) into a project's Claude Code — pull both secrets from 1Password and write a self-contained .mcp.json entry. No gh CLI, no .npmrc. +description: Connect the private Refact Control MCP server to Claude Code or local Codex for project context. Read credentials from 1Password and use the active host's configuration format. pattern: procedure when_to_use: Setting up the Refact Control MCP server in a project so the agent gets read-only client/project context — "/setup-refact-control-mcp-server", "install the refact-control mcp server", "add refact context to this repo", "set up the refact-control MCP". Run in the target project, not in the refact-control repo itself. when_not_to_use: You're in the refact-control source repo and just want to run it locally from source (use `npm run dev` in apps/mcp-server); you're publishing a new version of the package (use publish-mcp-server); the project already has a working `refact-control` MCP entry. @@ -10,6 +10,12 @@ sub_agents: [] # Setup Refact Control MCP Server +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + +For **Codex**, follow [Codex setup](references/codex.md). Use the credential +lookup in step 1 below, but do not apply the Claude `.mcp.json` or +`enabledMcpjsonServers` steps. The remaining setup applies to **Claude Code**. + Add the **Refact Control MCP server** to *this* project's Claude Code so the agent can read client/project context (clients, projects, decisions, concerns, milestones, stack, etc.). diff --git a/plugins/base/skills/setup-refact-control-mcp-server/references/codex.md b/plugins/base/skills/setup-refact-control-mcp-server/references/codex.md new file mode 100644 index 0000000..50faa61 --- /dev/null +++ b/plugins/base/skills/setup-refact-control-mcp-server/references/codex.md @@ -0,0 +1,35 @@ +# Refact Control setup for Codex + +The same private npm package can run as a local MCP server in Codex. This is a +local Codex setup; it does not register a ChatGPT web connector. + +1. Check for an existing `mcp_servers.refact-control` entry in the effective + Codex configuration. If it already works, keep it. +2. Use the parent skill's 1Password lookup to obtain the two secrets. Do not + print values or ask the user to paste them into chat. +3. Merge the following into the target project's `.codex/config.toml`. Replace + placeholders locally with the retrieved values, using a TOML writer or proper + string escaping. Preserve all unrelated configuration. + +```toml +[mcp_servers.refact-control] +command = "npx" +args = ["-y", "@refactco/refact-control-mcp-server"] + +[mcp_servers.refact-control.env] +"npm_config_@refactco:registry" = "https://npm.pkg.github.com" +"npm_config_//npm.pkg.github.com/:_authToken" = "" +CONTROL_API_URL = "https://refact-control.netlify.app" +AGENT_CONTEXT_API_KEY = "" +``` + +This file contains secrets after setup. Before writing, check whether the file +is tracked. If it is tracked, keep placeholders in the shared file and use an +untracked local credential-loading wrapper instead, or ask for the user's chosen +credential store. Do not place secret values into a tracked config. +For a new personal config, add `.codex/config.toml` to `.git/info/exclude` and use +restrictive file permissions. Project-local config is read only for trusted +projects. Do not alter project trust or widen tool approvals as part of setup. + +Start a new Codex task and verify a read-only Refact Control tool. Do not print +the MCP configuration or secret environment in the verification result. diff --git a/plugins/base/skills/sync-env-vars/SKILL.md b/plugins/base/skills/sync-env-vars/SKILL.md index a1423e0..e8b04d4 100644 --- a/plugins/base/skills/sync-env-vars/SKILL.md +++ b/plugins/base/skills/sync-env-vars/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Sync Env Vars +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + ## What This Skill Does Keep the two value sources for a project aligned: @@ -32,7 +34,7 @@ The env file belongs next to the app that reads it (e.g. `dashboard/.env`), **no 1. **Any existing `.env.example` or `.env`** — use its directory (the `.env.example` wins because it declares the keys). 2. **Otherwise, the directory where env vars are read** — using the exact accessor patterns from "Codebase Discovery Search Method" below. The file goes in the top-level directory where those accessors live. -If neither rule finds anything, it falls back to the repo root. Searches always ignore `node_modules`, `.git`, `.next`, `dist`, `build`, `vendor`, any WordPress app directory (detect it from the repo, or ask the user — e.g. `apps/` in a monorepo), `.claude`, and `agent`. The `.claude` and `agent` root folders are tooling/skill directories — they are never var accessors and must not influence env file placement. The chosen path is printed as `Env location: ` at the top of every run. +If neither rule finds anything, it falls back to the repo root. Searches always ignore `node_modules`, `.git`, `.next`, `dist`, `build`, `vendor`, any WordPress app directory (detect it from the repo, or ask the user — e.g. `apps/` in a monorepo), `.claude`, `.codex`, `.agents`, and `agent`. The `.claude`, `.codex`, `.agents`, and `agent` root folders are tooling/skill directories — they are never var accessors and must not influence env file placement. The chosen path is printed as `Env location: ` at the top of every run. If a rule finds **more than one** candidate directory, the location is ambiguous: the script stops and lists them. Ask the user which one, then pin it explicitly: @@ -227,6 +229,8 @@ rg --no-filename -o -r '$1' \ \ --glob '!/**' \ --glob '!.claude/**' \ + --glob '!.codex/**' \ + --glob '!.agents/**' \ --glob '!agent/**' | sort -u ``` diff --git a/plugins/base/skills/sync-env-vars/scripts/sync-env.sh b/plugins/base/skills/sync-env-vars/scripts/sync-env.sh index 5ad4b88..2246613 100755 --- a/plugins/base/skills/sync-env-vars/scripts/sync-env.sh +++ b/plugins/base/skills/sync-env-vars/scripts/sync-env.sh @@ -158,14 +158,14 @@ ENV_ACCESSOR_PATTERNS=( # Print the top-level segments (first path component under CWD, "." for files at # the root) of every file that reads an env var. Used only when no .env or # .env.example exists yet, to place the file where env vars are actually used. -# .cursor, .claude, and agents are excluded: they contain tooling/skill files +# .cursor, .claude, .codex, .agents, and agent contain tooling/skill files # that reference accessor patterns as documentation, not actual app code. find_accessor_top_segments() { command -v rg >/dev/null 2>&1 || return 0 rg -l --no-messages "${ENV_ACCESSOR_PATTERNS[@]}" \ -g '!node_modules' -g '!.git' -g '!.next' -g '!dist' -g '!build' \ -g '!vendor' -g '!apps/wordpress/**' \ - -g '!.cursor/**' -g '!.claude/**' -g '!agent/**' . 2>/dev/null \ + -g '!.cursor/**' -g '!.claude/**' -g '!.codex/**' -g '!.agents/**' -g '!agent/**' . 2>/dev/null \ | sed -e 's#^\./##' \ | awk -F/ '{ if (NF > 1) print $1; else print "." }' \ | sort -u diff --git a/plugins/base/skills/update-project-config/SKILL.md b/plugins/base/skills/update-project-config/SKILL.md index 51754be..f91a95b 100644 --- a/plugins/base/skills/update-project-config/SKILL.md +++ b/plugins/base/skills/update-project-config/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Update Project Config +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + ## What this file is `.refact-os.json` is a **slim** project-context file. It holds only two top-level keys: diff --git a/plugins/base/skills/verify-visual-change/SKILL.md b/plugins/base/skills/verify-visual-change/SKILL.md index 0006aed..28bf974 100644 --- a/plugins/base/skills/verify-visual-change/SKILL.md +++ b/plugins/base/skills/verify-visual-change/SKILL.md @@ -11,6 +11,8 @@ sub_agents: [] # Verify a visual change before claiming it done +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Do not guess from source alone and ship. Confirm the component renders, change it, then measure the result in a real browser. ## 1. Confirm the component actually renders diff --git a/plugins/base/skills/writing-client-updates/SKILL.md b/plugins/base/skills/writing-client-updates/SKILL.md index 07502d3..59329d2 100644 --- a/plugins/base/skills/writing-client-updates/SKILL.md +++ b/plugins/base/skills/writing-client-updates/SKILL.md @@ -11,6 +11,8 @@ sub_agents: [] # Writing Client Updates +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Draft a client-facing update that is clear, structured, and confident — email or Slack. ## How to use this skill diff --git a/plugins/client/.claude-plugin/plugin.json b/plugins/client/.claude-plugin/plugin.json index 50156bf..be074cc 100644 --- a/plugins/client/.claude-plugin/plugin.json +++ b/plugins/client/.claude-plugin/plugin.json @@ -1,10 +1,17 @@ { "name": "client", - "version": "1.1.2", + "version": "1.2.0", "description": "Client deliverables: discovery-first proposals and branded print-ready PDF rendering.", "author": { "name": "Refact Developer", "email": "dev@refact.co" }, - "keywords": ["refact", "skills", "client", "proposal", "deliverable", "pdf"] + "keywords": [ + "refact", + "skills", + "client", + "proposal", + "deliverable", + "pdf" + ] } diff --git a/plugins/client/.codex-plugin/plugin.json b/plugins/client/.codex-plugin/plugin.json new file mode 100644 index 0000000..3581d1f --- /dev/null +++ b/plugins/client/.codex-plugin/plugin.json @@ -0,0 +1,28 @@ +{ + "name": "client", + "version": "1.2.0", + "description": "Refact client workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "client", + "proposal", + "deliverable", + "pdf" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact Client", + "shortDescription": "Use the Refact client skill pack.", + "longDescription": "Shared Refact client skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact client skills for this project." + } +} diff --git a/plugins/client/references/plugin-runtime.md b/plugins/client/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/client/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/client/skills/draft-discovery-proposal/SKILL.md b/plugins/client/skills/draft-discovery-proposal/SKILL.md index cc3e988..7bd2d6a 100644 --- a/plugins/client/skills/draft-discovery-proposal/SKILL.md +++ b/plugins/client/skills/draft-discovery-proposal/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Draft Discovery Proposal +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Draft a prospect proposal in Refact's house style: **discovery-first, fixed-price front door, client-owned deliverables, build phase priced off Discovery.** This skill is the *how*; the fillable skeleton is [`template.md`](template.md) in this folder — copy it and diff --git a/plugins/client/skills/render-deliverable/SKILL.md b/plugins/client/skills/render-deliverable/SKILL.md index 2a95f3e..3310373 100644 --- a/plugins/client/skills/render-deliverable/SKILL.md +++ b/plugins/client/skills/render-deliverable/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Render Deliverable +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Turn a markdown deliverable into a polished, print-ready document using the shared Refact design system — editorial Swiss layout, Inter + Source Serif 4, claret accent on warm cream, with a full print stylesheet (running header, page numbers, page breaks). diff --git a/plugins/insights/.claude-plugin/plugin.json b/plugins/insights/.claude-plugin/plugin.json index 19192b0..cff1cf1 100644 --- a/plugins/insights/.claude-plugin/plugin.json +++ b/plugins/insights/.claude-plugin/plugin.json @@ -1,10 +1,21 @@ { "name": "insights", - "version": "1.1.0", + "version": "1.2.0", "description": "Site insights: SEO (Ahrefs, Search Console), web analytics (GA4), tag management (GTM), and PageSpeed/Core Web Vitals.", "author": { "name": "Refact Developer", "email": "dev@refact.co" }, - "keywords": ["refact", "skills", "insights", "seo", "analytics", "ahrefs", "ga4", "search-console", "gtm", "pagespeed"] + "keywords": [ + "refact", + "skills", + "insights", + "seo", + "analytics", + "ahrefs", + "ga4", + "search-console", + "gtm", + "pagespeed" + ] } diff --git a/plugins/insights/.codex-plugin/plugin.json b/plugins/insights/.codex-plugin/plugin.json new file mode 100644 index 0000000..467bdfd --- /dev/null +++ b/plugins/insights/.codex-plugin/plugin.json @@ -0,0 +1,32 @@ +{ + "name": "insights", + "version": "1.2.0", + "description": "Refact insights workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "insights", + "seo", + "analytics", + "ahrefs", + "ga4", + "search-console", + "gtm", + "pagespeed" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact Insights", + "shortDescription": "Use the Refact insights skill pack.", + "longDescription": "Shared Refact insights skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact insights skills for this project." + } +} diff --git a/plugins/insights/references/plugin-runtime.md b/plugins/insights/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/insights/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/insights/skills/ahrefs/SKILL.md b/plugins/insights/skills/ahrefs/SKILL.md index 8ae217d..740ee6f 100644 --- a/plugins/insights/skills/ahrefs/SKILL.md +++ b/plugins/insights/skills/ahrefs/SKILL.md @@ -14,6 +14,8 @@ references: # Ahrefs +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Ahrefs is **read-only / diagnostic**: it reports SEO data and *detects* Site Audit issues, but every **fix lands in the site code** — in the app directory (detect it from the repo, or ask the user — e.g. `apps/` in a monorepo; Next.js or diff --git a/plugins/insights/skills/ga4/SKILL.md b/plugins/insights/skills/ga4/SKILL.md index 9bbb119..0894af2 100644 --- a/plugins/insights/skills/ga4/SKILL.md +++ b/plugins/insights/skills/ga4/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Google Analytics 4 (GA4) +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Single entry point for GA4 **data**. Shares one auth + config model with the `gsc` and `gtm` skills (same Google account, same 1Password item, same one-time login). diff --git a/plugins/insights/skills/gsc/SKILL.md b/plugins/insights/skills/gsc/SKILL.md index 1c23ca8..58d3278 100644 --- a/plugins/insights/skills/gsc/SKILL.md +++ b/plugins/insights/skills/gsc/SKILL.md @@ -15,6 +15,8 @@ references: # Google Search Console (GSC) +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + This skill is the single entry point for everything Search Console. It shares one auth + config model across every action, then splits into focused references for each capability. **Load the reference that matches the task** — don't read them diff --git a/plugins/insights/skills/gtm/SKILL.md b/plugins/insights/skills/gtm/SKILL.md index c95e887..4620f1c 100644 --- a/plugins/insights/skills/gtm/SKILL.md +++ b/plugins/insights/skills/gtm/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Google Tag Manager (GTM) +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Read-only access to the **live (published) container configuration**. Use it to audit what's actually deployed — GTM holds *tag configuration*, not analytics **data** (for numbers, use the `ga4` skill). diff --git a/plugins/insights/skills/pagespeed/SKILL.md b/plugins/insights/skills/pagespeed/SKILL.md index 9226f9f..db8f8d0 100644 --- a/plugins/insights/skills/pagespeed/SKILL.md +++ b/plugins/insights/skills/pagespeed/SKILL.md @@ -13,9 +13,13 @@ model: sonnet # PageSpeed & Core Web Vitals -> **Forked execution**: this skill runs in an isolated sub-agent context -> (`context: fork`) — the scripts do all scoring, and big Lighthouse/CrUX JSON stays -> out of the main conversation. There are no mid-flow user questions here; if the API +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + +> **Execution**: Claude Code uses the `context: fork` settings above. In Codex, +> use an available subagent with the same procedure, or run the scripts directly +> and save large results to files. The active host chooses the model. The scripts +> do all scoring, and big Lighthouse/CrUX JSON stays out of the main conversation. +> There are no mid-flow user questions here; if the API > key or config is missing, report exactly what's missing (and the Prerequisites steps) > back to the main conversation instead of asking. diff --git a/plugins/memory/.claude-plugin/plugin.json b/plugins/memory/.claude-plugin/plugin.json index acbd04f..8e6a5dc 100644 --- a/plugins/memory/.claude-plugin/plugin.json +++ b/plugins/memory/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "memory", - "version": "1.0.0", - "description": "Memory workflows on the refact-memory mount: ingest evidence, tracker entries, canonical-record edits, ticket anchor + outcome, status scan — plus a SessionStart hook that keeps the local clone fresh.", + "version": "1.1.0", + "description": "Memory workflows on the refact-memory mount: ingest evidence, tracker entries, canonical-record edits, ticket anchor + outcome, status scan \u2014 plus a SessionStart hook that keeps the local clone fresh.", "author": { "name": "Refact Developer", "email": "dev@refact.co" @@ -15,5 +15,6 @@ "knowledge", "mount", "asana" - ] + ], + "hooks": "./hooks/claude-hooks.json" } diff --git a/plugins/memory/.codex-plugin/plugin.json b/plugins/memory/.codex-plugin/plugin.json new file mode 100644 index 0000000..ac3b4b8 --- /dev/null +++ b/plugins/memory/.codex-plugin/plugin.json @@ -0,0 +1,30 @@ +{ + "name": "memory", + "version": "1.1.0", + "description": "Refact memory workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "memory", + "evidence", + "tracker", + "knowledge", + "mount", + "asana" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact Memory", + "shortDescription": "Use the Refact memory skill pack.", + "longDescription": "Shared Refact memory skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact memory skills for this project." + } +} diff --git a/plugins/memory/hooks/hooks.json b/plugins/memory/hooks/claude-hooks.json similarity index 100% rename from plugins/memory/hooks/hooks.json rename to plugins/memory/hooks/claude-hooks.json diff --git a/plugins/memory/references/plugin-runtime.md b/plugins/memory/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/memory/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/memory/skills/close-ticket/SKILL.md b/plugins/memory/skills/close-ticket/SKILL.md index 407cab1..d3adcd1 100644 --- a/plugins/memory/skills/close-ticket/SKILL.md +++ b/plugins/memory/skills/close-ticket/SKILL.md @@ -14,6 +14,8 @@ sub_agents: [] # Close Ticket +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + **Spawned/unattended runs: if `REFACT_MEMORY_READONLY` is set in your environment, stop — durable output goes in your run report / the propose→approve path.** The durable residue of a closed ticket is a **tracker entry** (memory-model §6.1); Asana keeps the task history. Nothing under `task/` is ever committed. diff --git a/plugins/memory/skills/ingest-input/SKILL.md b/plugins/memory/skills/ingest-input/SKILL.md index b8cbb55..d306746 100644 --- a/plugins/memory/skills/ingest-input/SKILL.md +++ b/plugins/memory/skills/ingest-input/SKILL.md @@ -17,6 +17,8 @@ sub_agents: [] # Ingest Input +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + **Spawned/unattended runs: if `REFACT_MEMORY_READONLY` is set in your environment, stop — the mount is read-only for you; durable output goes in your run report / the propose→approve path.** Capture what arrived as **evidence** *before* acting on it — agents work from saved files, not chat memory. Schema: refact-memory `memory-model.md` (§3.2 evidence, §6.2 ingest table). Requires the mount: if `memory/` is missing or dangling, run the repo's link script (`npm run link-memory` or `node scripts/link-memory.mjs` — see the First-run section in `AGENTS.md`). Your company/project slugs come from the mount path: `realpath memory` → `…/companies/[/projects/]`. diff --git a/plugins/memory/skills/log-entry/SKILL.md b/plugins/memory/skills/log-entry/SKILL.md index 3190009..8473d94 100644 --- a/plugins/memory/skills/log-entry/SKILL.md +++ b/plugins/memory/skills/log-entry/SKILL.md @@ -14,6 +14,8 @@ sub_agents: [] # Log Entry +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + **Spawned/unattended runs: if `REFACT_MEMORY_READONLY` is set in your environment, stop — the mount is read-only for you; durable output goes in your run report / the propose→approve path.** Tracker writes on the mount. The schema is `memory-model.md` in refact-memory (§3.2 tracker, §3.3 vocabularies) — this skill applies it. Requires the mount: if `memory/` is missing or dangling, run the repo's link script (`npm run link-memory` or `node scripts/link-memory.mjs` — see the First-run section in `AGENTS.md`). Your company/project slugs come from the mount path: `realpath memory` → `…/companies/[/projects/]`. diff --git a/plugins/memory/skills/open-ticket/SKILL.md b/plugins/memory/skills/open-ticket/SKILL.md index dac0e7b..36fbb56 100644 --- a/plugins/memory/skills/open-ticket/SKILL.md +++ b/plugins/memory/skills/open-ticket/SKILL.md @@ -15,6 +15,8 @@ sub_agents: [] # Open Ticket +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + **Spawned/unattended runs: if `REFACT_MEMORY_READONLY` is set in your environment, stop — durable output goes in your run report / the propose→approve path.** **Asana is the system of record for work items** (memory-model §1/§6.1); `memory/task/` is a gitignored local cache of it, refreshed by the repo's link script. A work item without an Asana anchor is a hard stop for execution — this skill's job is to guarantee the anchor. diff --git a/plugins/memory/skills/process-docs/SKILL.md b/plugins/memory/skills/process-docs/SKILL.md index f25824e..639aed5 100644 --- a/plugins/memory/skills/process-docs/SKILL.md +++ b/plugins/memory/skills/process-docs/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Process Docs Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + **Spawned/unattended runs: if `REFACT_MEMORY_READONLY` is set in your environment, stop — the mount is read-only for you; durable output goes in your run report / the propose→approve path.** Use this when the user asks to process / ingest / digest new docs. Requires the mount: if `memory/` is missing or dangling, run the repo's link script (`npm run link-memory` or `node scripts/link-memory.mjs` — see the First-run section in `AGENTS.md`). diff --git a/plugins/memory/skills/project-status/SKILL.md b/plugins/memory/skills/project-status/SKILL.md index 88fb6b8..8e2a96f 100644 --- a/plugins/memory/skills/project-status/SKILL.md +++ b/plugins/memory/skills/project-status/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Status Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + **Spawned/unattended runs: if `REFACT_MEMORY_READONLY` is set in your environment, do not use this skill — your spawn already received a memory digest at mount time.** Use this when the user asks "what's the status of the project context?" (or what's pending / unprocessed). diff --git a/plugins/memory/skills/update-canonical-record/SKILL.md b/plugins/memory/skills/update-canonical-record/SKILL.md index 2fb1b36..669e0bd 100644 --- a/plugins/memory/skills/update-canonical-record/SKILL.md +++ b/plugins/memory/skills/update-canonical-record/SKILL.md @@ -15,6 +15,8 @@ sub_agents: [] # Update Canonical Record +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + **Spawned/unattended runs: if `REFACT_MEMORY_READONLY` is set in your environment, stop — the mount is read-only for you; durable output goes in your run report / the propose→approve path.** The canonical record lives on the mount: **`memory/project.md`** (the standing overview; `memory/company.md` at company level) and the knowledge docs it names as current truth. Requires the mount: if `memory/` is missing or dangling, run the repo's link script (`npm run link-memory` or `node scripts/link-memory.mjs` — see the First-run section in `AGENTS.md`). diff --git a/plugins/migrate/.claude-plugin/plugin.json b/plugins/migrate/.claude-plugin/plugin.json index 26beaf8..2a2321f 100644 --- a/plugins/migrate/.claude-plugin/plugin.json +++ b/plugins/migrate/.claude-plugin/plugin.json @@ -1,10 +1,17 @@ { "name": "migrate", - "version": "1.1.0", - "description": "One-time migration: move a refact-os-scaffolded project (agent/skills + generated .claude/.cursor + fat .refact-os.json) onto the refact-os plugin marketplace — detect, back up, remove the generated trees, slim the config, and print the pack install commands.", + "version": "1.2.0", + "description": "One-time migration: move a refact-os-scaffolded project (agent/skills + generated .claude/.cursor + fat .refact-os.json) onto the refact-os plugin marketplace \u2014 detect, back up, remove the generated trees, slim the config, and print the pack install commands.", "author": { "name": "Refact Developer", "email": "dev@refact.co" }, - "keywords": ["refact", "skills", "migration", "scaffold", "marketplace", "adopt"] + "keywords": [ + "refact", + "skills", + "migration", + "scaffold", + "marketplace", + "adopt" + ] } diff --git a/plugins/migrate/.codex-plugin/plugin.json b/plugins/migrate/.codex-plugin/plugin.json new file mode 100644 index 0000000..c08836f --- /dev/null +++ b/plugins/migrate/.codex-plugin/plugin.json @@ -0,0 +1,28 @@ +{ + "name": "migrate", + "version": "1.2.0", + "description": "Refact migrate workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "migration", + "scaffold", + "marketplace", + "adopt" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact Migrate", + "shortDescription": "Use the Refact migrate skill pack.", + "longDescription": "Shared Refact migrate skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact migrate skills for this project." + } +} diff --git a/plugins/migrate/references/plugin-runtime.md b/plugins/migrate/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/migrate/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/migrate/skills/migrate-to-marketplace/SKILL.md b/plugins/migrate/skills/migrate-to-marketplace/SKILL.md index b2ed340..3fd45a5 100644 --- a/plugins/migrate/skills/migrate-to-marketplace/SKILL.md +++ b/plugins/migrate/skills/migrate-to-marketplace/SKILL.md @@ -11,6 +11,20 @@ requires_approval: true # Migrate to marketplace +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + +## Codex target + +For a Codex migration, use `AGENTS.md` as the default contract in steps 1 and 4. +Keep existing Claude hooks and settings unless the approved scaffold cleanup +explicitly includes them; Codex's base pack does not replace transcript hooks. +In step 10, use `codex plugin marketplace add refactco/claude-toolkit`, install +the selected packs with `codex plugin add @refact-os`, and merge +`[plugins."@refact-os"]` tables with `enabled = true` or `false` in the +project's `.codex/config.toml`. Start a new Codex task. Do not write Claude +enablement settings for a Codex-only migration. The backup, drift review, +secret preservation, and explicit approval rules below still apply. + Move a **refact-os-scaffolded** repo off the npm scaffolder and onto the **plugin marketplace**. The old model bundled skills under `agent/skills/` with generated `.claude/` + `.cursor/` copies; the new model installs skills as packs (`/plugin install @refact-os`). This skill does the diff --git a/plugins/nextjs/.claude-plugin/plugin.json b/plugins/nextjs/.claude-plugin/plugin.json index f9c3928..0345c78 100644 --- a/plugins/nextjs/.claude-plugin/plugin.json +++ b/plugins/nextjs/.claude-plugin/plugin.json @@ -1,10 +1,17 @@ { "name": "nextjs", - "version": "1.0.2", + "version": "1.1.0", "description": "Next.js: scaffold or adopt an app, run/diagnose it, and set up Vercel or Netlify deploys.", "author": { "name": "Refact Developer", "email": "dev@refact.co" }, - "keywords": ["refact", "skills", "nextjs", "vercel", "netlify", "deploy"] + "keywords": [ + "refact", + "skills", + "nextjs", + "vercel", + "netlify", + "deploy" + ] } diff --git a/plugins/nextjs/.codex-plugin/plugin.json b/plugins/nextjs/.codex-plugin/plugin.json new file mode 100644 index 0000000..ff86bf3 --- /dev/null +++ b/plugins/nextjs/.codex-plugin/plugin.json @@ -0,0 +1,28 @@ +{ + "name": "nextjs", + "version": "1.1.0", + "description": "Refact nextjs workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "nextjs", + "vercel", + "netlify", + "deploy" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact Next.js", + "shortDescription": "Use the Refact nextjs skill pack.", + "longDescription": "Shared Refact nextjs skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact nextjs skills for this project." + } +} diff --git a/plugins/nextjs/references/plugin-runtime.md b/plugins/nextjs/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/nextjs/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/nextjs/skills/nextjs-dev/SKILL.md b/plugins/nextjs/skills/nextjs-dev/SKILL.md index d86ca6f..30d4fbe 100644 --- a/plugins/nextjs/skills/nextjs-dev/SKILL.md +++ b/plugins/nextjs/skills/nextjs-dev/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Next.js Development Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this reference for day-to-day development work in an existing Next.js app. ## Goal diff --git a/plugins/nextjs/skills/setup-netlify-deploy/SKILL.md b/plugins/nextjs/skills/setup-netlify-deploy/SKILL.md index 8e61a17..093de95 100644 --- a/plugins/nextjs/skills/setup-netlify-deploy/SKILL.md +++ b/plugins/nextjs/skills/setup-netlify-deploy/SKILL.md @@ -12,6 +12,8 @@ sub_agents: [] # Netlify Deploy Setup Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this reference when the user explicitly wants a Next.js app linked or configured for Netlify. Do not run this automatically for every Next.js project. ## Goal diff --git a/plugins/nextjs/skills/setup-nextjs-app/SKILL.md b/plugins/nextjs/skills/setup-nextjs-app/SKILL.md index fbf6cb9..7fc3e67 100644 --- a/plugins/nextjs/skills/setup-nextjs-app/SKILL.md +++ b/plugins/nextjs/skills/setup-nextjs-app/SKILL.md @@ -13,6 +13,8 @@ sub_agents: [] # Setup Next.js App Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this reference when the user asks to create a new Next.js application or bring an existing Next.js app into the project. ## Goal diff --git a/plugins/nextjs/skills/setup-vercel-deploy/SKILL.md b/plugins/nextjs/skills/setup-vercel-deploy/SKILL.md index dbf2be9..ed96230 100644 --- a/plugins/nextjs/skills/setup-vercel-deploy/SKILL.md +++ b/plugins/nextjs/skills/setup-vercel-deploy/SKILL.md @@ -12,6 +12,8 @@ sub_agents: [] # Vercel Deploy Setup Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this reference when the user explicitly wants a Next.js app linked or configured for Vercel. Do not run this automatically for every Next.js project. ## Goal diff --git a/plugins/ops/.claude-plugin/plugin.json b/plugins/ops/.claude-plugin/plugin.json index 47f8fcc..eb0b6c3 100644 --- a/plugins/ops/.claude-plugin/plugin.json +++ b/plugins/ops/.claude-plugin/plugin.json @@ -1,10 +1,18 @@ { "name": "ops", - "version": "1.1.0", + "version": "1.2.0", "description": "Ops integrations: Cloudflare client-zone operations and Sentry backlog triage.", "author": { "name": "Refact Developer", "email": "dev@refact.co" }, - "keywords": ["refact", "skills", "cloudflare", "sentry", "ops", "waf", "dns"] + "keywords": [ + "refact", + "skills", + "cloudflare", + "sentry", + "ops", + "waf", + "dns" + ] } diff --git a/plugins/ops/.codex-plugin/plugin.json b/plugins/ops/.codex-plugin/plugin.json new file mode 100644 index 0000000..c07e0cb --- /dev/null +++ b/plugins/ops/.codex-plugin/plugin.json @@ -0,0 +1,29 @@ +{ + "name": "ops", + "version": "1.2.0", + "description": "Refact ops workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "cloudflare", + "sentry", + "ops", + "waf", + "dns" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact Ops", + "shortDescription": "Use the Refact ops skill pack.", + "longDescription": "Shared Refact ops skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact ops skills for this project." + } +} diff --git a/plugins/ops/references/plugin-runtime.md b/plugins/ops/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/ops/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/ops/skills/cloudflare/SKILL.md b/plugins/ops/skills/cloudflare/SKILL.md index faebaf5..4da6c5c 100644 --- a/plugins/ops/skills/cloudflare/SKILL.md +++ b/plugins/ops/skills/cloudflare/SKILL.md @@ -19,6 +19,8 @@ references: # Cloudflare Skill — Refact +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use the decision trees below to find the right workflow, then load the relevant references. ## How to Use This Skill diff --git a/plugins/ops/skills/sentry/SKILL.md b/plugins/ops/skills/sentry/SKILL.md index 65a90a9..83c475f 100644 --- a/plugins/ops/skills/sentry/SKILL.md +++ b/plugins/ops/skills/sentry/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Sentry Triage +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this when a ticket says something like "review the Sentry logs and fix what we can, ignore what we can't so it doesn't fill our quota." The job has three moves: **inventory** (what's firing and how much), **fix what's ours**, and **mute what isn't** so the quota diff --git a/plugins/testing/.claude-plugin/plugin.json b/plugins/testing/.claude-plugin/plugin.json index 5614acc..7e5149e 100644 --- a/plugins/testing/.claude-plugin/plugin.json +++ b/plugins/testing/.claude-plugin/plugin.json @@ -1,10 +1,18 @@ { "name": "testing", - "version": "1.2.0", + "version": "1.3.0", "description": "Testing: TDD harness (plan -> red-green-refactor) plus WordPress characterization and real-plugin integration tests.", "author": { "name": "Refact Developer", "email": "dev@refact.co" }, - "keywords": ["refact", "skills", "testing", "tdd", "phpunit", "wordpress", "integration"] + "keywords": [ + "refact", + "skills", + "testing", + "tdd", + "phpunit", + "wordpress", + "integration" + ] } diff --git a/plugins/testing/.codex-plugin/plugin.json b/plugins/testing/.codex-plugin/plugin.json new file mode 100644 index 0000000..958e1d8 --- /dev/null +++ b/plugins/testing/.codex-plugin/plugin.json @@ -0,0 +1,29 @@ +{ + "name": "testing", + "version": "1.3.0", + "description": "Refact testing workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "testing", + "tdd", + "phpunit", + "wordpress", + "integration" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact Testing", + "shortDescription": "Use the Refact testing skill pack.", + "longDescription": "Shared Refact testing skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact testing skills for this project." + } +} diff --git a/plugins/testing/references/plugin-runtime.md b/plugins/testing/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/testing/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/testing/skills/backfill-tests/SKILL.md b/plugins/testing/skills/backfill-tests/SKILL.md index 76180c6..11d3e13 100644 --- a/plugins/testing/skills/backfill-tests/SKILL.md +++ b/plugins/testing/skills/backfill-tests/SKILL.md @@ -11,6 +11,8 @@ sub_agents: [] # Backfill Tests — Characterization Tests for Existing Code +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + The code already exists — written before TDD — and you want a safety net under it. So instead of driving design (that's the TDD harness), you **characterize** the code's current observable behaviour and pin it with behaviour-driven unit tests. The result is a regression suite that lets the code be changed later with confidence. ## What this skill does NOT do diff --git a/plugins/testing/skills/integration-tests/SKILL.md b/plugins/testing/skills/integration-tests/SKILL.md index 7288e1c..257ebf3 100644 --- a/plugins/testing/skills/integration-tests/SKILL.md +++ b/plugins/testing/skills/integration-tests/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Integration Tests — Decide What's Worth It, Then Build It +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + The `backfill-tests` skill characterizes maintained WordPress code with **unit** tests. When a surface's correctness depends on a **complex** third-party object graph — a full `WC_Cart` with line items, coupons, taxes; a `MeprUser` and its transaction/subscription objects — backfill refuses to fake it (a faithful fake would reimplement a chunk of the library) and marks it `🔌 integration`, deferring it to "a separate integration suite this skill does not build." **This is that skill.** Its input is the `🔌 integration` rows in backfill's `COVERAGE.md`. But it does **not** blindly write an integration test for every one — integration tests are slow, need the real plugin present, and flake more, so building them indiscriminately produces a brittle suite nobody trusts. The heart of this skill is a **decision gate** (step 2): *which `🔌` surfaces is integration testing actually worth it for?* Only the ones that pass the gate get built. The rest are deferred with a reason and a cheaper alternative noted (a contract test, a staging/manual check). diff --git a/plugins/testing/skills/red-green-refactor/SKILL.md b/plugins/testing/skills/red-green-refactor/SKILL.md index 63c1dd5..3e3f2f5 100644 --- a/plugins/testing/skills/red-green-refactor/SKILL.md +++ b/plugins/testing/skills/red-green-refactor/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # Red-Green-Refactor — Unit-Loop TDD (Phase 2) +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Develop **one slice** test-first: a failing unit test sets the next goal, the minimum code makes it pass, and a refactor-on-green cleans it up. Repeat until the slice's behaviour — its acceptance criterion — is met. This harness runs **unit tests only** (WordPress PHPUnit via wp-env); there is no automated end-to-end / browser layer. **Read `references/red-green-refactor-philosophy.md` now** if you have not this session — it is the authoritative rulebook, and everything below is a summary of it. For detecting, setting up, and running the project's unit tooling (WordPress wp-env + PHPUnit), read `references/test-strategy.md`. diff --git a/plugins/testing/skills/tdd-plan/SKILL.md b/plugins/testing/skills/tdd-plan/SKILL.md index ee827ea..9f3348e 100644 --- a/plugins/testing/skills/tdd-plan/SKILL.md +++ b/plugins/testing/skills/tdd-plan/SKILL.md @@ -11,6 +11,8 @@ sub_agents: [] # TDD Plan — Slice & Plan (Phase 1) +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Turn a request into a set of **thin vertical slices**, each captured as a markdown execution plan in `plans/`. A good slice is the smallest change in system behaviour that is independently valuable and verifiable through tests. The plan you write here is the contract the `red-green-refactor` skill executes next — so make it precise. **Slicing is the hardest and most valuable judgement in TDD.** "Sequencing the tests properly is a skill — pick tests that drive you quickly to the salient points in the design." Take your time here. diff --git a/plugins/testing/skills/tdd/SKILL.md b/plugins/testing/skills/tdd/SKILL.md index 3f153f5..7a04c8b 100644 --- a/plugins/testing/skills/tdd/SKILL.md +++ b/plugins/testing/skills/tdd/SKILL.md @@ -12,6 +12,8 @@ sub_agents: [] # TDD Harness — Orchestrator +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + You are running an enterprise-grade Test-Driven Development harness. Your job is to take whatever the user wants built and shepherd it through three disciplined phases, **enforcing the gate between each**. You do not write feature code ad hoc; you drive the pipeline. The harness runs **unit tests only** (WordPress PHPUnit via wp-env) — there is no end-to-end / browser layer. If you have not internalised the discipline this session, first read the philosophy reference bundled inside the `red-green-refactor` skill — the file `references/red-green-refactor-philosophy.md` within that skill's own directory. The whole harness rests on it. diff --git a/plugins/wordpress/.claude-plugin/plugin.json b/plugins/wordpress/.claude-plugin/plugin.json index e94c07b..bc0a889 100644 --- a/plugins/wordpress/.claude-plugin/plugin.json +++ b/plugins/wordpress/.claude-plugin/plugin.json @@ -1,10 +1,20 @@ { "name": "wordpress", - "version": "1.1.0", + "version": "1.2.0", "description": "WordPress: local wp-env stack, safe plugin updates with QA + rollback, Kinsta/WP Engine deploy workflows + PHP LSP.", "author": { "name": "Refact Developer", "email": "dev@refact.co" }, - "keywords": ["refact", "skills", "wordpress", "wp-env", "kinsta", "wpengine", "php", "lsp"] + "keywords": [ + "refact", + "skills", + "wordpress", + "wp-env", + "kinsta", + "wpengine", + "php", + "lsp" + ], + "hooks": "./hooks/claude-hooks.json" } diff --git a/plugins/wordpress/.codex-plugin/plugin.json b/plugins/wordpress/.codex-plugin/plugin.json new file mode 100644 index 0000000..cc0d825 --- /dev/null +++ b/plugins/wordpress/.codex-plugin/plugin.json @@ -0,0 +1,30 @@ +{ + "name": "wordpress", + "version": "1.2.0", + "description": "Refact wordpress workflows for Claude Code and Codex.", + "author": { + "name": "Refact Developer", + "email": "dev@refact.co" + }, + "repository": "https://github.com/refactco/claude-toolkit", + "keywords": [ + "refact", + "skills", + "wordpress", + "wp-env", + "kinsta", + "wpengine", + "php", + "lsp" + ], + "skills": "./skills/", + "interface": { + "displayName": "Refact WordPress", + "shortDescription": "Use the Refact wordpress skill pack.", + "longDescription": "Shared Refact wordpress skills, scripts, and references. Requires the local tools and service connections described by each skill.", + "developerName": "Refact Developer", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Use the Refact wordpress skills for this project." + } +} diff --git a/plugins/wordpress/hooks/hooks.json b/plugins/wordpress/hooks/claude-hooks.json similarity index 100% rename from plugins/wordpress/hooks/hooks.json rename to plugins/wordpress/hooks/claude-hooks.json diff --git a/plugins/wordpress/references/plugin-runtime.md b/plugins/wordpress/references/plugin-runtime.md new file mode 100644 index 0000000..001849f --- /dev/null +++ b/plugins/wordpress/references/plugin-runtime.md @@ -0,0 +1,43 @@ + + +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/plugins/wordpress/skills/install-wp-skills/SKILL.md b/plugins/wordpress/skills/install-wp-skills/SKILL.md index 1181a38..08a7639 100644 --- a/plugins/wordpress/skills/install-wp-skills/SKILL.md +++ b/plugins/wordpress/skills/install-wp-skills/SKILL.md @@ -10,6 +10,17 @@ sub_agents: [] # Install WordPress Agent Skills Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + +In **Codex**, the destination is the project's `.agents/skills/`, not +`.claude/skills/`. Follow the same preflight and selected skill list below. +After cloning, inspect the upstream installer's help for its current Codex +target. Use that supported target and verify the actual destination. If it has +no Codex target, copy only the selected self-contained skill folders from the +built distribution into `.agents/skills/`, including their support files. +Do not guess a `--targets` value or claim a Claude-directory install enables +Codex skills. The `--targets=claude` example below is for Claude Code only. + Use this reference when the user invokes `/refact install wp skills` (or asks to "add WordPress skills", "pull the WP agent skills", "install Gutenberg/block skills", etc.). ## Goal diff --git a/plugins/wordpress/skills/plugin-update/SKILL.md b/plugins/wordpress/skills/plugin-update/SKILL.md index f332fb0..bad0c1d 100644 --- a/plugins/wordpress/skills/plugin-update/SKILL.md +++ b/plugins/wordpress/skills/plugin-update/SKILL.md @@ -11,6 +11,8 @@ sub_agents: [] # plugin-update Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this reference when the user asks to **check for and safely apply WordPress plugin updates** — e.g. "are there plugin updates?", "update the plugins", "safely update WPForms", "run the plugin update QA loop". It runs the full loop for **one plugin at a time**: read the changelog → draft a targeted QA checklist → snapshot → update **on staging** → QA (three layered signals) → **pass** promotes the *same* version to production (human-gated) or **fail** rolls back on staging. It never updates production blind, and never updates more than one plugin per cycle so rollback scope stays clean. diff --git a/plugins/wordpress/skills/setup-kinsta-deploy/SKILL.md b/plugins/wordpress/skills/setup-kinsta-deploy/SKILL.md index 3dd9544..28ed86c 100644 --- a/plugins/wordpress/skills/setup-kinsta-deploy/SKILL.md +++ b/plugins/wordpress/skills/setup-kinsta-deploy/SKILL.md @@ -11,6 +11,8 @@ sub_agents: [] # Kinsta Auto-Deploy Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this reference when the user invokes any of: - `/refact setup kinsta auto-deploy` diff --git a/plugins/wordpress/skills/setup-wpengine-deploy/SKILL.md b/plugins/wordpress/skills/setup-wpengine-deploy/SKILL.md index 24dc70e..c11b8a9 100644 --- a/plugins/wordpress/skills/setup-wpengine-deploy/SKILL.md +++ b/plugins/wordpress/skills/setup-wpengine-deploy/SKILL.md @@ -11,6 +11,8 @@ sub_agents: [] # WP Engine Auto-Deploy Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this reference when the user invokes any of: - `/refact setup wpengine auto-deploy` diff --git a/plugins/wordpress/skills/wp-env/SKILL.md b/plugins/wordpress/skills/wp-env/SKILL.md index 1e56cb2..beb677f 100644 --- a/plugins/wordpress/skills/wp-env/SKILL.md +++ b/plugins/wordpress/skills/wp-env/SKILL.md @@ -10,6 +10,8 @@ sub_agents: [] # wp-env Reference +Read [runtime instructions](../../references/plugin-runtime.md) before using this skill. + Use this reference when the user invokes any of: - `/refact wp-env setup [--with-tests]` — bring up a fresh local WordPress stack and, in the same flow, optionally pull plugins/mu-plugins + DB from staging and set a local domain. Idempotent: each sub-step is verified independently and skipped silently if already met, so re-running on a fully-configured project is a no-op. By default, the tests instance is stopped to save resources; pass `--with-tests` to keep it running. diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..f62ce0c --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1 @@ +PyYAML==6.0.3 diff --git a/scripts/check-plugins.py b/scripts/check-plugins.py new file mode 100644 index 0000000..af49b53 --- /dev/null +++ b/scripts/check-plugins.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python3 +"""Check both package formats and shared skill files without executing tools.""" +import json +import re +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parent.parent + + +def check(root=ROOT): + errors = [] + claude = json.loads((root / '.claude-plugin/marketplace.json').read_text()) + codex = json.loads((root / '.agents/plugins/marketplace.json').read_text()) + expected_names = [entry['name'] for entry in claude['plugins']] + if [entry['name'] for entry in codex['plugins']] != expected_names: + errors.append('Codex catalog must preserve the Claude pack list and order') + if claude['name'] != codex['name']: + errors.append('Marketplace names differ') + if len(expected_names) != len(set(expected_names)): + errors.append('Duplicate pack name') + skills = 0 + for entry in claude['plugins']: + name = entry['name'] + if not re.fullmatch(r'[a-z0-9-]+', name): + errors.append(f'Invalid pack name: {name}') + continue + pack = root / 'plugins' / name + source = json.loads((pack / '.claude-plugin/plugin.json').read_text()) + native = json.loads((pack / '.codex-plugin/plugin.json').read_text()) + if not (source['name'] == native['name'] == name): + errors.append(f'{name}: inconsistent plugin names') + if not (source['version'] == native['version'] == entry['version']): + errors.append(f'{name}: inconsistent versions') + if native.get('skills') != './skills/': + errors.append(f'{name}: native manifest must load shared skills') + if (pack / 'hooks/hooks.json').exists(): + errors.append(f'{name}: Claude hooks would be auto-loaded by Codex') + if source.get('hooks'): + path = pack / source['hooks'] + if not path.is_file(): + errors.append(f'{name}: missing Claude hooks') + else: + json.loads(path.read_text()) + runtime = pack / 'references/plugin-runtime.md' + for skill in sorted((pack / 'skills').glob('*/SKILL.md')): + skills += 1 + text = skill.read_text() + match = re.match(r'^---\n(.*?)\n---', text, re.S) + if not match: + errors.append(f'{skill}: missing frontmatter') + continue + try: + metadata = yaml.safe_load(match.group(1)) + except yaml.YAMLError as error: + errors.append(f'{skill}: invalid YAML: {error}') + continue + if not isinstance(metadata, dict) or metadata.get('name') != skill.parent.name: + errors.append(f'{skill}: invalid or mismatched skill name') + continue + if not isinstance(metadata.get('description'), str) or not metadata['description'].strip(): + errors.append(f'{skill}: missing skill description') + if '../../references/plugin-runtime.md' not in text or not runtime.is_file(): + errors.append(f'{skill}: missing shared runtime instructions') + for sibling in metadata.get('next_skills', []): + if not (pack / 'skills' / sibling / 'SKILL.md').is_file(): + errors.append(f'{skill}: missing next skill {sibling}') + if errors: + raise ValueError('\n'.join(errors)) + return len(expected_names), skills + + +if __name__ == '__main__': + packs, skills = check() + print(f'Validated {packs} Claude/Codex packs and {skills} shared skills.') diff --git a/scripts/sync-codex.mjs b/scripts/sync-codex.mjs new file mode 100644 index 0000000..1bee8c1 --- /dev/null +++ b/scripts/sync-codex.mjs @@ -0,0 +1,81 @@ +#!/usr/bin/env node +// Generate Codex metadata and package-local runtime notes from the Claude packs. +import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'; +import { resolve, dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const check = process.argv.includes('--check'); +if (process.argv.slice(2).some((arg) => arg !== '--check')) { + throw new Error('Usage: node scripts/sync-codex.mjs [--check]'); +} +const catalogPath = join(root, '.claude-plugin/marketplace.json'); +const catalog = JSON.parse(readFileSync(catalogPath, 'utf8')); +const identifier = /^[A-Za-z0-9_-]+$/; +if (!identifier.test(catalog.name)) throw new Error('Invalid marketplace name'); +const runtime = '\n\n' + + readFileSync(join(root, 'shared/plugin-runtime.md'), 'utf8'); +const names = new Set(); +let changed = 0; +const emit = (path, contents) => { + const current = existsSync(path) ? readFileSync(path, 'utf8') : null; + if (current === contents) return; + changed++; + if (check) { + console.error(`Out of date: ${path.slice(root.length + 1)}`); + return; + } + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, contents); +}; +const json = (value) => JSON.stringify(value, null, 2) + '\n'; +const entries = catalog.plugins.map((entry) => { + if (!identifier.test(entry.name) || names.has(entry.name)) { + throw new Error(`Invalid or duplicate plugin name: ${entry.name}`); + } + names.add(entry.name); + if (entry.source !== `./plugins/${entry.name}`) { + throw new Error(`Unexpected source for ${entry.name}`); + } + const pack = join(root, 'plugins', entry.name); + const source = JSON.parse(readFileSync(join(pack, '.claude-plugin/plugin.json'), 'utf8')); + if (source.name !== entry.name) throw new Error(`Plugin name mismatch: ${entry.name}`); + // The pack manifest owns the version. Both catalogs are derived from it. + entry.version = source.version; + const label = `Refact ${entry.name === 'nextjs' ? 'Next.js' : entry.name === 'wordpress' + ? 'WordPress' : entry.name[0].toUpperCase() + entry.name.slice(1)}`; + emit(join(pack, '.codex-plugin/plugin.json'), json({ + name: source.name, + version: source.version, + description: `Refact ${entry.name} workflows for Claude Code and Codex.`, + author: source.author, + repository: 'https://github.com/refactco/claude-toolkit', + keywords: source.keywords, + skills: './skills/', + interface: { + displayName: label, + shortDescription: `Use the Refact ${entry.name} skill pack.`, + longDescription: `Shared Refact ${entry.name} skills, scripts, and references. ` + + 'Requires the local tools and service connections described by each skill.', + developerName: source.author.name, + category: 'Productivity', + capabilities: [], + defaultPrompt: `Use the Refact ${entry.name} skills for this project.`, + }, + })); + emit(join(pack, 'references/plugin-runtime.md'), runtime); + return { + name: entry.name, + source: { source: 'local', path: entry.source }, + policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' }, + category: 'Productivity', + }; +}); +emit(catalogPath, json(catalog)); +emit(join(root, '.agents/plugins/marketplace.json'), json({ + name: catalog.name, + interface: { displayName: 'Refact Toolkit' }, + plugins: entries, +})); +if (check && changed) process.exitCode = 1; +console.log(`${check ? 'Checked' : 'Synced'} ${entries.length} packs; ${changed} file(s) ${check ? 'need changes' : 'changed'}.`); diff --git a/shared/plugin-runtime.md b/shared/plugin-runtime.md new file mode 100644 index 0000000..ef44e6f --- /dev/null +++ b/shared/plugin-runtime.md @@ -0,0 +1,41 @@ +# Shared plugin runtime + +These skills work in Claude Code and Codex. Follow the active host's tools, +permissions, and user instructions. + +- Resolve bundled files from the loaded `SKILL.md`, not from the project working + directory. Its parent is the skill directory; two more parents give the plugin + root. In command examples, replace `${CLAUDE_PLUGIN_ROOT}` with that absolute + plugin root and quote the path. This is a path placeholder in shared instructions; + do not assume the environment variable exists in Codex. Keep script execution in + the target project so project config and relative output paths still work. +- To invoke another skill, use the host's skill tool when available. In Codex, + find the named skill in the available-skills list, read its `SKILL.md`, and follow + it. Within this pack, sibling skills are under `..//SKILL.md`. + Do not invent a `Skill` tool or run Claude's CLI to load a Codex skill. +- Names such as `insights:data-puller` identify agent briefs at + `/agents/data-puller.md`. In Claude Code, use the registered agent. + In Codex, read the brief and pass its instructions to an available subagent tool. + Claude agent/model frontmatter does not select a Codex model. Preserve read-only + limits, sequential work, approval gates, and output limits. If delegation is not + available, do the same bounded work in the current task and save large output to + files. Do not claim work ran in a separate agent when it did not. +- Use the active host's planning and question tools when a workflow asks for a + todo list or a question. If those tools are absent, keep a short written plan or + ask the user directly. Follow authorization already given in the conversation. +- Discover connected service tools by their purpose and schema. Tool prefixes + can differ by host. A missing service connection is a setup requirement; never + invent tool results or credentials. +- Claude's command menu is `/base:refact`. In Codex, use the `refact-toolkit` skill + or ask for the desired outcome. Plugin install/update commands belong to the + current host; see the `manage-plugins` skill for the correct branch. +- Claude lifecycle hooks and language-server setup are not enabled by these + Codex packages. Perform required project-config checks explicitly in the skill. + Transcript upload remains a Claude-only feature. +- For a `memory` pack workflow in Codex, first run the bundled + `hooks/refresh-memory-mount.mjs` from the target project, with an absolute script + path. Honor `REFACT_MEMORY_READONLY`. Then follow the memory skill's own checks. + Do not treat a missing memory mount as a successful refresh. + +Changes to these shared notes are copied into each installable pack by +`node scripts/sync-codex.mjs`. Edit the source under `shared/`. diff --git a/tests/plugin-support.test.mjs b/tests/plugin-support.test.mjs new file mode 100644 index 0000000..7c4f1cf --- /dev/null +++ b/tests/plugin-support.test.mjs @@ -0,0 +1,82 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdtempSync, readFileSync, writeFileSync, cpSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join, resolve, dirname } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { spawnSync } from 'node:child_process'; + +const root = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const json = (path) => JSON.parse(readFileSync(path, 'utf8')); + +test('generation detects a missed release and repairs both catalogs without changing skill bodies', () => { + const fixture = mkdtempSync(join(tmpdir(), 'refact-release-')); + try { + for (const path of ['scripts', 'shared', 'plugins', '.claude-plugin', '.agents']) { + cpSync(join(root, path), join(fixture, path), { recursive: true }); + } + const run = (...args) => spawnSync(process.execPath, ['scripts/sync-codex.mjs', ...args], { + cwd: fixture, encoding: 'utf8', + }); + assert.equal(run('--check').status, 0); + const sourcePath = join(fixture, 'plugins/base/.claude-plugin/plugin.json'); + const source = json(sourcePath); + source.version = '9.9.9'; + writeFileSync(sourcePath, JSON.stringify(source, null, 2) + '\n'); + const skillPath = join(fixture, 'plugins/base/skills/refact-toolkit/SKILL.md'); + const skillBefore = readFileSync(skillPath, 'utf8'); + const catalogBefore = readFileSync(join(fixture, '.claude-plugin/marketplace.json'), 'utf8'); + assert.equal(run('--check').status, 1); + assert.equal(readFileSync(join(fixture, '.claude-plugin/marketplace.json'), 'utf8'), catalogBefore); + assert.equal(run().status, 0); + assert.equal(json(join(fixture, 'plugins/base/.codex-plugin/plugin.json')).version, '9.9.9'); + assert.equal(json(join(fixture, '.claude-plugin/marketplace.json')).plugins[0].version, '9.9.9'); + assert.equal(readFileSync(skillPath, 'utf8'), skillBefore); + assert.equal(run('--check').status, 0); + } finally { + rmSync(fixture, { recursive: true, force: true }); + } +}); + +test('generation refuses duplicate plugin identities', () => { + const fixture = mkdtempSync(join(tmpdir(), 'refact-catalog-')); + try { + for (const path of ['scripts', 'shared', 'plugins', '.claude-plugin', '.agents']) { + cpSync(join(root, path), join(fixture, path), { recursive: true }); + } + const path = join(fixture, '.claude-plugin/marketplace.json'); + const catalog = json(path); + catalog.plugins.push(catalog.plugins[0]); + writeFileSync(path, JSON.stringify(catalog)); + const result = spawnSync(process.execPath, ['scripts/sync-codex.mjs', '--check'], { + cwd: fixture, encoding: 'utf8', + }); + assert.notEqual(result.status, 0); + assert.match(result.stderr, /duplicate plugin name/); + } finally { + rmSync(fixture, { recursive: true, force: true }); + } +}); + +test('preflight recognizes both Claude command spellings and respects existing config', () => { + const fixture = mkdtempSync(join(tmpdir(), 'refact preflight ')); + const script = join(root, 'plugins/base/hooks/preflight-refact-config.mjs'); + try { + const run = (prompt) => spawnSync(process.execPath, [script], { + cwd: fixture, + env: { ...process.env, CLAUDE_PROJECT_DIR: fixture }, + input: JSON.stringify({ prompt }), encoding: 'utf8', + }); + for (const prompt of ['/refact config', '/base:refact config']) { + const result = run(prompt); + assert.equal(result.status, 0); + assert.match(result.stdout, /was not found/); + } + assert.equal(run('Please review the project').stdout, ''); + assert.equal(run('/refactoring').stdout, ''); + writeFileSync(join(fixture, '.refact-os.json'), '{}'); + assert.equal(run('/base:refact config').stdout, ''); + } finally { + rmSync(fixture, { recursive: true, force: true }); + } +});