waypoint-codex 0.14.0 → 0.15.0

package/README.md

@@ -53,8 +53,7 @@ That keeps the default conversation focused on diagnosis, progress, and verifica
 
 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
@@ -81,7 +80,7 @@ Waypoint scans each configured root recursively and only includes Markdown files
 Waypoint is most useful when you want:
 
 - multi-session continuity in a real repo
-- a durable memory structure for agents
+- 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
 
@@ -108,7 +107,6 @@ repo/
 │   └── skills/
 └── .waypoint/
     ├── DOCS_INDEX.md
-    ├── MEMORY.md
     ├── TRACKS_INDEX.md
     ├── WORKSPACE.md
     ├── docs/
@@ -148,6 +146,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`
@@ -165,7 +164,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
 
@@ -174,7 +173,7 @@ 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
+- 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
 

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.15.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,175 @@
+---
+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."
+
+## 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` when the work or verification checklist is too large for `WORKSPACE.md`.
+- 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
+- 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 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.
+
+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.
+
+## 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
+
+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 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.
+
+## 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/.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,9 +50,13 @@ 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.
+- 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`.
 - 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.

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.
@@ -91,7 +95,8 @@ Delivery expectations:
 
 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
+- 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.

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/`.