Forem: Conan

Introducing PlanCollab: AI-Powered Cross-Agent Code Planning & Review

Conan — Tue, 26 May 2026 15:29:32 +0000

Ever wished you could get a second AI opinion on your implementation plans before writing code? PlanCollab makes this possible by orchestrating collaborative planning sessions between Claude Code 🐶 and Codex 🐱.

🎯 What is PlanCollab?

PlanCollab is an agent skill that enables adversarial collaboration between two different AI model families. One agent creates an implementation plan, the other reviews it, and they iterate automatically until reaching consensus - or escalate disagreements to you for final decision.

Why Two AIs Are Better Than One

A single AI can have blind spots - it won't challenge its own decisions. By bringing in a second AI with a different model architecture, you get:

Alternative approaches that weren't initially considered
Missing steps or incorrect dependency ordering caught early
Risk assessment from a fresh perspective
Test coverage gaps identified before coding

The greater the difference between model families (Claude vs GPT), the more valuable the review becomes.

🚀 Quick Start

Prerequisites

claude CLI (Claude Code)
codex CLI (for cross-agent communication)

Basic Usage

# Start a collaborative planning session
/plancollab implement user authentication module

# List all sessions
/plancollab list

# Check current status
/plancollab status

# Resume an interrupted session
/plancollab resume

# Delete sessions
/plancollab delete

Auto-Review Mode

When you generate a complex implementation plan in conversation, PlanCollab can automatically ask:

"I just generated an implementation plan. Would you like the other agent to review it?"

Choose "Yes, always" to enable auto-review for all future plans.

🔄 How It Works

User provides task
    ↓
Baseline check (first-time project scan, reused later)
    ↓
┌─ 🐶 Creates plan ──────────────────────────────┐
│    ↓                                            │
│ 🐱 Reviews (automatic)                          │
│    ↓                                            │
│ Agreed sections locked, disputed sections continue │
│    ↓                                            │
│ Communication sends only disputed sections      │
│    ↓                                            │
│ Next round focuses on disagreements ────────────┘
    ↓
Result: Consensus reached / Conflicts escalated to user

Key Design Principles

Projection Communication: Each round sends a "projection" to the other agent - agreed sections become one-liners, only disputed sections are sent in full. As consensus grows, communication shrinks, preventing context overflow.

Consensus Tracking: After each review, a consensus file records which sections are agreed and which are still disputed. This drives the projection and conflict resolution.

Discussion Log: Tracks what was discussed each round, what was resolved, and what remains. The reviewer uses this to avoid re-raising already-addressed issues.

⚡ Conflict Resolution

If consensus isn't reached after 3 rounds (default), PlanCollab:

Extracts specific disagreement points
Shows both positions in a structured table
Lists reasoning from both agents
References source files for verification

Example conflict summary:

🐶 ⚡ 🐱 3 rounds without full consensus. Your decision needed.

1. Token Storage Method

|        | 🐶 Claude              | 🐱 Codex                          |
|--------|------------------------|
| Position | httpOnly cookie       | localStorage                       |
| Concession | Round 2 added SameSite | Round 3 acknowledged security |

🐶 Reasoning:
1. XSS cannot read cookies, natural protection
2. Combined with SameSite=Strict prevents CSRF
3. Server-controlled expiry, reliable forced logout

🐱 Reasoning:
1. Simpler implementation, no backend coordination needed
2. Cross-domain scenarios have SameSite restrictions
3. Short expiry + refresh token makes risk manageable

You can then:

Decide each point - Make a call on each disagreement
Continue discussion - Let them negotiate more rounds
Accept current version - Use the latest plan as-is

🔧 Bidirectional Support

PlanCollab works from both Claude Code and Codex:

Environment	Default Role	Calls Other Agent
In Claude Code	🐶 plans, 🐱 reviews	`codex exec`
In Codex	🐱 plans, 🐶 reviews	`claude -p`

The skill auto-detects the environment via $CLAUDECODE variable. Roles can be swapped anytime by saying "swap roles" or "let the other agent plan".

📊 Review Criteria

Plans are evaluated on 6 dimensions:

Completeness - Covers all aspects of the task
Correctness - Technically sound for this codebase
Feasibility - Each step is implementable as described
Step ordering - Correct dependency order
Risk coverage - Edge cases addressed
Testing - Adequate verification strategy

Verdict: APPROVED (no critical/major issues) or NEEDS_REVISION (any critical/major issue).

📁 File Structure

Each collaboration creates a session directory with complete history:

.plancollab/
├── config.json                    # User preferences (auto_review)
├── baseline.md                    # Project architecture baseline
├── 2026-04-25-lru-cache/          # A collaboration session
│   ├── state.json                 # State (rounds, consensus, timestamps)
│   ├── plan.md                    # Final approved plan
│   ├── plans/
│   │   ├── round-1-cc.md          # 🐶 Claude round 1 plan
│   │   └── round-2-cc.md          # 🐶 Claude round 2 plan (revised)
│   └── reviews/
│       ├── round-1-cx.md          # 🐱 Codex round 1 review
│       ├── round-1-consensus-cx.md # Consensus: agreed/disputed
│       └── round-2-cx.md
└── 2026-04-25-auth/               # Another session
    └── ...

File naming: -cc = Claude created, -cx = Codex created.

🎨 Identity System

Clear visual markers throughout:

🐶 = Claude (always)
🐱 = Codex (always)

Session output examples:

🐶 🐱 PlanCollab Started
Task:     Implement user authentication module
Planner:  🐶 Claude
Reviewer: 🐱 Codex
Rounds:   max 3

🐶 🐱 PlanCollab Ended
Result:  ✅ approved
Rounds:  2/3
Final:   .plancollab/2026-04-25-auth/plan.md

📦 Installation

Using npx skills (Recommended)

npx skills add conanttu/skills/plancollab -g -y

Manual Installation

# Clone the skills repository
git clone https://github.com/conanttu/skills.git
cd skills

# Symlink to Claude Code
ln -s $(pwd)/plancollab ~/.claude/skills/plancollab

# Also symlink to Codex for bidirectional support
ln -s $(pwd)/plancollab ~/.agents/skills/plancollab

Prerequisites: Both codex CLI and claude CLI must be installed and in PATH.

🆚 vs Traditional Code Review

	Traditional Code Review	PlanCollab
Review Target	Code	Implementation plan (before code)
Reviewer	Human	Another AI Agent
Iteration	Manual back-and-forth	Automatic multi-round discussion
Consensus Management	Mental notes	File-based consensus tracking
Conflict Resolution	Offline communication	Structured display + user arbitration
History	In PR comments	Independent session directory, fully preserved

🌟 Use Cases

Perfect for:

Complex features with multiple implementation approaches
Architectural decisions that need validation
Refactoring plans that affect many files
Security-sensitive implementations
Performance-critical code paths

Not ideal for:

Simple bug fixes
Single-file changes
Well-established patterns in your codebase

💡 Tips for Best Results

Be specific in your task description - The clearer the task, the better the plan
Keep baseline updated - Rescan after major architectural changes
Review conflict summaries carefully - Both agents often have valid points
Use auto-review for non-trivial plans - Catches issues early
Archive approved plans - They serve as implementation documentation

📚 Learn More

Ready to level up your implementation planning? Try PlanCollab today and experience the power of AI-to-AI collaboration!

🐶 🐱 Happy Collaborating!

What are your thoughts on AI-to-AI collaboration? Have you tried similar approaches? Share your experiences in the comments below!

skill-insp: A Skill That Scores Other Skills

Conan — Mon, 25 May 2026 16:48:54 +0000

skill-insp: A Skill That Scores Other Skills

If you've been building Claude Code skills for a while, you've probably noticed a pattern: every skill author makes the same mistakes the first few times. Vague descriptions that fail to trigger. Workflows that don't say what to do when files are missing. allowed-tools that ask for Bash with no glob restriction. No eval scenarios, so you have no idea if the skill actually works.

I built skill-insp to catch those mistakes automatically. It's a skill that inspects other skills, scores them across 8 dimensions, and tells you what to fix.

Source: github.com/conanttu/skills

What It Does

You point skill-insp at a folder containing a SKILL.md and it gives you:

A 0–100 score across 8 weighted dimensions (Structure, Triggering, Usability, Completeness, Progressive Disclosure, Testability, Maintainability, Safety & Trust)
A prioritized list of findings (High / Medium / Low) with file:line references
An HTML report you can open in a browser
The ability to apply high-priority fixes with automatic backup and revert with SHA-256 hash verification
A functional eval runner that spawns sub-agents against fixture skills to verify the skill's own logic

✨ skill-insp ✨

Overall: my-skill scores 66/100 — risk low, readiness usable-with-improvements.

Key strengths
- Minimal, appropriate permissions (Read and Write only)
- Clear 3-step workflow
- Clean YAML frontmatter with version tracking

Scorecard
| Dimension              | Score |
|------------------------|-------|
| Structure              |  8/10 |
| Triggering             |  9/15 |
| Usability              |  9/15 |
| Completeness           |  7/15 |
| Progressive Disclosure |  7/10 |
| Testability            |  4/10 |
| Maintainability        |  8/10 |
| Safety & Trust         | 14/15 |
| Total                  | 66/100 |

Recommendations
  Medium  Add error-handling for missing or unreadable files.
  Medium  Create evals/ with at least one input and expected output.
  Low     Expand README with usage examples or remove the placeholder.

HTML report: /abs/path/to/cache/my-skill/latest.html
✨ skill-insp ✨

The Scoring Rubric

The 100 points are weighted toward what actually breaks skills in practice:

Dimension	Max	Why it matters
Structure	10	Frontmatter parses, folder layout makes sense
Triggering	15	Description gets the skill invoked in the right contexts
Usability	15	Workflow steps are concrete and runnable
Completeness	15	Edge cases, inputs/outputs, failure handling
Progressive Disclosure	10	SKILL.md stays lean; details live in references
Testability	10	Evals or success criteria exist
Maintainability	10	No duplication, no stale placeholders
Safety & Trust	15	Permissions scoped, no hidden network, no destructive ops

Safety & Trust is the dimension where pattern-matching tools fall apart, so skill-insp does semantic analysis here. It distinguishes between documentation and executable code: a SKILL.md that says "check for rm -rf usage" in a safety checklist is not a destructive operation. A scripts/cleanup.sh that actually runs rm -rf "$TEMP_DIR" is, and gets flagged with the file:line reference.

How It's Built

The skill follows the "model is the analyzer" pattern. There's no Python or Node script that parses YAML and counts characters. Instead:

skill-insp/
├── SKILL.md                       # Workflow + the 4 modes (default, detailed, apply, revert) + Run Evals
├── README.md
├── references/
│   ├── rubric.md                  # Scoring dimensions and what good looks like
│   └── output-format.md           # JSON schema for analysis.json
├── scripts/
│   ├── render-html.js             # analysis.json → latest.html
│   └── run-evals.js               # fixture setup + sub-agent prompt generation
├── assets/
│   └── report_template.html       # Self-contained HTML template
└── evals/
    └── evals.json                 # 8 functional eval scenarios

Two deterministic scripts handle the parts that should be deterministic:

render-html.js turns a JSON analysis into a self-contained HTML report. The template uses CSS custom properties for theming, conic-gradient score rings, and an auto-hidden eval results section.
run-evals.js creates a fixture skill in cache/_fixtures/<id>/, copies a snapshot of skill-insp itself into _skill_home/ so sub-agents can resolve <this-skill> references, and prints a self-contained sub-agent prompt.

Everything else — reading files, parsing YAML, evaluating the rubric, distinguishing documentation from code — is done by the model. This sounds slower than a parser, but it's actually the only way to do it correctly. A regex doesn't know that rm -rf inside a markdown code fence labeled "examples to flag" is not the same as rm -rf inside an executable script.

Progressive Disclosure in Practice

Earlier versions of skill-insp had a 300-line SKILL.md with the entire rubric inline. That hit context budget hard and made the skill harder to edit. The current layout pushes details to references:

SKILL.md holds the workflow and mode entry points. ~150 lines.
rubric.md holds the scoring dimensions, priority levels, compactness rules, and safety guidance. Only loaded when the skill actually scores something.
output-format.md holds the JSON schema. Only loaded when writing analysis.json.

The result: SKILL.md is small enough to read in one sitting, and the model only loads the rubric when it's about to score.

The Eval Runner

This is the part that took the most iteration. The idea is simple: skill-insp ships with 8 eval scenarios in evals/evals.json, each describing a user prompt, fixture files to create, and expectations to verify. To run them:

node scripts/run-evals.js <skill-path> list
node scripts/run-evals.js <skill-path> setup <id>

setup creates a fixture directory, writes the fixture files, copies skill-insp's own resources into _skill_home/, and prints a JSON payload that includes a sub_agent_prompt. The parent agent reads that JSON, spawns a sub-agent with the prompt, and after the sub-agent finishes, checks each expectation:

File expectations ("analysis.json is written") → find over the fixture directory.
Content expectations ("a high-priority finding is raised") → read the output files.
Behavioral expectations ("the model reports an error and stops") → judge from the sub-agent's text output.

The Sandbox Gotcha

In the first version, fixtures were created under os.tmpdir(). This worked when I ran it manually, but sub-agents spawned by the harness were sandboxed to the project root — they got "permission denied" on every Read and Bash call against /var/folders/.../T/eval-skill-insp-*. Three out of eight evals failed for sandbox reasons that had nothing to do with the skill's logic.

The fix was a one-line change: move fixtures into cache/_fixtures/<id>/ inside the project. Now sub-agents inherit the project's filesystem permissions, and the cache directory is .gitignored so it doesn't pollute commits. After the change, all 8 evals run cleanly.

Lesson worth remembering: if you're going to spawn sub-agents, keep their working directory inside the parent's sandbox. Temp directories outside the project tree look like a clean choice but break under tighter permission policies.

Apply and Revert

When you say "apply recommendations", skill-insp:

Re-reads the target files (state may have changed since the inspection).
Copies each file it's about to modify into <cache_dir>/last-apply/.
Computes SHA-256 hashes before and after, recording them in manifest.json.
Makes the minimal edits.
Re-runs the analysis so you see the new score.

The manifest looks like this:

{
  "applied_at": "2026-05-25T23:16:00Z",
  "recommendations_applied": [
    { "priority": "high", "dimension": "triggering", "text": "Replace vague description..." },
    { "priority": "high", "dimension": "usability", "text": "Add a ## Workflow section..." },
    { "priority": "high", "dimension": "completeness", "text": "Add allowed-tools list..." }
  ],
  "files": [
    {
      "relative_path": "SKILL.md",
      "before_sha256": "e698920f94613f8fc335cd0e941938e0990bedd72cea66e52a6b956d4ff47845",
      "after_sha256":  "10c1fafffbfd2b0089a85e72aafc43432374ef627cb0b41602f8396083fa2800"
    }
  ]
}

Revert is the inverse: read the manifest, verify the current file hash matches the recorded after_sha256 (so we don't blow away edits made after the apply), then restore from backup. If the hash doesn't match, skill-insp reports the conflict instead of overwriting. It never falls back to git reset --hard or git checkout -- — those are blast-radius operations that don't belong in a recovery path.

Self-Inspection

Because skill-insp is itself a skill, it can score itself:

You: 评估 .claude/skills/skill-insp
Claude: ✨ skill-insp ✨
        Overall: skill-insp scores 94/100 — risk low, readiness ready.
        ...

The first time I did this, the report flagged things I'd already half-noticed but not bothered to fix: the cache slug derivation rule was dense without an example, the description didn't mention "fix" or "improve" as triggers, and there was no Node.js version floor documented. All of these became Low/Medium recommendations, which I then applied — and the score went up.

This is the most useful feedback loop I've found for skill authoring: write the skill, run skill-insp against it, apply the high-priority recommendations, repeat. The eval suite then verifies the workflow still works end-to-end.

When NOT to Use It

skill-insp's description explicitly says "Not for general code review." It's not a linter for arbitrary Python or TypeScript. It's specifically tuned to the structure and conventions of Claude Code skills:

It expects SKILL.md with YAML frontmatter.
It scores against a skill-specific rubric.
Its safety analysis is calibrated to skills (permission scoping, undisclosed network access in scripts, prompt injection in instructions).

If you point it at a normal source tree, it'll refuse to score because there's no SKILL.md — that's the intended behavior, not a bug.

Trying It

Clone the repo and drop the folder into your Claude Code skills directory:

git clone https://github.com/conanttu/skills.git
ln -s "$(pwd)/skills/skill-insp" ~/.claude/skills/skill-insp

Then in any Claude Code session:

inspect the skill at ./my-skill

Or in Chinese:

evaluate ./my-skill

The trigger phrases are listed in the description so the skill is invoked automatically. After the inspection, follow the numbered prompts:

detailed mode to expand evidence
apply recommendations to auto-fix high-priority findings
run evals to verify the skill with eval scenarios
revert to undo the last apply

What's Next

The current version is 1.0.0. A few things I'd like to add:

Diff view in the HTML report showing what apply actually changed.
Cross-skill consistency checks for repos that ship multiple skills.
Optional schema validation for evals.json and analysis.json.

If you build skills regularly, give it a try and let me know what falls over. The eval scenarios in evals/evals.json are a good place to start if you want to extend it — adding a new scenario is just adding a JSON entry with a prompt, fixture files, and expectations.