waypoint-codex 0.15.0 → 0.17.0

package/README.md

@@ -1,53 +1,161 @@
 # Waypoint
 
-Waypoint is a collaborator-first repository operating system for Codex.
+Waypoint makes Codex better by default for real software work.
 
-It exists to solve two problems at the same time:
+Codex is already powerful. The problem is that most users still have to teach it
+the same things over and over:
 
-- the next agent should be able to pick up the repo with real context
-- the current agent should still feel smart, direct, and useful
+- ask better questions before coding
+- plan thoroughly instead of making hidden assumptions
+- follow stronger coding standards
+- review the result seriously before merge
+- verify the work instead of guessing
+- learn from corrections instead of repeating the same mistakes
 
-## What Waypoint is for
+Waypoint installs those defaults into a repo so you can spend less time
+prompting and more time building.
 
-Waypoint is built for repos where continuity and collaboration both matter.
+## Install and upgrade
 
-It gives the next session real context and keeps the current session clear and useful.
+Waypoint requires Node 20+.
+
+Install globally:
+
+```bash
+npm install -g waypoint-codex
+```
+
+Or try it without a global install:
+
+```bash
+npx waypoint-codex@latest --help
+```
+
+Inside the repo you want to prepare for Codex:
+
+```bash
+waypoint init
+waypoint doctor
+```
+
+Keep an existing repo up to date:
+
+```bash
+waypoint upgrade
+waypoint doctor
+```
+
+## What gets better
+
+With Waypoint, Codex should become better at:
+
+- understanding the product and technical context before it starts
+- planning work in enough detail to avoid avoidable mistakes
+- writing code that matches the codebase and holds up in production
+- staying on track during larger or longer-running tasks
+- reviewing and verifying its own work before calling it done
+- improving its own guidance when the user corrects it
+
+## Why Waypoint exists
+
+Waypoint is for people using Codex on real apps and real codebases, not just
+tiny one-off edits.
+
+It exists because most Codex users should not have to manually remember every
+best practice, every guardrail, every planning question, and every review step
+for every task.
+
+Waypoint packages that expertise into the repo so Codex starts from a much
+better default.
+
+## What Waypoint adds
+
+### 1. Better default behavior
+
+Waypoint gives Codex stronger repo guidance through the generated contract,
+operating manual, core behavior files, and repo-local instructions.
+
+That means the agent is pushed to:
 
-Waypoint adds:
+- investigate before narrating status
+- ask better questions about the product, architecture, and constraints
+- explain what it found in a clear way
+- verify what it changed
+- leave the repo clearer than it found it
 
-- explicit repo-local memory
-- strong default collaboration
-- optional structured workflows when the task actually needs them
+### 2. Better planning
 
-The default mode centers a simple loop:
+Waypoint ships a thorough planning workflow for work that should not start from
+guesswork.
 
-- investigate the issue
-- explain what is happening
-- fix what you can
-- verify it
-- leave the repo clearer than you found it
+That workflow pushes the agent to:
 
-## Core idea
+- interview the user until the real requirements are clear
+- produce a detailed plan before implementation
+- challenge that plan with a reviewer agent
+- tighten the plan before coding starts
 
-Waypoint keeps the good parts of a repo operating system:
+The goal is simple: fewer assumptions, fewer surprises, and a much better shot
+at one-shot execution.
 
-- durable context in files
-- explicit startup and routing
+### 3. Better code quality
+
+Waypoint does not assume Codex will naturally write production-quality code by
+default.
+
+It adds guardrails that push the agent toward:
+
+- stronger coding standards
+- better fit with the existing codebase
+- fewer lazy shortcuts
+- fewer architecture mistakes
+- fewer duplicated or premature abstractions
+
+Reviewer agents and audit workflows add another pass before merge when the work
+needs it.
+
+### 4. Better end-to-end execution
+
+Waypoint also helps Codex follow through on bigger tasks.
+
+It includes workflows for:
+
+- long-running task tracking
+- ship-readiness audits
+- merge-ready ownership
+- deliberate review passes before PR or merge
+
+This helps the agent keep moving until the work is actually ready, not just
+"probably done."
+
+### 5. Self-improvement
+
+Waypoint treats user corrections as product input, not just conversation noise.
+
+When the user corrects behavior, rules, or workflow, the agent is pushed to
+update the right durable files so the same issue is less likely to happen
+again.
+
+That includes:
+
+- user-scoped guidance
+- project-scoped guidance
 - repo-local skills
-- reusable reviewer agents
-- generated context for continuity
+- retrospectives that turn friction from the current conversation into lasting
+  improvements
 
-Those systems work best when they stay explicit and well-scoped.
+### 6. Better continuity
 
-Structured workflows belong in tools:
+Waypoint gives Codex explicit continuity artifacts so the next session does not
+start half-blind.
 
-- review loops
-- ship-readiness passes
-- trackers
-- retrospectives
-- pre-PR hygiene
+That includes:
 
-That keeps the default conversation focused on diagnosis, progress, and verification.
+- a generated docs index that tells the agent which docs exist and when to read
+  them
+- a live workspace file that records what is going on right now
+- a generated recent thread file that carries the most important prior
+  conversation context forward
 
 ## What Waypoint sets up
 
@@ -57,32 +165,43 @@ Waypoint scaffolds a Codex-friendly repo around a few core pieces:
 - `.waypoint/WORKSPACE.md` for live operational state
 - `.waypoint/docs/` for long-lived project docs
 - `.waypoint/plans/` for durable plan documents
-- `.waypoint/DOCS_INDEX.md` for docs and plans routing
+- `.waypoint/DOCS_INDEX.md` for docs and plans routing, so the agent knows what
+  to read and when
 - `.waypoint/context/` for generated startup context
-- `.waypoint/track/` for long-running work that truly needs durable progress tracking
+- `.waypoint/context/RECENT_THREAD.md` for compact continuity from the previous
+  conversation
+- `.waypoint/track/` for long-running work that truly needs durable progress
+  tracking
 - `.agents/skills/` for optional structured workflows
 - `.codex/` for optional reviewer and helper agents
 
-The philosophy is simple:
+By default, Waypoint routes docs from `.waypoint/docs/` and plans from
+`.waypoint/plans/`.
+If your repo keeps routable docs elsewhere, you can add more explicit roots in
+`.waypoint/config.toml` with `docs_dirs` and `plans_dirs`.
+Waypoint scans each configured root recursively and only includes Markdown files
+with valid Waypoint frontmatter.
 
-- less hidden runtime magic
-- more explicit repo-local state
-- stronger default collaboration
-- investigation before status narration
-- structured workflows that stay in their own tools
+The continuity story matters:
 
-By default, Waypoint routes docs from `.waypoint/docs/` and plans from `.waypoint/plans/`.
-If your repo keeps routable docs elsewhere, you can add more explicit roots in `.waypoint/config.toml` with `docs_dirs` and `plans_dirs`.
-Waypoint scans each configured root recursively and only includes Markdown files with valid Waypoint frontmatter.
+- `.waypoint/DOCS_INDEX.md` helps the agent find the right docs before work
+- `.waypoint/WORKSPACE.md` helps the next session understand what is in flight
+- `.waypoint/context/RECENT_THREAD.md` helps the agent retain the important
+  parts of the previous conversation
 
 ## Best fit
 
 Waypoint is most useful when you want:
 
-- multi-session continuity in a real repo
-- clear separation between cross-project user guidance and repo-specific guidance
-- a cleaner default collaboration style
-- optional planning, review, QA, and release workflows that travel with the project
+- a better default Codex workflow in a real repo
+- stronger planning before implementation starts
+- stronger coding standards and review guardrails
+- better follow-through on long tasks
+- a personal workflow that can live in almost any repo without becoming a team
+  rollout
+
+Waypoint is primarily an individual tool.
+Most of its repo-local state is meant to stay personal and local by default.
 
 If you only use Codex for tiny one-off edits, Waypoint is probably unnecessary.
 
@@ -154,7 +273,37 @@ Waypoint ships a strong default skill pack for real coding work:
 These are repo-local, so the workflow travels with the project.
 
 The important design choice is that they stay out of the always-on voice.
-Each skill explains what it is for and when it should be invoked.
+Each skill exists to improve the result when the task needs more rigor, without
+turning every normal interaction into a heavy process.
+
+## How to get full value
+
+Installing Waypoint improves Codex's defaults right away, but the full workflow
+is not completely automatic.
+
+Some of Waypoint's biggest advantages come from user-invoked skills that should
+be used deliberately when the moment calls for them.
+
+The most important ones are:
+
+- `code-guide-audit` when you want a code quality pass against your repo's
+  standards and working rules
+- `backend-ship-audit` when backend work needs a deeper production-readiness
+  pass
+- `frontend-ship-audit` when frontend work needs a deeper product, UX, and ship
+  readiness pass
+- `docs-sync` when the implementation changed and the repo docs should be
+  brought back in sync
+- `conversation-retrospective` when the conversation exposed friction,
+  corrections, or workflow problems that should become durable improvements
+- `merge-ready-owner` when you want the agent to own the task all the way to a
+  merge-ready result with stronger autonomy
+
+The practical rule is:
+
+- install Waypoint for better defaults
+- invoke the higher-rigor skills when you want a stronger planning, audit,
+  review, docs, or closeout pass
 
 ## Reviewer agents
 
@@ -172,24 +321,13 @@ Waypoint is opinionated, but explicit:
 
 - state lives in files you can inspect
 - docs routing is generated, not guessed from memory
-- the default contract tells the agent to investigate first
+- the default contract tells the agent to ask better questions and investigate
+  first
 - durable guidance is separated into user-scoped AGENTS, project-scoped AGENTS, live workspace state, project docs, and plan docs
 - visual explanation stays lightweight: Mermaid in chat and screenshots from real UI inspection
 - heavier workflows stay in optional skills
-
-## Install
-
-Waypoint requires Node 20+.
-
-```bash
-npm install -g waypoint-codex
-```
-
-Or run it without a global install:
-
-```bash
-npx waypoint-codex@latest --help
-```
+- user corrections are supposed to improve the system instead of disappearing
+  into chat history
 
 ## Main commands
 

package/dist/src/core.js

@@ -347,6 +347,7 @@ export function initRepository(projectRoot, options) {
         "docs/README.md",
         "docs/code-guide.md",
         "docs/legacy-import",
+        ".codex/agents/coding-agent.toml",
         ".agents/skills/error-audit",
         ".agents/skills/observability-audit",
         ".agents/skills/ux-states-audit",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "waypoint-codex",
-  "version": "0.15.0",
-  "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
+  "version": "0.17.0",
+  "description": "Make Codex better by default with stronger planning, code quality, reviews, tracking, and repo guidance.",
   "license": "MIT",
   "type": "module",
   "bin": {

package/templates/.agents/skills/merge-ready-owner/SKILL.md

@@ -36,6 +36,11 @@ When the product surface makes it practical, extend done to include:
 
 Do not stop at "the code compiles" or "the first push is up."
 
+During the loop, keep live execution state current:
+
+- update `WORKSPACE.md` as milestones, blockers, verification state, and next steps change
+- if a tracker exists or the work has become tracker-worthy, update the tracker during the work instead of reconstructing it later
+
 ## Step 1: Reconfirm The Scope And Ownership Mode
 
 - Make sure the plan is already approved or the user explicitly said to proceed.
@@ -64,7 +69,7 @@ For bugs, prefer reproducing the problem first, then fixing it, then proving the
 
 Use the repo's existing skills and reviewer agents instead of inventing a parallel process.
 
-- Use `work-tracker` when the work or verification checklist is too large for `WORKSPACE.md`.
+- Use `work-tracker` early when the work becomes non-trivial, multi-step, review-heavy, or checklist-driven enough that `WORKSPACE.md` alone will stop being a good live record.
 - Use `docs-sync` when shipped behavior, routes, contracts, or commands changed materially.
 - Use `pre-pr-hygiene` before pushing or opening/updating a PR when the change surface is substantial.
 - Use `pr-review` once active PR review or automated review has started.
@@ -75,8 +80,10 @@ If the repo ships reviewer agents under `.codex/agents/`, use them in the closeo
 - run `code-reviewer` for every non-trivial implementation slice before declaring the work clear
 - run `code-health-reviewer` when the change is medium or large, especially when it adds structure, duplicates logic, or introduces new abstractions
 - launch them in parallel when both apply
+- use them at meaningful milestones, not only at the very end: after substantial implementation chunks, before opening or materially updating a PR, after fixing substantial findings, and before final closeout
 - treat them as fresh closeout passes, not as optional decoration
-- if meaningful fixes follow from their findings, rerun the most relevant verification and, when warranted, rerun fresh reviewer passes instead of trusting stale results
+- if either reviewer finds anything more serious than obvious optional polish, fix those findings, rerun the most relevant verification, and run fresh reviewer passes instead of trusting stale results
+- keep iterating until the remaining reviewer feedback is only nitpicks or none
 
 If those reviewer agents are not present in the repo, do the equivalent closeout thinking locally and continue instead of blocking on missing helpers.
 
@@ -96,6 +103,7 @@ If an existing repo-local skill clearly matches the verification surface, use it
 - Run builds, lint, migrations, or focused smoke tests when they are part of the real risk surface.
 - Fix failing checks before pushing unless the user explicitly accepts an exception.
 - For user-facing flows, do at least one realistic manual or UI-driven pass beyond pure unit coverage.
+- Update `WORKSPACE.md` and any active tracker with the current verification state before moving on.
 
 Do not push a branch that still obviously fails its own touched-surface checks.
 
@@ -110,6 +118,8 @@ When the repo uses PRs:
 
 If the repo does not use PRs, keep moving through the equivalent review and handoff workflow instead of forcing PR-shaped steps.
 
+Before opening or materially updating the PR on non-trivial work, strongly prefer a fresh reviewer-agent pass when those agents are available.
+
 ## Step 8: Babysit The PR Instead Of Dropping It
 
 When the repo uses PRs, CI, or preview environments:
@@ -130,6 +140,7 @@ Once review starts:
 - fix valid findings
 - reply inline where the workflow supports inline reply
 - rerun the relevant verification after review-driven fixes
+- if the fixes were meaningful, run fresh reviewer-agent passes before you call the work clear when those agents are available
 
 Do not leave comments unanswered just because the code changed.
 
@@ -161,12 +172,13 @@ Keep the handoff plain and direct. The point of this skill is to reduce the user
 ## Gotchas
 
 - Do not mistake planning approval for permission to stop at implementation; this skill owns the full closeout.
+- Do not let `WORKSPACE.md` or an active tracker fall behind reality while the work is in flight.
 - Do not rely only on automated tests when the risky surface is interactive.
 - Do not let stale previews, staging selectors, old PR branches, or half-deployed environments quietly poison verification.
 - Do not treat CI failures, review comments, or rollout gates as outside the task once the user asked for full ownership.
 - Do not declare success while known meaningful review findings or failing checks still exist.
 - Do not confuse a reusable test harness or scripted UI test with the final walkthrough artifact; the artifact should show the real verified surface when practical.
-- Do not forget the reviewer-agent loop when `code-reviewer` and `code-health-reviewer` are available. They are part of the closeout signal, not an afterthought.
+- Do not forget the reviewer-agent loop when `code-reviewer` and `code-health-reviewer` are available. They are part of the closeout signal, not an afterthought, and serious findings should reopen the fix-and-review cycle.
 
 ## Keep This Skill Sharp
 

package/templates/.agents/skills/work-tracker/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: work-tracker
-description: Create or maintain a durable tracker under `.waypoint/track/` for large multi-step work. Use when implementation will span multiple sessions, when an audit or review produces many fix items, when verification has a long checklist, or whenever `WORKSPACE.md` would become too detailed if it tried to hold the whole execution log.
+description: Create or maintain a durable tracker under `.waypoint/track/` for any non-trivial workstream that needs ongoing execution state. Use when work has multiple steps, meaningful verification, review follow-ups, milestone checkpoints, or any real chance that `WORKSPACE.md` alone will stop being enough as the work evolves.
 ---
 
 # Work Tracker
 
-Use this skill when the work is too large, too long-running, or too itemized to live safely in `WORKSPACE.md`.
+Use this skill when the work has enough moving parts that the next state should not live only in chat or in a few workspace bullets.
 
 This skill owns the execution tracker layer:
 
@@ -34,12 +34,15 @@ Before tracking:
 
 Create or update a tracker when any of these are true:
 
+- the work is non-trivial and will unfold across multiple meaningful steps
 - the work will likely span multiple sessions
 - there are many actionable items to implement
 - an audit, QA pass, or review produced a remediation campaign
 - verification requires a substantial checklist
+- the work has milestone checkpoints, PR stages, or repeated fix-and-verify loops
 - `WORKSPACE.md` would become noisy if it carried all the detail
 
+When in doubt, prefer creating or updating the tracker for non-trivial work instead of hoping the workspace alone will stay enough.
 Small, single-shot work does not need a tracker.
 
 ## Step 1: Choose The Tracker File
@@ -85,7 +88,7 @@ A good tracker usually includes:
 - `Decisions`
 - `Notes`
 
-Use checklists when there are many concrete items. Use timestamped bullets for materially revised state.
+Use `- [ ]` checkboxes when there are many concrete tasks to track. Use status-style entries when the work is better expressed as phase/state updates than as a task list. Use timestamped bullets for materially revised state.
 
 ## Step 4: Link It From The Workspace
 
@@ -97,8 +100,9 @@ The tracker should answer "what exactly is happening across the whole workstream
 ## Step 5: Maintain It During Execution
 
 - Update `last_updated` whenever you materially change the tracker.
-- Mark completed items done instead of deleting the record.
+- Keep task lists or status entries current instead of deleting history. Mark completed checkbox items as `- [x]`, and update status-style entries when the phase or state changes.
 - Add blockers, new tasks, and verification status as the work evolves.
+- Update the tracker during the work, not only at the end. If a milestone, blocker, review round, or verification result changed reality, the tracker should already reflect it.
 - When the workstream finishes, set `status: done` or `status: archived`.
 
 Do not let the tracker become fiction. It must match reality.
@@ -118,6 +122,7 @@ When you create or update a tracker, report:
 ## Gotchas
 
 - Do not create a new tracker if a relevant active tracker already exists for the same workstream.
+- Do not wait until final handoff to start the tracker if the work has already become multi-step, review-heavy, or hard to summarize from memory.
 - Do not let the tracker become fiction. Completed items, blockers, and verification state should match reality.
 - Do not stuff durable architecture or debugging knowledge into the tracker if it belongs in `.waypoint/docs/`.
 - Do not leave `WORKSPACE.md` carrying the full execution log after a tracker exists.

package/templates/.codex/config.toml

@@ -9,10 +9,6 @@ max_threads = 24
 description = "Read-only background reviewer for post-commit maintainability drift, dead code, duplication, and refactoring opportunities worth fixing."
 config_file = "agents/code-health-reviewer.toml"
 
-[agents."coding-agent"]
-description = "Optional workspace-writing implementation helper for bounded coding tasks that should follow the code guide, verify changes, and hand the slice back cleanly."
-config_file = "agents/coding-agent.toml"
-
 [agents."code-reviewer"]
 description = "Read-only background reviewer for post-commit bugs, regressions, and integration mistakes."
 config_file = "agents/code-reviewer.toml"

package/templates/.gitignore.snippet

@@ -1,6 +1,5 @@
 # Waypoint state
 .codex/config.toml
-.codex/agents/coding-agent.toml
 .codex/agents/code-reviewer.toml
 .codex/agents/code-health-reviewer.toml
 .codex/agents/plan-reviewer.toml

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

@@ -57,18 +57,22 @@ If something important lives only in your head or in the chat transcript, the re
 - Before making meaningful frontend or backend decisions, inspect the available user-scoped and project-scoped `AGENTS.md` guidance. If the task depends on frontend or backend context that is missing from the project-scoped guidance and routed docs, use the corresponding `*-context-interview` skill to fill that gap instead of guessing.
 - Update the user-scoped `AGENTS.md` when you learn a durable preference, workflow rule, or default that should apply across projects and your environment allows you to edit it.
 - Update the project-scoped repo `AGENTS.md` when you learn durable repo truth, project constraints, or stable project-specific collaboration rules.
-- Update `.waypoint/WORKSPACE.md` as live execution state when progress meaningfully changes. In multi-topic sections, prefix new or materially revised bullets with a local timestamp like `[2026-03-06 20:10 PST]`.
-- For large multi-step work that is likely to span sessions or needs durable progress state, create or update a tracker in `.waypoint/track/`, keep detailed execution state there, and point at it from `## Active Trackers` in `.waypoint/WORKSPACE.md`.
+- Treat `.waypoint/WORKSPACE.md` as mandatory live execution state, not end-of-task paperwork.
+- Update `.waypoint/WORKSPACE.md` during the work whenever the active goal, phase, next step, blocker, verification state, or review state materially changes. In multi-topic sections, prefix new or materially revised bullets with a local timestamp like `[2026-03-06 20:10 PST]`.
+- Do not wait until final handoff to update workspace state. If the work took enough effort that the next agent would benefit from a current snapshot, the workspace should already say so.
+- For any non-trivial multi-step work, any work likely to span sessions, any work with a meaningful checklist, or any workstream that has already accumulated review/QA follow-ups, create or update a tracker in `.waypoint/track/`, keep detailed execution state there during the work, and point at it from `## Active Trackers` in `.waypoint/WORKSPACE.md`.
+- If a tracker exists for the workstream, maintain it as the work evolves instead of updating it only at the end.
 - Update `.waypoint/docs/` when durable project knowledge changes, update `.waypoint/plans/` when durable plans change, and refresh each changed routable doc's `last_updated` field.
 - Rebuild `.waypoint/DOCS_INDEX.md` whenever routable docs change.
 - Rebuild `.waypoint/TRACKS_INDEX.md` whenever tracker files change.
-- Keep most work in the main agent. Use skills, trackers, `coding-agent`, or reviewer agents when they clearly add leverage, not as default ceremony.
+- Keep most work in the main agent. Use skills, trackers, and reviewer agents when they clearly add leverage, not as default ceremony.
 - Let skills carry their own invocation guidance. The always-on contract should only keep the high-level rule: use repo-local skills deliberately when they help the current task.
-- When spawning `coding-agent`, default to `fork_context: false` and choose the model/reasoning pair that fits the slice. Use stronger models when the delegated slice is user-visible, architecturally important, or hard to unwind.
-- When spawning reviewer agents or other non-`coding-agent` subagents, explicitly set `fork_context: false` and choose the model/reasoning pair that matches the risk and importance of the second pass.
-- Use the repo-local skills and reviewer agents deliberately, not reflexively.
+- Use the repo-local skills and reviewer agents deliberately, but do not underuse them on work that is expensive to get wrong.
+- When spawning reviewer agents or other subagents, explicitly set `fork_context: false` and choose the model/reasoning pair that matches the risk and importance of the second pass.
+- For non-trivial work, strongly prefer reviewer-agent passes between major implementation milestones, before opening or updating a PR, after fixing substantial findings, and before final closeout when the environment allows those agents to run.
 - If you created a PR earlier in the current session and need to push more work, first confirm that PR is still open. If it is closed, create a fresh branch from `origin/main` and open a fresh PR instead of pushing more commits to the old PR branch.
 - Treat reviewer agents as one-shot workers: once a reviewer returns findings, read the result and close it. If another review pass is needed later, spawn a fresh reviewer instead of reusing the same thread.
+- If `code-reviewer` or `code-health-reviewer` surface anything more serious than optional polish, fix the findings, rerun the relevant verification, and launch fresh passes until the remaining feedback is only nitpicks or none.
 - Do not kill long-running subagents or reviewer agents just because they are slow.
 - When waiting on reviewers, subagents, CI, automated review, or external jobs that you deliberately chose to start, wait as long as required. There is no fixed timeout where waiting itself becomes the problem.
 - Never interrupt in-flight work just to force a partial result, salvage something quickly, or avoid making the user wait longer.
@@ -113,7 +117,6 @@ Do not document every trivial implementation detail. Document the non-obvious, d
 
 Waypoint scaffolds these focused specialists by default:
 
-- `coding-agent` for bounded implementation slices the main agent deliberately wants to hand off because parallelism or context preservation will clearly help
 - `code-reviewer` for correctness and regression review
 - `code-health-reviewer` for maintainability drift
 - `plan-reviewer` to challenge non-trivial implementation plans when an independent second pass would materially improve the result
@@ -133,6 +136,7 @@ Deliberate closeout review is available when you want a second pass for ship-rea
 - If you use it, follow the skill's loop fully: define the reviewable slice, run the needed reviewers, wait for the outputs, fix meaningful findings, and rerun fresh passes when warranted.
 - Treat reviewer agents as one-shot workers. Once a reviewer returns its findings, read the result and close it.
 - Do not widen the scope casually; keep the second pass anchored to the slice you are actually trying to validate.
+- For non-trivial work, the healthy default is to use reviewer passes at meaningful milestones instead of saving all second-pass scrutiny for the very end.
 
 ## Quality bar
 

package/templates/managed-agents-block.md

@@ -94,13 +94,18 @@ Delivery expectations:
 - Only come back before that if you hit a genuine blocker you cannot clear with the codebase, tools, or available context. If that happens, say it plainly and be explicit about what remains unverified.
 
 Working rules:
-- Keep `.waypoint/WORKSPACE.md` current as the live execution state, with timestamped new or materially revised entries in multi-topic sections
+- Treat `.waypoint/WORKSPACE.md` as a mandatory live execution log, not a closeout chore.
+- Update `.waypoint/WORKSPACE.md` during the work whenever the active goal, current phase, next step, blocker, verification state, or handoff context materially changes.
+- For multi-step work, keep the workspace moving as you move: do not wait until the end of the task to reconstruct what happened.
+- If a tracker exists for the active workstream, update the tracker during the work as well and keep `WORKSPACE.md` pointing at the current tracker state.
 - Update user-scoped `AGENTS.md` when you learn a durable preference, standing rule, or default that should apply across projects and your environment allows you to edit that file
 - Update the project-scoped repo `AGENTS.md` when you learn durable repo truth, project constraints, or stable project-specific collaboration rules
 - Update `.waypoint/docs/` when durable project knowledge changes, update `.waypoint/plans/` when a durable plan changes, and refresh `last_updated` on touched routable docs
-- Keep most work in the main agent. Use repo-local skills, trackers, reviewer agents, or `coding-agent` when they create clear leverage, not as default ceremony.
+- Keep most work in the main agent. Use repo-local skills, trackers, and reviewer agents when they create clear leverage, not as default ceremony.
 - Let repo-local skills describe their own triggers. The managed block should keep only the high-level rule: use those tools deliberately when they clearly help the task.
-- Use reviewer agents when an independent second pass would materially improve the result, not before every plan or fix by default.
+- Use reviewer agents proactively at meaningful milestones when the work is non-trivial, risky, user-facing, merge-bound, or otherwise expensive to get wrong.
+- Strong default moments for reviewer-agent passes are: after a meaningful implementation milestone, before opening or updating a PR, after fixing substantial review findings, and before finally calling the work clear.
+- When `code-reviewer` or `code-health-reviewer` find anything more serious than obvious optional polish, fix those findings, rerun the relevant verification, and run fresh review passes until the remaining feedback is only nitpicks or none.
 - Treat `plan-reviewer`, `code-reviewer`, and `code-health-reviewer` as one-shot agents: once a reviewer returns findings, close it; if another pass is needed later, spawn a fresh reviewer instead of reusing the old thread
 - If you created a PR earlier in the current session and need to push more work, first confirm that PR is still open. If it is closed, create a fresh branch from `origin/main` and open a fresh PR instead of pushing more commits to the old PR branch
 - Treat the generated context bundle as required session bootstrap, not optional reference material

package/templates/.codex/agents/coding-agent.toml

@@ -1,49 +0,0 @@
-model = "gpt-5.4-mini"
-model_reasoning_effort = "high"
-sandbox_mode = "workspace-write"
-developer_instructions = """
-Read these files in order before doing anything else:
-1. .waypoint/SOUL.md
-2. .waypoint/agent-operating-manual.md
-3. .waypoint/WORKSPACE.md
-4. .waypoint/context/MANIFEST.md
-5. every file listed in that manifest
-6. .waypoint/docs/code-guide.md
-
-After reading them, follow these operating instructions:
-
-You are the coding agent. You implement a bounded slice that the main agent deliberately handed to you because delegation is useful here.
-
-You are a single-slice execution worker:
-- Finish the specific implementation task you were handed, then stop.
-- Do not silently broaden scope.
-- If the handoff is missing something essential, inspect the repo first and make the narrowest reasonable assumption instead of bouncing the task back immediately.
-
-Working rules:
-- Read the files you plan to change before editing them.
-- Read the docs relevant to the area you touch.
-- Follow `.waypoint/docs/code-guide.md` as an active contract, not background reading.
-- Prefer direct, explicit code over speculative abstraction.
-- Keep changes reviewable and easy to explain.
-- When the handed-off slice involves a bug or broken behavior, investigate first and explain the likely cause plainly in your handoff.
-- Do not revert user work you did not create.
-- Do not make unrelated cleanup changes unless they are required to land the slice safely.
-
-Implementation expectations:
-- Resolve the exact files and entry points involved in the handed-off slice before editing.
-- Validate inputs, state changes, and integration points at the boundaries you touch.
-- Update tests when behavior changes.
-- Update docs or workspace state when the slice changes durable behavior or repo memory.
-- Run the most relevant verification you can for the owned slice before handing back.
-- If verification fails, keep iterating when you can fix it yourself.
-
-Output:
-Return a concise implementation handoff that includes:
-- what you changed
-- files changed
-- verification run and outcome
-- any assumptions, follow-ups, or risks the main agent should know about
-
-Do not pretend the slice is verified if you did not run verification.
-Do not use readiness-disclaimer language as the main point of the handoff. If important known issues remain, say what they are, why they matter, and what needs to happen next.
-"""