waypoint-codex 0.18.0 → 0.18.2

package/README.md

@@ -189,6 +189,15 @@ The continuity story matters:
 - `.waypoint/context/RECENT_THREAD.md` helps the agent retain the important
   parts of the previous conversation
 
+Waypoint defaults to Codex transcript discovery.
+If you use Pi instead, set this in `.waypoint/config.toml`:
+
+```toml
+coding_agent = "pi"
+```
+
+Supported values are `"codex"` and `"pi"`.
+
 ## Best fit
 
 Waypoint is most useful when you want:

package/dist/src/core.js

@@ -143,6 +143,7 @@ function buildWaypointConfig(projectRoot, existingConfig, options) {
     return {
         version: existingConfig?.version ?? defaults.version,
         profile: options.profile,
+        coding_agent: existingConfig?.coding_agent ?? defaults.coding_agent,
         workspace_file: existingConfig?.workspace_file ?? defaults.workspace_file,
         docs_dirs: configuredRootDirs(projectRoot, existingConfig?.docs_dirs, existingConfig?.docs_dir, DEFAULT_DOCS_DIR).map((dir) => path.relative(projectRoot, dir).split(path.sep).join("/")),
         plans_dirs: configuredRootDirs(projectRoot, existingConfig?.plans_dirs, existingConfig?.plans_dir, DEFAULT_PLANS_DIR).map((dir) => path.relative(projectRoot, dir).split(path.sep).join("/")),

package/dist/src/templates.js

@@ -30,6 +30,7 @@ export function defaultWaypointConfig(options) {
     return {
         version: 1,
         profile: options.profile,
+        coding_agent: "codex",
         workspace_file: ".waypoint/WORKSPACE.md",
         docs_dirs: [".waypoint/docs"],
         plans_dirs: [".waypoint/plans"],
@@ -44,6 +45,7 @@ export function renderWaypointConfig(config) {
     const renderedConfig = {
         version: config.version,
         profile: config.profile,
+        coding_agent: config.coding_agent,
         workspace_file: config.workspace_file,
         docs_dirs: config.docs_dirs,
         plans_dirs: config.plans_dirs,

package/package.json

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

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

@@ -102,6 +102,7 @@ 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
+- **Scope checklist**: Concrete implementation items that can be marked done or not done
 - **Acceptance criteria**: What must be true when each step is "done"
 - **Test cases**: For behavioral changes, include input -> expected output examples
 - **Non-Goals**: Explicitly out of scope to prevent implementation drift
@@ -125,6 +126,8 @@ 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
+- 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 +143,10 @@ 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. Scope checklist
+5. Acceptance criteria
+6. Verification
+7. TL;DR
 
 ## Final Response
 
@@ -152,6 +156,7 @@ 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
 
 ## Quality Bar
 

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

@@ -49,10 +49,13 @@ 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.
@@ -96,6 +99,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 +147,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

@@ -116,7 +116,7 @@ function renderPullRequestBlock(result, emptyMessage) {
   return result.stdout || emptyMessage;
 }
 
-const SESSION_DIR_NAMES = ["sessions", "archived_sessions"];
+const CODEX_SESSION_DIR_NAMES = ["sessions", "archived_sessions"];
 const SECRET_PATTERNS = [
   /npm_[A-Za-z0-9]+/g,
   /github_pat_[A-Za-z0-9_]+/g,
@@ -132,6 +132,29 @@ function codexHome() {
   return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }
 
+function piAgentHome() {
+  return process.env.PI_AGENT_HOME || path.join(os.homedir(), ".pi", "agent");
+}
+
+function loadCodingAgent(projectRoot) {
+  const configPath = path.join(projectRoot, ".waypoint", "config.toml");
+  if (!existsSync(configPath)) {
+    return "codex";
+  }
+
+  const configText = readFileSync(configPath, "utf8");
+  const match = configText.match(/^\s*coding_agent\s*=\s*"(codex|pi)"\s*$/m);
+  return match?.[1] || "codex";
+}
+
+function codingAgentLabel(codingAgent) {
+  return codingAgent === "pi" ? "Pi" : "Codex";
+}
+
+function codingAgentHome(codingAgent) {
+  return codingAgent === "pi" ? piAgentHome() : codexHome();
+}
+
 function redactSecrets(text) {
   return SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, "[REDACTED]"), text);
 }
@@ -181,7 +204,7 @@ function collectSessionFiles(rootDir) {
   return files;
 }
 
-function extractMessageText(content) {
+function extractCodexMessageText(content) {
   if (!Array.isArray(content)) {
     return "";
   }
@@ -192,6 +215,17 @@ function extractMessageText(content) {
     .trim();
 }
 
+function extractPiMessageText(content) {
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content
+    .filter((block) => block?.type === "text")
+    .map((block) => (typeof block?.text === "string" ? block.text : ""))
+    .join("")
+    .trim();
+}
+
 function isBootstrapNoise(role, text) {
   return role === "user" && text.startsWith("# AGENTS.md instructions for ");
 }
@@ -213,11 +247,33 @@ function mergeConsecutiveTurns(turns) {
   return merged;
 }
 
-function parseSession(sessionFile, projectRoot) {
+function finalizeParsedSession(sessionFile, projectRoot, sessionId, sessionCwd, sessionStartedAt, rawTurns, compactionBoundaries) {
+  if (!sessionCwd || !isWithinPath(sessionCwd, projectRoot)) {
+    return null;
+  }
+
+  const selectedFromPreCompaction = compactionBoundaries.length > 0;
+  const relevantTurns = selectedFromPreCompaction ? rawTurns.slice(0, compactionBoundaries.at(-1)) : rawTurns;
+  const turns = mergeConsecutiveTurns(relevantTurns);
+  if (turns.length === 0) {
+    return null;
+  }
+
+  return {
+    path: sessionFile,
+    sessionId,
+    sessionCwd,
+    turns,
+    compactionCount: compactionBoundaries.length,
+    selectedFromPreCompaction,
+    sessionStartedAt,
+  };
+}
+
+function parseCodexSession(sessionFile, projectRoot) {
   let sessionId = null;
   let sessionCwd = null;
   let sessionStartedAt = null;
-  let compactionCount = 0;
   const rawTurns = [];
   const compactionBoundaries = [];
 
@@ -250,7 +306,6 @@ function parseSession(sessionFile, projectRoot) {
     }
 
     if (parsed.type === "compacted") {
-      compactionCount += 1;
       compactionBoundaries.push(rawTurns.length);
       continue;
     }
@@ -264,7 +319,7 @@ function parseSession(sessionFile, projectRoot) {
       continue;
     }
 
-    const text = redactSecrets(extractMessageText(parsed.payload?.content));
+    const text = redactSecrets(extractCodexMessageText(parsed.payload?.content));
     if (!text || isBootstrapNoise(role, text)) {
       continue;
     }
@@ -277,37 +332,90 @@ function parseSession(sessionFile, projectRoot) {
     });
   }
 
-  if (!sessionCwd || !isWithinPath(sessionCwd, projectRoot)) {
-    return null;
-  }
+  return finalizeParsedSession(sessionFile, projectRoot, sessionId, sessionCwd, sessionStartedAt, rawTurns, compactionBoundaries);
+}
 
-  const selectedFromPreCompaction = compactionBoundaries.length > 0;
-  const relevantTurns = selectedFromPreCompaction ? rawTurns.slice(0, compactionBoundaries.at(-1)) : rawTurns;
-  const turns = mergeConsecutiveTurns(relevantTurns);
-  if (turns.length === 0) {
-    return null;
+function parsePiSession(sessionFile, projectRoot) {
+  let sessionId = null;
+  let sessionCwd = null;
+  let sessionStartedAt = null;
+  const rawTurns = [];
+  const compactionBoundaries = [];
+
+  for (const line of readFileSync(sessionFile, "utf8").split("\n")) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (parsed.type === "session") {
+      if (typeof parsed.id === "string") {
+        sessionId = parsed.id;
+      }
+      if (typeof parsed.cwd === "string") {
+        sessionCwd = parsed.cwd;
+      }
+      if (typeof parsed.timestamp === "string") {
+        sessionStartedAt = parsed.timestamp;
+      }
+      continue;
+    }
+
+    if (parsed.type === "compaction") {
+      compactionBoundaries.push(rawTurns.length);
+      continue;
+    }
+
+    if (parsed.type !== "message") {
+      continue;
+    }
+
+    const role = parsed.message?.role;
+    if (role !== "user" && role !== "assistant") {
+      continue;
+    }
+
+    const text = redactSecrets(extractPiMessageText(parsed.message?.content));
+    if (!text || isBootstrapNoise(role, text)) {
+      continue;
+    }
+
+    rawTurns.push({
+      role,
+      text,
+      timestamp: parsed.timestamp || parsed.message?.timestamp || null,
+      messageCount: 1,
+    });
   }
 
-  return {
-    path: sessionFile,
-    sessionId,
-    sessionCwd,
-    turns,
-    compactionCount,
-    selectedFromPreCompaction,
-    sessionStartedAt,
-  };
+  return finalizeParsedSession(sessionFile, projectRoot, sessionId, sessionCwd, sessionStartedAt, rawTurns, compactionBoundaries);
 }
 
-function latestMatchingSession(projectRoot, threadIdOverride = null) {
+function latestMatchingSession(projectRoot, codingAgent, threadIdOverride = null) {
   const matches = [];
-  for (const dirName of SESSION_DIR_NAMES) {
-    for (const sessionFile of collectSessionFiles(path.join(codexHome(), dirName))) {
-      const parsed = parseSession(sessionFile, projectRoot);
+
+  if (codingAgent === "pi") {
+    for (const sessionFile of collectSessionFiles(path.join(piAgentHome(), "sessions"))) {
+      const parsed = parsePiSession(sessionFile, projectRoot);
       if (parsed) {
         matches.push(parsed);
       }
     }
+  } else {
+    for (const dirName of CODEX_SESSION_DIR_NAMES) {
+      for (const sessionFile of collectSessionFiles(path.join(codexHome(), dirName))) {
+        const parsed = parseCodexSession(sessionFile, projectRoot);
+        if (parsed) {
+          matches.push(parsed);
+        }
+      }
+    }
   }
 
   const requestedThreadId = threadIdOverride || process.env.CODEX_THREAD_ID || null;
@@ -331,7 +439,10 @@ function latestMatchingSession(projectRoot, threadIdOverride = null) {
 
 function writeRecentThread(contextDir, projectRoot, threadIdOverride = null) {
   const filePath = path.join(contextDir, "RECENT_THREAD.md");
-  const snapshot = latestMatchingSession(projectRoot, threadIdOverride);
+  const codingAgent = loadCodingAgent(projectRoot);
+  const agentLabel = codingAgentLabel(codingAgent);
+  const agentHome = codingAgentHome(codingAgent);
+  const snapshot = latestMatchingSession(projectRoot, codingAgent, threadIdOverride);
   const generatedAt = new Date().toString();
 
   if (!snapshot) {
@@ -342,7 +453,7 @@ function writeRecentThread(contextDir, projectRoot, threadIdOverride = null) {
         "",
         `Generated by \`${path.relative(projectRoot, fileURLToPath(import.meta.url))}\` on ${generatedAt}.`,
         "",
-        "No matching local Codex session was found for this repo yet.",
+        `No matching local ${agentLabel} session was found for this repo yet.`,
         "",
       ].join("\n"),
       "utf8"
@@ -358,10 +469,10 @@ function writeRecentThread(contextDir, projectRoot, threadIdOverride = null) {
         "",
         `Generated by \`${path.relative(projectRoot, fileURLToPath(import.meta.url))}\` on ${generatedAt}.`,
         "",
-        `- Source session: \`${path.relative(codexHome(), snapshot.path)}\``,
+        `- Source session: \`${path.relative(agentHome, snapshot.path)}\``,
         `- Session cwd: \`${snapshot.sessionCwd}\``,
         `- Compactions in source session: ${snapshot.compactionCount}`,
-        "- No compaction was found in the latest matching local Codex session, so there is nothing to restore into startup context yet.",
+        `- No compaction was found in the latest matching local ${agentLabel} session, so there is nothing to restore into startup context yet.`,
         "",
       ].join("\n"),
       "utf8"
@@ -370,7 +481,7 @@ function writeRecentThread(contextDir, projectRoot, threadIdOverride = null) {
   }
 
   const selectedTurns = snapshot.turns.slice(-MAX_RECENT_TURNS);
-  const relSessionPath = path.relative(codexHome(), snapshot.path);
+  const relSessionPath = path.relative(agentHome, snapshot.path);
   const lines = [
     "# Recent Thread",
     "",
@@ -435,6 +546,8 @@ function main() {
 
   const docsIndexPath = writeDocsIndex(projectRoot);
   const { outputPath: tracksIndexPath, activeTracks } = writeTracksIndex(projectRoot);
+  const codingAgent = loadCodingAgent(projectRoot);
+  const codingAgentLabelText = codingAgentLabel(codingAgent);
 
   const currentTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
   const currentLocalDatetime = new Date().toString();
@@ -577,7 +690,7 @@ function main() {
     `- \`${path.relative(projectRoot, uncommittedChangesPath)}\` — uncommitted change summary`,
     `- \`${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 Codex session for this repo`,
+    `- \`${path.relative(projectRoot, recentThreadPath)}\` — latest meaningful turns from the local ${codingAgentLabelText} session for this repo`,
     `- \`${path.relative(projectRoot, docsIndexPath)}\` — current docs index`,
     `- \`${path.relative(projectRoot, tracksIndexPath)}\` — current tracker index`,
     `- \`${path.relative(projectRoot, activeTrackersPath)}\` — active tracker summary`,

package/templates/managed-agents-block.md

@@ -69,18 +69,20 @@ 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, define done from the approved scope and acceptance criteria, not from your own sense that the system is already good enough.
 - 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,6 +92,7 @@ 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.