ox-plan

Whether to render at all is decided by the ox plan JSON (signals.material, guidance) + the user's confirmation / the plan.html config setting — not by this skill. Do not nag on trivial plans; honor the command's signal.

You author the page. ox injects the chrome. For any material plan, author a rich, self-contained interactive HTML page — that page IS the plan of record. ox plan save --file plan.html stores it verbatim in the ledger, derives plan.md from it, and computes the deterministic badges itself. ox plan render --file plan.html serves it with the ox chrome injected (append-only, between <!-- ox-chrome:start/end --> markers — never wrapped, never rewritten). Contract + quality bar: docs/specs/plan-authoring-html.md. Markdown-first remains only the quick path for small, low-stakes plans.

Orchestration (what this skill does)

flowchart TB
  RUN["Run ox plan enrich --json on the topic or draft"] --> DET["ox returns DETERMINISTIC badges + context bundle (0 LLM tokens)"]
  DET --> READ["AI coworker reads the context bundle: murmurs, sessions, decisions, ADRs, expert artifacts"]
  READ --> PAGE["AI coworker authors plan.html: tabs, inspectors, data-driven viz, dark design register"]
  READ --> JUDGE["Optional: AI coworker authors JUDGMENT badges, CITED-ONLY (aligns / conflicts / expert-perspective)"]
  PAGE --> SAVE["ox plan save --file plan.html  (ox derives plan.md + deterministic badges; --annotations optional)"]
  JUDGE --> SAVE
  SAVE --> GATE{"Render confirmed? (user asked OR plan.html recommend + confirm)"}
  GATE -->|"no"| DONE["Saved to ledger; report slug"]
  GATE -->|"yes"| RENDER["ox plan render --file plan.html --open  (ox injects chrome, opens review loop)"]

1. Get the deterministic signals + context bundle. Run:

   ox plan enrich --json --file <plan-file>   # or --topic "<subject>" before drafting
   

   This makes no LLM or network call. It returns a Result JSON:

   • annotations[] — deterministic, ox-computed badges: collision, prior-art, expert-routing. Each carries {section, kind:"deterministic", type, why, source_url, expert, files}. These are factual — keep them as-is, do not second-guess them. On save, ox computes these itself; you never re-author them.
   • context[] — the pre-retrieved bundle the AI coworker reasons over: {kind: murmur|session|decision|adr|commit|discussion, title, ref, snippet, score, author, when}.
   • signals — {collisions, prior_art, expert_routes, material}. material is ox's call on whether a render is worth recommending.

2. Author the page (the main event — see "Authoring the page" below). Build the rich, self-contained plan.html that carries the plan's whole argument: tabbed views, interactive inspectors, data-driven visualizations, the dark design register.

3. Optionally author JUDGMENT badges (ox does NO inference). Read the context[] bundle and produce judgment annotations — additive, passed via --annotations:

   • aligns / conflicts — does the plan agree or clash with a cited ADR, decision, or convention?
   • expert-perspective — the synthesized stance of the area expert.

   CITED-ONLY is non-negotiable. Every judgment badge MUST point at a real artifact from the bundle (ref / source_url): a specific ADR, decision doc, session, commit, or discussion. Rules:

   • Never invent an opinion, a quote, or a conflict. Precision over recall.
   • When the evidence is thin or ambiguous, degrade to a routing nudge — expert-perspective becomes "consult <name>" (naming the expert from annotations[].expert), NOT a fabricated stance. Putting words in a teammate's mouth is the one failure mode that destroys trust.
   • When unsure whether a conflict is real, downgrade to "Novel — no prior decision found," not a false conflicts.
   • Set kind:"judgment" on every badge you author so the chrome styles it distinctly from ox's deterministic ones (outlined vs. filled — ox owns that treatment).