{"id":"e8dc6371-e7ff-41f0-8beb-a88e2be2f4de","slug":"codexops","kind":"skill","name":"codexops","summary":"Codex workflow template with skills, agents, hooks, and setup wizard","owner":"alexandrbasis","repoUrl":"https://github.com/alexandrbasis/codexops","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-04-24T08:43:00.000Z","addedAt":"2026-10-22T00:57:08.883Z","logoUrl":"https://avatars.githubusercontent.com/u/139048128?u=2051007b3129608112d7e1154fcb69b669377b67&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T23:15:03.962Z","sample":false,"url":"https://conduits.dev/tools/codexops","language":"HTML","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# codexops\n\n> Universal Codex workflow template — install, run `$setup`, start building\n\n**Author:** [@alexandrbasis](https://x.com/alexandrbasis) | [@MishkaKey](https://x.com/MishkaKey)\n\n[![Live Site](https://img.shields.io/badge/Live_Site-codexops-0d9488?style=flat-square)](https://alexandrbasis.com/codexops/workflows/)\n\n---\n\nA 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.\n\nWorks with any language, framework, and architecture — TypeScript, Python, Go, Ruby, Java, and more.\n\n## Philosophy\n\nThis 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.\n\n- **You trigger** each stage — `$nf` for discovery, `$ct` for planning, `$si` for implementation, `$sr` for review\n- **You validate** between stages — review the discovery doc before planning, review the plan before coding\n- **You control the gates** — quality checks run automatically, but merging is always your decision\n- **Agents assist, not replace** — 17 agents handle the grunt work (linting, testing, architecture checks), you make the calls\n\nThe result: AI speed with human judgment. Full context at every step, no black-box automation.\n\n## Highlights\n\n- **`$setup` wizard** — auto-detects your tech stack, project structure, and commands, then configures all skills, agents, and hooks in one pass\n- **`$update-setup`** — pulls upstream changes from codexops, shows a diff, lets you cherry-pick updates while preserving your local customizations\n- **17 project custom agents** — TDD, code review, task validation, research\n- **31 skills** — full dev lifecycle, dev server monitoring, and cross-AI helpers (Gemini CLI, Codex CLI, Cursor CLI)\n- **Skills + agents workflow** — orchestrator skills tell Codex when to spawn narrow custom agents and which convention skills to consult\n- **Cross-AI plan review** — optional Gemini verification of plans (see `review-plan-gemini.sh`)\n- **Hooks** — Bash command logging, pre-commit validation, plus template guards you can enable after `$setup`\n- **Linear integration** — project management from your terminal (`cc-linear` skill)\n\n---\n\n## What's Inside\n\n### Agents (17)\n\n**Automation** (`.codex/agents/`)\n| Agent | Purpose |\n|-------|---------|\n| `automated-quality-gate` | Runs lint, types, tests before review |\n| `developer-agent` | Universal agent for scoped work items |\n| `integration-test-runner` | E2E and integration test execution |\n| `senior-architecture-reviewer` | Reviews approach, architecture, TDD compliance |\n\n**Code review** (`.codex/agents/`)\n| Agent | Focus |\n|-------|-------|\n| `code-quality-reviewer` | SOLID, maintainability, code smells |\n| `documentation-accuracy-reviewer` | Docs completeness and accuracy |\n| `performance-reviewer` | N+1 queries, caching, optimization |\n| `security-code-reviewer` | OWASP Top 10, injection, auth issues |\n| `spec-compliance-reviewer` | Spec and requirements alignment |\n| `test-coverage-reviewer` | Coverage gaps, test quality |\n\n**Task validators** (`.codex/agents/`)\n| Agent | Purpose |\n|-------|---------|\n| `plan-reviewer` | Technical plan validation |\n| `task-splitter` | Evaluates if a task needs breakdown |\n| `task-decomposer` | Phase structure for split tasks |\n\n**Workflow** (`.codex/agents/`)\n| Agent | Purpose |\n|-------|---------|\n| `changelog-generator` | Changelog from task docs |\n| `create-pr-agent` | PR automation with Linear integration |\n| `docs-updater` | Documentation synchronization |\n\n**Helpers** (`.codex/agents/`)\n| Agent | Purpose |\n|-------|---------|\n| `comprehensive-researcher` | In-depth research tasks |\n\n---\n\n### Skills (31)\n\nSee [`.agents/skills/README.md`](.agents/skills/README.md) for the full index. Summary:\n\n| Area | Examples |\n|------|----------|\n| Setup & conventions | `setup`, `update-setup`, `coding-conventions`, `review-conventions` |\n| Core workflow | `ct`, `si`, `si-quick`, `sr`, `prc`, `ph`, `nf`, `product`, `vp`, `blueprint` |\n| Discovery & design | `brainstorm`, `design-exploration`, `analyze`, `grill-me`, `rip` |\n| Quality & debugging | `dev-server`, `code-analysis`, `dbg`, `fci` |\n| Cross-AI | `gemini-cli`, `codex-cli`, `cursor-cli` |\n| Integrations & meta | `cc-linear`, `deep-research`, `parallelization`, `sbs`, `update-docs` |\n\n---\n\n### Skills + Agents\n\nCodex 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.\n\nThe `$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.\n\n---\n\n### Cross-AI plan review\n\nOptional flow when Gemini CLI is configured — see `.codex/scripts/review-plan-gemini.sh` and hook wiring in `.codex/hooks.json`.\n\n**What Gemini can check:** security, architecture, performance, edge cases, testability.\n\n---\n\n### Hooks\n\nPython/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`](.codex/hooks/README.md).\n\n---\n\n## Repository structure\n\n```\nAGENTS.md              # Project instructions loaded by Codex\n.agents/\n└── skills/            # Repo-scoped Codex skills\n\n.codex/\n├── agents/            # Project custom agents as TOML files\n├── config.toml        # Project Codex config\n├── docs/\n│   ├── templates/     # PRD, JTBD, decomposition, review templates\n│   └── references/\n├── hooks/             # Hook scripts\n├── hooks.json         # Optional hook wiring\n└── scripts/           # e.g. review-plan-gemini.sh, linear-api.sh\n\nscripts/install-codexops.sh\nworkflow-visualization.html\n```\n\n---\n\n## Quick Start\n\n### 1. Clone codexops\n```bash\ngit clone https://github.com/alexandrbasis/codexops.git\n```\n\n### 2. Install into your project\n```bash\n./codexops/scripts/install-codexops.sh /path/to/your-project\ncd /path/to/your-project\n```\n\nThe 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.\n\n### 3. Run the setup wizard\n```\n$setup\n```\n\nThe wizard will:\n1. **Scan your codebase** with 3 parallel agents (tech stack, project structure, commands)\n2. **Confirm** detected values with you (framework, ORM, test/lint/build commands, architecture)\n3. **Fill in** all `{{PLACEHOLDER}}` variables directly in every skill, agent, and hook file\n\nAfter setup, every file has your real values baked in — no runtime resolution, no config indirection.\n\n### 4. Keep it updated\n```\n$update-setup\n```\n\nPulls 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.\n\n### 5. Start using workflows\n```\n$ct    — create a technical decomposition\n$si    — start implementation from a task\n$sr    — run multi-agent code review\n```\n\n### Cherry-pick individual skills\n```bash\ncp -r codexops/.agents/skills/si your-project/.agents/skills/\ncp codexops/.codex/scripts/review-plan-gemini.sh your-project/.codex/scripts/\n```\n\n### As reference\nStudy the patterns and adapt them to your own workflows.\n\n---\n\n## Key workflows\n\n### TDD pipeline\n```\n$ct → $si → automated-quality-gate → senior-architecture-reviewer\n```\n\n### Multi-agent code review\n```\ncode-quality + security + performance + test-coverage + documentation\n```\n\n### Task-driven flow\n```\n$ct → $si → $sr → $prc → merge\n```\n\n### Cross-AI\n- Gemini CLI — plan review, web-grounded research\n- Codex / Cursor CLI — second-opinion review (see `cross-ai-protocol` template)\n\n---\n\n## Prerequisites\n\n- [Codex](https://developers.openai.com/codex/) installed\n- Git + GitHub CLI (`gh`)\n- Optional: Gemini CLI (`npm i -g @google/gemini-cli`)\n- Optional: Linear API access\n\n---\n\n## Security & privacy\n\n**Not included (sensitive):** `settings.local.json`, API keys, MCP credentials, log files\n\n**Safe to share:** Agents, skills, hook scripts, and templates in this repo (exclude local overrides)\n\n---\n\n## Contributing\n\nFound a better pattern? Have suggestions?\n- Open an issue with your idea\n- Share your own workflows\n- Contribute improvements via PR\n\n---\n\n## License\n\nMIT — See [LICENSE](LICENSE)\n"}