{"id":"725d71c1-91a1-43ab-816b-9610564e692c","entityType":"agent","slug":"clawhub-chpomob-adversarial-plan","name":"adversarial-plan","canonicalUrl":"https://www.xpersona.co/agent/clawhub-chpomob-adversarial-plan","canonicalPath":"/agent/clawhub-chpomob-adversarial-plan","generatedAt":"2026-10-09T20:20:56.414Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T11:52:46.409Z","emptyReason":null},"description":"Adversarial implementation planner. Takes a spec.md (from adversarial-spec) and optionally review findings, then produces a plan.md with ordered steps, dependencies, files, tests, and risks. Execute the result through focused per-step specs. Skill: adversarial-plan Owner: chpomob Summary: Adversarial implementation planner. Takes a spec.md (from adversarial-spec) and optionally review findings, then produces a plan.md with ordered steps, dependencies, files, tests, and risks. Execute the result through focused per-step specs. Tags: latest:0.1.0 Version history: v0.1.0 | 2026-08-03T18:11:42.037Z | auto Initial release of adversarial-plan: an adversarial i","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.7K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17435m3chty5jmw4jhpkyhnb58brn8g:adversarial-plan","sourceUrl":"https://clawhub.ai/chpomob/adversarial-plan","homepage":"https://clawhub.ai/chpomob/skills/adversarial-plan","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/chpomob/adversarial-plan","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/chpomob/skills/adversarial-plan","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":69,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Adversarial implementation planner. Takes a spec.md (from adversarial-spec) and optionally review findings, then produces a plan.md with ordered steps, dependen"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T11:52:46.409Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T11:52:46.409Z","emptyReason":null},"stars":null,"forks":null,"downloads":2736,"packageName":null,"latestVersion":"0.1.0","tractionLabel":"2.7K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T11:52:46.409Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T11:52:46.409Z","lastCrawledAt":"2026-10-09T11:52:46.409Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T11:52:46.409Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.0","createdAt":"2026-08-03T18:11:42.037Z","changelog":"Initial release of adversarial-plan: an adversarial implementation planner. - Takes a spec.md (from adversarial-spec), optional review findings, and generates a structured plan.md with ordered steps, dependencies, files, tests, and risks. - CLI supports extensive options for workflow control, provider selection, research, and CI integration. - Implements a challenge-revise-verify loop, with support for delegated execution and deep external research. - Outputs plan.md with clear YAML frontmatter and step breakdown; integrates with adversarial-code-loop for stepwise implementation. - Includes HTML reporting, detailed exit codes, and integration guidance. - Personas and related skills organized via adversarial-common for extensibility.","fileCount":29,"zipByteSize":65513}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17435m3chty5jmw4jhpkyhnb58brn8g:adversarial-plan","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T20:20:56.413Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chpomob-adversarial-plan/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T11:52:46.409Z","emptyReason":null},"readme":"Skill: adversarial-plan\n\nOwner: chpomob\n\nSummary: Adversarial implementation planner. Takes a spec.md (from adversarial-spec) and optionally review findings, then produces a plan.md with ordered steps, dependencies, files, tests, and risks. Execute the result through focused per-step specs.\n\nTags: latest:0.1.0\n\nVersion history:\n\nv0.1.0 | 2026-08-03T18:11:42.037Z | auto\n\nInitial release of adversarial-plan: an adversarial implementation planner.\n\n- Takes a spec.md (from adversarial-spec), optional review findings, and generates a structured plan.md with ordered steps, dependencies, files, tests, and risks.\n- CLI supports extensive options for workflow control, provider selection, research, and CI integration.\n- Implements a challenge-revise-verify loop, with support for delegated execution and deep external research.\n- Outputs plan.md with clear YAML frontmatter and step breakdown; integrates with adversarial-code-loop for stepwise implementation.\n- Includes HTML reporting, detailed exit codes, and integration guidance.\n- Personas and related skills organized via adversarial-common for extensibility.\n\nArchive index:\n\nArchive v0.1.0: 29 files, 65513 bytes\n\nFiles: _retrospective (0b), _retrospective/ISSUES.md (387b), .gitignore (100b), LICENSE (665b), README.md (3087b), references (0b), references/claude-timeout-notes.md (515b), references/codex-claude-full-pipeline.md (2902b), references/pipeline-review-to-plan.md (4311b), references/run-plan-steps-without-plan-mode.md (3229b), scripts (0b), scripts/__init__.py (235b), scripts/adversarial_plan.py (44950b), scripts/install.sh (1934b), scripts/phases (0b), scripts/phases/__init__.py (8396b), scripts/phases/phase_challenge.py (8041b), scripts/phases/phase_plan.py (10854b), scripts/phases/phase_revise.py (5010b), scripts/phases/phase_verify.py (6714b), skill-card.md (2771b), SKILL.md (10219b), spec.md (17363b), tests (0b), tests/conftest.py (1999b), tests/test_contract_gate.py (6274b), tests/test_orchestrator.py (34683b), tests/test_phases.py (17961b), _meta.json (135b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: adversarial-plan\ndescription: \"Adversarial implementation planner. Takes a spec.md (from adversarial-spec) and optionally review findings, then produces a plan.md with ordered steps, dependencies, files, tests, and risks. Execute the result through focused per-step specs.\"\nversion: 1.0.0\nauthor: Hermes Agent\nlicense: 0BSD\nplatforms: [linux, macos]\nmetadata:\n hermes:\n tags: [adversarial, planning, implementation, plan, architecture]\n related_skills: [adversarial-spec, adversarial-code-loop, adversarial-code-review]\n---\n\n# Adversarial Plan\n\n**Spec → implementation plan.** Two-role adversarial pipeline that takes a spec.md (from\nadversarial-spec) and optionally review findings (from adversarial-code-review), and\nproduces a plan.md with ordered steps. To implement it with\nadversarial-code-loop, convert each step to a focused spec and run the steps in\ndependency order; adversarial-code-loop has no functional `--plan` mode.\n\n## Installation\n\nRequires the `adversarial-common` sibling repo (shared engine). One-line install:\n\ncurl -fsSL https://raw.githubusercontent.com/chpomob/adversarial-plan/main/scripts/install.sh | bash\n\nor, from an existing checkout:\n\nbash scripts/install.sh\n\nBoth place adversarial-plan and adversarial-common side by side under `~/.hermes/skills` (override the target with `$1` or `$HERMES_HOME`).\n\n## Workflow\n\n```text\nPREFLIGHT ──→ optional DEEP RESEARCH ──→ GIT SETUP\n │\n ├─ delegated success ──→ FINALIZE\n │\n └─ direct/fallback ──→ PLAN ──→ CHALLENGE\n │\n APPROVE + no findings ──────┤\n │\n otherwise ──→ REVISE ──→ VERIFY\n ↑ │\n └──────────┘ up to --max-loops\n │\n FINALIZE\n```\n\nThere is one CHALLENGE phase and no `CROSS_2` phase. A successful delegated\nrun bypasses PLAN/CHALLENGE/REVISE/VERIFY; a delegated fallback enters the\nnormal adversarial loop. FINALIZE squash-merges an approved plan unless\n`--no-merge` is set, or records a rejection marker when findings remain.\n\n## Prompt design\n\nThe CHALLENGE prompt references `plan.md` and `spec.md` on disk and instructs\nthe challenger to read them from the current working directory (the phase\nworkdir). No document text is embedded in the prompt; the provider runs with\nthe phase workdir as its cwd, so filesystem-capable providers inspect both\nfiles and the cumulative branch diff directly.\n\n## CLI\n\n\n\n| Flag | Value/default | Purpose |\n|------|---------------|---------|\n| `--help` | `-h` alias | Show command help and exit. |\n| `--spec` | path; `/spec.md` | Specification to plan. |\n| `--findings` | path; optional | JSON array, or object containing a `findings` array, to incorporate into the plan. |\n| `--dev-cmd` | command; `$APLAN_DEV_CMD` or built-in default | Explicit plan-writer command; with a provider registry, bypasses registry selection for writer phases. |\n| `--review-cmd` | command; `$APLAN_REVIEW_CMD` or built-in default | Explicit challenger/verifier command; with a provider registry, bypasses registry selection for those phases. |\n| `--provider-config` | path; `$ADVERSARIAL_PROVIDER_CONFIG` | Provider registry YAML. |\n| `--force` | off | Skip quota checks and select each registry role's primary provider. |\n| `--force-provider` | `ROLE:ALIAS`; repeatable | Force one provider alias for `writer`, `challenger`, or `verify`. |\n| `--workdir` | directory; `.` | Target Git repository and phase working directory. |\n| `--max-loops` | positive integer; `2` | Maximum REVISE/VERIFY rounds after CHALLENGE. |\n| `--feature` | name; derived from spec | Branch and artifact name. |\n| `--timeout` | positive seconds; `600` | Timeout for each planner/challenger subprocess. |\n| `--out` | directory; `.adversarial-plan` | Artifact base directory; relative paths resolve under `--workdir`. |\n| `--no-merge` | off | On approval, leave the plan branch unmerged. |\n| `--show-costs` | off | Print a per-phase cost breakdown to stderr. |\n| `--retries` | positive integer; `3` | Maximum CLI retries for each phase call. |\n| `--max-input-chars` | positive integer; unlimited | Cap prompt input characters for each phase call. |\n| `--max-output-chars` | positive integer; unlimited | Cap provider output characters for each phase call. |\n| `--html` | off; optional mode | Render an HTML report after `final.json`. This does not change the adversarial flow. |\n| `--ci` | off; optional mode | Suppress banners, use plain stderr, and return stable CI exit codes. |\n| `--fail-on` | selector; optional CI mode | Set CI failure conditions, for example `findings,severity:blocker`; used when `--ci` is active. |\n| `--deep-research` | off; optional mode | Run bounded external research after preflight and merge its findings before planning. |\n| `--research-cmd` | command; research env/dev/default fallback | Provider command used by `--deep-research`. |\n| `--research-max-queries` | positive integer; `5` | Maximum research queries. |\n| `--research-max-results` | positive integer; `5` | Maximum results retained per research query. |\n| `--research-timeout` | positive seconds; `60` | Timeout for each research query. |\n| `--delegated` | off; optional mode | Decompose high-complexity work among workers. A successful delegated run **bypasses the adversarial PLAN/CHALLENGE/REVISE/VERIFY loop**; a direct fallback resumes it. |\n| `--delegated-concurrency` | positive integer; complexity recommendation | Maximum concurrent delegated workers. |\n\n\n\n## Output format\n\nplan.md with YAML frontmatter + ordered steps:\n\n```yaml\n---\nspec: \"feature-name\"\nversion: \"1.0\"\nauthor: \"adversarial-plan\"\nbased-on: \"adversarial-spec\"\nfindings-input: false\n---\n\n## Steps\n\n### P1: First task\n- **Files:** [path/to/file.rs]\n- **Description:** What changes in this file\n- **Dependencies:** []\n- **Tests:** What tests to write\n- **Risks:** What could go wrong\n\n### P2: Second task\n- **Files:** [path/to/another.rs]\n- **Description:** What changes\n- **Dependencies:** [P1]\n- **Tests:** Integration test\n- **Risks:** Deadlock risk\n```\n\n## Personas\n\nLoaded from adversarial-common/personas/:\n- plan-writer.md — reads spec.md + optional findings, writes plan.md\n- plan-challenger.md — reads plan.md, outputs JSON findings (risks, order, gaps)\n\n## Exit codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | APPROVED — plan squash-merged |\n| 1 | Infrastructure failure |\n| 2 | Usage error |\n| 3 | REJECT |\n\n## Integration with dev loop\n\n**IMPORTANT: `--plan` mode is not wired in `adversarial-code-loop`.** Its\nparser accepts `--spec`, not a plan file.\n\nInstead, execute each plan step as a separate code loop with a focused per-step\nspec. See [Running plan steps without plan mode](references/run-plan-steps-without-plan-mode.md)\nfor the step-to-spec template, launch pattern, and pre-flight checklist.\n\n```bash\n# Example: running P1 of a plan\npython3 ~/.hermes/skills/adversarial-code-loop/scripts/adversarial_loop.py \\\n --spec /path/to/step-P1-spec.md \\\n --workdir /path/to/target-repo \\\n --dev-cmd \"codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --sandbox workspace-write\" \\\n --review-cmd \"python3 .../claude-tmux.py --timeout 900 --hard-timeout 1800 --cwd /path/to/target-repo\" \\\n --timeout 1800 --max-loops 3 --no-arbiter\n```\n\nSteps without dependencies targeting different repos can run in parallel (safe).\nParallel on the same repo is forbidden (adversarial-code-loop pitfall #8).\n\n## Plan format constraints\n\n- **Plan validation is partial.** It checks frontmatter, at least one step,\n contiguous step IDs, and requirement-ID coverage in the spec. It does NOT\n enforce step field schemas, parse dependency lists, detect cycles,\n topologically sort, validate file paths, or verify that review findings\n are addressed. Most semantic correctness is delegated to the challenger model.\n\n## Pitfalls\n\n- **The `--findings` flag does NOT accept adversarial-review's `final.json` as-is.** That file contains finding *counts* (`{blocker: 1, major: 2}`), not finding objects. You must extract structured findings from the review synthesis report and craft a findings.json manually.\n- Each step must have explicit dependencies (or empty list). Circular deps cause validation failure.\n- If review findings are provided via --findings, the plan must address each finding in at least one step.\n- Step order should respect dependencies (enforced manually; no automatic topological sort).\n- The same code patterns as adversarial-code-loop v4: git branch isolation, phase modules, squash merge.\n- **For implementation, treat one plan step as one code-loop spec.** Run steps in\n dependency order. Independent steps may run concurrently only when their\n code loops use different repositories.\n- **Plan parser is strict about bullet format.** Files and Dependencies must be on a single\n line: `- **Files:** /path1, /path2`. Indented sub-lists are NOT parsed.\n- **CHALLENGE reads plan.md and spec.md from disk** (provider file tools). The\n orchestrator validates both files are regular files and are UTF-8 decodable\n before running the phase (fail-fast on FIFOs, device nodes, or binary content).\n- **Stash pop may conflict** if untracked files (e.g. `findings.json`) exist in\n the workdir at pipeline end. Fix: `git add` the file before launching, or\n pass `--findings` from outside the workdir.\n- **`write_final_json()` may crash** if stash state is inconsistent at finish\n time. The squash-merge already succeeded; only the artifact write is lost.\n\nFile v0.1.0:README.md\n\n# adversarial-plan\n\n**Spec → implementation plan.** Two-role adversarial pipeline that reads a spec (from `adversarial-spec`) and optional review findings (from `adversarial-code-review`), then produces a `plan.md` with ordered steps.\n\nFor Hermes Agent, Claude Code, Codex, or any LLM CLI.\n\n## How it works\n\n```text\nPREFLIGHT ──→ optional DEEP RESEARCH ──→ GIT SETUP\n │\n ├─ delegated success ──→ FINALIZE\n │\n └─ direct/fallback ──→ PLAN ──→ CHALLENGE\n │\n APPROVE + no findings ──────┤\n │\n otherwise ──→ REVISE ──→ VERIFY\n ↑ │\n └──────────┘ up to --max-loops\n │\n FINALIZE\n```\n\nThe direct pipeline has one CHALLENGE phase and no `CROSS_2` phase. A successful\ndelegated run bypasses the adversarial loop; delegated fallback uses the direct\npipeline. FINALIZE squash-merges approval unless `--no-merge` is set, or records\na rejection marker if findings remain.\n\n## Plan format\n\n```yaml\n### P1: Step title\n- **Files:** /path/to/file1, /path/to/file2\n- **Description:** What to implement\n- **Dependencies:** []\n- **Tests:** How to verify\n- **Risks:** What could go wrong\n```\n\n`adversarial-code-loop` does not provide a functional plan-file mode. To\nimplement a generated plan, convert each step's Files, Description, Tests, and\nRisks into a focused spec, then invoke the code loop with `--spec` for each step\nin dependency order. See [Running plan steps without plan mode](references/run-plan-steps-without-plan-mode.md)\nfor the complete workflow and launch example.\n\n## Comparison\n\n| Feature | adversarial-plan | Manual planning |\n|---------|-----------------|-----------------|\n| Adversarial challenge | ✅ plan-challenger critiques order, gaps, risks | ❌ |\n| Git-native | ✅ branch-per-plan, squash-merge | ❌ |\n| Findings-aware | ✅ accepts structured findings JSON | ❌ |\n| Code-loop workflow | ✅ per-step specs feed repeated `--spec` runs | Manual step extraction |\n\n## Quick start\n\n```bash\npython3 scripts/adversarial_plan.py \\\n --spec spec.md \\\n --findings findings.json \\\n --dev-cmd \"pi --provider zai --model glm-5.2\" \\\n --review-cmd \"pi --provider deepseek --model deepseek-v4-pro\"\n```\n\n## Dependencies\n\n- Python ≥ 3.11\n- Git ≥ 2.5\n- Two LLM CLIs (plan-writer + plan-challenger)\n\nUses `adversarial-common` as the shared engine.\n\n## License\n\n0BSD — see [LICENSE](LICENSE).\n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn7e26az9x7m8bgwfwg90q1wkh8bsqw0\",\n \"slug\": \"adversarial-plan\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1785780702037\n}\n\nFile v0.1.0:references/claude-timeout-notes.md\n\n# Claude Fable 5 Timeout Notes\n\nWhen using Claude Fable 5 as plan-challenger:\n\n- Extended thinking takes 8-12 min per response\n- The default adversarial-plan timeout of 600s is often insufficient\n- Increase `--timeout` to at least 1200 when Claude is the `--review-cmd`\n- Pair with `--hard-timeout 1800` inside the claude-tmux command\n- If Claude exits code 3 (REJECT) due to non-parseable JSON, retry with DeepSeek or GLM-5.2\n- Validated 2026-07-10: 4 findings, REQUEST_CHANGES → REVISE → APPROVE, 4/4 settled\n\nFile v0.1.0:references/codex-claude-full-pipeline.md\n\n# Codex GPT-5.6-Sol + Claude Fable 5 — Full Adversarial Pipeline\n\nValidated 2026-07-10 on the OmniSense firmware project (ESP32-S3 + CC1101).\n\n## Pipeline stages\n\nAll three stages completed in 1 cycle each with Codex as writer/DEV and Claude as\nchallenger/reviewer:\n\n| Stage | Writer | Challenger | Findings | Result |\n|-------|--------|------------|----------|--------|\n| Spec | Codex GPT-5.6-Sol (reasoning=high) | Claude Fable 5 (tmux) | 11 findings | APPROVED (11/11 settled) |\n| Plan | Codex GPT-5.6-Sol (reasoning=high) | Claude Fable 5 (tmux) | 4 findings | APPROVED (4/4 settled) |\n| Code loop | Codex GPT-5.6-Sol (reasoning=high) | Claude Fable 5 (tmux) | 4+ findings per step | In progress (P5/8 reached) |\n\n## Commands used\n\n### Spec\n```bash\npython3 adversarial_spec.py \\\n --brief /tmp/brief.md \\\n --dev-cmd \"codex exec -C /path/to/target-repo --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox -c model='gpt-5.6-sol' -c model_reasoning_effort='high'\" \\\n --review-cmd \"python3 /path/to/claude-tmux.py --timeout 600 --hard-timeout 1200 --cwd /path/to/target-repo\" \\\n --feature \"feature-name\" --timeout 1200\n```\n\n### Plan\n```bash\npython3 adversarial_plan.py \\\n --spec spec.md \\\n --dev-cmd \"codex exec -C /path/to/target-repo ...\" \\\n --review-cmd \"python3 /path/to/claude-tmux.py --cwd /path/to/target-repo ...\" \\\n --feature \"feature-name\" --timeout 1200\n```\n\n### Code loop\n```bash\npython3 adversarial_loop.py \\\n --plan /tmp/plan.md \\\n --dev-cmd \"codex exec -C /path/to/target-repo ...\" \\\n --review-cmd \"python3 /path/to/claude-tmux.py --cwd /path/to/target-repo ...\" \\\n --feature \"feature-name\" --out .adversarial-loop \\\n --timeout 1200 --max-loops 2 --no-arbiter\n```\n\n## Key observations\n\n- Claude Fable 5 via `claude-tmux.py` produced valid JSON for both the embedded-prompt\n pattern (spec/plan challenger) and the files-on-disk pattern (code loop reviewer).\n Earlier documentation claiming Claude cannot do the embedded-prompt pattern was\n pre-Fable-5 or related to an older claude-tmux wrapper version.\n- claude-tmux wrapper buffers ALL output until the session completes — no partial\n output appears in `process(action='poll')`. Only `notify_on_complete` reveals the result.\n- Codex with `codex exec -C ` + inline prompt (`-C` for context directory,\n prompt as argument) is the preferred approach for focused reviews, avoiding the\n 1 MB stdin input limit of the review script's `--project-dir` mode.\n- `reasoning=high` on GPT-5.6-Sol produces deeper analysis but can cause 5+ minute\n silent pauses between actions. `reasoning=low` is faster for exploration-heavy tasks.\n- The full pipeline produces real git commits at every stage, making rollback safe.\n- Claude quota is the main bottleneck: ~200-300K tokens per 5h window. For long\n code loops (8+ steps), GLM-5.2 (pi --provider zai) or DeepSeek are viable\n fallbacks for the reviewer role.\n\nFile v0.1.0:references/pipeline-review-to-plan.md\n\n# Bridging adversarial-code-review → adversarial-plan\n\n## The gap\n\nAdversarial-review outputs `final.json` with `{verdict, findings: {blocker: N, major: N}}` — finding **counts**, not finding objects. The plan pipeline's `--findings` flag expects either a JSON array of finding objects or an object with a `findings` array. **These are not compatible formats.** You must extract structured findings from the review synthesis and craft a findings.json manually.\n\n## Detection\n\nAfter `adversarial_review.py` completes, check:\n\n```\nls / # e.g. /tmp/acr-quota-publish/\n# → 01_architect.txt 02_inspector.txt 03_cross_1.txt ...\n# → 05_synthesis.txt review.md final.json\ncat /final.json\n# → {\"verdict\":\"REQUEST_CHANGES\",\"findings\":{\"major\":10,\"minor\":5,\"nit\":2},...}\n# ⚠ These are COUNTS, not finding objects — NOT plan-consumable.\n```\n\n## Extraction procedure\n\n### 1. Read the synthesis report (`05_synthesis.txt` or `review.md`)\n\nIt contains the complete ranked findings list with id, severity, file, line, summary, and evidence for each.\n\n### 2. Craft a findings.json\n\nFormat accepted by `adversarial_plan.py --findings`:\n\n**Option A — bare array (preferred):**\n```json\n[\n {\n \"id\": \"C1\",\n \"severity\": \"blocker\",\n \"summary\": \"Short title\",\n \"detail\": \"Full description with root cause and fix guidance\",\n \"file\": \"file.py:42-56\"\n },\n ...\n]\n```\n\n**Option B — object with `findings` key (also accepted):**\n```json\n{\n \"findings\": [...]\n}\n```\n\nEach finding object supports these fields:\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `id` | Yes | Unique identifier, e.g. `C1`, `M2`. Used by the plan pipeline for tracking finding-to-step mapping. |\n| `severity` | Yes | `blocker`, `major`, `minor`, or `nit`. |\n| `summary` | Yes | One-line title. |\n| `detail` | No | Multi-sentence description with root cause, impact, and fix direction. |\n| `file` | No | Path and line range, e.g. `__init__.py:549-556`. |\n\n### 3. Strip review-only metadata\n\nRemove any fields the synthesis report adds for the human reader (e.g. \"cross-review consensus\", \"risk level: confirmed\"). Only id, severity, summary, detail, and file are consumed by the plan pipeline.\n\n### 4. Validate\n\n```bash\npython3 -c \"\nimport json, sys\nwith open('/tmp/findings.json') as f:\n data = json.load(f)\nif isinstance(data, dict):\n data = data.get('findings', [])\nassert isinstance(data, list), 'must be array or object with findings key'\nfor f in data:\n assert f.get('id'), f'missing id in {f}'\n assert f.get('severity'), f'missing severity in {f}'\n assert f.get('summary'), f'missing summary in {f}'\nprint(f'{len(data)} findings valid')\n\"\n```\n\n### 5. Feed to plan\n\n```bash\npython3 /path/to/adversarial_plan.py \\\n --spec spec.md \\\n --findings /tmp/findings.json \\\n --workdir /path/to/project \\\n ...\n```\n\n## Alternative: extract from earlier artifacts\n\nIf the synthesis report is missing or truncated, extract findings from the raw reviewer output artifacts:\n\n```\n01_architect.txt → JSON with \"findings\" array (Architect perspective)\n02_inspector.txt → JSON with \"findings\" array (Inspector perspective)\n```\n\nThese contain individual reviewer findings but lack the cross-validation consensus and ranking. Merge manually, deduplicate by id (the synthesis already does this in its report).\n\n## Pitfalls\n\n- **Do NOT feed `final.json` directly to `--findings`.** The plan pipeline will parse `{findings: {blocker: 1, major: 2}}` as a dict, try `payload.get(\"findings\")` which returns the dict, then fail `isinstance(payload, list)` → exit 2 \"must be a JSON array or an object with a 'findings' array\".\n- **Do NOT skip findings.** Every finding id in the findings.json must be addressed by at least one plan step or the plan-challenger will flag it as uncovered.\n- **Severity drives plan urgency.** `blocker` findings should get their own step early. `nit` findings can be grouped in a cleanup step at the end.\n- **File paths help the plan-writer generate accurate step descriptions.** Include them even though they're not strictly required.\n- **Cross-review ADD findings (from 03_cross_1.txt / 04_cross_2.txt)** are already consolidated in the synthesis report — check the report's \"Critical Findings\" section which lists cross-review additions per finding.\n\nFile v0.1.0:references/run-plan-steps-without-plan-mode.md\n\n# Running plan steps without `--plan` mode\n\n**`--plan` mode is NOT wired in `adversarial-code-loop`** (pitfall #1, validated\n2026-07-15). The `adversarial_loop.py` argparse only accepts `--spec`, not `--plan`.\nThis reference documents the working workflow: execute each plan step as a separate\ncode loop with a focused per-step spec.\n\n## Workflow\n\n1. **Extract one step from the plan** — copy its Files, Description, Tests, and Risks\n into a standalone spec.md with YAML frontmatter.\n2. **Launch a code loop** on that spec using the target repo as `--workdir`.\n3. **Repeat for each step**, respecting dependency order.\n\n## Step → spec pattern\n\nGiven a plan step like:\n\n```\n### P3: Implement the model-agnostic quota resolver\n- **Files:** [adversarial_common/quota.py, adversarial_common/__init__.py, adversarial_common/tests/test_quota.py]\n- **Dependencies:** [P1, P2]\n- **Description:** Create QuotaResolver with TTL cache, state machine, thresholds...\n- **Tests:** Add tests for ordered fallback, cache, force modes, thresholds...\n- **Risks:** Cache sync, partial checker data...\n```\n\nCreate a spec:\n\n```yaml\n---\nname: \"quota-resolver\"\nversion: \"1.0\"\nauthor: \"adversarial-plan\"\nstatus: \"draft\"\ntargets:\n - file: adversarial_common/quota.py\n description: \"QuotaResolver with cache, state machine, thresholds, force modes.\"\n - file: adversarial_common/__init__.py\n description: \"Export resolver symbols.\"\n - file: adversarial_common/tests/test_quota.py\n description: \"Tests for resolver, cache, fallback, force.\"\n---\n\n# Quota Resolver\n\n## Problem\n...\n\n## Requirements\n- R1: ...\n```\n\n## Launch pattern\n\n```bash\npython3 ~/.hermes/skills/adversarial-code-loop/scripts/adversarial_loop.py \\\n --spec /path/to/step-spec.md \\\n --feature short-descriptive-name \\\n --dev-cmd \"codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --sandbox workspace-write\" \\\n --review-cmd \"python3 /path/to/claude-tmux.py --timeout 900 --hard-timeout 1800 --cwd /path/to/target-repo\" \\\n --workdir /path/to/target-repo \\\n --timeout 1800 \\\n --max-loops 3 \\\n --no-arbiter\n```\n\n## Key decisions\n\n| Decision | Rule |\n|----------|------|\n| `--workdir` | Point to the **repo** containing the step's files (e.g. adversarial-common for quota.py) |\n| `--cwd` for claude-tmux | Always set to the same `--workdir` so reviewer finds the right git repo |\n| Parallel steps | Safe ONLY when steps target different repos (different `--workdir`). Never parallel on same repo (pitfall #8) |\n| File paths in spec | Relative to `--workdir` (e.g. `adversarial_common/quota.py` not `../adversarial-common/...`) |\n| `--no-arbiter` | Recommended for atomic steps — single model review is sufficient |\n| `--feature` | Short slug matching the step purpose, avoids branch collisions |\n\n## Pre-flight checklist\n\n- [ ] Target repo is on `main` with clean `git status`\n- [ ] `--workdir` is an individual skill repo (NOT `~/.hermes/skills/`)\n- [ ] claude-tmux `--cwd` matches `--workdir`\n- [ ] No `--yolo` in claude-tmux command (flag doesn't exist in v1)\n- [ ] No `--model` in claude-tmux command (use wrapper default)\n- [ ] Spec targets use paths relative to `--workdir`\n- [ ] Timeout is generous (1800+ for Claude extended thinking)\n\nFile v0.1.0:_retrospective/ISSUES.md\n\n# adversarial-plan — retrospective issues\n\nThis tracked file is for curated post-mortem notes. The pipeline does not write\ninto the skill install tree: `scripts/adversarial_plan.py` auto-appends phase\nfailures to `/ISSUES.md` instead (`.adversarial-plan/ISSUES.md` by default).\nPromote findings from a run's artifact log here when they should be retained as\nproject-wide lessons.\n\nFile v0.1.0:skill-card.md\n\n## Description:\n\nAdversarial implementation planner. Takes a spec.md (from adversarial-spec) and optionally review findings, then produces a plan.md with ordered steps, dependencies, files, tests, and risks. Execute the result through focused per-step specs.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[chpomob](https://clawhub.ai/user/chpomob)\n\n### License/Terms of Use:\n\n0BSD\n\n## Use Case:\n\nDevelopers and engineers use this skill to turn a specification and optional review findings into an ordered implementation plan with files, dependencies, tests, and risks. It is intended for workflows that pass each plan step into a focused implementation loop.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Installer and example commands can run unchecked code.\n\nMitigation: Review before installing, prefer a local pinned checkout instead of curl-to-bash, and avoid sandbox-bypass examples unless the repository is disposable or trusted.\n\nRisk: The workflow can allow AI tools to change or merge repository files beyond producing a plan.\n\nMitigation: Use --no-merge for review-first runs and inspect the full git diff before accepting generated output.\n\nRisk: Specs and findings are untrusted inputs that can influence provider actions and contract checks.\n\nMitigation: Review spec.md and findings files before running the planner and keep provider execution constrained to the intended working directory.\n\n## Reference(s):\n\n- [Server-resolved GitHub source](https://github.com/chpomob/adversarial-plan)\n- [ClawHub skill page](https://clawhub.ai/chpomob/skills/adversarial-plan)\n- [Running plan steps without plan mode](references/run-plan-steps-without-plan-mode.md)\n- [Bridging adversarial-code-review to adversarial-plan](references/pipeline-review-to-plan.md)\n- [Codex GPT-5.6-Sol + Claude Fable 5 full adversarial pipeline](references/codex-claude-full-pipeline.md)\n- [Claude Fable 5 timeout notes](references/claude-timeout-notes.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown plan.md with YAML frontmatter, optional JSON or Markdown reports, and inline shell/configuration guidance.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Writes planning artifacts under the configured output directory and can leave or merge a planning branch depending on CLI options.]\n\n## Skill Version(s):\n\n0.1.0 (source: ClawHub release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.0:spec.md\n\n---\nname: quota-aware-provider-registry\nversion: \"1.0\"\nauthor: adversarial-spec\nstatus: draft\ntargets:\n - file: adversarial_common/quota.py\n description: \"New module — quota resolver that checks provider availability and returns the best command to run.\"\n - file: adversarial_common/runner.py\n description: \"Modified — run_phase() integrates quota check before executing commands, with automatic fallback chain.\"\n - file: adversarial_common/__init__.py\n description: \"Export new quota module symbols.\"\n - file: adversarial_common/providers.py\n description: \"Add ProviderConfig dataclass and YAML config loader for provider registries.\"\n - file: adversarial_common/report.py\n description: \"Add quota metadata to the final report (which provider was used, quota state at decision time).\"\n - file: adversarial_common/jsonio.py\n description: \"No changes needed — already handles JSON read/write used by check-ai-quota.py output.\"\n---\n\n# Quota-Aware Provider Registry\n\n## Problem\n\nThe adversarial pipeline (spec, plan, code loop) launches model commands blindly — it\nexecutes `--dev-cmd` and `--review-cmd` without knowing whether the target model has\nremaining quota. When a model exhausts its rate limit mid-pipeline (Claude 5h sliding\nwindow, Codex monthly cap, GLM-5.2 80 req/5h, Fable 5 separate limit), the running\nphase fails with a cryptic timeout or error, the pipeline restarts from scratch after\na manual `--resume`, and the user must manually check quotas with `check-ai-quota.py`\nbefore each launch.\n\nThe user already has:\n- A `hermes-quota-status` plugin with `quota_api.py` that checks Claude, Codex, Gemini,\n GLM (Z.AI), and DeepSeek quotas via direct API calls.\n- A `check-ai-quota.py` script in adversarial-code-review that wraps the plugin into\n a CLI with `--json` output for programmatic consumption.\n- Hardcoded fallback rules in SKILL.md (\"if Claude quota low → GLM\", \"if Fable 5\n blocked → Sonnet\") that the user applies manually.\n- A clear preference: **Claude as primary**, **Codex as secondary**, with fallback\n chains that differ per role (DEV vs REVIEW vs CHALLENGER).\n\nWhat's missing: an automated, model-agnostic layer that selects the right command for\neach phase based on real-time quota data, without the pipeline needing to know what\n\"Claude\" or \"Codex\" actually are.\n\n## Requirements\n\n- R1: The pipeline shall check provider quotas before launching each phase (DEV,\n REVIEW, VERIFY, ARBITER, CHALLENGE) and select the best available command.\n- R2: The quota integration shall be fully model-agnostic — the pipeline never\n hardcodes model names; it works with provider aliases resolved by an external\n quota checker.\n- R3: The system shall support a configurable ordered list of providers per role\n with fallback semantics (try #1 → quota low → try #2 → quota exhausted → try #3).\n- R4: When no provider in the fallback chain has available quota, the phase shall\n report a clear \"no provider available\" error with per-provider quota snapshots\n and exit the pipeline cleanly (not timeout).\n- R5: The quota check shall be fast — a single parallel call to\n `check-ai-quota.py --json` that resolves all known providers in one shot, using a\n **global cache** shared across all roles (Claude à 80% l'est pour tous les rôles).\n Configurable TTL (default 30s) to avoid hammering provider APIs on every sub-phase.\n The cache is keyed by provider alias, not by role.\n- R6: The system shall log which provider was selected, why (quota state), and the\n raw quota snapshot in the pipeline's final report (final.json / final.md).\n- R7: The provider registry shall be loaded from an external YAML file specified via\n `--provider-config` CLI flag, `ADVERSARIAL_PROVIDER_CONFIG` environment variable,\n or default path `~/.config/adversarial/providers.yaml`. No provider config file\n shall be shipped inside any skill directory.\n- R8: The quota resolver shall handle the case where `check-ai-quota.py` is not\n installed or returns errors — fall back to executing the primary command directly\n (legacy behaviour) with a warning logged.\n- R9: The system shall support environment variable overrides per role\n (`ADVERSARIAL_DEV_PROVIDERS`, `ADVERSARIAL_REVIEW_PROVIDERS`) as inline JSON\n that overrides the YAML config without touching files — useful for pipeline\n orchestration where the config file is read-only or in CI.\n- R10: The existing `--dev-cmd`, `--review-cmd`, `--arbiter-cmd` CLI flags shall\n still work as positional overrides: when the user passes an explicit `--dev-cmd`,\n quota checking for that role is skipped (the explicit command wins). This preserves\n backward compatibility and manual override.\n- R11: The report shall include a `provider_history` array tracking every phase's\n provider decision: which alias was selected, quota state at decision time, and\n whether a fallback was triggered.\n- R12: All error messages and report fields shall be in English (pipeline convention).\n User-facing CLI output (--help, warnings) stays in the conversation's language.\n- R13: Command strings in the provider config shall support `{workdir}` as a placeholder\n that the resolver substitutes with the effective workdir at execution time. This allows\n commands like claude-tmux's `--cwd` to point to the correct project directory without\n hardcoding paths.\n- R14: The system shall include and maintain a `check-ai-quota.py` CLI wrapper that exposes\n `--glm` and `--deepseek` flags in addition to the existing `--claude`, `--codex`,\n `--gemini` flags. This ensures all providers used in the fallback chain have a quota\n check path, preventing silent UNKNOWN fallback for GLM and DeepSeek.\n- R15: Each provider entry in the config may specify a `stop_threshold` field. For\n **percentage-based** providers (Claude, Codex, GLM sliding window), it represents the\n max used_pct before the provider is skipped (default: 100). For **balance-based**\n providers (DeepSeek, Gemini credits), it represents the minimum remaining balance\n before the provider is skipped (default: 0 — use until empty). The resolver shall\n detect which model a provider uses from its quota response schema (presence of\n `balance` vs `session.used_pct`).\n- R16: A `--force` CLI flag shall bypass all quota checks for all roles. The pipeline\n uses the first provider in each role's config chain regardless of quota state.\n Useful for degraded mode, testing, or when quota APIs are down.\n- R17: A `--force-provider :` CLI flag shall force a specific provider\n alias for a single role (e.g. `--force-provider review:deepseek`). Other roles\n still check quotas normally. This allows unblocking a specific phase without\n disabling quota awareness globally.\n\n## Acceptance criteria\n\n- AC1 (R1): Run a pipeline with two providers configured (claude→deepseek). Block\n Claude's quota artificially (set session_pct=100 in mock). Pipeline selects deepseek.\n Phase completes. Verified via final.md showing deepseek as selected provider.\n- AC2 (R2): Add a new provider with alias \"my-model\" to the YAML config. Provide\n a working quota check script that returns OK for it. Pipeline uses it without any\n code changes. No model name string appears in runner.py or quota.py source.\n- AC3 (R3): Configure providers.prod: cmd1, cmd2, cmd3. Set cmd1 to simulate\n RATE-LIMITED, cmd2 DRAINING, cmd3 OK. Pipeline selects cmd3. Set cmd3 to\n RATE-LIMITED too. Pipeline reports \"no provider available\" with a snapshot of\n all three states and exits code 3 (REJECT).\n- AC4 (R5): Run a pipeline with 4 phases. First check-quota call takes ~1s (parallel\n HTTP calls). Subsequent phase checks in the same 30s window return cached results\n (sub-millisecond). Verify only one HTTP batch per TTL window.\n- AC5 (R6): After a pipeline run, final.json contains a `provider_history` array.\n Each entry has phase name, selected alias, quota state (OK/DRAINING/RATE-LIMITED),\n and `fallback: true/false`.\n- AC6 (R8): Run a pipeline on a system without check-ai-quota.py or quota_api.py.\n Pipeline runs normally using the primary command for each role, with a warning\n logged to stderr. Exit code is the same as if the script had run without quota\n awareness (legacy behaviour).\n- AC7 (R9): Set `ADVERSARIAL_DEV_PROVIDERS='[{\"alias\":\"claude\", \"cmd\":\"...\"}]'`\n in environment. Pipeline ignores the YAML file's dev section and uses the env var.\n- AC8 (R10): Run pipeline with `--dev-cmd \"echo primary\"`. Pipeline skips quota\n check for DEV role, executes the explicit command directly. Other roles still\n check quotas.\n- AC9 (R11): After a 3-phase pipeline run, provider_history has exactly 3 entries\n (one per phase that checks quotas). Each entry has `phase`, `alias`, `quota_state`,\n `fallback` fields. Fields are non-empty.\n- AC10 (R12): All fields in final.json are in English. CLI --help output may be in\n French when the user's session language is French.\n- AC11 (R13): A provider config entry with cmd containing `{workdir}` executes with\n `{workdir}` replaced by the absolute path of the pipeline's working directory.\n Verified by running `echo {workdir}` as a provider command and checking the phase log\n contains the expected path. Trailing slashes shall be stripped.\n- AC12 (R14): `check-ai-quota.py --json --glm` returns a structured JSON response\n with GLM quota data. `check-ai-quota.py --json --deepseek` returns structured JSON\n with DeepSeek balance data. Both return exit 0 on success, exit 1 with an error\n message if credentials are missing.\n- AC13 (R15): Configure DeepSeek with `stop_threshold: 2.0`. Set mock balance to $1.50.\n Pipeline skips DeepSeek and falls to next provider. Set mock balance to $5.00.\n Pipeline selects DeepSeek. Same test with Claude: `stop_threshold: 90`, mock\n used_pct=95 → skipped, mock used_pct=80 → selected.\n- AC14 (R16): Run pipeline with `--force`. All providers in RATE-LIMITED state.\n Pipeline uses the first provider for each role anyway. Phases execute normally.\n- AC15 (R17): Run pipeline with `--force-provider review:deepseek`. Set Claude to\n RATE-LIMITED, DeepSeek to OK. Review phase uses DeepSeek (the forced one, not\n the fallback chain). DEV phase still checks quotas normally for its own chain.\n\n## Provider config file — user provided\n\nThe user creates this file (e.g. at `~/.config/adversarial/providers.yaml`)\nand passes it to the pipeline via `--provider-config`. Example content:\n\n```yaml\n# One provider section per role. Ordered by preference.\n# First provider with available quota wins.\ndev:\n - alias: codex\n cmd: \"codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --sandbox workspace-write\"\n quota_check: --codex\n stop_threshold: 95 # skip if used_pct > 95%\n\n - alias: glm\n cmd: \"pi -p --provider zai --model glm-5.2 --thinking high\"\n # No quota_check → treated UNKNOWN (used anyway with warning)\n\nreview:\n - alias: claude\n cmd: \"python3 /path/to/claude-tmux.py --timeout 600 --hard-timeout 1800 --cwd {workdir}\"\n quota_check: --claude\n stop_threshold: 90 # skip if used_pct > 90%\n\n - alias: glm\n cmd: \"pi -p --provider zai --model glm-5.2 --thinking high\"\n\n - alias: deepseek\n cmd: \"pi -p --provider deepseek --model deepseek-v4-pro --thinking high\"\n quota_check: --deepseek\n stop_threshold: 2.0 # skip if balance < $2.00\n\nchallenger:\n - alias: claude\n cmd: \"python3 /path/to/claude-tmux.py --timeout 900 --hard-timeout 1800 --cwd {workdir}\"\n quota_check: --claude\n\n - alias: glm\n cmd: \"pi -p --provider zai --model glm-5.2 --thinking high\"\n\n - alias: deepseek\n cmd: \"pi -p --provider deepseek --model deepseek-v4-pro --thinking high\"\n quota_check: --deepseek\n stop_threshold: 3.0\n\n# Global quota_check command (used when per-entry quota_check is absent)\nquota_cmd: \"python3 /path/to/check-ai-quota.py --json\"\n\n# Cache TTL in seconds (default 30)\nquota_cache_ttl: 30\n```\n\n## Provider configuration is purely external\n\nNo skill — adversarial-code-loop, adversarial-spec, adversarial-plan, or adversarial-code-review —\nshall hardcode or ship defaults for any provider alias, command string, or fallback chain.\nThe skills know only about **roles** (dev, review, verify, arbiter, writer, challenger).\nWhich provider commands map to which role is entirely determined by the user's config.\n\n**Rationale:** The skills are a model-agnostic orchestration framework. They run commands\nand check quotas; they do not know what \"Claude\", \"Codex\", \"GLM\", or \"DeepSeek\" are.\nHardcoding a default chain in any skill would:\n- Break when the user's preferred model lineup changes\n- Create a false implicit coupling between skills and specific providers\n- Violate separation of concerns (provider selection is operational config, not skill logic)\n\n## Quota state resolution\n\nThe quota resolver interprets `check-ai-quota.py --json` output via a simple\nstate machine:\n\n```\ncheck-ai-quota.py --json --claude\n → {\"results\": {\"claude\": {\"session\": {\"used_pct\": 45}, \"status\": \"OK\"}}}\n\nState → OK: used_pct < 50 → green, command can run\nState → DRAINING: used_pct 50-99 → yellow, command can run but warn\nState → RATE-LIMITED: used_pct >= 100 or HTTP 429 → skip, try next provider\nState → KEY_INVALID: token missing or expired → skip, try next provider\nState → UNKNOWN: no data or error → use command anyway (conservative)\n```\n\nWhen `--all` is passed, the script checks all known providers in parallel, returns\na combined JSON. The resolver picks the first provider in the config whose state\nis OK or DRAINING (in order of preference). RATE-LIMITED and KEY_INVALID are\nskipped; UNKNOWN is used but logged as a warning.\n\n## Impact analysis\n\n### adversarial-common (new code)\n- `quota.py` (~150 lines) — quota_cache, resolve_provider(), parse_quota_state().\n- `providers.py` (~60 lines added) — ProviderConfig dataclass, load_provider_config()\n with YAML path arg + env override support.\n- `runner.py` (~40 lines modified) — run_phase_cmd() wraps command execution with\n pre-flight provider selection.\n- `report.py` (~20 lines added) — provider_history appended to final report.\n\n### No defaults shipped\nNo skill ships a `.adversarial-providers.yaml`. Provider config is entirely external —\nloaded from a path provided by the user via:\n- `--provider-config ` CLI flag (available on all pipeline entry points)\n- `ADVERSARIAL_PROVIDER_CONFIG` environment variable\n- Fallback: `~/.config/adversarial/providers.yaml`\n\nSkills are clean of any model references. The pipeline is a pure orchestration framework.\n\n### Pipeline entry points affected\n- `adversarial-code-loop/scripts/adversarial_loop.py` — accept `--provider-config` flag\n- `adversarial-spec/scripts/adversarial_spec.py` — accept `--provider-config` flag\n- `adversarial-plan/scripts/adversarial_plan.py` — accept `--provider-config` flag\n- `adversarial-code-review/scripts/adversarial_review.py` — accept `--provider-config` flag\n\nEach entry point loads the config and passes it to `adversarial_common.runner.run_phase()`.\n\n### Not modified\n- `adversarial_common/jsonio.py` — already handles structured JSON output.\n- `adversarial_common/gitops.py` — no quota awareness needed.\n- `adversarial_common/gates.py` — no quota awareness needed.\n- `adversarial_common/snapshot.py` — no quota awareness needed.\n- `adversarial_common/costs.py` — orthogonal, already tracks costs post-hoc.\n\n## Out of scope (v2)\n\n- **Automatic retry after quota reset** — detecting that a provider came back and\n retrying a failed phase. v1 just fails cleanly with a useful message.\n- **Quota-aware step scheduling** — reordering pipeline steps to fit within\n available quota windows. v1 selects a provider per phase independently.\n- **Cost-aware provider selection** — preferring cheaper models when within quota.\n v1 selects by availability only (preference order from config).\n- **Cross-pipeline quota coordination** — two concurrent pipelines sharing quota\n state. v1's cache is per-process.\n- **HTML / visual quota dashboard** — the quota data is available in final.json\n but no dashboard is built in v1.\n\n## Known open questions\n\n1. **How to detect Fable 5 separate quota from Claude Pro quota?** The\n `quota_api.py` fetches Claude's 5h sliding window. Fable 5 has an independent\n limit that requires a separate endpoint or heuristic (probe a small prompt\n before launching the real one). v1 may treat Fable 5 as claude-claude alias\n with an additional heuristic probe.\n2. **Should the quota check be per-phase or per-call?** The pipeline has\n BUILD→REVIEW→FIX→VERIFY cycles. A single phase (e.g. REVIEW) may run a model\n for 10+ minutes and consume quota. v1 checks before the phase starts; it cannot\n detect mid-phase exhaustion. That's acceptable — the error would surface as a\n phase timeout which is already handled.\n3. **What happens when two providers share the same alias name?** (e.g. \"claude\"\n for both DEV and REVIEW). They have separate entries in separate role sections\n of the YAML, so no collision. Same alias can have different quota_check commands\n per role if needed.\n4. **How to handle GLM and Codex quotas?** `quota_api.py` already supports both.\n The resolver just passes `--glm` or `--codex` to `check-ai-quota.py --json`.\n\nFile v0.1.0:LICENSE\n\nCopyright (C) 2026 chpomob\nSPDX-License-Identifier: 0BSD\n\nPermission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.","readmeExcerpt":"Skill: adversarial-plan Owner: chpomob Summary: Adversarial implementation planner. Takes a spec.md (from adversarial-spec) and optionally review findings, then produces a plan.md with ordered steps, dependencies, files, tests, and risks. Execute the result through focused per-step specs. Tags: latest:0.1.0 Version history: v0.1.0 | 2026-08-03T18:11:42.037Z | auto Initial release of adversarial-plan: an adversarial i","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"PREFLIGHT ──→ optional DEEP RESEARCH ──→ GIT SETUP\n │\n ├─ delegated success ──→ FINALIZE\n │\n └─ direct/fallback ──→ PLAN ──→ CHALLENGE\n │\n APPROVE + no findings ──────┤\n │\n otherwise ──→ REVISE ──→ VERIFY\n ↑ │\n └──────────┘ up to --max-loops\n │\n FINALIZE"},{"language":"yaml","snippet":"---\nspec: \"feature-name\"\nversion: \"1.0\"\nauthor: \"adversarial-plan\"\nbased-on: \"adversarial-spec\"\nfindings-input: false\n---\n\n## Steps\n\n### P1: First task\n- **Files:** [path/to/file.rs]\n- **Description:** What changes in this file\n- **Dependencies:** []\n- **Tests:** What tests to write\n- **Risks:** What could go wrong\n\n### P2: Second task\n- **Files:** [path/to/another.rs]\n- **Description:** What changes\n- **Dependencies:** [P1]\n- **Tests:** Integration test\n- **Risks:** Deadlock risk"},{"language":"bash","snippet":"# Example: running P1 of a plan\npython3 ~/.hermes/skills/adversarial-code-loop/scripts/adversarial_loop.py \\\n --spec /path/to/step-P1-spec.md \\\n --workdir /path/to/target-repo \\\n --dev-cmd \"codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --sandbox workspace-write\" \\\n --review-cmd \"python3 .../claude-tmux.py --timeout 900 --hard-timeout 1800 --cwd /path/to/target-repo\" \\\n --timeout 1800 --max-loops 3 --no-arbiter"},{"language":"text","snippet":"PREFLIGHT ──→ optional DEEP RESEARCH ──→ GIT SETUP\n │\n ├─ delegated success ──→ FINALIZE\n │\n └─ direct/fallback ──→ PLAN ──→ CHALLENGE\n │\n APPROVE + no findings ──────┤\n │\n otherwise ──→ REVISE ──→ VERIFY\n ↑ │\n └──────────┘ up to --max-loops\n │\n FINALIZE"},{"language":"yaml","snippet":"### P1: Step title\n- **Files:** /path/to/file1, /path/to/file2\n- **Description:** What to implement\n- **Dependencies:** []\n- **Tests:** How to verify\n- **Risks:** What could go wrong"},{"language":"bash","snippet":"python3 scripts/adversarial_plan.py \\\n --spec spec.md \\\n --findings findings.json \\\n --dev-cmd \"pi --provider zai --model glm-5.2\" \\\n --review-cmd \"pi --provider deepseek --model deepseek-v4-pro\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: adversarial-plan\ndescription: \"Adversarial implementation planner. Takes a spec.md (from adversarial-spec) and optionally review findings, then produces a plan.md with ordered steps, dependencies, files, tests, and risks. Execute the result through focused per-step specs.\"\nversion: 1.0.0\nauthor: Hermes Agent\nlicense: 0BSD\nplatforms: [linux, macos]\nmetadata:\n hermes:\n tags: [adversarial, planning, implementation, plan, architecture]\n related_skills: [adversarial-spec, adversarial-code-loop, adversarial-code-review]\n---\n\n# Adversarial Plan\n\n**Spec → implementation plan.** Two-role adversarial pipeline that takes a spec.md (from\nadversarial-spec) and optionally review findings (from adversarial-code-review), and\nproduces a plan.md with ordered steps. To implement it with\nadversarial-code-loop, convert each step to a focused spec and run the steps in\ndependency order; adversarial-code-loop has no functional `--plan` mode.\n\n## Installation\n\nRequires the `adversarial-common` sibling repo (shared engine). One-line install:\n\ncurl -fsSL https://raw.githubusercontent.com/chpomob/adversarial-plan/main/scripts/install.sh | bash\n\nor, from an existing checkout:\n\nbash scripts/install.sh\n\nBoth place adversarial-plan and adversarial-common side by side under `~/.hermes/skills` (override the target with `$1` or `$HERMES_HOME`).\n\n## Workflow\n\n```text\nPREFLIGHT ──→ optional DEEP RESEARCH ──→ GIT SETUP\n │\n ├─ delegated success ──→ FINALIZE\n │\n └─ direct/fallback ──→ PLAN ──→ CHALLENGE\n │\n APPROVE + no findings ──────┤\n │\n otherwise ──→ REVISE ──→ VERIFY\n ↑ │\n └──────────┘ up to --max-loops\n │\n FINALIZE\n```\n\nThere is one CHALLENGE phase and no `CROSS_2` phase. A successful delegated\nrun bypasses PLAN/CHALLENGE/REVISE/VERIFY; a delegated fallback enters the\nnormal adversarial loop. FINALIZE squash-merges an approved plan unless\n`--no-merge` is set, or records a rejection marker when findings remain.\n\n## Prompt design\n\nThe CHALLENGE prompt references `plan.md` and `spec.md` on disk and instructs\nthe challenger to read them from the current working directory (the phase\nworkdir). No document text is embedded in the prompt; the provider runs with\nthe phase workdir as its cwd, so filesystem-capable providers inspect both\nfiles and the cumulative branch diff directly.\n\n## CLI\n\n