waypoint-codex 1.0.13 → 1.0.15

package/templates/.agents/skills/hard-cut/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: hard-cut
+description: "Enforce a hard-cut cleanup policy: keep one canonical implementation and delete compatibility, migration, fallback, adapter, coercion, and dual-shape code. Use for pre-release or internal-draft refactors where the goal is one final shape, especially when changing schemas, contracts, persisted state, routing, configuration, feature flags, enum/value sets, or architecture."
+---
+
+# Hard-Cut Policy
+
+Apply a hard-cut policy by default for refactors or behavior changes that alter schemas, contracts, persisted state, routing, configuration, feature flags, enum/value sets, or architecture where old-state preservation might otherwise be retained.
+
+Keep one canonical codepath. Remove old-shape handling. Do not preserve draft or legacy behavior unless there is concrete evidence of a real external compatibility boundary.
+
+## Default assumption
+
+Treat previous shapes as internal draft shapes unless there is concrete evidence they are already:
+- persisted external or user data
+- on-disk or database state that must still load
+- a wire format used across process or service boundaries
+- a documented or publicly supported contract
+- actively depended on outside the refactor boundary
+
+Mere existence of old code is not proof of a compatibility obligation.
+
+## Core policy
+
+When an old shape appears, remove that path and convert the codebase to the canonical shape. Do not add code to support it. Do not add code specifically to reject it just because it once existed.
+
+## Hard rules
+
+Apply these rules in order:
+
+1. Do not add fallback behavior.
+2. Do not add compatibility branches.
+3. Do not add shims, adapters, coercions, aliases, or dual-shape support.
+4. Do not add fail-fast guards whose purpose is to detect or reject old shapes.
+5. Do not add tests whose purpose is to assert rejection of old or legacy shapes.
+6. Prefer deleting old-shape handling over preserving or policing it.
+7. Update producers, consumers, fixtures, and tests to use only the canonical shape.
+8. Remove dead code, dead conditionals, obsolete comments, and translation helpers related to old shapes.
+9. Keep validation only for the current canonical contract. Validation may reject malformed current-shape input, but must not branch on legacy discriminators, old field names, aliases, old enum members, or draft formats.
+10. When choosing between backward compatibility and simplification, choose simplification.
+
+## Execution workflow
+
+1. Identify the canonical target shape.
+2. Trace every producer and consumer of that shape.
+3. Update all live codepaths to emit and consume only the canonical shape.
+4. Update fixtures, test data, builders, and snapshots to the canonical shape.
+5. Delete legacy handling, branching, comments, and helpers.
+6. Keep only current-shape validation that is still required for correctness.
+7. If a real external compatibility boundary exists, isolate it and call out the exact file, function, boundary, and reason it cannot be removed yet.
+
+## Review checklist
+
+- Reject changes that preserve old-shape behavior behind conditionals.
+- Reject translation layers between old and new shapes.
+- Reject validation branches added only to reject legacy inputs.
+- Reject tests added only to memorialize abandoned draft formats.
+- Remove dead helpers and comments that describe removed draft formats.
+- Keep one owner for the canonical contract.
+
+## Deliverables
+
+Deliver only:
+- a minimal implementation that supports the canonical shape
+- updated tests for the canonical shape only
+- removal of obsolete legacy-shape tests
+- no new rejection tests for old shapes
+- no runtime logic dedicated to recognizing legacy formats
+
+## Exception rule
+
+Make an exception only when removing the old shape would break already persisted external or user data, on-disk or database state, cross-boundary wire formats, or a real public contract.
+
+If such a boundary exists:
+- do not invent new compatibility layers elsewhere
+- name the exact file and function
+- describe the concrete persisted or public dependency
+- limit any compatibility discussion to that boundary only

package/templates/.agents/skills/hard-cut/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hard Cut"
+  short_description: "Prefer one canonical shape and delete legacy paths"
+  default_prompt: "Use $hard-cut to enforce a single canonical implementation, remove legacy/compatibility layers, and keep exceptions only at proven external boundaries."

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

@@ -1,34 +1,38 @@
 ---
 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.
+description: Legibility-only refactors for code that is already behaviorally correct but hard to read, reason about, or safely modify. Use only for local readability improvements inside an explicitly requested scope. Do not use for behavior changes, invariant redesign, architectural cleanup, or broad refactors that change boundaries.
 ---
 
-Refactor the given scope to make the current truth easier to see.
+# Legibility Pass
 
-Preserve behavior unless the user asked for functional change.
+Refactor the requested scope so the current behavior is easier to read without changing what the code does.
 
-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
+## Core Instruction
+Make the smallest readable change that improves comprehension while preserving the existing contract, control flow, and runtime behavior.
 
-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.
+## Default Workflow
+1. Identify the narrow scope where readability is actively hurting maintenance or review.
+2. Find the least intrusive change that improves naming, flow, or local structure.
+3. Rewrite the code so the main path, failure path, and key boundary are easier to see.
+4. Keep the public shape, observable behavior, and important data flow unchanged.
+5. Verify the refactor did not introduce a new abstraction, boundary shift, or hidden dependency.
 
-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.
+## Rules
+- Do not change behavior, public API, persistence shape, wire format, timing, or error semantics.
+- Do not rename or restructure code unless the change reduces reading friction in the requested scope.
+- Do not introduce new layers, helper abstractions, or framework patterns just to make the diff look cleaner.
+- Do not perform broad cleanup, mechanical formatting, dead-code sweeps, or unrelated simplification.
+- Do not use this skill for collapsing unrelated abstractions, making invariants stricter, or redesigning architecture.
+- Do not use this skill as a substitute for a foundational refactor, make-invariants pass, or behavior-preserving optimization.
+- Do not rely on comments to explain code that can be made directly legible.
+- Do not add comments unless they capture a local constraint that cannot be expressed clearly in code.
+
+## Exception Rule
+If the only readability improvement would require a change that risks an unacceptable behavior shift, boundary violation, or contract change, stop and leave the code unchanged except for a brief explanation of the constraint. Use this exception only when the safer rewrite would cross one of the hard rules above.
+
+## Output Contract
+- Return a diff limited to the explicitly requested scope.
+- Include only legibility edits that preserve observable behavior.
+- List the files changed and the specific readability improvements made.
+- State any tempting cleanup, boundary change, or abstraction you intentionally left out because it would exceed the skill boundary.
+- If no safe readability improvement exists, report that the scope was left unchanged and why.

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

@@ -1,4 +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."
+  short_description: "Legibility-only refactors within a requested scope"
+  default_prompt: "Use $legibility-pass only for local readability refactors in the requested scope. Improve naming, flow, and local reasoning without changing behavior, boundaries, invariants, or architecture."

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

@@ -0,0 +1,73 @@
+---
+name: make-invariants-explicit
+description: Use when behavior depends on hidden assumptions about data shape, ordering, uniqueness, idempotency, authorization, state transitions, or lifecycle constraints. Surface the invariant, choose the correct enforcement layer, and make invalid states hard to represent or hard to persist.
+---
+
+# Make Invariants Explicit
+
+## Core Instruction
+Find the invariant that correctness depends on, enforce it at the strongest appropriate layer, and remove hidden assumptions from the implementation.
+
+## Trigger Examples
+Use this skill when the requested change involves one or more of these cases:
+- a value must always be present before processing
+- operations must happen in a specific order
+- a transition is forbidden from a given state
+- a record must be unique
+- a side effect must happen exactly once
+- retries, duplicate delivery, or replay are possible
+- a caller may have skipped validation
+- authorization depends on a stable contract, not an informal assumption
+- external data may not match the expected shape
+
+Do not use this skill for purely stylistic cleanup, broad refactors with no correctness invariant, or features where the only goal is to make code shorter.
+
+## Default Workflow
+1. State the invariant in one sentence.
+2. Identify the owner of the invariant.
+   - If the invariant is owned by persistence, enforce it in schema, constraints, or transactional logic.
+   - If the invariant is owned by the domain model, encode it in types, constructors, or state transitions.
+   - If the invariant is owned by an external boundary, validate it at ingress before it reaches core logic.
+3. Choose the enforcement layer using this order:
+   - persistence or database constraint when multiple writers, processes, or retries can violate the rule
+   - type or schema constraint when the invalid state should not be representable
+   - state machine or transition guard when the rule depends on lifecycle order
+   - boundary validation when the input is untrusted or externally shaped
+   - idempotency key, deduplication, or lock when duplicates or replay are possible
+   - assertion or defensive guard only when the invariant is guaranteed elsewhere and this code sits at the true correctness boundary
+4. Replace scattered checks with one authoritative enforcement point unless the invariant genuinely exists at multiple boundaries.
+5. Add or update tests that prove the invariant is enforced and that the failure mode is rejected.
+6. Call out any remaining gap that the code does not and cannot fully eliminate.
+
+If an important invariant is only implied, make it explicit.
+
+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 a critical invariant unless that contract is explicit, stable, and tested.
+- Do not scatter partial checks across many places when one authoritative enforcement point exists.
+- Do not normalize invalid state away when the correct behavior is to reject it.
+- Do not use assertions as the primary enforcement mechanism when a stronger boundary exists.
+- Do not leave a critical invariant implicit if it can be represented in code, types, schema, or transitions.
+
+## Exception Rule
+You may leave an invariant implicit only when all of the following are true:
+- the invariant is already enforced by a documented contract in the same repository or a strictly stronger upstream boundary
+- that contract is stable enough that breaking it would be a compatibility defect, not a routine possibility
+- the current change does not weaken, duplicate, or relocate that enforcement point
+- the output explicitly records the dependency and residual risk
+
+This exception does not apply to correctness, security, permissions, uniqueness, idempotency, duplicate handling, or lifecycle-transition invariants.
+
+## Output Contract
+Return the result with these fields:
+- Invariant: the exact rule being enforced
+- Owner: the layer or component responsible for the invariant
+- Enforcement point: the concrete code, schema, type, or transition boundary used
+- Verification/tests: the tests or checks added or updated to prove enforcement
+- Residual risk: any remaining assumption, dependency, or gap

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Make Invariants Explicit"
+  short_description: "Enforce hidden correctness assumptions at the right layer"
+  default_prompt: "Use $make-invariants-explicit when correctness depends on hidden assumptions about data shape, ordering, uniqueness, idempotency, authorization, or lifecycle state. Identify the invariant, choose the authoritative enforcement layer, implement it, and report the verification/tests and residual risk."

package/templates/.agents/skills/plan-start/SKILL.md

@@ -1,42 +1,79 @@
 ---
 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.
+description: Bootstrap a fresh session onto an existing implementation plan. Use when a referenced plan already exists, execution has not meaningfully started in the current session, and Codex needs to reconstruct the active phase from the plan plus current repository state before beginning the first substantial work package.
 ---
 
-Start from the plan and the current codebase, not from assumptions.
+# Plan Start
 
-1. Read the referenced plan.
-2. Inspect the current repository state relevant to that plan.
+## Core Instruction
+Convert a referenced plan into the first executable work package for a fresh session.
+
+## Trigger Boundary
+Use this skill when:
+- a durable plan, roadmap, or phase list already exists
+- the current session has not yet become a stalled execution loop
+- the task is to re-enter the plan, recover the active phase, and begin substantive work
+
+Do not use this skill when:
+- the session is already mid-execution and progress has degraded into micro-edits, repeated patching, or phase drift
+- the current problem is recovering momentum on a stuck phase
+- the request is to revise the plan itself before execution can begin
+
+In those cases, route to:
+- `$execution-reset` for stalled or compacted plan execution
+- `$planning` when the plan is missing, non-durable, or too underspecified to execute
+
+## Required Inputs
+Do not proceed until you have:
+- a plan path, plan identifier, or equivalent durable plan reference
+- the current repository/worktree state relevant to that plan
+- enough current context to tell whether the referenced plan is still actionable
+
+If any required input is missing, stop and route to `$planning` or ask for the missing reference instead of guessing.
+
+## Workflow
+1. Read the referenced plan end to end.
+2. Inspect the current repository state relevant to the plan.
 3. Determine:
-   - which phases are already complete
+   - which phases are complete
    - which phase is active
-   - what remains in the active phase
+   - what remains inside 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:
+5. Select the first substantial work package that most directly advances that phase.
+6. Begin execution on that package.
 
-## Plan Start
-### Active Phase
-[phase]
+## Rules
+- Do not re-plan the whole project unless the referenced plan is locally stale.
+- Do not use this skill to recover from a stalled session; that is `$execution-reset`.
+- Do not spend the session on summaries, narration, or cosmetic cleanup when a substantive work package is available.
+- Do not choose a micro-edit as the first move unless it is the smallest change that unblocks the first substantial package.
+- Select the work package that most directly advances the active phase.
 
-### Goal
-[what this phase must accomplish]
+## Bounded Exception
+If the plan is locally stale, allow one bounded re-anchoring pass:
+- reconcile the active phase against the current codebase
+- update the phase boundary only as needed to make execution possible
+- do not rewrite the whole roadmap
 
-### Current State
-- Complete: [...]
-- In progress: [...]
-- Missing: [...]
+If the plan still cannot be executed after that pass, stop and route to `$planning`.
 
-### First Work Package
-[one substantial chunk]
+## Output Contract
+### Normal
+Return:
+- `Active Phase`
+- `Objective`
+- `Current State`
+- `First Work Package`
+- `Definition of Done`
 
-### Definition of Done
-[what makes this chunk complete]
+### Blocked
+Return `Blocked` when required inputs are missing or the plan cannot be safely actioned yet. Include:
+- what is missing
+- why execution cannot start
+- the exact reroute target: `$planning` or `$execution-reset`
 
-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.
+### Reroute
+Return `Reroute` when the request belongs to another skill. Include:
+- `Reroute Target`
+- `Reason`
+- the minimal handoff needed to continue

package/templates/.agents/skills/plan-start/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Plan Start"
+  short_description: "Bootstrap a fresh session onto an existing implementation plan"
+  default_prompt: "Use $plan-start when a durable implementation plan already exists and this is a fresh-session bootstrap, not a stalled execution recovery. Read the plan, inspect the current repo state, identify the active phase, pick the first substantial work package, and begin execution. If the plan is missing or underspecified, route to $planning; if the session is already stalled, route to $execution-reset."

package/templates/.agents/skills/plan-swarm-audit/SKILL.md

@@ -1,21 +1,35 @@
 ---
 name: plan-swarm-audit
-description: Use during execution of an approved multi-phase plan when a second-pass audit is needed. Spawn five parallel subagents with distinct audit scopes, consolidate findings, fix blockers, and repeat in bounded rounds until the phase or plan meets acceptance criteria.
+description: Use during execution of an approved plan phase when a bounded second-pass audit is needed. Requires plan path, active phase, changed-file scope or scope anchor commit, phase acceptance criteria, and a verify-completeness closeout target. If those inputs are missing or subagents cannot be staffed, block instead of spawning.
 ---
 
 # Plan Swarm Audit
 
-Use this skill while implementing an approved plan when you want an independent multi-agent audit loop before calling work complete.
+Use this skill while executing an approved plan phase when you need an independent audit loop before closeout. Do not improvise the audit shape or start from partial context.
 
 ## Required inputs
 
 - plan path (for example `.waypoint/plans/<plan>.md`)
 - active phase
 - current changed-file scope (or scope anchor commit)
+- phase acceptance criteria for the active phase
+- verify-completeness closeout target
 
-## Swarm setup (5 agents, disjoint scopes)
+## Precondition validation
 
-Spawn exactly five subagents in parallel, each with one owned audit lens:
+Before spawning any audit agents, confirm all of the following:
+
+1. The referenced plan exists and is the approved source of truth for the work.
+2. The active phase is identified and not already closed.
+3. The changed-file scope or scope anchor commit is available.
+4. The active phase acceptance criteria are explicit enough to test against.
+5. A `verify-completeness` closeout pass will be run after the swarm loop.
+
+If any required input is missing, ambiguous, or stale, do not spawn the swarm. Return `blocked` with the missing input(s) and the exact next input needed from the user or from the plan.
+
+## Swarm setup
+
+Spawn five parallel subagents when the preconditions are satisfied. Keep their scopes disjoint and narrow.
 
 1. Plan-scope compliance
 2. Correctness and regression risk
@@ -29,7 +43,9 @@ Each subagent must return:
 - exact file/line references
 - whether each finding blocks phase completion
 - recommended fix
-- a final status suitable for immediate closeout
+- a final status suitable for immediate closeout or escalation
+
+If a subagent cannot be spawned, use the exception rule below. Do not silently reduce coverage.
 
 ## Consolidation pass
 
@@ -47,7 +63,17 @@ After all five return:
 2. Run targeted verification for the changed area.
 3. Re-check plan checklist and acceptance criteria.
 4. Update `ACTIVE_PLANS.md` / `WORKSPACE.md` when state materially changes.
-5. If blockers remain, run another swarm round.
+5. If blockers remain and the round cap has not been reached, run another swarm round.
+
+## Exception rule
+
+Use the normal five-agent shape by default. You may deviate only in these bounded cases:
+
+- Missing required inputs: block immediately and do not spawn any agents.
+- Unavailable subagents: run fewer than five only if the remaining agents can still cover the five lenses by merging at most one adjacent lens per missing agent. Do not run with fewer than three agents.
+- Justified fewer-agents mode: document why the reduction is necessary, which lenses were merged, and what residual risk remains. Treat the reduced coverage as a blocker if it weakens the audit materially.
+
+Do not use the exception rule for convenience, speed, or to avoid waiting for missing context.
 
 ## Stop condition
 
@@ -57,6 +83,20 @@ You may stop only when all are true:
 - active phase acceptance criteria are satisfied
 - `verify-completeness` closeout is clean
 
+## Escalation
+
+Escalate to the user instead of continuing when either of these is true:
+
+- the round cap for the phase has been reached
+- the same blocker appears in two rounds after targeted fixes
+
+Escalation must include:
+
+- the exact blocker(s)
+- what was tried
+- why the blocker still remains
+- the decision needed from the user, such as scope change, plan update, more context, or acceptance of a blocked phase
+
 ## Guardrails
 
 - Use at most 3 swarm rounds per phase by default.
@@ -70,8 +110,12 @@ You may stop only when all are true:
 
 Report:
 
+- status: `complete`, `blocked`, or `escalated`
 - swarm round number
+- precondition check result
 - consolidated blockers (with file/line refs)
 - fixes applied
 - verification run
+- verify-completeness handoff result
 - remaining blockers or confirmation that stop condition is met
+- escalation, if any, with the decision needed from the user

package/templates/.agents/skills/plan-swarm-audit/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Plan Swarm Audit"
-  short_description: "Run a 5-agent audit loop against the active plan phase"
-  default_prompt: "Use $plan-swarm-audit with the current plan path and active phase. Spawn five parallel audit agents with distinct scopes, consolidate blockers, fix them, and repeat in bounded rounds until phase acceptance criteria are satisfied."
+  short_description: "Run a bounded 5-agent audit loop against an approved plan phase"
+  default_prompt: "Use $plan-swarm-audit only when you already have the plan path, active phase, changed-file scope or scope anchor commit, phase acceptance criteria, and a verify-completeness closeout target. Validate those inputs first; if any are missing or stale, return blocked and do not spawn agents. Otherwise spawn five parallel audit agents with distinct scopes, consolidate findings, fix blockers, repeat in bounded rounds, and hand off to $verify-completeness before reporting complete. Escalate if the round cap is reached or the same blocker repeats after targeted fixes."