refactor(ai): replace counselors with Codex plugin for external reviews

stephendolan · claude · stephendolan · commit be5016b638cd · 2026-04-01T09:40:15.000-04:00
Counselors CLI is superseded by the official Codex plugin (openai-codex),
which provides GPT 5.4 second opinions via /codex:adversarial-review and
the codex:codex-rescue agent. Removes the skill, config, Brewfile entries,
DotBot symlinks, and updates all referencing skills/agents.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -89,7 +89,6 @@ The `ai/` directory contains configuration for Claude Code and other AI editors:
 - `ai/AGENTS.md` - Shared instructions (symlinked as `~/.claude/CLAUDE.md` and `~/.config/AGENTS.md`)
 - `ai/agents/*.md` - Agent prompts that define specialized subagent behavior
 - `ai/skills/*/SKILL.md` - Skill prompts that define workflows (slash commands) and domain expertise
-- `ai/counselors/config.json` - Counselors CLI config (symlinked to `~/.config/counselors/config.json`)
 - `ai/hooks/*.sh` - Hook scripts for Claude Code lifecycle events
 - `ai/mcp.json` - MCP server definitions (source of truth)
 - `ai/generate-mcp.sh` - Generates MCP configs for Claude Desktop, Claude Code CLI, and Codex CLI
diff --git a/ai/.claude-plugin/plugin.json b/ai/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "stephendolan",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Personal agents and skills for development workflows, code review, architecture analysis, and domain expertise.",
   "author": {
     "name": "Stephen Dolan",
diff --git a/ai/AGENTS.md b/ai/AGENTS.md
@@ -23,7 +23,6 @@ When work decomposes into independent pieces, delegate each to a sub-agent and r
 | -------------------------- | ----------------------------------------- |
 | `/commit`                  | Commit with conventional message (why > what) |
 | `/create-pr`               | Create PR with concise description        |
-| `/counselors`              | Fan out a review to Claude and Codex      |
 | `/ship`                    | Autonomous end-to-end feature development |
 | `/refine-implementation`   | Multi-pass code review before commit      |
 | `/examine-architecture`    | Evaluate codebase for structural problems |
@@ -79,9 +78,8 @@ Avoid temporal references: "vs previous", "used to be X", "now uses Y", "the new
 
 ### External Review Gate
 
-Use `/counselors` selectively when you want a true external second opinion from the configured Claude and Codex tools.
+Use `/codex:adversarial-review` to get a second opinion from GPT 5.4 on implementation diffs. Use the `codex:codex-rescue` agent to delegate plan reviews to Codex.
 
-- `/ship` is the exception: run one `/counselors` pass on the implementation plan before building
 - Good targets: high-risk plans before implementation, architecture reviews with cross-cutting findings, and risky diffs before commit
 - Bad targets: small edits, routine refactors, or cases where local reviewers already agree and the risk is low
 
diff --git a/ai/README.md b/ai/README.md
@@ -36,7 +36,6 @@ ai/
     plugin.json          Plugin manifest
   agents/                Subagent definitions
   skills/                Slash command workflows and domain expertise
-  counselors/            Counselors CLI configuration
   hooks/                 Event handlers
   AGENTS.md              Shared instructions
   mcp.json               MCP server definitions
@@ -121,7 +120,6 @@ flowchart LR
 | -------------------------- | -------------------------------------------------- |
 | `/commit`                  | Commit with conventional message (why > what)      |
 | `/create-pr`               | Create PR with concise description                 |
-| `/counselors`              | Fan out a review to Claude and Codex in parallel   |
 | `/ship`                    | Autonomous end-to-end feature development          |
 | `/refine-implementation`   | Multi-pass quality review before committing        |
 | `/examine-architecture`    | Evaluate codebase for structural problems          |
diff --git a/ai/agents/plan-refiner.md b/ai/agents/plan-refiner.md
@@ -26,7 +26,7 @@ Suggest alternatives only with high confidence. Intervene when:
 3. Architecture hurts maintainability
 4. Missing context might change the optimal approach
 
-If the plan is high-risk and uncertainty remains after reviewing local context, recommend a `/counselors` pass rather than pretending confidence.
+If the plan is high-risk and uncertainty remains after reviewing local context, recommend a `/codex:adversarial-review` pass rather than pretending confidence.
 
 If the plan is reasonable, approve it and move on.
 
@@ -65,7 +65,7 @@ Only suggest changes when elegance gains clearly outweigh costs. Prefer what's e
 For plans touching auth, migrations, public APIs, infrastructure, billing, or large cross-cutting refactors:
 
 - If you have a strong view, state it plainly
-- If you do not, say so explicitly and recommend a `/counselors` review to gather one more independent perspective
+- If you do not, say so explicitly and recommend a `/codex:adversarial-review` to gather one more independent perspective
 
 ## Output Format
 
diff --git a/ai/claude-settings.json b/ai/claude-settings.json
@@ -296,7 +296,16 @@
     "stephendolan@dotfiles": true,
     "swift-lsp@claude-plugins-official": true,
     "clangd-lsp@claude-plugins-official": true,
-    "ruby-lsp@claude-plugins-official": true
+    "ruby-lsp@claude-plugins-official": true,
+    "codex@openai-codex": true
+  },
+  "extraKnownMarketplaces": {
+    "openai-codex": {
+      "source": {
+        "source": "github",
+        "repo": "openai/codex-plugin-cc"
+      }
+    }
   },
   "spinnerTipsOverride": {
     "tips": [
diff --git a/ai/counselors/config.json b/ai/counselors/config.json
diff --git a/ai/skills/counselors/SKILL.md b/ai/skills/counselors/SKILL.md
diff --git a/ai/skills/examine-architecture/SKILL.md b/ai/skills/examine-architecture/SKILL.md
@@ -14,7 +14,6 @@ You are examining a codebase's architecture to identify structural problems. Fol
 - **Analyze, don't fix**: This command identifies problems and creates implementation plans, but doesn't make changes
 - **Parallel analysis**: Launch multiple agents to examine different surfaces simultaneously
 - **Validate recommendations**: Use plan-refiner to eliminate over-engineering from proposed fixes
-- **Use Counselors on the top issues only**: External second opinions are valuable for high-severity or cross-cutting recommendations, not every surface
 - **Use TodoWrite**: Track all progress throughout
 
 ---
@@ -84,10 +83,9 @@ Focus area: $ARGUMENTS
    - Validate tractability
    - Suggest simpler approaches
    - Flag anything too complex to be worth fixing
-3. If the top issues are high-severity, cross-cutting, or likely to be controversial, run `/counselors` on the top 2-3 issues and proposed fixes
-4. Ask Counselors to challenge the root-cause analysis, spot missed risks, and call out fixes that feel overbuilt
-5. Incorporate plan-refiner and Counselors feedback
-6. Present validated findings to user
+3. If the top issues are high-severity, cross-cutting, or likely to be controversial, launch the `codex:codex-rescue` agent to challenge the root-cause analysis and spot missed risks
+4. Incorporate plan-refiner and Codex feedback
+5. Present validated findings to user
 
 ---
 
diff --git a/ai/skills/refine-implementation/SKILL.md b/ai/skills/refine-implementation/SKILL.md
@@ -86,7 +86,7 @@ After reviewing and discussing with agents as needed:
 
 ### 6. External Second Opinion (Optional)
 
-Run `/counselors` after local reconciliation when the change is risky enough to justify one more pass.
+Run `/codex:adversarial-review` after local reconciliation when the change is risky enough to justify one more pass.
 
 Good triggers:
 
@@ -95,8 +95,6 @@ Good triggers:
 - Local review agents disagreeing or repeatedly escalating
 - A branch that feels high-consequence and worth one last independent check
 
-Ask Counselors to focus on regressions, blind spots, and missing tests. Give it the key files and branch diff context, not a giant pasted prompt.
-
 Incorporate valid findings, then do another local pass only if the external review changed the shape of the branch materially.
 
 ### 7. Check for Another Pass
@@ -127,6 +125,6 @@ Stop after:
 
 - **No commits until user approves** - Changes stay uncommitted for review
 - **Multiple perspectives** - Different agents catch different issues
-- **External review is a scalpel** - Use `/counselors` for risky or disputed changes, not every pass
+- **External review is a scalpel** - Use `/codex:adversarial-review` for risky or disputed changes, not every pass
 - **Iterative improvement** - One pass rarely catches everything
 - **User control** - Always show changes, never auto-commit
diff --git a/ai/skills/ship/SKILL.md b/ai/skills/ship/SKILL.md
@@ -18,8 +18,7 @@ Autonomy requires conviction. When agents disagree, gather evidence and make a c
 - **Route decisions to plan-refiner**: When you face ambiguity, launch the plan-refiner with the specific question and context. Accept its decision.
 - **Defend with evidence**: When the skeptic challenges, respond with codebase evidence and reasoning. Change the plan only when the challenge is genuinely valid.
 - **Fresh perspectives catch blind spots**: Specialized agents review from angles you'd miss after building context.
-- **Always run one Counselors plan review**: Every `/ship` run gets one `/counselors` pass on the implementation plan before code is written.
-- **Use additional Counselors passes selectively**: Extra external reviews still need a reason.
+- **Get a Codex second opinion on the plan**: Every `/ship` run gets one `codex:codex-rescue` pass on the implementation plan before code is written.
 
 ---
 
@@ -62,10 +61,9 @@ Feature request: $ARGUMENTS
    - **plan-refiner**: Evaluate for elegance, over-engineering, and maintainability. Make decisions autonomously—you have final authority on approach.
    - **code-architect**: Validate architecture choices against codebase patterns. Provide a decisive blueprint, not multiple options.
 2. Incorporate feedback from both agents
-3. Run `/counselors` on the plan for one external second opinion every time
-4. Ask Counselors to look for blind spots, regressions, missing constraints, and simpler alternatives. Include the plan plus the most relevant files and diff context
-5. If local agents or Counselors suggest significant changes, update the plan and re-run the plan-refiner to settle tradeoffs
-6. The plan is ready when the internal reviewers are aligned and any valid Counselors feedback has been incorporated
+3. Launch the `codex:codex-rescue` agent to review the plan for blind spots, regressions, missing constraints, and simpler alternatives
+4. If agents or Codex suggest significant changes, update the plan and re-run the plan-refiner to settle tradeoffs
+5. The plan is ready when the internal reviewers are aligned and any valid Codex feedback has been incorporated
 
 ---
 
@@ -104,7 +102,7 @@ Feature request: $ARGUMENTS
 **Goal**: Multi-pass quality review
 
 1. Use the `/refine-implementation` skill for fresh-eyes review
-2. If the diff is high-risk, cross-cutting, or still contentious after local review, run one `/counselors` pass against the final diff before concluding
+2. If the diff is high-risk, cross-cutting, or still contentious after local review, run `/codex:adversarial-review` against the final diff before concluding
 3. Make decisions autonomously on all escalations: fix genuine issues, skip cosmetic preferences
 4. Run up to 2 refinement passes
 
diff --git a/install.conf.yaml b/install.conf.yaml
@@ -80,16 +80,11 @@
     # Agents and skills are installed via the stephendolan@dotfiles plugin
     ~/.claude/CLAUDE.md: ai/AGENTS.md
     ~/.claude/settings.json: ai/claude-settings.json
-    ~/.claude/skills/counselors: ai/skills/counselors
-
     # AI tools configuration (Codex)
     ~/.codex/skills/:
       glob: true
       path: ai/skills/*
 
-    # AI tools configuration (Counselors)
-    ~/.config/counselors/config.json: ai/counselors/config.json
-
     # AI tools configuration (Amp)
     ~/.config/AGENTS.md: ai/AGENTS.md
 
diff --git a/packages/homebrew/Brewfile.linux b/packages/homebrew/Brewfile.linux
@@ -15,7 +15,6 @@ brew "wget"
 
 # Modern CLI tools
 brew "atuin"            # Magical shell history
-brew "counselors"       # Fan out prompts to Claude and Codex
 brew "delta"            # Better git diff
 brew "direnv"           # Directory environments
 brew "eza"              # Better ls
diff --git a/packages/homebrew/Brewfile.mac b/packages/homebrew/Brewfile.mac
@@ -20,7 +20,6 @@ brew "wget"
 # Modern CLI tools
 brew "atuin"            # Magical shell history
 brew "bun"              # JavaScript runtime
-brew "counselors"       # Fan out prompts to Claude and Codex
 brew "delta"            # Better git diff
 brew "direnv"           # Directory environments
 brew "duti"             # Default app associations

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "stephendolan",`
`3`		`- "version": "1.5.0",`
	`3`	`+ "version": "1.6.0",`
`4`	`4`	`"description": "Personal agents and skills for development workflows, code review, architecture analysis, and domain expertise.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Stephen Dolan",`