waypoint-codex 0.10.3 → 0.10.5

package/README.md

@@ -161,7 +161,7 @@ The intended workflow is closeout-based: run `code-reviewer` before considering
 
 For planning work, run `plan-reviewer` before presenting a non-trivial implementation plan to the user and iterate until it has no meaningful review findings left.
 
-When the user approves a reviewed plan or explicitly says to proceed, the intended Waypoint behavior is autonomous execution: keep going through implementation, verification, review, and repo-memory updates unless a real blocker or materially risky unresolved decision requires a pause. If reviewers, subagents, CI, or other external work are still running, Waypoint should wait as long as necessary rather than interrupting them for speed.
+When the user approves a reviewed plan or explicitly says to proceed, the intended Waypoint behavior is autonomous execution: keep going through implementation, verification, review, and repo-memory updates unless a real blocker or materially risky unresolved decision requires a pause. If reviewers, subagents, CI, or other external work are still running, Waypoint should wait as long as necessary rather than interrupting them for speed. For PR work, placeholder automated-review states like CodeRabbit's "review in progress" do not count as a completed review.
 
 When browser-based reproduction or verification is part of the work, Waypoint should also send screenshots of the relevant UI states so the user can see the evidence directly.
 

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.3",
+  "version": "0.10.5",
   "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
   "license": "MIT",
   "type": "module",

package/templates/.agents/skills/pr-review/SKILL.md

@@ -12,6 +12,9 @@ Use this skill to drive the PR through review instead of treating review as a on
 - Check the PR's current review and CI status.
 - If CI is red or pending, inspect the failed check logs before triaging review comments so you do not chase comment fixes while a separate blocker is breaking the branch.
 - If automated review is still running, wait for it to finish instead of racing it.
+- Treat placeholder messages such as CodeRabbit's "review in progress" as unfinished state, not as a meaningful review result.
+- If an automated reviewer like CodeRabbit is still pending, in progress, or has not reached a green/completed check state yet, keep waiting before you conclude there are no findings.
+- Once the automated reviewer check turns green/completed, reread the review comments and threads because the real findings may only appear after the placeholder state clears.
 - If comments are still arriving, do not prematurely declare the loop complete.
 - For stacked or non-`main` PRs, explicitly compare the PR head against its base branch and make sure later fixes on the base branch have actually been merged or rebased forward. Do not assume a sibling/base PR fix is already present in the dependent PR.
 - Keep waiting as long as required. Do not interrupt or abandon the review loop just because CI, reviewers, or automated checks are taking a long time.
@@ -42,10 +45,12 @@ Do not leave comments unanswered.
 - push follow-up commit(s)
 - after pushing, return to the PR and wait for the next round of CI, automated review, and human review comments before deciding whether the loop is complete
 - if CI or review is still in flight, keep waiting instead of assuming your last push ended the process
+- before declaring the PR clear or ready, make sure the required Waypoint reviewer agents for this slice have actually run and that their real findings, if any, were handled
 
 Stay in the loop until no new meaningful issues remain.
 Never cut the loop short by forcing a partial return from still-running review or verification systems.
 The loop is not complete while any meaningful review thread still lacks an inline response.
+The loop is also not complete if required Waypoint reviewer-agent passes for the current slice have not been run yet.
 
 ## Step 5: Close With A Crisp State Summary
 

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/.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
@@ -132,6 +135,7 @@ Use reviewer agents before considering the work complete, not just as a reflex a
 6. Do not call the work finished before you read the required reviewer results.
 7. Wait for reviewer outputs even if that requires repeated or long waits. Do not interrupt them just because they are still running.
 8. Fix real findings, rerun the relevant verification, update workspace/docs if needed, and make a follow-up commit when fixes change the repo.
+9. Do not call a PR clear, ready, or done until the required reviewer-agent passes for the current slice have actually run.
 
 ## Quality bar
 

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