codexops

codexops

Universal Codex workflow template — install, run $setup, start building

Author: @alexandrbasis | @MishkaKey

---

A Codex-ready workflow bundle you can install into any codebase. It includes repo-scoped skills under .agents/skills, project custom agents under .codex/agents, project instructions in AGENTS.md, optional hooks, and a setup wizard that configures the workflow for your tech stack.

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

Philosophy

This is a human-in-the-loop pipeline, not a fully autonomous agent. Every stage is triggered by you, every output is validated by you. The AI proposes — you approve, adjust, or reject. Nothing ships without your explicit sign-off.

• You trigger each stage — $nf for discovery, $ct for planning, $si for implementation, $sr for review
• You validate between stages — review the discovery doc before planning, review the plan before coding
• You control the gates — quality checks run automatically, but merging is always your decision
• Agents assist, not replace — 17 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

• $setup wizard — auto-detects your tech stack, project structure, and commands, then configures all skills, agents, and hooks in one pass
• $update-setup — pulls upstream changes from codexops, shows a diff, lets you cherry-pick updates while preserving your local customizations
• 17 project custom agents — TDD, code review, task validation, research
• 31 skills — full dev lifecycle, dev server monitoring, and cross-AI helpers (Gemini CLI, Codex CLI, Cursor CLI)
• Skills + agents workflow — orchestrator skills tell Codex when to spawn narrow custom agents and which convention skills to consult
• Cross-AI plan review — optional Gemini verification of plans (see review-plan-gemini.sh)
• Hooks — Bash command logging, pre-commit validation, plus template guards you can enable after $setup
• Linear integration — project management from your terminal (cc-linear skill)

---

What's Inside

Agents (17)

Automation (.codex/agents/)

Agent	Purpose
automated-quality-gate	Runs lint, types, tests before review
developer-agent	Universal agent for scoped work items
integration-test-runner	E2E and integration test execution
senior-architecture-reviewer	Reviews approach, architecture, TDD compliance

Code review (.codex/agents/)

Agent	Focus
code-quality-reviewer	SOLID, maintainability, code smells
documentation-accuracy-reviewer	Docs completeness and accuracy
performance-reviewer	N+1 queries, caching, optimization
security-code-reviewer	OWASP Top 10, injection, auth issues
spec-compliance-reviewer	Spec and requirements alignment
test-coverage-reviewer	Coverage gaps, test quality

Task validators (.codex/agents/)

Agent	Purpose
plan-reviewer	Technical plan validation
task-splitter	Evaluates if a task needs breakdown
task-decomposer	Phase structure for split tasks

Workflow (.codex/agents/)

Agent	Purpose
changelog-generator	Changelog from task docs
create-pr-agent	PR automation with Linear integration
docs-updater	Documentation synchronization

Helpers (.codex/agents/)

Agent	Purpose
comprehensive-researcher	In-depth research tasks

---

Skills (31)

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

Area	Examples
Setup & conventions	setup, update-setup, coding-conventions, review-conventions
Core workflow	ct, si, si-quick, sr, prc, ph, nf, product, vp, blueprint
Discovery & design	brainstorm, design-exploration, analyze, grill-me, rip
Quality & debugging	dev-server, code-analysis, dbg, fci
Cross-AI	gemini-cli, codex-cli, cursor-cli
Integrations & meta	cc-linear, deep-research, parallelization, sbs, update-docs

---

Skills + Agents

Codex skills are reusable workflows. Codex custom agents are TOML files in .codex/agents/ and are spawned when you explicitly ask Codex to delegate work or when an orchestrator skill instructs Codex to use them.

The $setup wizard fills the shared coding-conventions and review-conventions skills with your project's tech stack, architecture rules, and commands. Migrated custom agents include instructions to consult those skills when relevant.

---

Cross-AI plan review

Optional flow when Gemini CLI is configured — see .codex/scripts/review-plan-gemini.sh and hook wiring in .codex/hooks.json.

What Gemini can check: security, architecture, performance, edge cases, testability.

---

Hooks

Python/shell hooks under .codex/hooks/ — command logging, pre-commit checks, bash guards, cost tracking, and optional project-specific guards. Codex hooks are experimental and current PreToolUse / PostToolUse interception is Bash-focused, so file-edit hooks are kept as templates unless Codex expands hook coverage. Details: .codex/hooks/README.md.

---

Repository structure

AGENTS.md              # Project instructions loaded by Codex
.agents/
└── skills/            # Repo-scoped Codex skills

.codex/
├── agents/            # Project custom agents as TOML files
├── config.toml        # Project Codex config
├── docs/
│   ├── templates/     # PRD, JTBD, decomposition, review templates
│   └── references/
├── hooks/             # Hook scripts
├── hooks.json         # Optional hook wiring
└── scripts/           # e.g. review-plan-gemini.sh, linear-api.sh

scripts/install-codexops.sh
workflow-visualization.html

---

Quick Start

1. Clone codexops

git clone https://github.com/alexandrbasis/codexops.git

2. Install into your project

./codexops/scripts/install-codexops.sh /path/to/your-project
cd /path/to/your-project

The installer preserves existing AGENTS.md, .codex/config.toml, and .codex/hooks.json by writing *.codexops.* merge files when needed. Use --force only when you intentionally want to overwrite existing workflow files.

3. Run the setup wizard

$setup

The wizard will:

1. Scan your codebase with 3 parallel agents (tech stack, project structure, commands)
2. Confirm detected values with you (framework, ORM, test/lint/build commands, architecture)
3. Fill in all {{PLACEHOLDER}} variables directly in every skill, agent, and hook file

After setup, every file has your real values baked in — no runtime resolution, no config indirection.

4. Keep it updated

$update-setup

Pulls latest changes from the upstream codexops repo, shows what's new or modified, and lets you cherry-pick what to apply. Your custom local skills and hooks are never touched.

5. Start using workflows

$ct    — create a technical decomposition
$si    — start implementation from a task
$sr    — run multi-agent code review

Cherry-pick individual skills

cp -r codexops/.agents/skills/si your-project/.agents/skills/
cp codexops/.codex/scripts/review-plan-gemini.sh your-project/.codex/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

$ct → $si → $sr → $prc → merge

Cross-AI

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

---

Prerequisites

• Codex installed
• Git + GitHub CLI (gh)
• Optional: Gemini CLI (npm i -g @google/gemini-cli)
• 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