waypoint-codex 0.17.0 → 0.18.1

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:
@@ -269,6 +278,7 @@ Waypoint ships a strong default skill pack for real coding work:
 - `workspace-compress`
 - `pre-pr-hygiene`
 - `pr-review`
+- `agi-help`
 
 These are repo-local, so the workflow travels with the project.
 

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.17.0",
+  "version": "0.18.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/agi-help/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: agi-help
+description: Prepare a complete external handoff package for GPT-5.4-Pro in ChatGPT when a task is unusually high-stakes, ambiguous, leverage-heavy, or quality-sensitive and one excellent answer is worth a slower manual loop. Use for greenfield project starts, major refactors, architecture rethinks, migration strategy, big-feature planning, hard product or strategy decisions, and other work where the external model needs full relevant context because it has no access to the repo, files, history, or local tools.
+---
+
+# AGI-Help
+
+Use this skill to prepare a high-quality manual handoff for GPT-5.4-Pro.
+
+GPT-5.4-Pro is an external thinking partner, not a connected coding agent. It cannot see the repo, local files, prior discussion, current state, or failed attempts unless you package that context for Mark to send manually in ChatGPT.
+
+The job of this skill is to create a complete handoff bundle that gives GPT-5.4-Pro the best possible chance of producing one exceptional answer.
+
+## What This Skill Owns
+
+This skill owns the preparation step:
+
+- decide whether GPT-5.4-Pro is justified for this task
+- collect all relevant context in full
+- copy the relevant files into a temporary handoff folder
+- write a strong prompt for an external model with zero local context
+- tell Mark exactly what to send
+- stop and wait for the external response
+
+This skill does **not** send anything itself.
+
+## When To Use This Skill
+
+Use AGI-Help when:
+
+- the task is high-stakes and a weak answer would be costly
+- one strong answer is more valuable than a fast back-and-forth loop
+- deep synthesis, architecture judgment, strategy, or reframing quality matters more than local tool execution speed
+- the task is large enough or important enough that a manual GPT-5.4-Pro pass is worth 20-50 minutes
+
+Typical examples:
+
+- starting a project from scratch
+- major refactors or system redesigns
+- architecture or migration strategy
+- planning a large feature or multi-phase initiative
+- resolving hard tradeoffs across product, UX, engineering, and operations
+- reshaping positioning, messaging, or strategy where synthesis quality matters a lot
+- any other difficult task where Mark explicitly wants the strongest available single response
+
+## When Not To Use This Skill
+
+Do not use it for:
+
+- small or routine edits
+- local debugging where filesystem access matters more than abstract reasoning
+- simple implementation tasks that are already clear
+- requests where a normal answer or normal planning pass is sufficient
+
+## Output
+
+Create a handoff bundle at one of these locations:
+
+- prefer `tmp/agi-help/<timestamp>/` inside the current workspace when that is practical
+- otherwise use `~/.codex/tmp/agi-help/<timestamp>/`
+
+The bundle should contain:
+
+```text
+tmp/agi-help/<timestamp>/
+├── prompt.md
+├── manifest.md
+├── request-summary.md
+└── files/
+    └── ...copied source files...
+```
+
+### prompt.md
+
+The exact prompt Mark should paste into GPT-5.4-Pro.
+
+### manifest.md
+
+A file-by-file list of what is included and why each file matters.
+
+### request-summary.md
+
+A short operator note for Mark that explains:
+
+- why AGI-Help was used here
+- what to paste
+- which files to attach
+- what kind of answer to ask for
+
+### files/
+
+Copies of every relevant file that should be attached.
+
+## Core Rule: Include All Relevant Context
+
+Do not optimize for brevity by dropping relevant material.
+
+If a file is relevant, include it in full.
+If multiple files are relevant, include all of them.
+If prior plans, failed attempts, docs, architecture notes, or state files materially change the answer, include them too.
+
+The bottleneck here is not token thrift inside Codex. The bottleneck is giving GPT-5.4-Pro enough real context to reason well.
+
+Curate relevance aggressively. Compress relevance only by excluding things that truly do not matter.
+Do **not** compress relevant context just because it is long.
+
+## Workflow
+
+### 1. Justify AGI-Help
+
+Before building the bundle, write 3-6 bullets in `request-summary.md` explaining why GPT-5.4-Pro is warranted here.
+
+Focus on why:
+
+- the task is unusually important, difficult, or leverage-heavy
+- the answer needs deep synthesis, design judgment, or strategy
+- normal local iteration is likely to be weaker than one high-quality external pass
+
+### 2. Reconstruct The Full Situation
+
+Assume GPT-5.4-Pro knows nothing.
+
+Collect the context it would need to reason well, such as:
+
+- what the project, company, system, or situation is
+- who the users are
+- what the current state is
+- what we want to achieve
+- why this matters now
+- what constraints exist
+- what tradeoffs matter
+- what has already been tried
+- what is blocked, unclear, risky, or contentious
+- what a successful answer would help us decide or do next
+
+This is not a fixed checklist. Include whatever materially changes the quality of the answer.
+
+### 3. Copy The Relevant Files
+
+Create `files/` and copy in the relevant source material.
+
+Examples of relevant files:
+
+- core implementation files
+- architecture docs
+- plans
+- tracker files
+- config files
+- failing or partial implementations
+- screenshots or exported artifacts when available through the current tool surface
+- strategy docs, briefs, drafts, notes, or prior outputs that define the problem
+
+Preserve relative structure inside `files/` when it helps orientation.
+
+### 4. Write manifest.md
+
+For each included file, list:
+
+- copied path inside the bundle
+- original path
+- why the file matters
+- any brief note about how GPT-5.4-Pro should interpret it
+
+Keep this concise but useful.
+
+### 5. Write prompt.md
+
+Write the prompt as if briefing a world-class expert who has zero implicit context.
+
+The prompt should usually include:
+
+1. **Role / framing**
+   - who GPT-5.4-Pro should act as for this task
+2. **Project or situation context**
+   - what this is, who it serves, and how to think about it
+3. **Current state**
+   - what exists today and what is happening now
+4. **Objective**
+   - what we need help with
+5. **Constraints and tradeoffs**
+   - technical, product, operational, organizational, or personal constraints
+6. **What has already been tried or considered**
+   - prior attempts, rejected options, partial work, or known problems
+7. **Attached materials**
+   - tell it that files are attached and should be read before answering
+8. **Specific request**
+   - the concrete question or task
+9. **Desired output shape**
+   - exactly how the answer should be structured
+
+## Prompt Writing Rules
+
+### Be Exhaustive About Relevant Context
+
+Write enough that GPT-5.4-Pro can reason without guessing the basics.
+
+### Ask For A Concrete Deliverable
+
+Do not ask vague questions like "thoughts?"
+
+Ask for something concrete, such as:
+
+- a recommendation with reasoning
+- a detailed architecture proposal
+- a refactor or migration plan
+- a critique of the current direction
+- a better strategy or positioning approach
+- a decision memo with tradeoffs and risks
+
+### Specify The Output Format
+
+Tell GPT-5.4-Pro how to respond.
+
+Good example shapes:
+
+- recommendation first, then reasoning, then alternatives, then risks, then implementation plan
+- diagnosis, root causes, proposed direction, concrete changes, failure modes, validation plan
+- executive summary, strategic recommendation, tradeoffs, suggested next steps, open questions
+
+### Tell It To Read The Attachments First
+
+Explicitly instruct it to review the attached files before answering.
+
+## Final Handoff To Mark
+
+When the bundle is ready, report:
+
+- the bundle path
+- why AGI-Help was used here
+- the exact file to paste: `prompt.md`
+- which files to attach from `files/`
+- any note about what kind of response will be most useful when Mark pastes it back
+
+Do not continue into implementation as if GPT-5.4-Pro already answered.
+Stop and wait for Mark.
+
+## After Mark Returns With The Response
+
+Once Mark pastes the GPT-5.4-Pro response back into the conversation:
+
+- treat it as a strong external input, not automatic truth
+- compare it against the actual repo and current state
+- identify where it fits reality, where it conflicts, and what needs adaptation
+- turn the useful parts into a concrete plan, decision, or implementation path
+
+## Gotchas
+
+- Do not use this skill just because a task is non-trivial. Use it when answer quality is worth the slower manual loop.
+- Do not assume GPT-5.4-Pro knows the repo, current state, history, or constraints.
+- Do not omit relevant files just because they are large.
+- Do not give GPT-5.4-Pro a vague prompt when a concrete deliverable is needed.
+- Do not bury the actual question under context; the prompt needs both deep context and a crisp ask.
+- Do not continue as though the external answer has already arrived.
+
+## Keep This Skill Sharp
+
+- Tighten the trigger description if it fires on normal planning or routine coding tasks.
+- Add new gotchas when a GPT-5.4-Pro handoff fails because context, constraints, or the requested output shape were incomplete.
+- If the same bundle structure or prompt sections keep recurring, strengthen this skill around those patterns instead of rediscovering them each time.

package/templates/.agents/skills/agi-help/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AGI-Help"
+  short_description: "Prepare a full GPT-5.4-Pro handoff package for high-stakes work"
+  default_prompt: "Use $agi-help when this task is unusually high-stakes, ambiguous, or leverage-heavy and the best next move is to prepare a complete GPT-5.4-Pro handoff package with full relevant context, copied source files, and a strong external prompt for Mark to send manually in ChatGPT."

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`,