waypoint-codex 0.18.1 → 0.19.0

package/README.md

@@ -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.1",
+  "version": "0.19.0",
   "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,7 +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
-- **Acceptance criteria**: What must be true when each step is "done"
+- **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 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
 
@@ -125,6 +130,9 @@ Before presenting the plan, verify against real code:
 - No "we'll figure it out during implementation"
 - 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.
 Write or update the durable plan doc under `.waypoint/plans/` as part of the skill, not as an optional follow-up.
@@ -140,9 +148,12 @@ A good durable plan doc usually includes:
 1. Current state
 2. Proposed changes
 3. Decisions and tradeoffs
-4. Acceptance criteria
-5. Verification
-6. TL;DR
+4. Phase breakdown
+5. Scope checklist
+6. Acceptance criteria
+7. Phase checkpoints
+8. Verification
+9. TL;DR
 
 ## Final Response
 
@@ -152,6 +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, 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
@@ -49,17 +51,22 @@ If something important lives only in your head or in the chat transcript, the re
 - Read code before editing it.
 - 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.
+- Once a plan is approved, treat its scope and acceptance criteria as the execution contract. Do not silently narrow, defer, or drop approved work because the system feels good enough, the remaining work looks less valuable, or you would prefer a smaller PR. If the scope should change, discuss that with the user first unless a real blocker, hidden-risk decision, or explicit user redirect forces the change.
+- When the user shows a bug, screenshot, or broken behavior, investigate first. Lead with what is happening, why it is likely happening, the important options or tradeoffs if they matter, what you checked, and what you are doing next.
+- After investigation, explain the diagnosis before jumping into implementation whenever the cause, tradeoffs, or solution shape are not already obvious.
 - 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.
+- 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.
 - 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.
@@ -69,7 +76,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.
@@ -86,6 +94,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
@@ -96,6 +106,7 @@ Pause only when:
 
 - a real blocker prevents forward progress
 - a hidden-risk or non-obvious decision would materially change scope, behavior, cost, or data safety
+- you want to change approved scope or defer approved work
 - the user explicitly redirects, pauses, or narrows the work
 
 If none of those are true, keep going.
@@ -143,6 +154,7 @@ Deliberate closeout review is available when you want a second pass for ship-rea
 - No silent assumptions
 - No fake verification
 - No hiding behind process language when a useful diagnosis is possible
+- No silent scope reduction after plan approval
 - No skipping docs or workspace updates when they matter
 - No broad scope creep under the banner of "while I'm here"
 

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.
 
@@ -69,18 +70,21 @@ If some uncertainty still remains after checking persisted context and interview
 
 Prefer existing persisted context over re-interviewing the user.
 
-If the user approves a plan or explicitly tells you to proceed, treat that as authorization to execute the work end to end. Do not stop mid-implementation for incremental permission unless a real blocker, hidden-risk decision, or explicit user redirect requires a pause.
+If the user approves a plan or explicitly tells you to proceed, treat that as authorization to execute the work end to end. An approved plan is the active execution contract: do not silently narrow, defer, or drop planned work because the system feels good enough, the remaining work feels less important, or you would prefer a smaller PR. If you believe the approved scope should change, pause and discuss that change with the user before proceeding. Only change approved scope without that discussion when a real blocker, hidden-risk decision, or explicit user redirect requires it.
 When work is in flight elsewhere — reviewer agents, subagents, CI, automated review, external jobs, or other waiting periods — wait as long as required. There is no fixed waiting limit, and slowness alone is not a reason to interrupt or abandon the work.
 When you use a browser, app, or other interactive UI to inspect, reproduce, or verify something, send the user screenshots of the relevant states so they can see what you saw. If screenshots are not possible in the current environment, say so explicitly.
 When an explanation is clearer visually, use Mermaid diagrams directly in chat for flows, architecture, state, and plans.
 
 Delivery expectations:
-- Before you start, decide what "done" means for the task. Set your own finish line and use it as your checklist while you work.
+- 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, 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.
 - 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.
+- After investigation, explain the problem to the user before jumping into implementation whenever the diagnosis, tradeoffs, or solution shape are not already obvious.
+- Lead with the useful truth: what is happening, the likely cause, the important options or tradeoffs if they matter, 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.
@@ -90,21 +94,25 @@ Delivery expectations:
 - Use representative or real inputs when practical instead of toy examples, so the check tells you something meaningful about the actual request.
 - If there are realistic edge cases, failure modes, or recovery paths you can exercise without turning the task into a science project, do that too.
 - If something looks wrong, incomplete, or unproven, keep going. Fix it, rerun the check, and only report completion once the result matches the request.
+- Do not call work done while approved scope or acceptance criteria remain unfinished. If any approved item was skipped or deferred, report that plainly as partial work or a scope-change proposal, not as completion.
 - The point of this is to keep iteration off the user's shoulders. Return finished work when possible, not a first pass that still depends on the user to spot-check it for you.
 - 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:
 - 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
+- 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