waypoint-codex 0.14.0 → 0.16.0

package/README.md

@@ -1,89 +1,199 @@
 # 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
+```
+
+Keep an existing repo up to date:
+
+```bash
+waypoint upgrade
+```
+
+## 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:
+
+- 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
+
+### 2. Better planning
+
+Waypoint ships a thorough planning workflow for work that should not start from
+guesswork.
+
+That workflow pushes the agent to:
 
-Waypoint adds:
+- 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
 
-- explicit repo-local memory
-- strong default collaboration
-- optional structured workflows when the task actually needs them
+The goal is simple: fewer assumptions, fewer surprises, and a much better shot
+at one-shot execution.
 
-The default mode centers a simple loop:
+### 3. Better code quality
 
-- investigate the issue
-- explain what is happening
-- fix what you can
-- verify it
-- leave the repo clearer than you found it
+Waypoint does not assume Codex will naturally write production-quality code by
+default.
 
-## Core idea
+It adds guardrails that push the agent toward:
 
-Waypoint keeps the good parts of a repo operating system:
+- stronger coding standards
+- better fit with the existing codebase
+- fewer lazy shortcuts
+- fewer architecture mistakes
+- fewer duplicated or premature abstractions
 
-- durable context in files
-- explicit startup and routing
+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
 
 Waypoint scaffolds a Codex-friendly repo around a few core pieces:
 
-- `AGENTS.md` for the startup contract
-- `.waypoint/MEMORY.md` for durable user/team preferences and collaboration context
+- `AGENTS.md` for the project-scoped startup contract and durable repo guidance
 - `.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
-- a durable memory structure for agents
-- 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.
 
@@ -108,7 +218,6 @@ repo/
 │   └── skills/
 └── .waypoint/
     ├── DOCS_INDEX.md
-    ├── MEMORY.md
     ├── TRACKS_INDEX.md
     ├── WORKSPACE.md
     ├── docs/
@@ -148,6 +257,7 @@ Waypoint ships a strong default skill pack for real coding work:
 - `conversation-retrospective`
 - `frontend-ship-audit`
 - `backend-ship-audit`
+- `merge-ready-owner`
 - `workspace-compress`
 - `pre-pr-hygiene`
 - `pr-review`
@@ -155,7 +265,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
 
@@ -165,7 +305,7 @@ Waypoint scaffolds these reviewer agents by default:
 - `code-reviewer`
 - `plan-reviewer`
 
-They are available for deliberate second passes.
+They are available for deliberate second passes and for ownership workflows like `merge-ready-owner`.
 
 ## What makes Waypoint different
 
@@ -173,24 +313,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
-- durable memory is separated into user/team memory, live workspace state, project docs, and plan docs
+- 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

@@ -7,7 +7,6 @@ import { defaultWaypointConfig, readTemplate, renderWaypointConfig, MANAGED_BLOC
 const DEFAULT_CONFIG_PATH = ".waypoint/config.toml";
 const DEFAULT_DOCS_DIR = ".waypoint/docs";
 const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
-const DEFAULT_MEMORY = ".waypoint/MEMORY.md";
 const DEFAULT_PLANS_DIR = ".waypoint/plans";
 const DEFAULT_TRACK_DIR = ".waypoint/track";
 const DEFAULT_TRACKS_INDEX = ".waypoint/TRACKS_INDEX.md";
@@ -36,11 +35,11 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
     ".agents/skills/frontend-ship-audit/",
     ".agents/skills/backend-ship-audit/",
     ".agents/skills/conversation-retrospective/",
+    ".agents/skills/merge-ready-owner/",
     ".agents/skills/workspace-compress/",
     ".agents/skills/pre-pr-hygiene/",
     ".agents/skills/pr-review/",
     ".waypoint/config.toml",
-    ".waypoint/MEMORY.md",
     ".waypoint/README.md",
     ".waypoint/SOUL.md",
     ".waypoint/WORKSPACE.md",
@@ -67,6 +66,7 @@ const SHIPPED_SKILL_NAMES = [
     "adversarial-review",
     "break-it-qa",
     "conversation-retrospective",
+    "merge-ready-owner",
     "workspace-compress",
     "pre-pr-hygiene",
     "pr-review",
@@ -177,13 +177,8 @@ function migrateLegacyRootFiles(projectRoot) {
     if (existsSync(legacyWorkspace) && !existsSync(newWorkspace)) {
         writeText(newWorkspace, readFileSync(legacyWorkspace, "utf8"));
     }
-    const legacyMemory = path.join(projectRoot, "MEMORY.md");
-    const newMemory = path.join(projectRoot, DEFAULT_MEMORY);
-    if (existsSync(legacyMemory) && !existsSync(newMemory)) {
-        writeText(newMemory, readFileSync(legacyMemory, "utf8"));
-    }
     removePathIfExists(legacyWorkspace);
-    removePathIfExists(legacyMemory);
+    removePathIfExists(path.join(projectRoot, "MEMORY.md"));
     removePathIfExists(path.join(projectRoot, "DOCS_INDEX.md"));
 }
 function appendGitignoreSnippet(projectRoot) {
@@ -373,6 +368,7 @@ export function initRepository(projectRoot, options) {
         ".codex/agents/implementer.toml",
         ".waypoint/agents",
         ".waypoint/automations",
+        ".waypoint/MEMORY.md",
         ".waypoint/rules",
         ".waypoint/state",
     ]) {
@@ -381,7 +377,6 @@ export function initRepository(projectRoot, options) {
     writeText(path.join(projectRoot, ".waypoint/README.md"), readTemplate(".waypoint/README.md"));
     writeText(path.join(projectRoot, ".waypoint/SOUL.md"), readTemplate(".waypoint/SOUL.md"));
     writeText(path.join(projectRoot, ".waypoint/agent-operating-manual.md"), readTemplate(".waypoint/agent-operating-manual.md"));
-    writeIfMissing(path.join(projectRoot, DEFAULT_MEMORY), readTemplate(".waypoint/MEMORY.md"));
     scaffoldWaypointOptionalTemplates(projectRoot);
     writeText(path.join(projectRoot, DEFAULT_CONFIG_PATH), renderWaypointConfig(config));
     writeIfMissing(path.join(projectRoot, DEFAULT_WORKSPACE), readTemplate("WORKSPACE.md"));
@@ -403,7 +398,7 @@ export function initRepository(projectRoot, options) {
     return [
         "Initialized Waypoint scaffold",
         "Installed managed AGENTS block",
-        "Created .waypoint/MEMORY.md, .waypoint/WORKSPACE.md, .waypoint/docs/, .waypoint/plans/, and .waypoint/track/ scaffold",
+        "Created .waypoint/WORKSPACE.md, .waypoint/docs/, .waypoint/plans/, and .waypoint/track/ scaffold",
         "Installed repo-local Waypoint skills",
         "Installed coding/reviewer agents and project Codex config",
         "Generated .waypoint/DOCS_INDEX.md and .waypoint/TRACKS_INDEX.md",
@@ -515,7 +510,6 @@ export function doctorRepository(projectRoot) {
         }
     }
     for (const requiredFile of [
-        path.join(projectRoot, DEFAULT_MEMORY),
         path.join(projectRoot, ".waypoint", "SOUL.md"),
         path.join(projectRoot, ".waypoint", "agent-operating-manual.md"),
         path.join(projectRoot, ".waypoint", "scripts", "prepare-context.mjs"),

package/package.json

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

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

@@ -1,11 +1,11 @@
 ---
 name: adversarial-review
-description: Run a deliberate second-pass review loop for ship-readiness or risky changes. Use when the user asks for a final review pass, asks whether something is ready to ship, asks to "close the loop," or when the implementation risk clearly warrants an explicit closeout workflow. This skill scopes the slice, runs `code-reviewer`, runs `code-health-reviewer` when the change is medium or large or structurally risky, runs `code-guide-audit`, waits for the required outputs, fixes real findings, and repeats with fresh rounds until no meaningful issues remain. Do not use this for tiny obvious edits, normal debugging back-and-forth, pre-implementation plan review, or active PR comment triage.
+description: Second-pass closeout review for a non-trivial implementation slice. Use when risky work needs a deliberate final review before being called done. This skill scopes the slice, runs the right reviewer agents and code-guide checks, fixes meaningful findings, and repeats until only optional polish remains.
 ---
 
 # Adversarial Review
 
-Use this skill when you explicitly want a closeout-grade second pass instead of a normal implementation loop.
+Use this skill when you explicitly want a closeout-grade second pass before calling a non-trivial slice done or ready to ship.
 
 This skill coordinates the specialist reviewers, keeps the scope tight, waits as long as needed, fixes meaningful findings, and reruns fresh review rounds until the remaining feedback is only optional polish or no findings at all.
 

package/templates/.agents/skills/adversarial-review/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Adversarial Review"
-  short_description: "Close out a code slice with iterative review"
-  default_prompt: "Use $adversarial-review to close out this non-trivial implementation slice before calling it done."
+  short_description: "Run a deliberate second-pass closeout review"
+  default_prompt: "Use $adversarial-review when this non-trivial implementation slice needs a deliberate final review loop with reviewer agents and code-guide checks before we call it done."

package/templates/.agents/skills/backend-context-interview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backend-context-interview
-description: Gather and persist durable backend project context when it is missing, stale, contradictory, or too weak to support implementation, architecture, migration, or ship-readiness decisions. Use when a task needs project-level backend facts such as deployment reality, user exposure, scale, criticality, tenant model, compatibility expectations, security posture, observability expectations, or compliance constraints, and those facts are not already clear in `AGENTS.md` or the repo docs. This is not a feature-discovery skill and should not trigger for endpoint details, acceptance criteria, or other task-specific product questions.
+description: Fill missing backend project context that materially changes engineering decisions. Use when durable backend facts like exposure, scale, criticality, compatibility, tenant model, security, observability, or compliance are not already clear in `AGENTS.md` or routed docs.
 ---
 
 # Backend Context Interview

package/templates/.agents/skills/backend-ship-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backend-ship-audit
-description: Audit a backend scope for practical ship readiness with evidence-based findings focused on real release risk rather than style. Use when the user asks whether a backend service, API, worker, scheduler, endpoint group, pull request, or backend directory is ready to ship; when Codex needs to perform a release-risk review before launch; when the audit scope must be resolved from repository structure; when complete-file reading is required to understand behavior and dependencies; when only high-leverage deployment-context questions should be asked after repository exploration; or when a timestamped backend audit should be written under `.waypoint/audit/`. Do not use this for frontend ship review, generic style review, PR comment triage, or a one-off coding-guide check.
+description: Audit a backend scope for ship-readiness with evidence-based findings focused on real release risk. Use when a backend service, API, worker, scheduler, PR, or backend area needs a launch-readiness review rather than style feedback or PR comment triage.
 ---
 
 # Backend ship audit

package/templates/.agents/skills/break-it-qa/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Break-It QA"
   short_description: "Try to break a feature through the UI"
-  default_prompt: "Use this skill to verify a user-facing feature by trying to break it through the browser with invalid inputs, wrong action order, refreshes, back navigation, repeated clicks, and other adversarial interactions, then fix clear issues and repeat."
+  default_prompt: "Use $break-it-qa to verify this user-facing feature by trying to break it through the browser with invalid inputs, wrong action order, refreshes, back navigation, repeated clicks, and other adversarial interactions, then fix clear issues and repeat."

package/templates/.agents/skills/code-guide-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-guide-audit
-description: Audit a specific feature, file set, or implementation slice against the coding guide and report only coding-guide-related violations or risks in that scope. Use when the user asks for a code-guide audit, coding-guide compliance check, guide-specific review, or wants to know whether a change follows rules like no silent fallbacks, strong boundary validation, frontend reuse, explicit state handling, and behavior-focused verification. Do not use this for broad ship-readiness review, generic bug hunting, PR comment triage, or repo-wide cleanup.
+description: Audit a scoped implementation slice against the code guide and report only guide-related violations or risks. Use for coding-guide compliance checks on explicit behavior, root-cause fixes, boundary validation, security, concurrency, accessibility, performance, and future legibility.
 ---
 
 # Code Guide Audit

package/templates/.agents/skills/frontend-context-interview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-context-interview
-description: Gather and persist durable frontend project context when missing or insufficient for implementation or review work. Use this to ask project-level questions about audience, deployment surface, browser/device expectations, accessibility, SEO, localization, analytics obligations, and other durable frontend context that is not clearly documented. This is not a feature-discovery skill.
+description: Fill missing frontend project context that materially changes implementation or review decisions. Use when durable frontend facts like audience, deployment surface, browser and device support, accessibility, SEO, localization, analytics, or design-system constraints are not already clear in `AGENTS.md` or routed docs.
 ---
 
 # Frontend Context Interview

package/templates/.agents/skills/frontend-ship-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-ship-audit
-description: Audit a defined frontend scope for ship-readiness with a strong focus on real product risk, user-facing correctness, and evidence from the repository. Use when Codex needs to review an app, route group, feature, page set, component area, PR, or frontend directory to decide whether it is ready to ship; resolve the actual reviewable frontend scope from the user request and repository structure; read all relevant frontend code and docs completely; ask a concise high-leverage interview only for missing context that materially changes the release bar; persist durable frontend deployment context into the project root AGENTS.md under a Frontend Context section; and write an evidence-based audit with prioritized P0-P4 findings at .waypoint/audit/dd-mm-yyyy-hh-mm-frontend-audit.md.
+description: Audit a frontend scope for ship-readiness with evidence-based findings focused on product risk and user-facing correctness. Use when an app area, route group, feature, PR, or frontend surface needs a launch-readiness review rather than style feedback or PR comment triage.
 ---
 
 Audit ship-readiness like a strong frontend reviewer. Optimize for user impact, release risk, and production correctness. Do not optimize for style policing.

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

@@ -0,0 +1,187 @@
+---
+name: merge-ready-owner
+description: Own a non-trivial change from approved plan through implementation, verification, PR creation or update, review handling, and merge-ready handoff. Use when the user wants Codex to take full ownership after the problem and plan are agreed, keep going without repeated check-ins, and return only when there is a clean PR ready to merge or a concrete blocker that cannot be cleared alone.
+---
+
+# Merge Ready Owner
+
+Use this skill when the user wants one continuous ownership loop instead of a handoff after coding.
+
+The job is not "write some code." The job is "carry the agreed work all the way to a merge-ready PR or a clearly explained blocker."
+
+## When Not To Use This Skill
+
+- Skip it when the problem is still being shaped or the plan is not actually approved. Use `planning` first.
+- Skip it for tiny local edits that do not justify a full ship loop.
+- Skip it when the user explicitly wants to stay in the loop for each step instead of delegating the closeout.
+
+## Finish Line
+
+Before starting, treat this as the default definition of done:
+
+- the agreed scope is implemented
+- the work is based on the repo's current default branch state
+- the right PR exists and is up to date when the repo uses PRs
+- the relevant tests, typechecks, lint, builds, or smoke checks for the touched surface are green
+- real verification has been done against the risky user or runtime path when practical
+- docs, trackers, and workspace state are updated when the shipped behavior changed materially
+- review comments are answered and meaningful findings are fixed
+- CI is green when the repo uses CI
+- the PR is merge-ready, or there is a concrete blocker that cannot be cleared alone
+
+When the product surface makes it practical, extend done to include:
+
+- a short recorded walkthrough of the verified final browser or app flow
+- the local path to that recording
+
+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.
+- Restate the finish line to yourself before editing.
+- Identify the highest-risk parts of the change so verification matches the real failure surface.
+
+If the plan is not actually settled, stop and use `planning` instead of guessing.
+
+## Step 2: Start From Fresh Branch State
+
+- Sync with the repo's current default branch and base the work on that fresh state.
+- If there is no branch yet, create one from the refreshed default branch.
+- If there is already a PR, confirm it is still open before pushing more commits.
+- If an old PR was closed or merged, create a fresh branch from the current default branch, carry forward only the needed work, and open a new PR if the repo uses PRs.
+
+## Step 3: Implement In Small Verified Chunks
+
+- Make the change in small logical chunks.
+- Commit in small steps when the repo workflow benefits from granular history.
+- Keep unrelated local changes intact.
+- Do not stop after the first implementation pass if clear follow-up fixes are still needed.
+
+For bugs, prefer reproducing the problem first, then fixing it, then proving the fix.
+
+## Step 4: Use The Right Repo-Local Helpers
+
+Use the repo's existing skills and reviewer agents instead of inventing a parallel process.
+
+- 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.
+- Use `break-it-qa` for extra abuse testing on risky interactive flows when that pass is worth the time.
+
+If the repo ships reviewer agents under `.codex/agents/`, use them in the closeout flow when they are available:
+
+- 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 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.
+
+## Step 5: Choose Verification That Matches The Real Risk
+
+- Discover and use the verification tools that already exist in the current project instead of assuming one fixed stack.
+- For browser-facing work, use the available browser QA tooling and exercise the real UI.
+- For mobile or desktop app work, use the app or simulator tooling available in the repo and exercise the real flow.
+- For backend work, hit the real route, worker, or runtime boundary when practical instead of trusting only unit tests.
+- For environment-specific bugs, prefer the environment's logs, traces, payloads, or metrics over local guesswork.
+
+If an existing repo-local skill clearly matches the verification surface, use it.
+
+## Step 6: Run The Full Pre-Push Loop
+
+- Run the required tests and typechecks for every touched package or service.
+- 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.
+
+## Step 7: Open Or Update The PR Cleanly
+
+When the repo uses PRs:
+
+- open the PR if one does not exist
+- keep the PR title and body focused on user value and capability, not implementation trivia
+- keep the PR description concise
+- request preview or staging environments when they are part of validation
+
+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:
+
+- watch CI until it settles
+- investigate red checks instead of treating them as someone else's problem
+- if a preview, staging, or deployment environment is required for validation, follow it through until the environment is usable or a real external blocker is proven
+- if the live preview or deployed environment is the real risk surface, verify it directly when helpful instead of waiting only on a bot summary
+
+The ownership loop is still active while CI, preview, or rollout is in flight.
+
+## Step 9: Close The Review Loop
+
+Once review starts:
+
+- use `pr-review`
+- read every meaningful comment
+- 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.
+
+## Step 10: Re-Test The Risky User Paths
+
+- Re-run the happy path after fixes.
+- Re-run the exact paths that were previously broken.
+- For stateful flows, also probe nearby failure surfaces: repeat actions, bad input, stale state, back navigation, recovery, and environment toggles.
+- Capture screenshots when using interactive UI tooling if the environment allows it.
+
+Record the walkthrough only after the verified final state is stable. Do not record the first flaky pass and call that proof.
+
+## Step 11: Hand Back A Merge-Ready Truthful State
+
+Only close out when you can truthfully say one of these:
+
+- the PR is ready to merge
+- or there is a concrete blocker you cannot clear alone
+
+The final handoff should say:
+
+- what is now working for the user
+- what verification actually ran
+- the PR link when there is one
+- any remaining blocker or caveat that still matters
+
+Keep the handoff plain and direct. The point of this skill is to reduce the user's need to supervise the loop.
+
+## 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, and serious findings should reopen the fix-and-review cycle.
+
+## Keep This Skill Sharp
+
+- Add new gotchas when the same ownership failure mode repeats.
+- Tighten the description if the skill fires too early before planning is settled.
+- If the closeout loop keeps depending on the same helper skills, reviewer agents, or verification surfaces, encode that expectation here instead of rediscovering it in chat.

package/templates/.agents/skills/merge-ready-owner/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Merge-Ready Owner"
+  short_description: "Own approved work through merge-ready closeout"
+  default_prompt: "Use $merge-ready-owner when the plan is already approved and you should carry the work all the way through implementation, verification, reviewer-agent passes, PR handling, and merge-ready handoff without repeated check-ins."

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
@@ -99,6 +102,7 @@ The tracker should answer "what exactly is happening across the whole workstream
 - Update `last_updated` whenever you materially change the tracker.
 - Mark completed items done instead of deleting the record.
 - 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/agents/coding-agent.toml

@@ -4,12 +4,11 @@ sandbox_mode = "workspace-write"
 developer_instructions = """
 Read these files in order before doing anything else:
 1. .waypoint/SOUL.md
-2. .waypoint/MEMORY.md if it exists
-3. .waypoint/agent-operating-manual.md
-4. .waypoint/WORKSPACE.md
-5. .waypoint/context/MANIFEST.md
-6. every file listed in that manifest
-7. .waypoint/docs/code-guide.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:
 

package/templates/.gitignore.snippet

@@ -15,11 +15,11 @@
 .agents/skills/frontend-ship-audit/
 .agents/skills/backend-ship-audit/
 .agents/skills/conversation-retrospective/
+.agents/skills/merge-ready-owner/
 .agents/skills/workspace-compress/
 .agents/skills/pre-pr-hygiene/
 .agents/skills/pr-review/
 .waypoint/config.toml
-.waypoint/MEMORY.md
 .waypoint/README.md
 .waypoint/SOUL.md
 .waypoint/WORKSPACE.md

package/templates/.waypoint/README.md

@@ -2,7 +2,6 @@
 
 Repo-local Waypoint configuration and project memory files.
 
-- `MEMORY.md` — durable user/team preferences, collaboration context, and stable product defaults
 - `config.toml` — Waypoint feature toggles and file locations
 - `WORKSPACE.md` — live operational state; new or materially revised entries in multi-topic sections are timestamped
 - `DOCS_INDEX.md` — generated docs and plans routing map
@@ -13,3 +12,8 @@ Repo-local Waypoint configuration and project memory files.
 - `agents/` — agent prompt files that Waypoint's reviewer agents can read and follow
 - `context/` — generated session context bundle
 - `scripts/` — repo-local Waypoint helper scripts
+
+Durable guidance now lives in `AGENTS.md`:
+
+- user-scoped `AGENTS.md` for cross-project preferences and standing rules
+- project-scoped repo `AGENTS.md` for project-specific context and constraints

package/templates/.waypoint/SOUL.md

@@ -12,6 +12,8 @@ You're direct, warm, opinionated, and evidence-driven. You read before you write
 
 **Investigation beats status narration.** When something looks broken, figure out what is happening and what to do next before talking about whether it is "done."
 
+**Fix causes, not symptoms.** A bug is often evidence of a bad underlying decision. Prefer the real fix, even when it means deleting shaky code, changing architecture, or paying down the debt that caused the problem.
+
 **Honesty should be useful.** Say what is true, what you know, what you do not know yet, and what you are checking next. Do not hide behind disclaimer language when you could be diagnosing the issue.
 
 **The repo must remain legible.** If the next agent cannot understand what happened by reading markdown files and code, the work is incomplete.

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

@@ -18,11 +18,10 @@ Bootstrap sequence:
 
 1. Run `node .waypoint/scripts/prepare-context.mjs`
 2. Read `.waypoint/SOUL.md`
-3. Read `.waypoint/MEMORY.md` if it exists
-4. Read this file
-5. Read `.waypoint/WORKSPACE.md`
-6. Read `.waypoint/context/MANIFEST.md`
-7. Read every file listed in that manifest
+3. Read this file
+4. Read `.waypoint/WORKSPACE.md`
+5. Read `.waypoint/context/MANIFEST.md`
+6. Read every file listed in that manifest
 
 Do not skip this sequence.
 
@@ -35,7 +34,8 @@ Do not skip this sequence.
 
 The repository should contain the context the next agent needs.
 
-- `.waypoint/MEMORY.md` is the durable user/team memory layer: collaboration preferences, stable defaults, and long-lived context that should survive across sessions
+- user-scoped `AGENTS.md` is the durable cross-project guidance layer: collaboration preferences, personal workflow rules, and stable defaults that should apply across repos
+- the repo root `AGENTS.md` is the project-scoped guidance layer: repo-specific context, constraints, and durable rules for this project
 - `.waypoint/WORKSPACE.md` is the live operational record: in progress, current state, next steps
 - `.waypoint/track/` is the optional execution-tracking layer for active long-running work that genuinely needs durable progress state
 - `.waypoint/docs/` is the durable project memory: architecture, decisions, integration notes, and debugging knowledge
@@ -50,11 +50,18 @@ If something important lives only in your head or in the chat transcript, the re
 - Follow the repo's documented patterns when they are healthy.
 - If the user approves a plan or explicitly tells you to proceed, treat that as authorization to finish the approved work end to end.
 - When the user shows a bug, screenshot, or broken behavior, investigate first. Lead with what is happening, why it is likely happening, what you checked, and what you are doing next.
+- Fix underlying causes instead of papering over symptoms. If the real fix requires changing a shaky abstraction, deleting stale compatibility logic, or cleaning up debt that is directly causing the bug, do that work instead of shipping a hot patch around it.
+- Do not stop at the first local patch that makes the symptom disappear if the root cause is still obviously in place.
 - Do not lead with readiness disclaimers such as "I can't call this done yet" unless the user explicitly asked whether the work is ready, shippable, or complete.
 - Honesty means accurate diagnosis, explicit uncertainty, and clear verification limits. It does not mean substituting process language for investigation.
-- Update `.waypoint/MEMORY.md` only when you learned a durable user/team preference, collaboration rule, or stable product default.
-- 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`.
+- 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.
+- 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.
@@ -62,9 +69,11 @@ If something important lives only in your head or in the chat transcript, the re
 - 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.
+- 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.
@@ -129,6 +138,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/.waypoint/docs/code-guide.md

@@ -1,6 +1,6 @@
 ---
-summary: Universal coding conventions — explicit behavior, type safety, frontend consistency, reliability, and behavior-focused verification
-last_updated: "2026-03-10 10:05 PDT"
+summary: Universal coding conventions — explicit behavior, root-cause fixes, security, concurrency, accessibility, performance, and behavior-focused verification
+last_updated: "2026-03-25 10:40 PDT"
 read_when:
   - writing code
   - coding standards
@@ -24,7 +24,16 @@ Do not preserve old behavior unless a user-facing requirement explicitly asks fo
 - Do not keep dead fields, dual formats, or migration-only logic "just in case."
 - If compatibility must stay, document the exact contract being preserved and the removal condition.
 
-## 2. Type safety is non-negotiable
+## 2. Fix root causes, not symptoms
+
+Bug fixes should remove the reason the problem exists, not only hide its most obvious effect.
+
+- Do not ship hot patches that leave the bad underlying decision untouched when the real cause is visible and fixable.
+- If the real fix requires deleting stale code, changing an unhealthy abstraction, or paying down the debt that directly caused the issue, do that work.
+- Prefer one clear correction over layering guards, retries, fallbacks, or one-off conditionals around broken logic.
+- If you intentionally choose a temporary mitigation, label it clearly as temporary, explain the remaining risk, and leave a removal path.
+
+## 3. Type safety is non-negotiable
 
 The compiler is part of the design, not an afterthought.
 
@@ -35,7 +44,7 @@ The compiler is part of the design, not an afterthought.
 - Validate external data at boundaries with schema validation and convert it into trusted internal shapes once.
 - Avoid cross-package type casts unless there is no better contract available; fix the shared types instead when practical.
 
-## 3. Fail clearly, never quietly
+## 4. Fail clearly, never quietly
 
 Errors are part of the contract.
 
@@ -45,7 +54,7 @@ Errors are part of the contract.
 - Required configuration has no silent defaults. Missing required config is a startup or boundary failure.
 - Error messages should identify what failed, where, and why.
 
-## 4. Validate at boundaries
+## 5. Validate at boundaries
 
 Anything crossing a boundary is untrusted until proven otherwise.
 
@@ -53,7 +62,17 @@ Anything crossing a boundary is untrusted until proven otherwise.
 - Reject invalid data instead of "normalizing" it into something ambiguous.
 - Keep validation near the boundary instead of scattering half-validation deep inside the system.
 
-## 5. Prefer direct code over speculative abstraction
+## 6. Security and privacy by default
+
+Security and privacy work is part of normal engineering, not a later hardening pass.
+
+- Validate authorization at boundaries and re-check it when trust changes across layers or actors.
+- Minimize privileges for services, jobs, tokens, and humans. Do not grant broad access when the narrower contract is known.
+- Protect secrets in config, logs, traces, prompts, fixtures, screenshots, and error paths.
+- Sanitize untrusted content before rendering, executing, storing, or forwarding it.
+- Avoid storing, returning, or exposing sensitive data unless the product truly needs it.
+
+## 7. Prefer direct code over speculative abstraction
 
 Do not invent complexity for hypothetical future needs.
 
@@ -61,7 +80,7 @@ Do not invent complexity for hypothetical future needs.
 - Prefer straightforward code and small duplication over the wrong generic layer.
 - If a helper hides critical validation, state changes, or failure modes, it is probably hurting clarity.
 
-## 6. Make state, contracts, and provenance explicit
+## 8. Make state, contracts, and provenance explicit
 
 Readers should be able to tell what states exist, what transitions are legal, and what data can be trusted.
 
@@ -71,7 +90,16 @@ Readers should be able to tell what states exist, what transitions are legal, an
 - New schema and persistence work should make provenance obvious and protect against duplication with the right uniqueness constraints, foreign keys, or equivalent invariants.
 - Shared schemas, fixtures, and contract types must match the real API and stored data shape.
 
-## 7. Frontend must reuse and fit the existing system
+## 9. Time, concurrency, and distributed failure are real inputs
+
+Systems do not run in a single-threaded, perfectly ordered world.
+
+- Be explicit about timeouts, cancellation, retries, duplicate delivery, race conditions, clock assumptions, and ordering guarantees.
+- Treat retry behavior, background work, and message handling as correctness boundaries, not incidental plumbing.
+- Assume network calls, workers, queues, and remote dependencies can be slow, reordered, repeated, or partially failed.
+- Make conflict handling and failure recovery explicit where concurrency can affect user or system state.
+
+## 10. Frontend must reuse and fit the existing system
 
 Frontend changes should extend the app, not fork its design language.
 
@@ -81,7 +109,16 @@ Frontend changes should extend the app, not fork its design language.
 - Handle all states for async and data-driven UI: loading, success, empty, error.
 - Optimistic UI must have an explicit rollback or invalidation strategy. Never leave optimistic state hanging without a recovery path.
 
-## 8. Observability is part of correctness
+## 11. Accessibility is part of correctness
+
+UI work is not correct if important users cannot operate it.
+
+- Support keyboard navigation, semantic structure, accessible names, focus states, and readable contrast.
+- Make interactive states and errors perceivable to assistive technologies, not only visually obvious.
+- Treat accessibility regressions as correctness issues, not optional polish.
+- Verify accessibility behavior in the actual UI surface when the change affects interaction or rendering.
+
+## 12. Observability is part of correctness
 
 If you cannot see the failure path, you have not finished the work.
 
@@ -90,7 +127,16 @@ If you cannot see the failure path, you have not finished the work.
 - Failed async work, retries, degraded paths, and rejected inputs must leave a useful trace.
 - Do not use noisy logging to compensate for unclear control flow.
 
-## 9. Test behavior, not implementation
+## 13. Performance by measurement
+
+Optimize based on real impact, not superstition, but do not ignore performance failures once users or operators feel them.
+
+- Measure before and after when performance work matters.
+- Treat pathological queries, unnecessary renders, large payloads, and unbounded memory or retry behavior as correctness issues once they affect users, cost, or operations.
+- Prefer targeted fixes at the real bottleneck over broad speculative optimization.
+- Keep performance assumptions visible in code, docs, or comments when they are important to correctness.
+
+## 14. Test behavior, not implementation
 
 Tests should protect the contract users depend on.
 
@@ -101,7 +147,17 @@ Tests should protect the contract users depend on.
 - For frontend bugs, prefer manual QA by default; add automated regression coverage only when there is a stable user-visible behavior worth protecting.
 - Do not merge behavior changes without leaving behind executable or clearly documented evidence of the new contract.
 
-## 10. Optimize for future legibility
+## 15. Simplicity in naming and organization
+
+Code should be easy to navigate under pressure.
+
+- Use names that describe intent, not cleverness, incidental mechanics, or historical accidents.
+- Keep functions, modules, and APIs small enough that a reader can understand the responsibility without cross-referencing half the repo.
+- Prefer one obvious place for a behavior over scattering it across thin wrappers and pass-through layers.
+- Group code by responsibility and boundary, not by vague convenience buckets.
+- If a file or API has grown hard to name clearly, it is probably doing too much.
+
+## 16. Optimize for future legibility
 
 Write code for the next engineer or agent who has to change it under pressure.
 

package/templates/managed-agents-block.md

@@ -17,11 +17,10 @@ Run the Waypoint bootstrap only in these cases:
 Bootstrap sequence:
 1. Run `node .waypoint/scripts/prepare-context.mjs`
 2. Read `.waypoint/SOUL.md`
-3. Read `.waypoint/MEMORY.md` if it exists
-4. Read `.waypoint/agent-operating-manual.md`
-5. Read `.waypoint/WORKSPACE.md`
-6. Read `.waypoint/context/MANIFEST.md`
-7. Read every file listed in the manifest
+3. Read `.waypoint/agent-operating-manual.md`
+4. Read `.waypoint/WORKSPACE.md`
+5. Read `.waypoint/context/MANIFEST.md`
+6. Read every file listed in the manifest
 
 This is mandatory, not optional.
 
@@ -34,7 +33,10 @@ This is mandatory, not optional.
 Before making meaningful implementation, review, architectural, or tradeoff decisions, inspect the project root guidance files for persisted project context.
 
 Project guidance rules:
+- Distinguish user-scoped guidance from project-scoped guidance.
+- User-scoped `AGENTS.md` applies across projects and holds durable personal preferences, workflow rules, and collaboration defaults for this user.
 - Prefer `AGENTS.md` in the project root if present.
+- The project root `AGENTS.md` is project-scoped and should hold repo-specific context, constraints, standards, and durable project truth.
 - Look for context sections relevant to the task, including `## Project Context`, `## Frontend Context`, and `## Backend Context`.
 - Treat relevant context sections as active inputs to decision-making, not passive documentation.
 - Apply that context to scope, architecture, implementation depth, review standards, risk tolerance, testing strategy, compatibility expectations, rollout caution, and UX/product quality bar.
@@ -53,8 +55,8 @@ Examples of durable context that can materially change the correct approach:
 
 If relevant context is missing, empty, stale, or insufficient and that gap would materially change the correct approach:
 - do not guess silently
-- use `frontend-context-interview` when project-level frontend context is missing
-- use `backend-context-interview` when project-level backend context is missing
+- if the task touches frontend and the needed frontend project context is not present in `AGENTS.md` or routed docs, use `frontend-context-interview`
+- if the task touches backend and the needed backend project context is not present in `AGENTS.md` or routed docs, use `backend-context-interview`
 - ask only the missing high-leverage questions
 - ask about the project, deployment reality, and operating constraints rather than the concrete feature
 - persist only durable context back into the project guidance file
@@ -79,6 +81,8 @@ Delivery expectations:
 - This communication rule applies to how you explain the work, not to how you do it. Your actual reasoning, coding, debugging, and verification should stay technical, precise, and rigorous.
 - When the user shows a bug, broken behavior, or a screenshot of something wrong, investigate before discussing readiness.
 - Lead with the useful truth: what is happening, the likely cause, what you checked, and what you are doing next.
+- Fix the underlying problem, not only the visible symptom. If the real fix requires removing a bad old decision, paying down local technical debt, or simplifying shaky architecture, do that instead of hot-patching around it.
+- Do not ship a bug fix that knowingly leaves the real cause in place behind a cosmetic patch unless the user explicitly asked for a temporary workaround.
 - Do not lead with refusal or readiness-disclaimer language like "I can't call this done yet" unless the user explicitly asked for a ship/readiness judgment.
 - Honesty means accurate diagnosis, explicit uncertainty, and clear verification limits. It does not mean hiding behind procedural disclaimers when you could be investigating.
 - Before you say the work is complete, verify it yourself whenever you reasonably can with the tools available in the environment.
@@ -90,12 +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
-- Keep `.waypoint/MEMORY.md` for durable user/team preferences, collaboration context, and stable product defaults; keep task status and active execution state out of it
+- 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.
 - 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/.waypoint/MEMORY.md

@@ -1,20 +0,0 @@
-# Memory
-
-Durable user, team, and collaboration context for this repository.
-
-Use this file for:
-
-- stable communication preferences
-- durable workflow preferences
-- standing product defaults or guardrails
-- user or team context that matters across sessions
-
-Do not use this file for:
-
-- active task status
-- current blockers or next steps
-- detailed architecture notes
-- transient complaints or one-off debugging chatter
-
-Put live execution state in `.waypoint/WORKSPACE.md`.
-Put durable project behavior and architecture in `.waypoint/docs/`.