claudops

Development workflows for Claude Code and Codex, with a portable Agent Plugins v1 package.

Author: @alexandrbasis | @MishkaKey

imageLive Site

Workflow skills for feature discovery, planning, implementation and review, available as a plugin or a repository-owned .claude/ copy. Task stages share a durable record and adapt to the repository's existing conventions.

Works with any language, framework, and architecture — TypeScript, Python, Go, Ruby, Java, and more.

Quick start

Claude Code

Open Claude Code in the project you want to work on. Inside Claude Code, add the marketplace and install the plugin:

/plugin marketplace add alexandrbasis/claudops
/plugin install claudops@claudops

Choose the installation scope when prompted. Claude Code installs the ready package; you do not need Python or a local build. If the installation asks you to activate the plugin, run /reload-plugins or start a new session.

Start a workflow with a concrete request:

/claudops:nf Add CSV export to the invoices page.

Plugin commands use the /claudops: prefix. /claudops:setup is optional when the project needs additional configuration. Check /plugin → Installed for the plugin and its components, or Errors for a loading problem. See Claude Code installation.

Codex

Run these commands in your terminal with a current Codex CLI:

codex plugin marketplace add alexandrbasis/claudops
codex plugin add claudops@claudops
codex plugin list --marketplace claudops --json

Check that claudops@claudops is installed and enabled. Open a new Codex task in the project you want to work on, then invoke a skill explicitly:

Use $claudops:nf to explore adding CSV export to the invoices page.

Codex loads the ready Agent Plugins package with all 40 skills. The small-change and documentation skills are $claudops:quick and $claudops:udoc. Setup is optional; $claudops:setup uses the project's existing instructions or AGENTS.md when new durable choices are needed. No Python or local build is required for installation. See Codex plugin commands.

Other Agent Plugins clients

The ready portable package is plugins/claudops-agent, with its manifest at the package root. Load that directory through the compatible client's installation mechanism. Agent Plugins is a package format; installation UI, tools and runtime behavior depend on the client.

The Claude package also registers 18 agents. The portable package contains their reference instructions as resources and adapts their roles to supported host workers; it registers no Claude agents. Neither package enables hooks, MCP or LSP servers. Optional cross-AI and tracker workflows need their own tools and access.

Philosophy

The command examples and agent inventory below describe Claude Code. In Codex, invoke the same skills as $claudops:<skill>; use quick and udoc for the two aliases. Codex applies the bundled role instructions through the host adapter, rather than registering the 18 Claude agent types.

This is a human-in-the-loop pipeline, not a fully autonomous agent. You choose the work and review the required artifacts. Once a bounded stage is approved, the agent completes that scope without asking again for the same decision. Nothing ships without your explicit sign-off.

• You trigger each stage — /claudops:nf for discovery, /claudops:ct for planning, /claudops:si for implementation, /claudops:sr for review
• You validate material decisions and required artifacts; existing approvals carry forward between stages
• You control the gates — quality checks run automatically, but merging is always your decision
• Agents assist, not replace — 18 agents handle the grunt work (linting, testing, architecture checks), you make the calls

The result: AI speed with human judgment. Full context at every step, no black-box automation.

Highlights

• /claudops:setup — records necessary project choices; plugin workflows discover repository commands without copying all instructions
• /update-setup for copied workflows — pulls upstream changes, shows a diff, and lets you select updates while preserving local customizations. Managed plugins update through the client's plugin manager.
• 18 specialized agents — TDD, code review, task validation, research
• 40 skills — full dev lifecycle, dev server monitoring, and cross-AI helpers (Antigravity, Codex CLI, Cursor CLI)
• Skills ↔ Agents composability — agents preload shared convention skills via skills: frontmatter
• Cross-AI plan review — optional Antigravity verification of plans (see review-plan-gemini.sh)
• Hooks — lint on write, sync, validation, guards, metrics
• Linear integration — project management from your terminal (cc-linear skill)

What's Inside

Agents (18)

Automation (.claude/agents/automation-agents/)

Code review (.claude/agents/code-review-agents/)

Task validators (.claude/agents/tasks-validators-agents/)

Workflow (.claude/agents/wf-agents/)

Helpers (.claude/agents/helpful-agents/)

Skills (40)

See .claude/skills/README.md for the full index. Summary:

Skills ↔ Agents Composability

Review agents and the developer agent preload shared convention skills via skills: frontmatter — no per-agent duplication:

# In agent frontmatter
skills:
  - review-conventions   # preloaded into all 7 review agents
  - coding-conventions   # preloaded into developer-agent

Plugin workflows read project instructions and command sources. For repository-owned installations, /setup can configure the local convention skills; existing customizations remain authoritative.

Cross-AI plan review

Use /antigravity-cli for a delegated or explicitly requested review through agy. The adapter captures JSON and diagnostics and rejects incomplete results, including permission-denied runs that exit successfully.

The legacy opt-in plan hook remains at .claude/scripts/review-plan-gemini.sh; it uses the same adapter. Plugin installation does not activate hooks.

Review scope: security, architecture, performance, edge cases, testability.

Hooks

Python/shell hooks under .claude/hooks/ — lint on write, agent sync, pre-commit checks, bash/file guards, cost tracking, etc. Details: .claude/hooks/README.md.

Repository structure

plugin.json                  # Agent Plugins manifest source
.claude-plugin/plugin.json   # Claude manifest source
.claude-plugin/marketplace.json # Claude Code marketplace catalog
.agents/plugins/marketplace.json # Codex marketplace catalog
plugins/claudops/            # Tracked ready-to-install Claude package
plugins/claudops-agent/      # Tracked portable package used by Codex
scripts/                    # Reproducible build and validation
packaging/marketplace.md     # Snapshot maintenance and release checks
dist/                       # Generated packages (not source)
.claude/
├── agents/           # Specialized subagents
├── docs/
│   ├── templates/    # PRD, JTBD, decomposition, review templates
│   └── references/
├── hooks/            # Claude Code hooks (see hooks/README.md)
├── scripts/          # e.g. review-plan-gemini.sh, linear-api.sh
├── skills/           # Slash-command skills (see skills/README.md)
└── settings.json     # Hook and project settings (copy & customize)

workflow-visualization.html   # Interactive workflow map (open in browser)

Plugin setup and updates

Start the nf, ct, si or sr skill in the target repository. Claude Code uses /claudops:<skill>; Codex uses $claudops:<skill>. Both packages contain all 40 skills; Claude Code also registers 18 agents. Setup is optional: use it for durable project choices or to maintain an explicitly requested local workflow copy. Shared plugin files stay unchanged, and hook activation requires its own authorized settings change.

Each task stage resolves the same task entrypoint. Existing layouts and documents are reused; the fallback is tasks/task-YYYY-MM-DD-<slug>/TASK.md. A small task can keep its requirements, plan and verification in that one file. Discovery, prototypes, phase plans and reviews become separate linked artifacts when needed. See the shared task contract.

To update a Claude Code user-scope installation, run these commands in your terminal:

claude plugin marketplace update claudops
claude plugin update claudops@claudops --scope user

Use --scope project or --scope local if that is where you installed it. claude plugin list shows the installed scope. Run /reload-plugins inside an open session or start a new session to load the updated files. /update-setup is only for a copied .claude/ workflow. See Claude Code updates.

For Codex, refresh the Git marketplace and install its current package:

codex plugin marketplace upgrade claudops
codex plugin add claudops@claudops
codex plugin list --marketplace claudops --json

Start a new Codex task to load the updated skills. See Codex marketplace commands.

For source builds and publication, see the marketplace maintainer guide. The package guide covers local development loading and the Agent Plugins v1 artifact for compatible clients.

Use the copied workflow

1. Clone the source and preview project templates

git clone https://github.com/alexandrbasis/claudops.git
python3 claudops/.claude/skills/setup/scripts/bootstrap_project.py --project /absolute/your-project
# Review the listed additions, then materialize them:
python3 claudops/.claude/skills/setup/scripts/bootstrap_project.py --project /absolute/your-project --apply
cd /absolute/your-project

2. Run the setup wizard

/setup

The wizard will:

1. Inspect your codebase for stack, structure, commands, and architecture
2. Resolve relevant settings from evidence and ask about material unknown choices
3. Apply the requested local configuration, reporting unresolved values and previewing hook activation

Configured values live in your local .claude/ files. Unknown values remain visible for follow-up; a copied hook is not active until it is wired into settings.

3. Keep it updated

/update-setup

Pulls latest changes from the upstream claudops repo, shows what's new or modified, and lets you cherry-pick what to apply. Local-only files are excluded; updates to customized upstream files require an explicit conflict decision.

4. Start using workflows

/ct    — create an implementation plan in the task record
/si    — start implementation from a task
/sr    — run multi-agent code review

Cherry-pick individual skills

cp -r claudops/.claude/skills/si your-project/.claude/skills/
cp -r claudops/.claude/skills/antigravity-cli your-project/.claude/skills/
cp claudops/.claude/scripts/review-plan-gemini.sh your-project/.claude/scripts/

As reference

Study the patterns and adapt them to your own workflows.

Key workflows

TDD pipeline

/ct → /si → automated-quality-gate → senior-architecture-reviewer

Multi-agent code review

code-quality + security + performance + test-coverage + documentation

Task-driven flow

/nf → /vp (optional) → /ct (split when needed) → /si → /sr → /prc → authorized delivery

/ct normally adds a concise implementation plan to the existing task record: changes, ordered steps, verification and material risks. It reuses discovery decisions and relevant code evidence. Detailed templates, independent plan review and phase splitting are used when the work's risk or an explicit request warrants them.

/si implements or resumes that active plan, keeps progress and verification in the same task record, and uses TDD for behavior changes. Other changes use appropriate validation. Independent work can be delegated when it helps; the combined result is checked before completion. Existing authorization carries forward to review and delivery within its scope.

Cross-AI

• Antigravity CLI (agy) — plan review, web-grounded research
• Codex / Cursor CLI — second-opinion review (see cross-ai-protocol template)

Prerequisites

• Claude Code, Codex, or a compatible Agent Plugins client
• Git for the GitHub marketplace source and repository workflows
• GitHub CLI (gh) for GitHub pull request workflows
• Optional: authenticated Antigravity CLI (agy) for cross-AI validation
• Optional: Linear API access

Security & privacy

Not included (sensitive): settings.local.json, API keys, MCP credentials, log files

Safe to share: Agents, skills, hook scripts, and templates in this repo (exclude local overrides)

Contributing

Found a better pattern? Have suggestions?

• Open an issue with your idea
• Share your own workflows
• Contribute improvements via PR

License

MIT — See LICENSE