waypoint-codex 1.0.5 → 1.0.7

package/README.md

@@ -255,6 +255,8 @@ docs_dirs = [
 Waypoint ships a strong default skill pack for real coding work:
 
 - `planning`
+- `foundational-redesign`
+- `verify-completeness`
 - `code-guide-audit`
 - `adversarial-review`
 - `frontend-ship-audit`
@@ -280,6 +282,8 @@ be used deliberately when the moment calls for them.
 
 The most important ones are:
 
+- `foundational-redesign` when the right move is a cleaner replacement that deletes legacy seams instead of patching around them
+- `verify-completeness` when you think implementation is done and need a strict final pass against approved scope, planned file changes, and completion gates
 - `code-guide-audit` when you want a code quality pass against your repo's
   standards and working rules
 - `backend-ship-audit` when backend work needs a deeper production-readiness

package/dist/src/core.js

@@ -22,6 +22,8 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
     ".agents/",
     ".agents/skills/",
     ".agents/skills/planning/",
+    ".agents/skills/foundational-redesign/",
+    ".agents/skills/verify-completeness/",
     ".agents/skills/code-guide-audit/",
     ".agents/skills/adversarial-review/",
     ".agents/skills/visual-explanations/",
@@ -49,6 +51,8 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
 ]);
 const SHIPPED_SKILL_NAMES = [
     "planning",
+    "foundational-redesign",
+    "verify-completeness",
     "code-guide-audit",
     "adversarial-review",
     "pr-review",

package/package.json

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

package/templates/.agents/skills/foundational-redesign/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: foundational-redesign
+description: Use for code changes, refactors, and migrations when quality matters. Treat the request as if it had been a foundational assumption from day one: inspect the current system, choose the clean target shape, implement direct replacement, and aggressively delete obsolete legacy code unless coexistence is explicitly required.
+---
+
+# Foundational Redesign
+
+Apply this skill when the change should leave the system cleaner, not just patched.
+
+## Core rule
+
+For each change, examine the existing system and redesign it into the most elegant solution that would have emerged if the change had been a foundational assumption from the start.
+
+## Execution loop
+
+1. Inspect the real current shape first: code paths, constraints, routed docs, and approved scope.
+2. Define the clean target shape that would exist if this requirement had always been true.
+3. Pick the smallest coherent redesign that reaches that target.
+4. If the redesign is non-trivial (architecture/interface/data-model impact), explain the redesign decision to the user and get agreement before executing it.
+5. Implement with direct replacement and aggressively delete legacy seams or compatibility scaffolding unless coexistence is explicitly required.
+6. Before stopping, re-read every changed file (mandatory), compare against the current plan and agreed scope, and continue working if any gap remains.
+
+## Output contract for non-trivial changes
+
+Summarize:
+
+- current shape
+- target shape
+- redesign decision confirmed with user (for non-trivial redesign)
+- what legacy code was deleted
+- what verification was run
+- any remaining gap to close
+
+## Gotchas
+
+- Do not preserve legacy branches by default "just in case".
+- Do not call work complete before the mandatory final file re-read.
+- Do not stop at partial scope; continue until approved scope is actually satisfied.

package/templates/.agents/skills/foundational-redesign/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Foundational Redesign"
+  short_description: "Redesign from first principles and delete legacy seams"
+  default_prompt: "Use $foundational-redesign for this change: inspect the existing system, design the clean target shape as if this requirement were foundational from the start, replace directly, and aggressively remove obsolete legacy code unless coexistence is explicitly required."

package/templates/.agents/skills/verify-completeness/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: verify-completeness
+description: Use when implementation appears done and before reporting completion. Re-read the original plan and agreed scope, re-read files that were supposed to be created or changed, verify no approved scope was reduced or skipped, and continue working until the scope is truly complete.
+---
+
+# Verify Completeness
+
+Use this skill at final closeout, right before you would report the work complete.
+
+## Required verification loop
+
+1. Re-read the original plan and the latest agreed scope before deciding status.
+2. Re-read `ACTIVE_PLANS.md` and `WORKSPACE.md` for current checklist, phase, blockers, and verification state.
+3. Build the expected file set from plan/scope: files that were supposed to be created, modified, or deleted.
+4. Re-read those files directly. This final re-read is mandatory even if they were read earlier in the session.
+5. Compare expected scope vs actual outcome and list any missing or partially completed items.
+6. Run a scope-discipline pass: identify additions that were not requested or approved. Remove/simplify them before completion, or explicitly ask the user to approve keeping them.
+7. Run a cleanup pass on changed files: remove duplicated logic, unnecessary abstractions/files, and low-value comments that create maintenance bloat.
+8. If any approved item is missing, incomplete, or silently deferred, do not report completion. Continue working until the agreed scope is fully satisfied or discuss a scope change explicitly.
+
+## Completion gate
+
+You can report complete only when all are true:
+
+- approved scope items are done
+- planned file changes match reality
+- verification/checkpoints required by the plan were run (or explicitly called out as blocked)
+- no hidden scope reduction occurred
+- no unapproved scope expansion remains
+- no obvious duplication or avoidable bloat remains in touched files
+
+## Output contract
+
+Before final status, summarize briefly:
+
+- scope reviewed
+- files re-read for final verification
+- completed items
+- removed unapproved extras or bloat cleanup applied
+- remaining gaps (if any)
+- next action (continue execution or complete)
+
+## Gotchas
+
+- Do not mark complete from memory; verify by re-reading files.
+- Do not treat partial completion as done.
+- Do not skip plan checkpoints just because code compiles.
+- Do not keep speculative extras "for future-proofing" unless the user approved them.

package/templates/.agents/skills/verify-completeness/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Verify Completeness"
+  short_description: "Run a strict final scope and file verification pass"
+  default_prompt: "Use $verify-completeness now: re-read the approved plan and scope, re-read all files that were supposed to change, remove unapproved extras and obvious bloat, verify nothing was dropped, and keep working if any approved scope item is still incomplete."

package/templates/.gitignore.snippet

@@ -4,6 +4,8 @@
 .codex/agents/code-health-reviewer.toml
 .codex/agents/plan-reviewer.toml
 .agents/skills/planning/
+.agents/skills/foundational-redesign/
+.agents/skills/verify-completeness/
 .agents/skills/work-tracker/
 .agents/skills/docs-sync/
 .agents/skills/code-guide-audit/

package/templates/.waypoint/scripts/build-docs-index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -101,19 +101,28 @@ function parseFrontmatter(filePath) {
   return { summary, readWhen };
 }
 
-function walkDocs(projectRoot, currentDir, output) {
-  for (const entry of readdirSync(currentDir)) {
-    const fullPath = path.join(currentDir, entry);
-    const stat = statSync(fullPath);
-    if (stat.isDirectory()) {
-      if (SKIP_DIRS.has(entry)) {
+function walkDocs(projectRoot, currentDir, output, visitedDirs) {
+  const resolvedCurrentDir = realpathSync(currentDir);
+  if (visitedDirs.has(resolvedCurrentDir)) {
+    return;
+  }
+  visitedDirs.add(resolvedCurrentDir);
+
+  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) {
+      continue;
+    }
+
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) {
         continue;
       }
-      walkDocs(projectRoot, fullPath, output);
+      walkDocs(projectRoot, fullPath, output, visitedDirs);
       continue;
     }
 
-    if (!entry.endsWith(".md") || SKIP_NAMES.has(entry)) {
+    if (!entry.isFile() || !entry.name.endsWith(".md") || SKIP_NAMES.has(entry.name)) {
       continue;
     }
 
@@ -134,7 +143,7 @@ function collectDocEntries(projectRoot, docsDir) {
   const entries = [];
 
   if (existsSync(docsDir)) {
-    walkDocs(projectRoot, docsDir, entries);
+    walkDocs(projectRoot, docsDir, entries, new Set());
   }
 
   return entries;

package/templates/managed-agents-block.md

@@ -3,6 +3,8 @@
 
 These instructions are mandatory in this repo and override weaker generic guidance unless the user says otherwise.
 
+The most important rule: For each change, examine the existing system and redesign it into the most elegant solution that would have emerged if the change had been a foundational assumption from the start.
+
 Waypoint owns only the text inside these `waypoint:start/end` markers.
 If you need repo-specific AGENTS instructions, write them outside this managed block.
 Do not put durable repo guidance inside the managed block, because `waypoint init` may replace it during upgrades.
@@ -19,13 +21,12 @@ This repo's default artifact flow is:
 
 Run the Waypoint bootstrap only at session start, after compaction, or when the user explicitly asks for it:
 1. Run `node .waypoint/scripts/prepare-context.mjs`
-2. Read `AGENTS.md`
-3. Read `.waypoint/WORKSPACE.md`
-4. Read `.waypoint/ACTIVE_PLANS.md`
-5. Read `.waypoint/docs/code-guide.md`
-6. Read `.waypoint/DOCS_INDEX.md`
-7. Read `.waypoint/context/SNAPSHOT.md`
-8. Read `.waypoint/context/RECENT_THREAD.md`
+2. Read `.waypoint/WORKSPACE.md`
+3. Read `.waypoint/ACTIVE_PLANS.md`
+4. Read `.waypoint/docs/code-guide.md`
+5. Read `.waypoint/DOCS_INDEX.md`
+6. Read `.waypoint/context/SNAPSHOT.md`
+7. Read `.waypoint/context/RECENT_THREAD.md`
 
 Investigate the actual code, docs, and routed context before you answer detailed questions or start implementation.
 Prefer visible repo state over hidden assumptions or chat-only memory.
@@ -37,12 +38,13 @@ Once the user approves a plan or tells you to proceed, that approved scope is th
 `WORKSPACE.md` is the live state file. `ACTIVE_PLANS.md` is the active execution checklist. Keep them current when state, blockers, or verification materially change.
 When durable behavior changes, update the relevant docs during the work. When live execution state changes, update `WORKSPACE.md` or `ACTIVE_PLANS.md` during the work, not only at the end.
 
-Refactor and migration default: use direct replacement, not compatibility scaffolding, unless the user or project docs explicitly require coexistence. Delete obsolete code aggressively and finish the phase back to green. Large destructive edits are allowed when they are the clearest path to the approved target state.
+When changing code, do not hesitate to aggressively delete legacy code and rebuild the system when that is the clearest path to accomplishing the goal. Prefer clean replacement over compatibility scaffolding unless the user or project docs explicitly require coexistence.
 
 Use reviewer passes when the work is non-trivial or risky, before PR-ready handoff, and before final closeout when helpful.
 
 Keep communication concise. Lead with the answer, diagnosis, decision, or next step. Explain the diagnosis before implementation when the cause, tradeoffs, or solution shape are not already obvious.
 
 Verification should match the real risk surface. Inspect real UI for UI work when practical, and run code or inspect real output for backend or script work when practical.
-Before reporting completion, verify the result yourself when reasonably possible, reread `ACTIVE_PLANS.md` and `WORKSPACE.md`, and compare reality against the approved scope. If the work is not actually complete, keep going.
+Before stopping, check the current plan and agreed scope, then re-read the files you changed to confirm they match the intended result. This final file re-read is mandatory even if you already read them earlier in the session. If the goal is not achieved, continue working.
+When work is non-trivial and you are about to report completion, run `verify-completeness` for a final scope-and-files closeout pass, including unapproved-scope and bloat cleanup checks.
 <!-- waypoint:end -->