waypoint-codex 0.10.4 → 0.10.6

package/dist/src/core.js

@@ -382,6 +382,7 @@ export function doctorRepository(projectRoot) {
         "work-tracker",
         "docs-sync",
         "code-guide-audit",
+        "visual-explanations",
         "break-it-qa",
         "conversation-retrospective",
         "workspace-compress",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
   "license": "MIT",
   "type": "module",

package/templates/.agents/skills/visual-explanations/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: visual-explanations
+description: Create generated images or annotated screenshots when a visual artifact would explain a concept, design, flow, comparison, or observed UI state more clearly than prose alone. Use for concept cards, visual summaries, mockups, labeled screenshots, timelines, comparisons, and other explanation-first visuals. Do not use this skill when a simple Mermaid diagram in chat is sufficient.
+---
+
+# Visual Explanations
+
+Use this skill when the explanation itself should become a visual artifact.
+
+Mermaid does not need this skill. If a Mermaid diagram in chat is enough, use Mermaid directly and stop here.
+
+## Step 1: Pick The Right Visual
+
+- Use Mermaid directly for flows, architecture, plans, state machines, and other text-native diagrams.
+- Use an annotated screenshot when you need to explain a real UI state, call out a specific element, or show evidence from an actual screen.
+- Use a generated image when Mermaid is too rigid and the explanation needs custom layout, stronger composition, a side-by-side comparison, a concept card, a rough mockup, or a more designed visual summary.
+
+Do not make an image just because you can. Use the lightest visual that makes the explanation clearer.
+
+## Step 2: Define The Message First
+
+Before drawing anything, write down:
+
+- the one main point the visual should communicate
+- which audience it is for
+- whether it is evidence, explanation, or a conceptual sketch
+
+One image should usually explain one idea.
+
+## Step 3: Gather Source Material
+
+For annotated screenshots:
+
+- capture the real UI state first
+- keep the untouched source screenshot available until the annotated version is verified
+- identify the exact element or area that the callout should reference
+
+For generated images:
+
+- list the minimum facts, labels, or comparison points that must appear
+- sketch the rough composition in words before building it
+- prefer using the repo's existing facts or screenshots over inventing fake details
+
+If the image is conceptual rather than a faithful representation of current UI, label it clearly in the visual or in the accompanying text.
+
+## Step 4: Build With Simple, Deterministic Tools
+
+Prefer straightforward local approaches:
+
+- SVG for cards, timelines, comparisons, and lightweight custom layouts
+- HTML/CSS rendered to an image when layout fidelity matters
+- image-editing tools such as ImageMagick or Pillow for callouts, arrows, labels, crops, and overlays
+- browser screenshots when the source needs to be a real page or app state
+
+Do not over-engineer the rendering path. Favor the most reliable approach available in the current environment.
+
+## Step 5: Design For Clarity
+
+- highlight the exact thing you are explaining
+- keep callout text short
+- use large, legible type
+- use strong contrast
+- leave enough whitespace so the image still scans quickly
+- prefer one or two callouts over covering the image in labels
+- crop or frame the relevant area when the full screen adds noise
+
+Good visuals feel obvious at a glance.
+
+## Step 6: Verify The Output Yourself
+
+Before sending the image:
+
+- open or inspect the rendered result
+- confirm it is not blank, clipped, washed out, or too tiny to read
+- confirm arrows and labels point at the intended target
+- confirm the image still makes sense without a long paragraph underneath it
+
+Do not trust the generation step blindly.
+
+## Step 7: Deliver Cleanly
+
+- show the image directly in chat
+- add one to three sentences that explain what the user should notice
+- prefer a single strong visual over a pile of mediocre ones
+
+If the artifact is only for the current conversation, store it in a temp or scratch location. If the user wants a durable asset in the repo, place it in the repo's normal docs or asset structure instead of inventing a new convention.

package/templates/.agents/skills/visual-explanations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Visual Explanations"
+  short_description: "Create generated images and annotated screenshots"
+  default_prompt: "Use this skill to create a generated image or annotated screenshot when a visual artifact would explain the point more clearly than prose alone. Prefer Mermaid directly when a simple in-chat diagram is enough."

package/templates/.codex/agents/code-health-reviewer.toml

@@ -19,6 +19,7 @@ Find code that works but should be refactored. You're not looking for bugs (`cod
 
 Critical rules:
 You set the standard. Don't learn quality standards from existing code - the codebase may already be degraded. Apply good engineering judgment regardless of what exists.
+- Read full files, not fragments.
 
 Explore what exists. Search for existing helpers, utilities, and patterns that could be reused instead of duplicated.
 
@@ -69,6 +70,10 @@ Focus on:
 - their imports
 - one level out when needed to validate a pattern
 
+Review method:
+- For each file you analyze, read the full file before forming a maintainability judgment.
+- Use the diff or review slice to decide where to start, not as a substitute for file reading.
+
 Output:
 Return findings directly as structured text.
 

package/templates/.gitignore.snippet

@@ -7,6 +7,7 @@
 .agents/skills/work-tracker/
 .agents/skills/docs-sync/
 .agents/skills/code-guide-audit/
+.agents/skills/visual-explanations/
 .agents/skills/break-it-qa/
 .agents/skills/frontend-context-interview/
 .agents/skills/backend-context-interview/

package/templates/.waypoint/agent-operating-manual.md

@@ -57,6 +57,8 @@ If something important lives only in your head or in the chat transcript, the re
 - When browser work is part of reproduction or verification, send screenshots of the relevant UI states to the user so they can visually confirm what you observed.
 - Capture the states that matter, such as the broken state, the fixed state, or an important intermediate state that explains the issue.
 - If the current environment cannot provide screenshots, state that explicitly instead of silently omitting visual evidence.
+- When an explanation would be clearer visually, prefer Mermaid diagrams directly in chat for flows, architecture, state, and plans instead of over-explaining in prose.
+- Use `visual-explanations` when the explanation needs a richer generated image or an annotated screenshot rather than only text or Mermaid.
 
 ## Execution autonomy
 
@@ -95,6 +97,7 @@ Do not document every trivial implementation detail. Document the non-obvious, d
 - `work-tracker` when large multi-step work needs durable progress tracking in `.waypoint/track/`
 - `docs-sync` when routed docs may be stale, missing, or inconsistent with the codebase
 - `code-guide-audit` when a specific feature or file set needs a targeted coding-guide compliance check
+- `visual-explanations` when a generated image or annotated screenshot would explain the work more clearly than prose alone; Mermaid diagrams do not need a skill
 - `conversation-retrospective` after major completed work pieces so the active conversation is distilled into durable memory, user feedback and errors are preserved, exercised skills are improved, and real new-skill candidates are recorded
 - `break-it-qa` when a browser-facing feature should be attacked with invalid inputs, refreshes, repeated clicks, wrong action order, or other adversarial manual QA
 - `frontend-ship-audit` and `backend-ship-audit` only when the user explicitly requests a ship-readiness audit; do not trigger them autonomously as part of the default Waypoint workflow

package/templates/managed-agents-block.md

@@ -69,6 +69,7 @@ Prefer existing persisted context over re-interviewing the user.
 If the user approves a plan or explicitly tells you to proceed, treat that as authorization to execute the work end to end. Do not stop mid-implementation for incremental permission unless a real blocker, hidden-risk decision, or explicit user redirect requires a pause.
 When work is in flight elsewhere — reviewer agents, subagents, CI, automated review, external jobs, or other waiting periods — wait as long as required. There is no fixed waiting limit, and slowness alone is not a reason to interrupt or abandon the work.
 When using a browser to reproduce a bug, verify behavior, or confirm that a fix works, send the user screenshots of the relevant UI states so they can see the evidence directly. If screenshots are not possible in the current environment, say so explicitly.
+When an explanation would be clearer as a visual than as prose, bias toward visual artifacts. Prefer Mermaid diagrams directly in chat for flows, architecture, state, and plans; use `visual-explanations` for richer generated images and for annotated screenshots that call out concrete UI states.
 
 Working rules:
 - Keep `.waypoint/WORKSPACE.md` current as the live execution state, with timestamped new or materially revised entries in multi-topic sections
@@ -78,6 +79,7 @@ Working rules:
 - Use `work-tracker` when a long-running implementation, remediation, or verification campaign needs durable progress tracking
 - Use `docs-sync` when the docs may be stale or a change altered shipped behavior, contracts, routes, or commands
 - Use `code-guide-audit` for a targeted coding-guide compliance pass on a specific feature, file set, or change slice
+- Use `visual-explanations` when a generated image or annotated screenshot would explain the work more clearly than prose alone; Mermaid diagrams can be written directly in chat without invoking a skill
 - Use `conversation-retrospective` after major completed work pieces to preserve durable learnings, capture user feedback and errors, improve any skills that were exercised, and record real new-skill candidates
 - Do not invoke `break-it-qa`, `frontend-ship-audit`, or `backend-ship-audit` yourself from the managed AGENTS block workflow; they are user-facing skills for explicit human-requested QA or ship-readiness audits, not default agent steps
 - Before presenting a non-trivial implementation plan to the user, run `plan-reviewer` and iterate on the plan until it has no meaningful review findings left