waypoint-codex 0.18.2 → 0.19.1

package/README.md

@@ -133,14 +133,14 @@ This helps the agent keep moving until the work is actually ready, not just
 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
+update the right durable layer so the same issue is less likely to happen
 again.
 
 That includes:
 
-- user-scoped guidance
-- project-scoped guidance
-- repo-local skills
+- user-scoped guidance for true cross-project standing rules
+- project-scoped guidance for durable repo-wide context and always-on rules
+- repo-local skills for workflow-specific or method-specific guidance
 - retrospectives that turn friction from the current conversation into lasting
   improvements
 
@@ -163,6 +163,7 @@ Waypoint scaffolds a Codex-friendly repo around a few core pieces:
 
 - `AGENTS.md` for the project-scoped startup contract and durable repo guidance
 - `.waypoint/WORKSPACE.md` for live operational state
+- `.waypoint/ACTIVE_PLANS.md` for the currently approved plan and active phase checkpoints
 - `.waypoint/docs/` for long-lived project docs
 - `.waypoint/plans/` for durable plan documents
 - `.waypoint/DOCS_INDEX.md` for docs and plans routing, so the agent knows what
@@ -186,6 +187,7 @@ The continuity story matters:
 
 - `.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/ACTIVE_PLANS.md` keeps the currently approved plan visible during execution
 - `.waypoint/context/RECENT_THREAD.md` helps the agent retain the important
   parts of the previous conversation
 
@@ -237,6 +239,7 @@ repo/
     ├── DOCS_INDEX.md
     ├── TRACKS_INDEX.md
     ├── WORKSPACE.md
+    ├── ACTIVE_PLANS.md
     ├── docs/
     ├── plans/
     ├── track/

package/dist/src/core.js

@@ -11,6 +11,7 @@ const DEFAULT_PLANS_DIR = ".waypoint/plans";
 const DEFAULT_TRACK_DIR = ".waypoint/track";
 const DEFAULT_TRACKS_INDEX = ".waypoint/TRACKS_INDEX.md";
 const DEFAULT_WORKSPACE = ".waypoint/WORKSPACE.md";
+const DEFAULT_ACTIVE_PLANS = ".waypoint/ACTIVE_PLANS.md";
 const GITIGNORE_WAYPOINT_START = "# Waypoint state";
 const GITIGNORE_WAYPOINT_END = "# End Waypoint state";
 const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
@@ -43,6 +44,7 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
     ".waypoint/README.md",
     ".waypoint/SOUL.md",
     ".waypoint/WORKSPACE.md",
+    ".waypoint/ACTIVE_PLANS.md",
     ".waypoint/agent-operating-manual.md",
     ".waypoint/",
     ".waypoint/DOCS_INDEX.md",
@@ -76,6 +78,7 @@ const SHIPPED_SKILL_NAMES = [
     "backend-ship-audit",
 ];
 const TIMESTAMPED_WORKSPACE_SECTIONS = new Set([
+    "## Active Plans",
     "## Active Trackers",
     "## Current State",
     "## In Progress",
@@ -382,6 +385,7 @@ export function initRepository(projectRoot, options) {
     scaffoldWaypointOptionalTemplates(projectRoot);
     writeText(path.join(projectRoot, DEFAULT_CONFIG_PATH), renderWaypointConfig(config));
     writeIfMissing(path.join(projectRoot, DEFAULT_WORKSPACE), readTemplate("WORKSPACE.md"));
+    writeIfMissing(path.join(projectRoot, DEFAULT_ACTIVE_PLANS), readTemplate(".waypoint/ACTIVE_PLANS.md"));
     ensureDir(path.join(projectRoot, DEFAULT_DOCS_DIR));
     ensureDir(path.join(projectRoot, DEFAULT_PLANS_DIR));
     ensureDir(path.join(projectRoot, DEFAULT_TRACK_DIR));
@@ -400,7 +404,7 @@ export function initRepository(projectRoot, options) {
     return [
         "Initialized Waypoint scaffold",
         "Installed managed AGENTS block",
-        "Created .waypoint/WORKSPACE.md, .waypoint/docs/, .waypoint/plans/, and .waypoint/track/ scaffold",
+        "Created .waypoint/WORKSPACE.md, .waypoint/ACTIVE_PLANS.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",
@@ -483,6 +487,7 @@ export function doctorRepository(projectRoot) {
         const workspaceText = readFileSync(workspacePath, "utf8");
         for (const section of [
             "## Active Goal",
+            "## Active Plans",
             "## Active Trackers",
             "## Current State",
             "## In Progress",
@@ -622,6 +627,25 @@ export function doctorRepository(projectRoot) {
             paths: [tracksIndexPath],
         });
     }
+    const activePlansPath = path.join(projectRoot, DEFAULT_ACTIVE_PLANS);
+    if (!existsSync(activePlansPath)) {
+        findings.push({
+            severity: "error",
+            category: "workspace",
+            message: ".waypoint/ACTIVE_PLANS.md is missing.",
+            remediation: "Run `waypoint init` to scaffold the active plans file.",
+            paths: [activePlansPath],
+        });
+    }
+    else if (existsSync(workspacePath) && !readFileSync(workspacePath, "utf8").includes(DEFAULT_ACTIVE_PLANS)) {
+        findings.push({
+            severity: "warn",
+            category: "workspace",
+            message: "Workspace does not reference .waypoint/ACTIVE_PLANS.md under `## Active Plans`.",
+            remediation: "Point `## Active Plans` at `.waypoint/ACTIVE_PLANS.md` and summarize the current active phase.",
+            paths: [workspacePath, activePlansPath],
+        });
+    }
     if (existsSync(workspacePath) &&
         tracksIndex.activeTrackPaths.length > 0 &&
         !tracksIndex.activeTrackPaths.some((trackPath) => readFileSync(workspacePath, "utf8").includes(trackPath))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.18.2",
+  "version": "0.19.1",
   "description": "Make Codex better by default with stronger planning, code quality, reviews, tracking, and repo guidance.",
   "license": "MIT",
   "type": "module",

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

@@ -58,8 +58,9 @@ If the plan is not actually settled, stop and use `planning` instead of guessing
 
 ## 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.
+- Make the change in small logical chunks inside the current approved plan phase.
+- Batch related edits into a meaningful phase slice before running heavyweight checks, reviewer passes, or a commit.
+- Commit at phase boundaries or other meaningful checkpoints 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.
 
@@ -77,10 +78,10 @@ Use the repo's existing skills and reviewer agents instead of inventing a parall
 
 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-reviewer` for every non-trivial completed phase 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
+- use them at phase checkpoints, not only at the very end: after completing a substantial phase, 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
@@ -97,13 +98,21 @@ If those reviewer agents are not present in the repo, do the equivalent closeout
 
 If an existing repo-local skill clearly matches the verification surface, use it.
 
-## Step 6: Run The Full Pre-Push Loop
+## Step 6: Run The Phase Checkpoint And 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.
+At the end of each completed phase:
+
+- run the required tests and typechecks for the touched package or service
+- run builds, lint, migrations, or focused smoke tests when they are part of the real risk surface
+- run the relevant reviewer-agent passes for non-trivial work
+- fix failing checks and reviewer findings before moving to the next phase
+- rerun the checkpoint until the current phase is clean
+- update `WORKSPACE.md`, `.waypoint/ACTIVE_PLANS.md`, and any active tracker with the current verification state before moving on
+
+Before pushing:
+
+- make sure the latest completed phase checkpoint is still green
+- 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.
 

package/templates/.agents/skills/planning/SKILL.md

@@ -28,9 +28,10 @@ Before planning:
 1. Read `.waypoint/SOUL.md`
 2. Read `.waypoint/agent-operating-manual.md`
 3. Read `.waypoint/WORKSPACE.md`
-4. Read `.waypoint/context/MANIFEST.md`
-5. Read every file listed in the manifest
-6. Read the routed docs relevant to the task
+4. Read `.waypoint/ACTIVE_PLANS.md`
+5. Read `.waypoint/context/MANIFEST.md`
+6. Read every file listed in the manifest
+7. Read the routed docs relevant to the task
 
 ## Output Location
 
@@ -40,6 +41,7 @@ The plan belongs in the repo, not only in chat.
 - Choose the smallest routed location that matches the work, such as a project plan, implementation plan, or focused design note.
 - If a relevant plan doc already exists, update it instead of creating a competing one.
 - Make sure the doc remains discoverable through the routed docs layer.
+- Update `.waypoint/ACTIVE_PLANS.md` when this plan becomes the approved active plan or when its current phase changes.
 - In chat, return only a concise summary plus the path to the plan doc.
 
 If the planned implementation will be large, multi-step, or likely to span multiple sessions, also create or update a tracker under `.waypoint/track/` and link it from `WORKSPACE.md` before implementation begins.
@@ -102,8 +104,10 @@ Plans document your understanding. Include what matters for this task:
 - **Current State**: What exists today — relevant files, data flows, constraints, existing patterns
 - **Changes**: Every file to create/modify/delete, how changes connect
 - **Decisions**: Why this approach, tradeoffs, assumptions
+- **Phase breakdown**: Distinct execution phases in the order they should happen
 - **Scope checklist**: Concrete implementation items that can be marked done or not done
-- **Acceptance criteria**: What must be true when each step is "done"
+- **Acceptance criteria**: What must be true when each phase is "done"
+- **Phase checkpoints**: What verification, reviewer passes, tests, typechecks, builds, or manual QA must pass before moving to the next phase
 - **Test cases**: For behavioral changes, include input -> expected output examples
 - **Non-Goals**: Explicitly out of scope to prevent implementation drift
 
@@ -127,6 +131,7 @@ Before presenting the plan, verify against real code:
 - No literal code unless the user explicitly wants it
 - No pretending you verified something you didn't
 - Approved scope must be explicit enough to act as an execution contract after user approval
+- The plan must be explicit enough to support phase-by-phase execution and checkpoints without rediscovering the intended order in chat
 - If the user approves the plan, do not silently defer or drop checklist items later; discuss any proposed scope change first
 
 If the change touches durable project behavior, include docs/workspace updates in the plan.
@@ -143,10 +148,12 @@ A good durable plan doc usually includes:
 1. Current state
 2. Proposed changes
 3. Decisions and tradeoffs
-4. Scope checklist
-5. Acceptance criteria
-6. Verification
-7. TL;DR
+4. Phase breakdown
+5. Scope checklist
+6. Acceptance criteria
+7. Phase checkpoints
+8. Verification
+9. TL;DR
 
 ## Final Response
 
@@ -156,7 +163,8 @@ When the plan doc is written:
 - include the doc path
 - call out any unresolved decisions that still need the user's input
 - if there are no unresolved decisions and the user approves the plan, treat that approval as authorization to execute the plan end to end rather than asking again at each obvious next step
-- once approved, use the plan's checklist and acceptance criteria to decide whether the work is actually done; if anything approved is skipped, report that as partial work or ask to change scope instead of calling it complete
+- once approved, update `.waypoint/ACTIVE_PLANS.md` so the active plan, current phase, and current checkpoint are visible during execution
+- once approved, use the plan's checklist, phase checkpoints, and acceptance criteria to decide whether the work is actually done; if anything approved is skipped, report that as partial work or ask to change scope instead of calling it complete
 
 ## Quality Bar
 

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

@@ -26,9 +26,10 @@ Before tracking:
 1. Read `.waypoint/SOUL.md`
 2. Read `.waypoint/agent-operating-manual.md`
 3. Read `.waypoint/WORKSPACE.md`
-4. Read `.waypoint/context/MANIFEST.md`
-5. Read every file listed in that manifest
-6. Read `.waypoint/track/README.md`
+4. Read `.waypoint/ACTIVE_PLANS.md`
+5. Read `.waypoint/context/MANIFEST.md`
+6. Read every file listed in that manifest
+7. Read `.waypoint/track/README.md`
 
 ## When A Tracker Is Required
 
@@ -84,6 +85,7 @@ A good tracker usually includes:
 - `Current State`
 - `Next`
 - `Workstreams`
+- `Phase Checkpoints`
 - `Verification`
 - `Decisions`
 - `Notes`
@@ -93,8 +95,10 @@ Use `- [ ]` checkboxes when there are many concrete tasks to track. Use status-s
 ## Step 4: Link It From The Workspace
 
 Add or update a bullet under `## Active Trackers` in `.waypoint/WORKSPACE.md` that points at the tracker path and states the current phase or next step.
+If the work is driven by an approved plan, keep `.waypoint/ACTIVE_PLANS.md` aligned with the same phase naming and checkpoint language.
 
 `WORKSPACE.md` should answer "what matters right now?"
+`.waypoint/ACTIVE_PLANS.md` should answer "what plan and phase must be followed right now?"
 The tracker should answer "what exactly is happening across the whole workstream?"
 
 ## Step 5: Maintain It During Execution

package/templates/.gitignore.snippet

@@ -22,6 +22,7 @@
 .waypoint/README.md
 .waypoint/SOUL.md
 .waypoint/WORKSPACE.md
+.waypoint/ACTIVE_PLANS.md
 .waypoint/agent-operating-manual.md
 .waypoint/DOCS_INDEX.md
 .waypoint/TRACKS_INDEX.md

package/templates/.waypoint/ACTIVE_PLANS.md

@@ -0,0 +1,23 @@
+# Active Plans
+
+This file is the live execution-contract layer for approved plans that are currently in flight.
+
+Keep it short and current.
+
+For each active plan, include:
+- source plan path under `.waypoint/plans/`
+- whether the plan is approved
+- the current phase
+- the checklist or acceptance criteria for that phase
+- what checkpoint must pass before moving to the next phase
+- any explicit non-goals or approved deferrals
+
+Rules:
+- Read this file during bootstrap and before meaningful implementation.
+- Follow the approved plan. Do not silently deviate from it.
+- Update this file whenever the active plan, current phase, checkpoint, or approved scope changes.
+- If no approved plan is active, say so plainly here.
+
+## Active Plan
+
+- None right now.

package/templates/.waypoint/README.md

@@ -4,6 +4,7 @@ Repo-local Waypoint configuration and project memory files.
 
 - `config.toml` — Waypoint feature toggles and file locations
 - `WORKSPACE.md` — live operational state; new or materially revised entries in multi-topic sections are timestamped
+- `ACTIVE_PLANS.md` — live execution-contract view of the approved plan(s) and current phase checkpoints
 - `DOCS_INDEX.md` — generated docs and plans routing map
 - `SOUL.md` — agent identity and working values
 - `agent-operating-manual.md` — required session workflow

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

@@ -20,8 +20,9 @@ Bootstrap sequence:
 2. Read `.waypoint/SOUL.md`
 3. Read this file
 4. Read `.waypoint/WORKSPACE.md`
-5. Read `.waypoint/context/MANIFEST.md`
-6. Read every file listed in that manifest
+5. Read `.waypoint/ACTIVE_PLANS.md`
+6. Read `.waypoint/context/MANIFEST.md`
+7. Read every file listed in that manifest
 
 Do not skip this sequence.
 
@@ -37,6 +38,7 @@ The repository should contain the context the next agent needs.
 - 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/ACTIVE_PLANS.md` is the live execution-contract record: which approved plan is active, which phase is active, and what checkpoint must pass before moving on
 - `.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
 - `.waypoint/plans/` is the durable planning layer: implementation plans, rollout plans, migration plans, and other task-shaped plans worth keeping
@@ -58,11 +60,15 @@ If something important lives only in your head or in the chat transcript, the re
 - Keep communication concise by default. Lead with the answer, diagnosis, decision, or next step, and include only the most important supporting detail unless the user asks for more.
 - Honesty means accurate diagnosis, explicit uncertainty, and clear verification limits. It does not mean substituting process language for investigation.
 - 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.
+- Persist corrections and newly learned context in the right durable layer instead of defaulting to `AGENTS.md`.
+- Update the user-scoped `AGENTS.md` only for true cross-project standing preferences or global operating rules.
+- Update the project-scoped repo `AGENTS.md` only for durable repo truth, project constraints, or stable project-wide rules that should always apply in this repo.
+- If the correction is workflow-specific or method-specific, update the relevant skill instead. If no existing skill owns it well, propose creating one instead of stuffing that guidance into `AGENTS.md`.
 - Treat `.waypoint/WORKSPACE.md` as mandatory live execution state, not end-of-task paperwork.
+- Treat `.waypoint/ACTIVE_PLANS.md` as mandatory live plan state for approved work, not a forgotten side file.
 - 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.
+- Update `.waypoint/ACTIVE_PLANS.md` whenever the active approved plan, current phase, phase checklist, checkpoint, or approved scope changes.
+- Do not wait until final handoff to update workspace or active plan state. If the work took enough effort that the next agent would benefit from a current snapshot, those files 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.
@@ -72,7 +78,8 @@ 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.
 - Use the repo-local skills and reviewer agents deliberately, but do not underuse them on work that is expensive to get wrong.
 - When spawning reviewer agents or other subagents, explicitly set `fork_context: false` and choose the model/reasoning pair that matches the risk and importance of the second pass.
-- For non-trivial work, strongly prefer reviewer-agent passes between major implementation milestones, before opening or updating a PR, after fixing substantial findings, and before final closeout when the environment allows those agents to run.
+- For non-trivial work, strongly prefer reviewer-agent passes at phase checkpoints, before opening or materially updating a PR, after fixing substantial findings, and before final closeout when the environment allows those agents to run.
+- Do not run heavyweight reviewer or full-suite loops after every tiny edit. Batch related work into the current approved phase, then run the checkpoint.
 - 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.
@@ -89,6 +96,8 @@ If something important lives only in your head or in the chat transcript, the re
 
 Once the user has approved a plan or otherwise told you to continue, own the work until the slice is genuinely complete.
 
+Execute approved work phase by phase. Complete the current phase, run the relevant checkpoint, fix findings, rerun verification, and only then move to the next phase.
+
 That means:
 
 - continue through implementation, verification, and required repo-memory updates without asking for incremental permission
@@ -140,7 +149,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.
+- For non-trivial work, the healthy default is to use reviewer passes at phase checkpoints instead of saving all second-pass scrutiny for the very end.
 
 ## Quality bar
 

package/templates/.waypoint/scripts/prepare-context.mjs

@@ -534,6 +534,22 @@ function writeActiveTrackers(contextDir, projectRoot, activeTracks) {
   );
 }
 
+function writeActivePlans(contextDir, projectRoot) {
+  const activePlansPath = path.join(projectRoot, ".waypoint", "ACTIVE_PLANS.md");
+  return writeContextFile(
+    contextDir,
+    "ACTIVE_PLANS.md",
+    "Active Plans",
+    existsSync(activePlansPath)
+      ? [
+          "Read this file before meaningful implementation when approved plan work is in flight:",
+          "",
+          `- \`${path.relative(projectRoot, activePlansPath)}\``,
+        ].join("\n")
+      : "`.waypoint/ACTIVE_PLANS.md` is missing.",
+  );
+}
+
 function main() {
   const projectRoot = detectProjectRoot();
   const contextDir = path.join(projectRoot, ".waypoint", "context");
@@ -672,6 +688,7 @@ function main() {
     ].join("\n")
   );
   const recentThreadPath = writeRecentThread(contextDir, projectRoot, threadIdOverride);
+  const activePlansPath = writeActivePlans(contextDir, projectRoot);
   const activeTrackersPath = writeActiveTrackers(contextDir, projectRoot, activeTracks);
 
   const manifestPath = path.join(contextDir, "MANIFEST.md");
@@ -691,6 +708,7 @@ function main() {
     `- \`${path.relative(projectRoot, recentCommitsPath)}\` — recent commits`,
     `- \`${path.relative(projectRoot, prsPath)}\` — open and recently merged pull requests`,
     `- \`${path.relative(projectRoot, recentThreadPath)}\` — latest meaningful turns from the local ${codingAgentLabelText} session for this repo`,
+    `- \`${path.relative(projectRoot, activePlansPath)}\` — active plan summary`,
     `- \`${path.relative(projectRoot, docsIndexPath)}\` — current docs index`,
     `- \`${path.relative(projectRoot, tracksIndexPath)}\` — current tracker index`,
     `- \`${path.relative(projectRoot, activeTrackersPath)}\` — active tracker summary`,
@@ -700,6 +718,7 @@ function main() {
     "- `.waypoint/SOUL.md`",
     "- `.waypoint/agent-operating-manual.md`",
     "- `.waypoint/WORKSPACE.md`",
+    "- `.waypoint/ACTIVE_PLANS.md`",
     "",
     "## Active tracker files to read after this manifest",
     "",

package/templates/.waypoint/track/_template.md

@@ -31,6 +31,10 @@ What outcome this tracker is trying to reach.
 - [ ] First task
 - [ ] Second task
 
+## Phase Checkpoints
+
+- [ ] Checkpoint required before leaving the current phase
+
 ## Verification
 
 - [ ] Verification step

package/templates/WORKSPACE.md

@@ -1,11 +1,15 @@
 # Workspace
 
-Timestamp discipline: Prefix new or materially revised bullets in `Active Trackers`, `Current State`, `In Progress`, `Next`, `Parked`, and `Done Recently` with `[YYYY-MM-DD HH:MM TZ]`.
+Timestamp discipline: Prefix new or materially revised bullets in `Active Plans`, `Active Trackers`, `Current State`, `In Progress`, `Next`, `Parked`, and `Done Recently` with `[YYYY-MM-DD HH:MM TZ]`.
 
 ## Active Goal
 
 Describe the main thing currently being built or changed.
 
+## Active Plans
+
+Point at `.waypoint/ACTIVE_PLANS.md` and note the currently active approved plan and phase.
+
 ## Active Trackers
 
 List any active tracker docs under `.waypoint/track/`, with the current phase or next step.

package/templates/managed-agents-block.md

@@ -19,8 +19,9 @@ Bootstrap sequence:
 2. Read `.waypoint/SOUL.md`
 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
+5. Read `.waypoint/ACTIVE_PLANS.md`
+6. Read `.waypoint/context/MANIFEST.md`
+7. Read every file listed in the manifest
 
 This is mandatory, not optional.
 
@@ -76,7 +77,8 @@ When an explanation is clearer visually, use Mermaid diagrams directly in chat f
 
 Delivery expectations:
 - Keep communication concise by default. Lead with the answer, diagnosis, decision, or next step, and include only the most important supporting detail unless the user asks for more.
-- For planned work, define done from the approved scope and acceptance criteria, not from your own sense that the system is already good enough.
+- For planned work, treat `.waypoint/ACTIVE_PLANS.md` as the live execution contract and define done from the approved scope, current phase checkpoint, and acceptance criteria, not from your own sense that the system is already good enough.
+- Execute approved plans phase by phase. Finish the current phase, run the relevant checkpoint, resolve findings, and only then move to the next phase.
 - When you report back to the user, explain the result in plain, direct language. Say what you changed, what happened, and anything the user actually needs to know, but do not lean on jargon, low-level implementation detail, or code-heavy narration unless the user asks for it.
 - Write for a smart person who is not looking at the code. The goal is clarity, not technical performance.
 - 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.
@@ -98,16 +100,21 @@ Delivery expectations:
 
 Working rules:
 - Treat `.waypoint/WORKSPACE.md` as a mandatory live execution log, not a closeout chore.
+- Treat `.waypoint/ACTIVE_PLANS.md` as the mandatory live execution-contract file for approved plans.
 - 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.
+- Update `.waypoint/ACTIVE_PLANS.md` whenever the active approved plan, current phase, phase checklist, checkpoint, or approved scope changes.
+- For multi-step work, keep the workspace and active plan file 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
+- Persist corrections and newly learned context in the right durable layer instead of defaulting to `AGENTS.md`.
+- Update user-scoped `AGENTS.md` only for true cross-project standing preferences or global operating rules.
+- Update the project-scoped repo `AGENTS.md` only for durable repo context or project-wide rules that should always apply in this repo.
+- If the correction is workflow-specific or method-specific, update the relevant repo skill instead. If no existing skill owns it well, propose creating one instead of stuffing that guidance into `AGENTS.md`.
+- Update `.waypoint/docs/` when durable project knowledge changes, update `.waypoint/plans/` when a durable plan changes, update `.waypoint/ACTIVE_PLANS.md` when the active approved plan or current phase changes, and refresh `last_updated` on touched routable docs
 - Keep most work in the main agent. Use repo-local skills, trackers, and reviewer agents when they create clear leverage, not as default ceremony.
 - Let repo-local skills describe their own triggers. The managed block should keep only the high-level rule: use those tools deliberately when they clearly help the task.
-- Use reviewer agents 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.
+- Use reviewer agents proactively at phase checkpoints 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 completing a plan phase, before opening or materially updating a PR, after fixing substantial review findings, and before finally calling the work clear.
+- Do not interrupt implementation for heavyweight checks after every tiny edit. Batch related work into the current plan phase, then run the checkpoint.
 - 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