Challenge plans

challenge-plans

Harden a plan/spec in multi-agent adversarial review before execution, to reduce rework. Slots into writing-plans → challenge-plans → executing-plans.

When to use (routing signals)

• Input is a single drafted artifact + intent "review / find flaws / can this execute / harden / QA" → use this skill. Pick --type by what the artifact is:
  • a spec / design doc / PRD you're about to build → --type spec
  • any plan with steps to execute (dev or not — a trip, a launch, a hire) → --type plan
  • a code change (git diff) → --type diff
  • a decision already made (an ADR / "we chose X because Y" — a tech-stack pick, a vendor, a hire) → --type decision. Audits the choice itself: skipped alternatives, weak evidence, sunk-cost reasoning, irreversibility.
• An agent has finished something and is about to ask the user to decide or QA → run this first and present the cross-review recommendation.
• Input is ≥2 options still open to choose among → use the sibling weigh-options (deliberation/voting), not this. (--type decision is the opposite: one option already chosen, audited after the fact.)

Run

# Installed from PyPI (pip install challenge-plans) — the console command is available directly.
# Already installed but on an old version? update: pip install -U challenge-plans (pipx: pipx upgrade; uvx: append @latest).
challenge-plans doctor                                                            # check adapter login state first
challenge-plans run <artifact> --type spec --profile standard --sink markdown     # review a plan/spec
challenge-plans run <artifact> --type spec --profile standard --sink markdown --lang zh   # localized output
# code-diff gate:  git diff > change.diff && challenge-plans run change.diff --type diff --sink markdown
# From a source checkout instead (not pip-installed): PYTHONPATH=src python3 -m challenge_plans.cli <args>

• --type spec|diff|plan|decision. diff reviews a raw git diff; plan reviews ANY plan (a trip, a launch, a hire — not just dev specs) with domain-neutral failure types (missing success criteria / ignored constraint / unaddressed risk / sequencing gap / unstated assumption / goal misalignment / irreversibility / no fallback) and feasibility·risk·goal-alignment lenses; decision audits a choice already made (ignored alternative / weak evidence / unstated assumption / sunk-cost bias / unaddressed downside / irreversibility / no review trigger / misframed problem) with alternatives·evidence·reversibility-cost lenses. All run the same verdict pipeline.
• --profile fast|standard|deep, --sink stdout|markdown, --enforce (request_changes/inconclusive/schema_invalid exit non-zero; discuss/approve exit 0); --strict (hard gate — only a clean approve passes); default advisory exits 0.
• --lang <code> (default en): write the review prose in the user's language, e.g. --lang zh. Set this from the user's language so the whole review comes back localized; JSON keys / enums / L12-15 anchors stay stable. Equivalent to exporting CHALLENGE_PLANS_LANG.
• Output: a 6-state verdict + surviving objections. [sev✓] = cross-family Verifier-confirmed, may hard-gate; [sev?] = unverified, advisory only.

If no backend is ready

challenge-plans needs at least one logged-in subscription CLI (it has no model of its own and uses no API keys). If doctor shows nothing ready, don't retry blindly — ask the user, then route:

1. Has a Claude or ChatGPT subscription, but the CLI is missing / logged out → walk them through the exact step doctor prints (install it, or claude → /login, or sign in to codex).
2. No subscription yet but wants one → point them to subscribe (Claude Pro/Max or ChatGPT), then install + log in the CLI.
3. No subscription and doesn't want one → explain challenge-plans cannot run without one, and stop — don't loop.

doctor already prints the per-backend fix plus this guidance; surface it to the user rather than failing silently.

BYO backends (optional). The user can register extra Anthropic-compatible endpoints (GLM/Kimi/a proxy) via env: CP_BYO_<n>_BASE_URL + CP_BYO_<n>_FAMILY + CP_BYO_<n>_TOKEN (all required; _MODEL optional; _1/_2/… for several). Two caveats to relay honestly: (1) the declared family is user-declared, not verified — confirmations through it render ✓(user-declared family) and diversity built on it is flagged, so never present a BYO pairing as the verified builtin claude+gpt cross-family guarantee; (2) the token goes only into that backend's subprocess and never appears in any output — but advise the user to set it via a secrets manager / leading-space export rather than plain shell history. A backend missing one of the three vars is skipped with a warning (never a fallback to subscription auth).

If a backend is too old / a run degrades or errors opaquely

A backend CLI that is logged in but out of date is a distinct failure from "logged out": login status still passes, but a real call is rejected server-side (observed: codex 400 "the model requires a newer version of Codex"), so a voter reports exit_nonzero and the run silently drops to a single family. A run can't cheaply tell this apart mid-flight — but doctor now can: it sends a real minimal call per backend, so a too-old codex reads unsupported_version → update Codex CLI: npm i -g @openai/codex@latest instead of a false ready.

So when a run errors, comes back single-family unexpectedly, or a voter shows exit_nonzero: run doctor and update any unsupported_version backend before retrying — don't just report the error to the user. Updating the backend CLI (npm i -g @openai/codex@latest, or update Claude Code) is part of the standard fix path, not a dead end to hand back.

Presenting to the user

Surface the verdict + surviving objections (✓ verified vs ? unverified) + missing required fields as "my cross-review recommendation", then let the user decide — rather than handing them a bare decision. See README.md for the full picture.

Composing with planning skills

• superpowers (writing-plans → executing-plans): after writing-plans saves a plan file (default docs/superpowers/plans/<date>-<feature>.md — read the actual path), run challenge-plans run <plan> --type spec before executing-plans. It occupies the same pre-execution review seam as superpowers' built-in plan-document-reviewer, but as a multi-CLI cross-family pass. Route surviving objections back into the plan, then execute.
• grill-me (mattpocock/skills): complementary and earlier — it interactively aligns the user while the plan forms (no file output). Run challenge-plans after a written plan/PRD exists.
• Nothing auto-invokes challenge-plans; the calling agent wires it into the seam and chooses --type from the routing signals above.