waypoint-codex 1.0.6 → 1.0.8

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.6",
+  "version": "1.0.8",
   "description": "Make Codex better by default with stronger planning, code quality, reviews, tracking, and repo guidance.",
   "license": "MIT",
   "type": "module",

package/templates/.agents/skills/execution-reset/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: execution-reset
+description: Recover momentum in long-running implementation plans when progress degrades into tiny local edits, repeated patching, or phase drift. Use when working from a referenced plan or roadmap and the current session is stalled, compacted, or no longer completing meaningful milestones. Reconstruct actual progress from the codebase, detect whether the current phase is stuck, and choose the next substantial work package that advances or completes the phase.
+---
+
+Rebuild state from the current codebase and the referenced plan, not from memory.
+
+1. Identify the active phase and its intended outcome.
+2. Inspect the current implementation and determine:
+   - complete
+   - partial
+   - missing
+   - broken or stale
+3. Decide whether execution is stalled.
+4. If stalled, restate the current phase as concrete system behavior.
+5. Pick exactly one substantial work package that will:
+   - complete a sub-milestone
+   - unblock the main dependency
+   - or finish the end-to-end path
+6. Execute that package.
+7. Re-check whether system capability materially increased.
+
+Use this output shape:
+
+## Execution Reset
+### Active Phase
+[phase]
+
+### Objective
+[what this phase must accomplish]
+
+### Actual Status
+- Complete: [...]
+- Partial: [...]
+- Missing: [...]
+- Broken/stale: [...]
+
+### Stall Diagnosis
+[why progress is not advancing]
+
+### Next Work Package
+[one substantial chunk]
+
+### Definition of Done
+[concrete completion conditions]
+
+### Plan Correction
+[only if the plan is locally stale]
+
+Rules:
+- Do not continue with micro-edits unless they directly unblock the chosen work package.
+- Do not polish incomplete phases.
+- Do not trust prior session context over the codebase.
+- Prefer end-to-end completion over local cleanup.
+- Revise the current phase if the original plan no longer matches reality, but do not rewrite the whole roadmap unless necessary.

package/templates/.agents/skills/execution-reset/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Execution Reset"
+  short_description: "Reset stalled plan execution and restore phase progress"
+  default_prompt: "Use $execution-reset with the active plan path and current phase to reset execution momentum and drive meaningful checklist progress."

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/plan-start/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: plan-start
+description: Start execution on an existing implementation plan in a fresh session. Use when a plan, roadmap, or phase list already exists and Codex needs to begin work on it without re-deriving everything from scratch. Rebuild context from the plan and current codebase, identify the active phase, choose the first meaningful work package, and begin execution.
+---
+
+Start from the plan and the current codebase, not from assumptions.
+
+1. Read the referenced plan.
+2. Inspect the current repository state relevant to that plan.
+3. Determine:
+   - which phases are already complete
+   - which phase is active
+   - what remains in the active phase
+4. Restate the active phase as concrete system behavior.
+5. Select the first substantial work package.
+6. Begin executing it immediately.
+
+Use this output shape:
+
+## Plan Start
+### Active Phase
+[phase]
+
+### Goal
+[what this phase must accomplish]
+
+### Current State
+- Complete: [...]
+- In progress: [...]
+- Missing: [...]
+
+### First Work Package
+[one substantial chunk]
+
+### Definition of Done
+[what makes this chunk complete]
+
+Rules:
+- Do not re-plan the whole project unless the plan is clearly stale.
+- Do not spend the session on broad summaries when execution can begin.
+- Do not start with cosmetic cleanup.
+- Prefer the work package that most directly advances the active phase.

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

@@ -105,7 +105,7 @@ Plans document your understanding. Include what matters for this task:
 - **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
+- **Phase checkpoints**: What verification, reviewer passes, tests, typechecks, builds, or manual QA must pass before moving to the next phase, with explicit cadence (targeted checks during implementation, full sweeps at phase-complete or pre-commit checkpoints unless the user asks otherwise)
 - **Grep gates**: Exact searches that must return clean before a phase is review-ready or complete
 - **Cleanup expectations**: What legacy or replaced paths must be removed before the work can be called complete
 - **Test cases**: For behavioral changes, include input -> expected output examples

package/templates/.agents/skills/replace-dont-layer/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: replace-dont-layer
+description: Prevent layering a new implementation path on top of an older one when the change should replace it. Use when modifying an existing flow, interface, abstraction, migration, or behavior and there is a risk of leaving both old and new paths alive. Determine whether the new path is additive, replacing, or transitional, and remove, redirect, or explicitly deprecate the old path as part of the same work.
+---
+
+Determine whether the requested change is additive, replacing, or transitional.
+
+Identify the old path, the new path, and where each is used.
+
+If the change is additive, keep both paths only if they serve clearly different intended roles.
+
+If the change is replacing, do not just add the new path. In the same work:
+- redirect callers to the new path
+- remove or deprecate the old path
+- delete obsolete conditionals, adapters, and compatibility glue
+- update tests to reflect the intended single path
+
+If the change is transitional:
+- keep duplication to the minimum necessary
+- make the temporary path explicit
+- attach a concrete removal condition
+- add a brief in-code comment only if it materially helps future cleanup, and make it specific rather than a vague TODO
+
+Before considering the work complete, check whether both old and new paths still exist without a clear reason. If they do, keep cleaning up.
+
+Rules:
+- Do not keep both paths alive by default.
+- Do not leave old logic in place just because removal feels riskier.
+- Do not call the work complete if the new path exists but the old one still silently handles traffic.
+- Prefer one clear path over split behavior.
+- If temporary coexistence is necessary, make the exit condition explicit.
+- Do not rely on vague TODO comments as the cleanup plan.

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

@@ -0,0 +1,49 @@
+---
+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. Before commit/final handoff, run the full checks required by the plan (for example full typecheck/test/build sweep) once, unless explicitly blocked or the user asks for a different cadence.
+9. 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 at the required cadence, including full pre-commit checks when required (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/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,14 @@ 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.
+Do not run full repo typecheck/test/build loops after every small edit by default. Use targeted checks during implementation and run full checks before commit or when the user explicitly asks.
+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 -->