waypoint-codex 1.0.12 → 1.0.14

package/dist/src/core.js

@@ -9,6 +9,7 @@ const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
 const DEFAULT_PLANS_DIR = ".waypoint/plans";
 const DEFAULT_WORKSPACE = ".waypoint/WORKSPACE.md";
 const DEFAULT_ACTIVE_PLANS = ".waypoint/ACTIVE_PLANS.md";
+const ENABLE_MANAGED_GITIGNORE = false;
 const GITIGNORE_WAYPOINT_START = "# Waypoint state";
 const GITIGNORE_WAYPOINT_END = "# End Waypoint state";
 const GITIGNORE_SKILLS_PLACEHOLDER = "__WAYPOINT_SKILL_IGNORES__";
@@ -25,8 +26,6 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
     ".agents/skills/planning/",
     ".agents/skills/foundational-redesign/",
     ".agents/skills/verify-completeness/",
-    ".agents/skills/code-guide-audit/",
-    ".agents/skills/adversarial-review/",
     ".agents/skills/visual-explanations/",
     ".agents/skills/frontend-context-interview/",
     ".agents/skills/backend-context-interview/",
@@ -54,8 +53,6 @@ const SHIPPED_SKILL_NAMES = [
     "planning",
     "foundational-redesign",
     "verify-completeness",
-    "code-guide-audit",
-    "adversarial-review",
     "pr-review",
     "agi-help",
     "frontend-context-interview",
@@ -403,7 +400,9 @@ export function initRepository(projectRoot, options) {
     upsertManagedBlock(path.join(projectRoot, "AGENTS.md"), readTemplate("managed-agents-block.md"));
     scaffoldSkills(projectRoot);
     scaffoldOptionalCodex(projectRoot);
-    appendGitignoreSnippet(projectRoot);
+    if (ENABLE_MANAGED_GITIGNORE) {
+        appendGitignoreSnippet(projectRoot);
+    }
     const docsIndexPath = path.join(projectRoot, config.docs_index_file ?? DEFAULT_DOCS_INDEX);
     const docsIndex = renderDocsIndex(projectRoot, docsIndexSections(projectRoot, config));
     writeText(docsIndexPath, `${docsIndex.content}\n`);

package/package.json

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

package/templates/.agents/skills/edit-at-the-right-layer/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: edit-at-the-right-layer
+description: Make changes at the true ownership layer instead of patching nearby call sites. Use when implementing features, bug fixes, or refactors where behavior should be corrected at its source of truth rather than through wrappers, flags, or duplicated logic.
+---
+
+Identify where this behavior is actually owned, then edit there.
+
+## Goal
+
+Fix or extend behavior at the layer that owns the contract so future changes stay local and coherent.
+
+## Workflow
+
+1. Trace the path from entry point to ownership.
+2. Identify the contract owner (domain/service/model/state boundary) for the requested behavior.
+3. Prefer changing that owner over adding patches in callers, controllers, views, adapters, or wrappers.
+4. Remove compensating logic that became unnecessary after the ownership-layer fix.
+5. Update boundary tests at the owning layer and only add higher/lower-layer tests when they cover a distinct risk.
+
+## Rules
+
+- Do not patch symptoms in outer layers when the source-of-truth layer can be fixed directly.
+- Do not add pass-through wrappers or compatibility branches as a default response.
+- Do not duplicate the same rule across multiple layers.
+- If a temporary cross-layer patch is unavoidable, mark it as transitional and remove it in the same phase whenever possible.
+- Prefer one clear owner per rule.

package/templates/.agents/skills/edit-at-the-right-layer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Edit At The Right Layer"
+  short_description: "Apply changes at the true ownership layer"
+  default_prompt: "Use $edit-at-the-right-layer to locate the source-of-truth ownership layer, implement the change there, and remove outer-layer patches or duplicated logic."

package/templates/.agents/skills/legibility-pass/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: legibility-pass
+description: Improve code legibility within a defined scope without changing intended behavior. Use when code is correct but hard to read, reason about, or safely modify. Focus on making intent, control flow, state, boundaries, and important behavior easier to see through better naming, clearer structure, reduced indirection, and simpler local reasoning.
+---
+
+Refactor the given scope to make the current truth easier to see.
+
+Preserve behavior unless the user asked for functional change.
+
+Focus on:
+- clearer names for modules, functions, variables, and states
+- making the main flow easy to follow
+- making failure paths and edge conditions explicit
+- reducing indirection that hides important behavior
+- making state, contracts, and boundaries easier to understand
+- collapsing unnecessary wrappers or pass-through helpers
+- improving local reasoning so a reader needs less cross-referencing
+
+Within the requested scope:
+1. Identify the parts that are hardest to understand or easiest to misread.
+2. Improve naming so intent is obvious.
+3. Restructure code so the main path is visible and important branches are easy to spot.
+4. Make hidden assumptions, state transitions, and invariants more explicit.
+5. Remove low-value indirection that makes behavior harder to trace.
+6. Keep comments rare; prefer making the code itself explain the behavior.
+7. Add a brief clarifying comment only when the underlying rule or constraint is not obvious from the code alone.
+
+Rules:
+- Do not preserve confusing structure just because it already exists.
+- Do not add abstractions that make reading harder.
+- Do not replace clear code with clever code.
+- Do not rely on comments to explain code that should be rewritten instead.
+- Prefer fewer mental hops.
+- Prefer one obvious reading of the code over multiple plausible interpretations.

package/templates/.agents/skills/legibility-pass/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Legibility Pass"
+  short_description: "Improve readability without changing behavior"
+  default_prompt: "Use $legibility-pass on the current scope to improve naming, control-flow clarity, and local reasoning while preserving intended behavior."

package/templates/.agents/skills/make-invariants-explicit/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: make-invariants-explicit
+description: Surface and enforce critical invariants directly in code so invalid states are hard to represent and easy to detect. Use when behavior depends on assumptions about data shape, ordering, state transitions, permissions, or lifecycle constraints.
+---
+
+Review the requested scope and identify assumptions that correctness depends on.
+
+Look for assumptions such as:
+- a value is always present
+- operations happen in a specific order
+- a transition cannot occur from a certain state
+- a record is unique
+- a side effect only happens once
+- retries or duplicate delivery cannot happen
+- a caller already validated something important
+- a user or actor is authorized because an earlier layer checked it
+- external data already has the expected shape
+
+If an important invariant is only implied, make it explicit.
+
+Make invariants explicit using the strongest fitting mechanism:
+- boundary validation
+- state modeling
+- type constraints
+- schema constraints
+- uniqueness or foreign-key rules
+- idempotency guards
+- explicit transition checks
+- assertions or defensive guards at the true correctness boundary
+
+When correcting violations:
+- encode the invariant where it is naturally enforced
+- remove duplicate or scattered half-checks when one authoritative check is better
+- keep the invariant visible in the code structure
+- preserve intended behavior unless the user asked for a change in behavior
+
+Rules:
+- Do not rely on hidden assumptions for correctness.
+- Do not assume earlier layers already enforced critical invariants unless that contract is explicit and stable.
+- Do not scatter partial checks across many places when one authoritative enforcement point exists.
+- Prefer explicit invalid-state rejection over ambiguous normalization.
+- If the invariant matters for correctness, make it visible in code, types, schema, or state transitions.

package/templates/.agents/skills/make-invariants-explicit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Make Invariants Explicit"
+  short_description: "Expose and enforce critical invariants"
+  default_prompt: "Use $make-invariants-explicit to identify hidden assumptions, encode them as explicit invariants at boundaries, and add focused validation/tests for high-risk rules."

package/templates/.agents/skills/verify-codebase-coherence/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: verify-codebase-coherence
+description: Verify that completed work fits the existing codebase instead of introducing unnecessary parallel patterns. Use after implementation within a defined scope to detect avoidable new components, utilities, abstractions, state paths, design patterns, or conventions that should have reused or extended existing ones. Correct the work so it integrates coherently with the repo's existing architecture, components, naming, contracts, and design language.
+---
+
+Review the completed work in the requested scope and check whether it fits the existing codebase.
+
+Look for unnecessary parallel patterns such as:
+- new frontend components where an existing component should have been reused or extended
+- new helpers, hooks, utilities, or adapters that duplicate an existing pattern
+- new state paths or data flows that bypass the established architecture
+- new naming, file structure, or API shapes that do not match nearby conventions
+- one-off design, styling, or interaction patterns that do not fit the app
+- local abstractions that solve a problem the codebase already has a standard way to solve
+
+Before keeping a new construct, check whether the repo already has:
+- a reusable component or composition pattern
+- an established state or data-fetching pattern
+- a standard boundary for validation, formatting, permissions, or persistence
+- an existing utility or shared contract
+- a nearby feature that should be extended instead of bypassed
+
+If the work introduced a parallel pattern without a clear reason, fix it. Do not just report it.
+
+When correcting violations:
+- reuse or extend existing components, utilities, and patterns where appropriate
+- remove unnecessary one-off abstractions or duplicate paths
+- align naming, structure, and interfaces with nearby code
+- preserve intended behavior unless the user asked for a behavioral change
+
+Rules:
+- Do not create a new component, utility, hook, adapter, or pattern if the repo already has one that should be reused or extended.
+- Do not fork the design language or architecture for a local feature without a clear reason.
+- Do not bypass established patterns just because creating a new path is faster.
+- Prefer extending the existing system over creating a parallel mini-system.
+- If divergence is necessary, it must be justified by a real requirement, not convenience.

package/templates/.agents/skills/verify-codebase-coherence/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Verify Codebase Coherence"
+  short_description: "Check architectural and structural coherence"
+  default_prompt: "Use $verify-codebase-coherence to audit the current scope for architectural coherence, boundary consistency, duplication, and drift before final handoff."

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

@@ -16,10 +16,11 @@ Use this skill at final closeout, right before you would report the work complet
 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. Run a file-footprint sanity pass: collapse avoidable tiny-file fragmentation and keep code that changes together in the same place when boundary/reuse/size reasons are weak.
-9. Run a test-signal sanity pass: remove redundant or brittle tests and keep the smallest high-signal set that still protects the contract.
-10. 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.
-11. 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.
+8. If changed code is still hard to read or reason about, run `legibility-pass` before completion and apply the resulting readability cleanup.
+9. Run a file-footprint sanity pass: collapse avoidable tiny-file fragmentation and keep code that changes together in the same place when boundary/reuse/size reasons are weak.
+10. Run a test-signal sanity pass: remove redundant or brittle tests and keep the smallest high-signal set that still protects the contract.
+11. 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.
+12. 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
 
@@ -42,6 +43,7 @@ Before final status, summarize briefly:
 - files re-read for final verification
 - completed items
 - removed unapproved extras or bloat cleanup applied
+- legibility cleanup applied (if run)
 - file-collapsing or test-pruning done during sanity passes
 - remaining gaps (if any)
 - next action (continue execution or complete)

package/templates/.agents/skills/adversarial-review/SKILL.md

@@ -1,86 +0,0 @@
----
-name: adversarial-review
-description: Second-pass closeout review for a non-trivial implementation slice. Use when risky work needs a deliberate final review before being called done. This skill scopes the slice, runs the right reviewer agents and code-guide checks, fixes meaningful findings, and repeats until only optional polish remains.
----
-
-# Adversarial Review
-
-Use this skill when you explicitly want a closeout-grade second pass before calling a non-trivial slice done or ready to ship.
-
-This skill coordinates the specialist reviewers, keeps the scope tight, waits as long as needed, fixes meaningful findings, and reruns fresh review rounds until the remaining feedback is only optional polish or no findings at all.
-
-## When To Skip This Skill
-
-- Skip it for tiny obvious edits where launching the full closeout loop would be noise.
-- Skip it for normal debugging or investigation where the user needs diagnosis and forward motion more than formal ship-readiness.
-- Skip it for pre-implementation planning; that is `plan-reviewer` territory.
-- Skip it for active PR comment back-and-forth; use `pr-review` for that workflow.
-- Skip it when the user wants a one-off targeted coding-guide check and not the full closeout loop; use `code-guide-audit` directly in that case.
-
-## Step 1: Define The Reviewable Slice
-
-- Resolve the exact slice you are trying to close out before launching reviewers.
-- Prefer a recent self-authored commit when one cleanly represents the slice.
-- Otherwise use the current changed files, diff, or feature path.
-- Pass the reviewers the same concrete scope anchor, plus a short plain-English summary of what changed.
-- If the scope is muddy, tighten it before review instead of asking the reviewers to figure it out from an entire worktree.
-
-## Step 2: Launch The Required Reviewers
-
-- Spawn `code-reviewer` for every non-trivial implementation slice.
-- Spawn `code-health-reviewer` when the change is medium or large, especially when it adds structure, duplicates logic, or introduces new abstractions.
-- Run `code-guide-audit` on the same scoped slice as part of the closeout loop.
-- Launch the reviewer agents with `fork_context: false`, `model: gpt-5.4`, and `reasoning_effort: high` unless the user explicitly asked for something else.
-- Tell the reviewer agents what changed, what scope anchor to use, and which files or feature area represent the slice under review.
-- When both reviewer agents apply, launch them in parallel.
-
-## Step 3: Wait For The Round To Finish
-
-- Wait for every required reviewer result, no matter how long it takes.
-- Do not interrupt slow reviewer agents just because they are still running.
-- Do not call the work done while a required reviewer round is still in flight.
-- Read the full reviewer outputs before deciding what to fix.
-
-## Step 4: Fix Meaningful Findings
-
-- Fix real correctness, regression, maintainability, and code-guide issues.
-- Rerun the most relevant verification for the changed area after the fixes.
-- If a reviewer comment is only a nit or clearly optional polish, note that distinction and do not keep reopening the loop just to satisfy minor taste differences.
-- If a finding changes durable behavior or repo memory, update the relevant docs and workspace state before the next round.
-
-## Step 5: Close The Old Review Round
-
-- Treat `code-reviewer` and `code-health-reviewer` as one-shot reviewer agents.
-- After you have read a reviewer result, close that reviewer thread.
-- If another pass is needed later, spawn a fresh reviewer instead of reusing the old thread.
-
-## Step 6: Repeat Until The Slice Is Actually Clear
-
-- Start a fresh round whenever you made meaningful fixes in response to the previous round.
-- Reuse the same scope anchor when it still represents the slice cleanly; otherwise hand the new round the updated changed-file set or follow-up commit.
-- Rerun `code-guide-audit` when the fixes materially changed guide-relevant behavior or when the previous round surfaced guide-related issues.
-- Stop only when no meaningful findings remain. Optional polish and obvious nitpicks do not block closeout.
-
-## Step 7: Report The Closeout State
-
-Summarize:
-
-- what scope was reviewed
-- which reviewers ran
-- what meaningful issues were fixed
-- what verification ran
-- whether the slice is now clear or what still blocks it
-
-## Gotchas
-
-- Fresh reviewer rounds matter. If you make meaningful fixes, do not treat older reviewer findings as if they still describe the current code.
-- Green local tests are not enough if required reviewer threads are still running. Wait for the actual reviewer outputs before calling the slice done.
-- Close reviewer agents after each round. Reusing a stale reviewer thread weakens the signal and blurs which code state the findings apply to.
-- When this loop changes repo-health or upgrade behavior, test real old-repo edge cases, not just fresh-init cases.
-- If a reviewer result is clean, it should still name the key paths and related files it checked. A "looks fine" skim is not a real closeout pass.
-
-## Keep This Skill Sharp
-
-- After meaningful runs, add new gotchas when the same review-loop failure, stale-review mistake, or repo-upgrade edge case is likely to happen again.
-- Tighten the description if the skill fires too broadly or misses real prompts like "final review pass" or "before we call this done."
-- If the loop keeps re-creating the same helper logic or review instructions, move that reusable logic into the skill or its supporting resources instead of leaving it in chat.

package/templates/.agents/skills/adversarial-review/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Adversarial Review"
-  short_description: "Run a deliberate second-pass closeout review"
-  default_prompt: "Use $adversarial-review when this non-trivial implementation slice needs a deliberate final review loop with reviewer agents and code-guide checks before we call it done."

package/templates/.agents/skills/code-guide-audit/SKILL.md

@@ -1,86 +0,0 @@
----
-name: code-guide-audit
-description: Audit a scoped implementation slice against the code guide and report only guide-related violations or risks. Use for coding-guide compliance checks on explicit behavior, root-cause fixes, boundary validation, security, concurrency, accessibility, performance, and future legibility.
----
-
-# Code Guide Audit
-
-Use this skill for a targeted audit against the coding guide, not for a whole-repo hygiene sweep.
-
-This skill owns one job: inspect the specific code the user points at, map it against the coding guide, and report only guide-related findings in that scope.
-
-## When Not To Use This Skill
-
-- Skip it for broad ship-readiness review; use a ship-audit workflow for that.
-- Skip it for generic bug finding or regression review that is not specifically about the coding guide.
-- Skip it for active PR comment triage; use `pr-review` for that loop.
-- Skip it for repo-wide cleanup unless the user explicitly asked for a repo-wide coding-guide audit.
-
-## Step 1: Load The Right Scope
-
-- Read the repo's routed code guide.
-- In standard Waypoint repos, use `.waypoint/docs/code-guide.md`.
-- If the repo routes the code guide somewhere else, follow the repo's own docs and routing instead of assuming another fixed path.
-- Read only the files, routes, tests, contracts, and nearby docs needed to understand the specific feature or slice under review.
-- If the scope is ambiguous, resolve it to a concrete file set, feature path, or commit-sized change surface before auditing.
-
-Do not expand into a whole-repo audit unless the user explicitly asks for that.
-
-## Step 2: Translate The Guide Into Checks
-
-Audit only for rules that actually apply to the scoped code.
-
-Look for:
-
-- stale compatibility layers, shims, aliases, or migration-only branches
-- weak typing, avoidable `any`, recreated shared types, or unsafe casts
-- silent fallbacks, swallowed errors, degraded paths, or missing required-config failures
-- missing validation at input, config, API, file, queue, or database boundaries
-- speculative abstractions that hide the actual behavior
-- unclear state transitions, weak transaction boundaries, missing idempotency, or weak persistence invariants
-- frontend code that ignored reusable components or broke the existing design language
-- missing loading, empty, or error states
-- optimistic UI without rollback or invalidation
-- missing observability at important failure or state boundaries
-- regression tests that assert implementation details instead of behavior
-
-Skip rules that genuinely do not apply, but say that you skipped them.
-
-## Step 3: Keep The Audit Narrow
-
-- Report only coding-guide findings for the requested scope.
-- Do not drift into generic architecture advice, repo-wide cleanup, docs sync, or PR readiness unless the finding is directly required by the guide.
-- If you notice issues outside scope, mention them only if they are severe enough that ignoring them would mislead the user about this audit.
-
-## Step 4: Verify Evidence
-
-Ground each finding in the actual code.
-
-- Read the real implementation before calling something a violation.
-- When relevant, inspect the nearest tests, contracts, schemas, or reused components to confirm the gap.
-- Do not invent verification that you did not run.
-
-If the user asked for a pure audit, stop at findings. If they asked for fixes too, fix the clear issues and then verify the changed area.
-
-## Step 5: Report The Result
-
-Summarize the scoped result in review style:
-
-- findings first, ordered by severity
-- each finding tied back to the relevant coding-guide rule
-- include exact file references
-- then note any skipped guide areas or residual uncertainty
-
-## Gotchas
-
-- Do not turn this into generic code review. Every finding should tie back to a specific coding-guide rule.
-- Do not audit the whole repo by accident. Resolve the narrow slice first, then stay inside it unless an out-of-scope issue would seriously mislead the user.
-- Do not report a guide violation from a grep hit alone. Read the real implementation and the nearby evidence before calling it a problem.
-- Do not force every coding-guide rule onto every change. Skip non-applicable rules explicitly instead of inventing weak findings.
-- If you notice a broader ship-risk issue that is not really a coding-guide issue, say it is outside this skill's scope instead of quietly drifting into another audit.
-
-## Keep This Skill Sharp
-
-- After meaningful runs, add new gotchas when the same guide-specific failure mode or scope-drift mistake keeps recurring.
-- Tighten the description if the skill fires on generic review requests or misses real prompts like "check this against the code guide."
-- If the same guide-rule translation logic keeps repeating, move that reusable detail into a supporting reference instead of expanding the hub file.

package/templates/.agents/skills/code-guide-audit/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Code Guide Audit"
-  short_description: "Audit code-guide compliance on a scoped slice"
-  default_prompt: "Use $code-guide-audit to audit this specific feature, file set, or implementation slice against the coding guide."