Set the direction. Score the upgrades. Build faster.
WizardOZ is a powerful, architecture-aware upgrade machine for turning rough build assets into scored, queued, implementation-ready upgrades.
It can improve almost any build asset or structured system that can be clarified, scored, queued, or refined, from stage-zero custom ideas to advanced architecture plans already in motion.
WizardOZ works by surfacing high-leverage improvements, scoring them honestly with OzScore, and sifting through dozens, hundreds, or even 300+ upgrade candidates to refine only the most intentional, high-signal moves.
It queues what deserves action, defers what is useful but premature, and rejects what would make the build bigger instead of better.
Upgrade anything. Build faster and stronger. Ship cleaner.
As a Codex Skill, WizardOZ accelerates architecture-to-build execution after direction is set.
It turns rough build assets, including architecture notes, repo instructions, implementation plans, workflow logic, Markdown specs, and LLM build prompts, into sharper, safer, implementation-ready artifacts through Builder Passes, OzScore, Upgrade Queues, Auditor Passes, public-safe checks, and overbuild prevention.
WizardOZ is not a direction-setting system. It is the next pass after direction is clear enough to move.
Use it from stage-zero custom builds through more sophisticated setups when the next execution asset needs to become clearer, safer, and more actionable.
The public Codex Skill lives in skills/wizardoz/.
To use it in Codex, copy that folder to your Codex skills directory as wizardoz. A local install usually lives at ~/.codex/skills/wizardoz/. Then select WizardOZ, say Use WizardOZ, or use the natural-language alias oz this.
Minimal Skill context:
Use the repo docs only when you want deeper method detail or a controlled self-upgrade pass.
- Open START_HERE.md.
- Add your goal, rough input, constraints, and audience.
- Ask WizardOZ for OzScore and an Upgrade Queue when prioritization matters.
- Use the final copy/paste-ready artifact.
- Run a second pass only before public, client-facing, regulated, or high-impact use.
| Use case | Rough input | WizardOZ output |
|---|---|---|
| Architecture-to-build acceleration | System direction, architecture notes, or build intent | Implementation-ready build prompt with guardrails |
| Repo instruction hardening | Loose Codex, Claude, Cursor, or local LLM instructions | Scoped execution instructions with acceptance criteria |
| Implementation-plan upgrade | Messy task list or plan | Prioritized build plan with assumptions and next action |
| Spec-to-execution conversion | Markdown spec or planning doc | Build-ready artifact with risks and open questions |
| Workflow upgrade | Rough workflow logic | Ordered workflow with checks |
| Upgrade prioritization | Many possible improvements | OzScore snapshot and Upgrade Queue |
| Public-safe rewrite | Content meant to be shared | Safer version with private context and claims flagged |
| Handoff compression | Long context or bloated output | Shorter operator-ready context packet |
| Overbuild prevention | Scope-creepy prompt, plan, or architecture | Smaller next-pass artifact plus deferred/rejected ideas |
| Strategic pathfinding | Ambiguous next steps, roadmap choices, or architecture tradeoffs | Yellow Brick Road route comparison with gates, what not to do yet, and cleanest next action |
WizardOZ can also support deeper architecture review when a build needs more than normal prompt or spec upgrading.
For advanced AI builds, load only the relevant architecture reference pack. The packs cover minimal AI implementation patterns, agentic-workflow compatibility, local model/runtime tradeoffs, context engineering, evaluation gates, repo architecture, and frontier-inspired architecture cautions.
The core Skill stays compact. References are optional, source-grounded pattern packs loaded on demand.
When the best next move is unclear, use the Operator Judgment Lens to run a Forward Gate and choose proceed, plan_first, ask_one_question, defer, or reject.
Yellow Brick Road is WizardOZ's pathfinding protocol for Claude/Codex and WizardOZ-compatible workflows.
Use it when several next moves are plausible and choosing between them materially changes the outcome. It compares viable paths, projects only to the next real gate, names What Not To Do Yet, and ends with the Cleanest Next Action.
It prevents two common AI planning failures: answering too narrowly without downstream judgment, or inventing a giant speculative roadmap with fake precision.
Yellow Brick Road is a decision protocol. It does not add autonomy, runtime behavior, hidden memory, platform scope, or automatic execution.
For advanced build and architecture tasks, WizardOZ can end with one optional Innovation Tailpiece: a single non-obvious concept scored with OzScore, labeled with complexity/context cost, and held for approval before implementation.
If no idea clears the bar, WizardOZ should omit it.
OzScore is a prioritization tool, not fake science. It helps decide what to apply now, what to save for a later pass, what to bundle, what to defer, and what to reject.
| Score | Meaning | Default treatment |
|---|---|---|
1.0-1.9 |
Harmful, unsafe, misleading, or off-scope | reject |
2.0-2.9 |
Very low value or major distraction | reject |
3.0-3.9 |
Cosmetic, tiny, or low-leverage | reject / bundle_only |
4.0-4.9 |
Minor useful improvement | bundle_only / defer |
5.0-5.9 |
Housekeeping | defer / bundle_only |
6.0-6.9 |
Medium operational improvement | next_pass if aligned |
7.0-7.9 |
Strong backlog candidate | next_pass |
8.0-8.9 |
Very strong upgrade | next_pass or scoped implement_now |
9.0-9.4 |
Elite upgrade | next_pass, or scoped implement_now only if tiny and obvious |
9.5-10.0 |
Foundational / A-tier upgrade | implement_now if public-safe and scope-aligned |
Treat 9.5+ as the A-tier gate. Strong 9.0-9.4 ideas usually wait unless they are tiny support edits. If every upgrade scores 9+, the scoring model is broken. See scoring/ozscore.md for the compact method and scoring/calibration.md for representative examples.
| Status | Meaning | Use when |
|---|---|---|
implement_now |
Apply now | High value, public-safe, scope-aligned, low enough complexity |
next_pass |
Save for the next iteration | Strong idea, not needed for the first useful artifact |
defer |
Keep out of current scope | Valid idea, wrong timing or too large |
reject |
Do not do it | Unsafe, off-scope, generic, redundant, or low value |
bundle_only |
Do only with related cleanup | Too small to justify standalone attention |
Large lists are exploration. The Upgrade Queue is execution.
Use WizardOZ to run a batch upgrade pass.
Direction:
{{WHAT_WE_ARE_BUILDING_OR_IMPROVING}}
Current Build Asset:
{{PROMPT_SPEC_REPO_INSTRUCTIONS_WORKFLOW_OR_PLAN}}
Batch Size:
{{50 | 100 | 300}}
Constraints:
{{WHAT_SHOULD_NOT_CHANGE_OR_EXPAND}}
Please:
1. generate candidates across small-ticket, medium-ticket, high-ticket, and foundational tiers
2. score candidates with OzScore
3. dedupe overlapping ideas
4. create an Upgrade Queue
5. show only the top 10-20 in detail
6. summarize the rest by tier
7. reject or defer overbuilt, unsafe, redundant, or low-leverage ideas
8. produce the upgraded implementation-ready artifact
9. end with the next action
Do not show full scorecards unless requested.
| Need | Load |
|---|---|
| First run | START_HERE.md, or select WizardOZ if installed |
| General method | SKILL.md |
| Codex Skill | skills/wizardoz/SKILL.md |
| Copy/paste prompt modes | prompts/README.md |
| Scoring method | scoring/ozscore.md |
| Scoring examples | scoring/calibration.md |
| Safety checks | safety/safe-use.md |
| Full decision report | templates/improvement-report-template.md |
| Method proof | examples/architecture-to-build-example.md |
| Advanced architecture review | references/architecture/architecture-intelligence-map.md |
| Strategic pathfinding | references/architecture/yellow-brick-road.md |
The Codex Skill is a compact operator card. The repo is the public methodology. Do not load the whole repo unless the task needs it.
| Path | Job |
|---|---|
| README.md | Public front door and positioning |
| START_HERE.md | Fastest first-use prompt |
| SKILL.md | Human-readable WizardOZ behavior spec |
| skills/wizardoz/ | Public installable Codex Skill |
| assets/ | Lightweight README visuals |
| references/ | Optional architecture intelligence pattern packs |
| prompts/ | High-use copy/paste operating prompts |
| scoring/ | OzScore method, scorecard, and calibration |
| safety/safe-use.md | Safe paste, publish, assumptions, and review rules |
| templates/improvement-report-template.md | Reusable full upgrade report format |
| examples/ | Synthetic examples that demonstrate the method |
| SECURITY.md | Security and reporting guidance |
| ROADMAP.md | Short public roadmap and boundaries |
Warning
Do not paste secrets, API keys, credentials, PHI, patient data, client data, private company data, investor-sensitive information, proprietary implementation details, or raw chat history into an LLM. Use synthetic placeholders or public-safe summaries.
WizardOZ is a manual, Markdown-native public Skill. It does not add unrelated product scope, independent background execution, private implementation claims, payment language, design-specific files, hosting-specific files, adapters, large candidate dumps, or hidden memory.
WizardOZ improves structure, clarity, usefulness, and implementation-readiness. It does not guarantee factual, legal, medical, financial, tax, compliance, or security correctness. Human review is required for high-impact, regulated, public-facing, or client-facing outputs.