waypoint-codex 1.0.9 → 1.0.10

package/package.json

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

package/templates/.agents/skills/collapse-fragmented-modules/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: collapse-fragmented-modules
+description: Consolidate over-fragmented existing code within a defined scope. Use when a feature, module, or directory has been split into too many tiny files, thin wrappers, pass-through layers, single-use helpers, local-only types, local-only constants, or other low-value fragments that make future changes harder. Reduce file count by merging code that changes together, removing unnecessary indirection, and reorganizing the scope into a smaller number of cohesive files without changing intended behavior.
+---
+
+Refactor the given scope to reduce unnecessary file fragmentation.
+
+Treat this as consolidation work, not feature work. Preserve behavior while making the code easier to change.
+
+Within the requested scope:
+
+1. Identify files that should be merged, removed, or kept.
+   Target especially:
+   - tiny files with little logic
+   - single-use helpers
+   - local-only types
+   - local-only constants
+   - thin wrappers
+   - pass-through adapters
+   - split files that always change together
+
+2. Merge code that belongs to the same feature or responsibility into a smaller number of cohesive files.
+
+3. Remove low-value indirection.
+   Collapse wrappers, adapters, and helper layers that do not enforce a real boundary or protect meaningful complexity.
+
+4. Keep splits only when they are justified by one of these:
+   - real shared reuse
+   - clear architectural boundary
+   - meaningful file size
+   - clearly separate responsibility that does not usually change with neighboring code
+
+5. Prefer edit locality over theoretical separation.
+   A routine change in this scope should touch as few files as reasonably possible.
+
+6. Preserve external behavior and stable public contracts unless the user asked for behavioral change.
+
+7. Update imports, exports, and tests to match the new structure.
+
+8. Delete obsolete files as part of the same work. Do not leave dead fragments behind.
+
+Rules:
+- Do not keep tiny files just because they already exist.
+- Do not preserve thin wrappers, pass-through hooks, local-only type files, or local-only constants files unless they provide real value.
+- Do not split by category alone.
+- Do not create a new abstraction while trying to remove fragmentation.
+- Prefer one cohesive file over several microscopic files when the code changes together.
+- Keep public boundaries clean, but aggressively collapse internal fragmentation.
+- If unsure whether two files should be merged, merge them unless there is a clear boundary reason not to.
+
+Before finishing, do a consolidation pass:
+- remove newly obsolete files
+- collapse redundant exports
+- simplify import paths
+- check whether the same feature is still spread across too many files
+- reduce file count further if behavior and clarity allow

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

@@ -0,0 +1,77 @@
+---
+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.
+---
+
+# Plan Swarm Audit
+
+Use this skill while implementing an approved plan when you want an independent multi-agent audit loop before calling work complete.
+
+## Required inputs
+
+- plan path (for example `.waypoint/plans/<plan>.md`)
+- active phase
+- current changed-file scope (or scope anchor commit)
+
+## Swarm setup (5 agents, disjoint scopes)
+
+Spawn exactly five subagents in parallel, each with one owned audit lens:
+
+1. Plan-scope compliance
+2. Correctness and regression risk
+3. Maintainability, duplication, and bloat
+4. Verification and test coverage gaps
+5. Docs and state drift (`ACTIVE_PLANS.md`, `WORKSPACE.md`, and relevant durable docs)
+
+Each subagent must return:
+
+- findings with severity
+- exact file/line references
+- whether each finding blocks phase completion
+- recommended fix
+- a final status suitable for immediate closeout
+
+## Consolidation pass
+
+After all five return:
+
+1. Merge findings into one deduplicated list.
+2. Group by severity and execution order.
+3. Identify blockers vs optional polish.
+4. Keep only findings within approved scope unless a scope-risk must be escalated to the user.
+5. Close all swarm subagents after their outputs are captured. Do not leave audit agents running across rounds.
+
+## Fix loop
+
+1. Fix blocking findings first.
+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.
+
+## Stop condition
+
+You may stop only when all are true:
+
+- no blocking findings remain across the five audit lenses
+- active phase acceptance criteria are satisfied
+- `verify-completeness` closeout is clean
+
+## Guardrails
+
+- Use at most 3 swarm rounds per phase by default.
+- Do not let subagents overlap ownership; keep scopes distinct.
+- Always close every swarm subagent thread after consolidation for that round.
+- Do not run full repo typecheck/test/build after every tiny fix. Use targeted checks during the loop, then full checks at pre-commit/final handoff.
+- If the same finding repeats in 2 rounds, treat it as a structural blocker and change approach instead of micro-patching.
+- Do not silently widen scope; escalate scope changes to the user.
+
+## Output contract
+
+Report:
+
+- swarm round number
+- consolidated blockers (with file/line refs)
+- fixes applied
+- verification run
+- remaining blockers or confirmation that stop condition is met

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

@@ -0,0 +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."

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

@@ -106,6 +106,8 @@ Plans document your understanding. Include what matters for this task:
 - **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, with explicit cadence (targeted checks during implementation, full sweeps at phase-complete or pre-commit checkpoints unless the user asks otherwise)
+- **File strategy**: Why each new file is necessary, how edit locality is preserved, and which splits are intentionally avoided
+- **Test strategy**: The smallest durable test set that gives confidence for this change, plus why additional tests are not needed right now
 - **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
@@ -135,6 +137,8 @@ Before presenting the plan, verify against real code:
 - Migration and refactor plans should include a legacy seam inventory before implementation starts
 - Migration and refactor phases should include exact grep gates for the legacy symbols being removed
 - Refactor and replacement plans should explicitly call out what legacy or obsolete code will be removed instead of preserving it by default
+- Do not split files by concern labels alone. A new file requires a clear boundary, reuse need, or size reason.
+- Do not inflate tests by default. Start from a small high-signal set and expand only when risk justifies it.
 - If the user approves the plan, do not silently defer or drop checklist items later; discuss any proposed scope change first
 
 If the change touches durable project behavior, include docs/workspace updates in the plan.

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

@@ -16,8 +16,10 @@ 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. 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.
+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.
 
 ## Completion gate
 
@@ -29,6 +31,8 @@ You can report complete only when all are true:
 - no hidden scope reduction occurred
 - no unapproved scope expansion remains
 - no obvious duplication or avoidable bloat remains in touched files
+- no avoidable file fragmentation remains in touched feature areas
+- test set remains high-signal and non-redundant for the risk level
 
 ## Output contract
 
@@ -38,6 +42,7 @@ Before final status, summarize briefly:
 - files re-read for final verification
 - completed items
 - removed unapproved extras or bloat cleanup applied
+- file-collapsing or test-pruning done during sanity passes
 - remaining gaps (if any)
 - next action (continue execution or complete)
 
@@ -47,3 +52,4 @@ Before final status, summarize briefly:
 - 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.
+- Do not keep fragmented tiny files or low-signal tests as evidence theater.

package/templates/.waypoint/docs/code-guide.md

@@ -78,6 +78,8 @@ Security and privacy work is part of normal engineering, not a later hardening p
 Do not invent complexity for hypothetical future needs.
 
 - Add abstractions only when multiple concrete cases already demand the same shape.
+- Do not introduce a new abstraction unless at least two concrete call sites already need the same contract, or a documented architectural boundary requires it.
+- Do not add a thin wrapper, adapter, or pass-through layer unless it enforces a real contract, boundary, or migration transition.
 - Prefer straightforward code and small duplication over the wrong generic layer.
 - If a helper hides critical validation, state changes, or failure modes, it is probably hurting clarity.
 
@@ -106,6 +108,7 @@ Frontend changes should extend the app, not fork its design language.
 
 - Before creating a new component, check whether the app already has a component or pattern that should be reused.
 - Reuse existing components when they satisfy the need, even if minor adaptation is required.
+- Do not create a thin wrapper component when a direct edit to the existing component is the cleaner path.
 - When a new component is necessary, make it match the design language, interaction model, spacing, states, and compositional patterns of the rest of the app.
 - Handle all states for async and data-driven UI: loading, success, empty, error.
 - Optimistic UI must have an explicit rollback or invalidation strategy. Never leave optimistic state hanging without a recovery path.
@@ -124,6 +127,7 @@ UI work is not correct if important users cannot operate it.
 If you cannot see the failure path, you have not finished the work.
 
 - Emit structured logs, metrics, or events at important boundaries and state transitions.
+- Instrument important boundaries and state transitions, not every internal hop.
 - Include enough context to reproduce issues without logging secrets or sensitive data.
 - Failed async work, retries, degraded paths, and rejected inputs must leave a useful trace.
 - Do not use noisy logging to compensate for unclear control flow.
@@ -142,6 +146,10 @@ Optimize based on real impact, not superstition, but do not ignore performance f
 Tests should protect the contract users depend on.
 
 - Test observable behavior and boundary cases, not implementation trivia.
+- Start with the smallest test set that gives strong confidence.
+- Default budget for a normal feature: one main-path test, one key edge or failure-path test, plus unit tests only for non-trivial pure logic.
+- Do not duplicate confidence across layers unless a distinct risk justifies it.
+- Do not add tests for trivial helpers, thin wrappers, pass-through glue, or refactor-sensitive internals unless they protect a meaningful rule.
 - Never write brittle regression tests that assert exact class strings, styling internals, private helper calls, incidental DOM structure, internal schema representations, or other implementation-detail artifacts.
 - Regression tests must focus on the behavior that was broken and the behavior that is now guaranteed.
 - For backend bugs, prefer behavior-focused regression tests by default.
@@ -153,7 +161,10 @@ Tests should protect the contract users depend on.
 Code should be easy to navigate under pressure.
 
 - Use names that describe intent, not cleverness, incidental mechanics, or historical accidents.
-- Keep functions, modules, and APIs small enough that a reader can understand the responsibility without cross-referencing half the repo.
+- Do not split by default. Keep code that changes together in the same file or module unless there is a clear boundary, reuse need, or size problem.
+- Before creating a new file, decide whether it reduces or increases the number of files touched by a routine future change.
+- Do not create standalone files for helpers, types, constants, hooks, adapters, or mappers unless they are shared, large enough to justify extraction, or represent a real architectural boundary.
+- Keep functions, modules, and APIs understandable without cross-referencing half the repo, but do not split cohesive feature code only to make files shorter.
 - Prefer one obvious place for a behavior over scattering it across thin wrappers and pass-through layers.
 - Group code by responsibility and boundary, not by vague convenience buckets.
 - If a file or API has grown hard to name clearly, it is probably doing too much.
@@ -162,7 +173,7 @@ Code should be easy to navigate under pressure.
 
 Write code for the next engineer or agent who has to change it under pressure.
 
-- Keep modules narrow in responsibility and data flow obvious.
+- Keep responsibilities cohesive and data flow obvious, but do not create additional modules unless they reduce routine edit spread or establish a real boundary.
 - Remove stale branches, half-migrations, dead code, and obsolete docs around the change.
 - Keep docs and shipped behavior aligned.
 - Before pushing or opening a PR, do a hygiene pass for stale docs, drifting contracts, typing gaps, missing rollback strategies, and new persistence correctness risks.

package/templates/managed-agents-block.md

@@ -39,12 +39,14 @@ Once the user approves a plan or tells you to proceed, that approved scope is th
 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.
 
 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.
+Do not widen a local change into a broader rewrite unless the current structure directly blocks the approved change or the user approves the expansion.
 
 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.
+Choose the smallest high-signal verification that proves the changed contract.
 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.