← The writingField guide 003

Claude Code + Codex · Skills · Human decisions

Claudops.
Choose your
workflow.

Give Claudops a real project. Choose a workflow for the change you need, then carry the requirements through implementation and review.

By Alex Basis · A practical guide to the plugin edition

DiscoverPlanImplementReview

01 / The plugin edition

The workflow can live
outside your repository.

The useful part of a coding workflow is the agreement about how work proceeds. What needs a decision? Where does the plan live? What proves the change works? Those questions come back with every feature.

Claudops packages my development workflows as skills. The core commands cover feature discovery, planning, implementation, and review. They share a task record, so the requirements from discovery remain available when the code is reviewed. Claude Code and Codex can load those instructions as plugins while the task and its evidence stay in your project.

The earlier workflow lived in a .claude/ directory copied into each repository. Packaging those skills as a plugin separates their maintenance from your project. Your code, project instructions and task documents stay in the repository. Install it through your client's plugin manager.

Where things belongPlugin mode
A

The loaded package

Reusable instructions and resources

Claude Codeskills/agents/40 skills · 18 agents
Codexskills/40 skills · No registered agents
B

Your project

Local choices and work you can inspect

CLAUDE.md Claude Code instructionsAGENTS.md Codex instructionstasks/…/TASK.md example task recordReuse your project's conventions

Loading instructions does not enable hooks, configure MCP servers, or copy the workflow into the repository. Those are separate actions. Package details ↗

CodexThe Codex edition uses the Agent Plugins format. Its skills run with the tools and permissions available in your session. It registers no agents, hooks, or MCP servers. For specialized review, it includes role instructions that Codex can give to an available worker or follow directly. A direct review is reported as such. Browser checks and external reviewers still need the corresponding tools. How roles run in Codex ↗

A skill gives the agent a procedure for a recurring job. An agent definition provides a specialized role for delegated work. A hook is executable behavior attached to an event. Keeping those separate matters: seeing a skill in your command list says nothing about whether a lint hook is active.

You also do not need to memorize the entire package. Start with one job and the command that fits it. The rest becomes useful when the work gives you a reason to reach for it.

02 / Install once

Two commands.
Then your first task.

A marketplace is a catalog of plugins. Add the Claudops catalog, then install its plugin. Your client manages the installed copy; project instructions and task records stay in your repository.

Claude CodeStart with Claude Code installed and signed in. Run the plugin commands inside a Claude Code session.

CodexStart with a current Codex CLI installed and signed in. Run installation commands in a terminal. The native plugin flow was checked with Codex CLI 0.153.4.

Getting started · Change client

Claude Code · Install

Add Claudops to Claude Code.

Open a terminal in the project you want to change and start Claude Code. Run each slash command below inside that session.

Shell · Replace the example path 
cd /path/to/your-project
claude
Inside Claude Code · 1. Add the catalog 
/plugin marketplace add alexandrbasis/claudops
Inside Claude Code · 2. Install the plugin 
/plugin install claudops@claudops

The first claudops is the plugin name; the second is the marketplace. Use user scope to make it available across your projects. Project scope shares the installation choice through repository settings.

Claudops installation instructions · Claude Code installation scopes

Codex · Install

Add Claudops to Codex.

Run these two commands in your terminal. Codex uses the same marketplace name and selects the package prepared for its runtime.

Shell · Codex · 1. Add the catalog 
codex plugin marketplace add alexandrbasis/claudops
Shell · Codex · 2. Install the plugin 
codex plugin add claudops@claudops

The first claudops is the plugin name; the second is the marketplace. The Codex package registers 40 skills and no agents, hooks, or MCP servers.

Claudops installation instructions · Codex package and runtime details

Claude Code · First task

Check the plugin. Give it one real change.

The installed plugin supplies the skills; your current directory supplies the code and project instructions. Reload plugins or start a new session in the same project, then check the installation.

Inside Claude Code · Load the installed skills 
/reload-plugins
Inside Claude Code · Check installed plugins 
/plugin

In Installed, check that Claudops is enabled and its skills are listed. Check Errors for loading failures. The Claude package includes 40 skills and 18 agents.

Inside Claude Code · A small first task 
/claudops:ct Describe the change you want to make.

Enter the slash command with its request. Replace the example request with your actual task. Use /claudops:nf when the feature still needs discovery.

Plugin installation and management ↗

Codex · First task

Check the installation. Start in your project.

Check that Claudops is enabled, then start a new Codex session in the repository you want to change. Codex reads its project instructions from AGENTS.md when present.

Shell · Codex · Check installed plugins 
codex plugin list --marketplace claudops --json

Find Claudops in the output and check that enabled is true. Start a new session after installing or updating it.

Shell · Replace the example project path 
cd /path/to/your-project
codex
Inside Codex · A small first task 
$claudops:ct Describe the change you want to make.

Mention the skill with its full dollar-prefixed name and give it your request. This is a prompt inside Codex, not a terminal command. Use $claudops:nf when the feature still needs discovery.

Codex installation and skill invocation ↗

Claude Code · Updates

Update through the same catalog.

In a terminal, refresh the catalog first, then update the installed plugin. The commands below assume user scope; use the scope you selected at installation.

Shell · Claude Code · 1. Refresh the catalog 
claude plugin marketplace update claudops
Shell · Claude Code · 2. Update your installation 
claude plugin update claudops@claudops --scope user

Apply the update with /reload-plugins inside Claude Code or start a new session. For automatic updates, open /plugin, select Claudops under Marketplaces, and enable auto-update.

Managing plugins and marketplaces ↗

Codex · Updates

Refresh the catalog. Apply its plugin.

Run these commands in your terminal, then start a new Codex session.

Shell · Codex · 1. Refresh the catalog 
codex plugin marketplace upgrade claudops
Shell · Codex · 2. Apply the current plugin 
codex plugin add claudops@claudops

Codex installation and updates ↗

The update-setup skill maintains an older project-owned copy of the workflow. It does not update the installed plugin. If your repository already has customized .claude/ skills, preserve those files and decide which installation you intend to use.

Scope of update-setup ↗

03 / Your first session

Make the project
legible first.

The most useful first conversation is about a real repository and a small, concrete change. You want the agent to find the evidence you already have, name the decisions you still need to make, and leave a record you can return to tomorrow.

Install Claudops and confirm it is loaded in your selected client, then use these examples in your project. The invoice CSV prompts below illustrate the workflow; they are not a transcript of a completed run. Step through them, then adapt the request to your project.

First-session worksheetExample · Invoice export
01

Start in the real repository

Start your selected client in a project you can run locally. The example below assumes it already has an invoice page. Substitute a real feature in your own project.

Your prompt · Inside Claude Code 
Find the invoice page, the project instructions, and the commands for running and testing this app. Show the relevant paths.
Your prompt · Inside Codex 
Find the invoice page, the project instructions, and the commands for running and testing this app. Show the relevant paths.

What comes back

The existing page and its code, plus the project commands found in package configuration, a Makefile, or CI.

Your decision

Check the repository and workspace paths. In a monorepo, name the package this task belongs to.

02

Configure only if needed

Skip this step when the project instructions and commands are already clear. Use setup for a missing project choice, such as which package to work in or where this team keeps task notes.

Your prompt · Inside Claude Code 
/claudops:setup Use the project's existing instructions and task convention. Help me resolve any missing project choices.
Your prompt · Inside Codex 
$claudops:setup Use the project's existing instructions and task convention, including AGENTS.md when present. Help me resolve any missing project choices.

What comes back

A summary of the project settings found and any choices you still need to make. Keep lasting instructions in the project's existing instruction files.

Your decision

Confirm only the choices that the repository could not answer.

03

Give one task a durable home

Use discovery when the request still leaves product decisions open. Here, "current list" could mean the visible page or every filtered invoice. If the behavior and scope are already settled, start with the planning skill, ct, instead.

Your prompt · Inside Claude Code 
/claudops:nf Account owners need to export the current invoice list as CSV. Inspect the existing page and help define which rows and fields the export should contain.
Your prompt · Inside Codex 
$claudops:nf Account owners need to export the current invoice list as CSV. Inspect the existing page and help define which rows and fields the export should contain.

What comes back

A discovery-<feature-name>.md document linked from the task record, with requirements, decisions, and open questions. The agent returns the actual paths. Keep the task path for the next command.

Your decision

Settle which rows and fields belong in the export. For the example below, choose all filtered rows, in the current sort order, with only fields the account owner can access.

04

Review the plan before implementation

Replace <task-path> below with the path returned by discovery. Planning reads that task and the affected code, then adds the changes and how to verify them. For a clear new request without discovery, omit the task path and give the planning skill a description of the change.

Your prompt · Inside Claude Code 
/claudops:ct <task-path> Plan the agreed invoice CSV export, including checks for account permissions, filters, sorting, CSV escaping, and an empty result.
Your prompt · Inside Codex 
$claudops:ct <task-path> Plan the agreed invoice CSV export, including checks for account permissions, filters, sorting, CSV escaping, and an empty result.

What comes back

An implementation plan in the same task, with affected files, ordered steps, verification, and any remaining decisions.

Your decision

Read the plan. When ready to implement, use the implementation skill, si, with this same task path.

Claude Code sources: setup, discovery, and planning.

Codex sources: setup, discovery, and planning.

04 / The part that survives the chat

One change.
One place to resume.

Repeatedly explaining the same feature is expensive in a quieter way than a failing build. Each retelling leaves room for the requirement to drift. A task record gives discovery, planning, implementation, and review the same place to look.

Claudops first resolves your existing task convention. When no convention exists, the fallback is tasks/task-YYYY-MM-DD-<slug>/TASK.md. A small, clearly defined change handled by ct or quick can keep its plan and verification in that file. Feature discovery with nf writes a linked discovery-<feature>.md. One task record means one entrypoint, not a rule that everything must fit in one file. Read the shared task contract.

Example task entrypointtasks/…-invoice-csv/TASK.md
Problem

Account owners need a CSV of the invoice list they filtered.

Discovery
Decision

Export all matching rows. Preserve the current sort order.

You
Plan

Reuse the filtered query and authorization path. Add serialization and a download action.

Planning
Evidence

Record the commands run, their result, and the behaviors checked.

Implementation
Next

Keep the current review findings and the next required decision visible.

Review

Illustrative content, not a required template. Reuse the project's actual structure.

A link to the task is more useful than a fresh summary written from memory. On the next session, give the existing task path and ask the agent to inspect the repository before continuing. If you need a fresh session, ph writes a HANDOFF.md for the task. Give the next session the returned task and handoff paths so it can resume from the files.

Keep the record proportionate. An architectural decision may deserve a linked document. A button label can fit beside a short plan and the verification result. The point is to preserve the decisions someone would otherwise have to rediscover.

05 / Pick the job in front of you

Different work.
Different starting points.

The full discovery-to-review sequence is useful when the feature itself is still being defined. A runtime bug already has a symptom. A small correction may already have a complete specification. An architectural exploration begins with friction in the code. An existing PR already has a diff and review history.

Choose a scenario to see its input, command sequence, expected output, and the decision that remains yours. The examples illustrate how to use the documented skills; they are not claims that these changes have been implemented.

Case 01

Export exactly what the user filtered

Continue the invoice example from the first session. Discovery has settled the export behavior, and the plan is in the task record. The next step is implementation.

The request

"Implement the agreed export: all filtered invoices in the current sort order, with only fields the account owner can access. Use our existing download pattern."

  1. 01

    Implement

    Claude Code: /claudops:si <task-path>Codex: $claudops:si <task-path>

    Read the existing plan. For each behavior change, observe a failing test, implement the change, and run the relevant checks. Save progress and verification in the same task.

  2. 02

    Review the current changes

    Claude Code: /claudops:srCodex: $claudops:sr

    Run from the project with the changes still present. The review inspects the current working tree and the agreed requirements. An uncommitted change receives a draft review; findings and unverified checks remain visible.

The reviewable result

A reviewable diff, tests for the agreed behavior, verification results, and a task record that explains what was decided.

The human checkpoint

You settle export semantics before implementation and authorize delivery after the review. A passing CSV test does not establish that the right rows were chosen.

A prompt to adapt · Inside Claude Code 
/claudops:si <task-path> Implement the invoice CSV plan. Verify the agreed rows, fields, ordering, permissions, and download behavior.
A prompt to adapt · Inside Codex 
$claudops:si <task-path> Implement the invoice CSV plan. Verify the agreed rows, fields, ordering, permissions, and download behavior.

Use the task path returned in the first session. After implementation, review the result against those same requirements.

Read the Claude Code skill ↗Read the Codex skill ↗

Case 02

The second click creates a duplicate

Two clicks create duplicate exports. You can reproduce this in a local development environment, but the cause could be the browser, a retry, or the job queue. The debugging skill needs access to that running path and its logs.

The request

"Locally, clicking Export CSV twice quickly creates two jobs. We expect one export while a job is running. Find the cause and fix it."

  1. 01

    Reproduce with the agent

    Claude Code: /claudops:dbgCodex: $claudops:dbg

    The agent adds temporary logging and gives you reproduction steps. Run them in the development app so it can inspect the logs. After an evidence-backed fix, reproduce again to verify it. The agent then removes its instrumentation.

  2. 02

    Review the edge

    Claude Code: /claudops:srCodex: $claudops:sr

    Review the fix for races, changed retry behavior, and assumptions that the reproduction did not cover.

The reviewable result

When both reproduction runs succeed: a cause supported by logs, a local fix, and recorded verification. Without runtime evidence, the diagnosis remains incomplete.

The human checkpoint

You may need to run the app or repeat the clicks. Reproducing a production-only failure needs an accessible test environment before this example can work.

A prompt to adapt · Inside Claude Code 
/claudops:dbg In the local app, clicking Export CSV twice quickly creates two jobs. We expect one export while a job is running. Find the cause, fix it locally, and give me the steps to verify it.
A prompt to adapt · Inside Codex 
$claudops:dbg In the local app, clicking Export CSV twice quickly creates two jobs. We expect one export while a job is running. Find the cause, fix it locally, and give me the steps to verify it.

Use dbg when the cause is unknown. A diagnosed, bounded bug can go straight to quick.

Read the Claude Code skill ↗Read the Codex skill ↗

Case 03

Correct one label without a ceremony

A button says "Download report" but downloads an invoice CSV. The existing behavior is correct. The task is a copy correction with an obvious boundary.

The request

"Change the invoice button label to Export CSV. Preserve the handler, permissions, and layout. Check the result at mobile width."

  1. 01

    Change and check the label

    Claude Code: /claudops:quickCodex: $claudops:quick

    Read the component, change the text, and check it in the running app at mobile width. Keep the result in a compact task record. The visual check requires browser access or your manual inspection.

  2. 02

    Optional code review

    Claude Code: /claudops:srCodex: $claudops:sr

    Use this for another review of the diff. Static review can flag unintended code changes; the rendered label and layout need the browser check above.

The reviewable result

The small diff and proportionate verification. Existing task conventions still apply; a short task record can hold the entire change.

The human checkpoint

If the label exposes an unresolved product question or changes behavior, expand the scope deliberately and return to planning.

A prompt to adapt · Inside Claude Code 
/claudops:quick Change the invoice button label from Download report to Export CSV. Preserve the handler and permissions. Check the rendered label at mobile width.
A prompt to adapt · Inside Codex 
$claudops:quick Change the invoice button label from Download report to Export CSV. Preserve the handler and permissions. Check the rendered label at mobile width.

Use the amount of process the change needs. A one-line correction does not need a product discovery document.

Read the Claude Code skill ↗Read the Codex skill ↗

Case 04

Make the billing boundary easier to change

A small billing change sends you through controllers, helpers, and thin wrappers. The code has modules, but understanding one behavior still requires opening all of them.

The request

"Explore the billing area for refactoring opportunities. Show where the current module boundaries make changes or tests harder. Keep this first pass read-only."

  1. 01

    Find candidates

    Claude Code: /claudops:improve-codebase-architectureCodex: $claudops:improve-codebase-architecture

    Inspect the relevant code and report specific refactoring candidates, with files, the friction, and the benefit. This pass reads and reports; it does not edit code.

  2. 02

    Explore the design

    Claude Code: Choose a candidateCodex: Choose a candidate

    Pick one candidate. The skill continues with questions about its constraints, dependencies, interface, and tests.

  3. 03

    Plan and implement

    Claude Code: /claudops:ct, then /claudops:siCodex: $claudops:ct, then $claudops:si

    Plan the chosen refactor, then implement that scope. Preserve the existing behavior and test it through the interface callers use. A small refactor with a known approach can use quick instead.

  4. 04

    Review the change

    Claude Code: /claudops:srCodex: $claudops:sr

    Check whether the refactor actually reduces the complexity callers need to understand, while preserving the agreed behavior.

The reviewable result

A chosen refactoring candidate, a concrete interface proposal, then a reviewed implementation and verification of preserved behavior.

The human checkpoint

You choose the candidate before interface design and approve the implementation scope. Exploring architecture does not authorize a broad rewrite.

A prompt to adapt · Inside Claude Code 
/claudops:improve-codebase-architecture Explore the billing area for refactoring opportunities. Show the affected files, the difficulty for callers, and how the tests would improve.
A prompt to adapt · Inside Codex 
$claudops:improve-codebase-architecture Explore the billing area for refactoring opportunities. Show the affected files, the difficulty for callers, and how the tests would improve.

A useful module hides complexity from its callers. More files are only useful when they make the next change easier to understand.

Read the Claude Code skill ↗Read the Codex skill ↗ · improved by · Original skill by Matt Pocock

Case 05

Finish the change that is already written

You are on the branch of an open GitHub PR, with GitHub CLI authenticated for that repository. Address the remaining feedback, then prepare the reviewed change for a manual merge.

The request

"Continue this PR and its task record. Resolve the review feedback, report the current checks, and prepare it for my merge decision."

  1. 01

    Address feedback

    Claude Code: /claudops:prcCodex: $claudops:prc

    Read the review comments and propose an Address, Skip, or Discuss decision for each. Get approval for the concrete fix plan, then apply the fixes. Sending reviewer replies requires explicit permission.

  2. 02

    Prepare for manual merge

    Claude Code: /claudops:finisher --no-mergeCodex: $claudops:finisher --no-merge

    After review is complete, handle the approved commits and pushes and wait for green CI. The --no-merge option stops before the merge gate so you can merge through GitHub yourself.

The reviewable result

The existing PR updated with approved fixes, its current CI results, and any remaining blockers. This example leaves the PR open for manual merge.

The human checkpoint

Finisher needs an existing PR and completed review. Without --no-merge, its shipping flow asks for a separate merge confirmation and then verifies the merged state.

A prompt to adapt · Inside Claude Code 
/claudops:finisher --no-merge Prepare this reviewed PR for manual merge. Check pending changes with me, push the approved work, and wait for CI.
A prompt to adapt · Inside Codex 
$claudops:finisher --no-merge Prepare this reviewed PR for manual merge. Check pending changes with me, push the approved work, and wait for CI.

Finishing starts with the work that exists. Reuse its record, inspect current state, and make the last decision against current evidence.

Read the Claude Code skill ↗Read the Codex skill ↗

06 / Keep a small working set

A shelf you can
actually reach for.

These are the commands I would keep within reach for the jobs above. Search by the work you want to do. The package has 40 skills; this is a selected working set, and each name links to its source.

Claude CodeInvoke plugin skills with slash commands such as /claudops:ct. The aliases /claudops:quick and /claudops:udoc cover small changes and documentation.

CodexMention a skill in your request with its dollar-prefixed name, such as $claudops:ct. The aliases $claudops:quick and $claudops:udoc cover small changes and documentation. These are prompts inside Codex, not shell commands.

The PR and CI skills shown here use GitHub and an authenticated GitHub CLI.

Selected skills · Your clientAll 40 skills ↗

07 / What "ready" actually means

Keep the last decision
attached to evidence.

A plugin can make a procedure available. It cannot turn every environment into the same environment. Repository commands, external tools, review configuration, and release permissions still determine what can be done.

Claudops carries existing authorization forward within its scope. Once you approve a bounded implementation, the agent should complete that work without reopening the same decision at every step. Material changes in scope still need a decision. Use finisher with --no-merge when you want the reviewed PR prepared for manual merge. Workflow philosophy · Finisher gates.

Review rule

"The command passed"
is evidence.
"The feature works"
needs the right check.

An editorial rule of thumb, not a test result.

For the CSV example, a passing build tells you that the project builds. It does not tell you that an account cannot export another account's invoices. A green unit test might prove escaping while missing filter behavior. Ask for the result at the same level as the requirement.

The task record should make that distinction visible. What was run? What behavior did it exercise? What remains unverified? Review that evidence before you decide to ship.

The installed skills are missing

Claude CodeOpen /plugin and check Installed for an enabled Claudops entry. Use /reload-plugins or start a new session after installation; check Errors if it still fails to load. A copied project workflow uses names such as /nf; the plugin uses /claudops:nf. If Claudops is absent from Installed, follow the two installation commands above.

CodexRun codex plugin list --marketplace claudops --json in a terminal and check that Claudops is enabled. Start a new Codex session after installation or an update. Use the full names, such as $claudops:nf, inside Codex. If the plugin is absent, return to installation. These instructions were checked with Codex CLI 0.153.4; update the CLI if its plugin commands are unavailable.

Setup cannot find a test command

Inspect the actual package configuration, Makefile, or CI job. Record a confirmed command in the existing configuration home if needed. Unknown values should block the work that depends on them, not trigger an invented command or an unrelated repository rewrite.

I expected hooks or a second AI reviewer

Claude CodePackage loading does not activate hooks. Hook wiring requires a settings change with its own authorization. Gemini plan review and the cross-AI helpers depend on external tools and configuration. Treat an unavailable reviewer as unavailable, and keep that gap visible. Hook activation guidance ↗

CodexBundled role instructions are reference material; Codex supplies the worker tools. Without an available worker, the skill can apply the same review criteria directly and records that the review was not independent. The bundled hook examples configure Claude Code, so setup must verify a supported Codex equivalent before activating anything. External review and browser checks also need tools available to your session.

The work needs a fresh session

Use ph for the current task. It prepares HANDOFF.md; give its path and the task entrypoint to the next session. Have the next session inspect the actual files and branch state. A handoff records the work in progress; finisher is for shipping an existing reviewed PR.

Your first useful run

Pick one change.
Keep the record.
Read the result.

With Claudops available in your session, choose a task small enough to review. Establish the project context, resolve the decision that matters, then carry that same task through implementation and review.

Back to getting started

08 / Sources & credits

Built in the open.

This guide describes the repository at 4dff1bd, rechecked on 8 September 2026. Commands and boundaries link to that revision so the claims stay inspectable as the project changes.

Adapted original skills and shared language
Claudops resourceOriginal work by Matt Pocock
tddimproved bytdd/SKILL.md
git-guardrailsimproved bygit-guardrails-claude-code/SKILL.md
ubiquitous-languageimproved byubiquitous-language/SKILL.md
improve-codebase-architectureimproved byimprove-codebase-architecture/SKILL.md
architecture-languageimproved byimprove-codebase-architecture/LANGUAGE.md
triage-issueimproved bytriage-issue/SKILL.md
qaimproved byqa/SKILL.md
zoom-outimproved byzoom-out/SKILL.md
grill-meimproved bygrill-me/SKILL.md

The links point to specific revisions of the original work. Claudops adapts these resources to its task and project conventions.

Shared testing guidance

The TDD reference used by implementation skills · improved by · Matt Pocock's original tdd skill. Its additional testing principles and warning signs · improved by · Addy Osmani's test-driven-development.

Adversarial questioning

The retained questioning discipline in grill-me · improved by · Addy Osmani's doubt-driven-development. It adds scrutiny of assumptions to the original Matt Pocock skill credited above.

Safeguard patterns

The Claudops adoption commit records the use of safeguard patterns from Addy Osmani's collection. Original review example · improved by · code-review-and-quality. Original shipping example · improved by · shipping-and-launch. These links credit the safeguard format and examples from that collection.

Scenario requests and sample task content are illustrative. They explain the workflow; they are not execution logs or delivery evidence.