waypoint-codex 0.4.0 → 0.6.0

package/README.md

@@ -60,6 +60,8 @@ repo/
 - `observability-audit`
 - `ux-states-audit`
 - `docs-sync`
+- `code-guide-audit`
+- `break-it-qa`
 - `workspace-compress`
 - `pre-pr-hygiene`
 - `pr-review`

package/dist/src/core.js

@@ -454,6 +454,8 @@ export function doctorRepository(projectRoot) {
         "observability-audit",
         "ux-states-audit",
         "docs-sync",
+        "code-guide-audit",
+        "break-it-qa",
         "workspace-compress",
         "pre-pr-hygiene",
         "pr-review",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
   "license": "MIT",
   "type": "module",

package/templates/.agents/skills/break-it-qa/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: break-it-qa
+description: Verify a user-facing feature by trying to break it on purpose instead of only following the happy path. Use after building forms, multistep flows, settings pages, onboarding, stateful UI, destructive actions, or any browser-facing feature where invalid inputs, refreshes, back navigation, repeated clicks, wrong action order, or recovery paths might expose real bugs.
+---
+
+# Break-It QA
+
+Use this skill to attack the feature like an impatient, confused, or careless user.
+
+This is not the same as `e2e-verify`.
+
+- `e2e-verify` proves the intended flow works end to end.
+- `break-it-qa` tries to make the feature fail through invalid, interrupted, stale, repeated, or out-of-order interactions.
+
+## Read First
+
+Before verification:
+
+1. Read `.waypoint/SOUL.md`
+2. Read `.waypoint/agent-operating-manual.md`
+3. Read `.waypoint/WORKSPACE.md`
+4. Read `.waypoint/context/MANIFEST.md`
+5. Read every file listed in that manifest
+6. Read the routed docs or nearby code that define the feature being tested
+
+## Step 1: Identify Break Surfaces
+
+- Identify the happy path first so you know what "broken" means.
+- Find the fragile surfaces: forms, wizards, pending states, destructive actions, async transitions, navigation changes, and persisted state.
+
+Do not test blindly.
+
+## Step 2: Use The Real UI
+
+- Use `playwright-interactive`.
+- Exercise the actual UI instead of mocking the flow in code.
+- Keep the scope focused on the feature the user asked you to verify.
+
+## Step 3: Try To Break It On Purpose
+
+Do more than a happy-path walkthrough.
+
+Actively try:
+
+- invalid inputs
+- empty required fields
+- boundary-length or malformed inputs
+- repeated or double clicks
+- submitting twice
+- wrong action order
+- back and forward navigation
+- page refresh during the flow
+- closing and reopening modals or screens
+- canceling mid-flow and re-entering
+- stale UI state after edits
+- conflicting selections or toggles
+- error recovery after a failed action
+
+If the feature is stateful, also check whether the UI, network result, and persisted state stay coherent after those interactions.
+
+## Step 4: Record And Fix Real Bugs
+
+- Document each meaningful issue you find.
+- Fix the issue when the remediation is clear.
+- If the behavior is ambiguous, call out the product decision instead of bluffing a fix.
+- Update docs when the verification exposes stale assumptions about how the feature works.
+
+Do not stop at the first bug.
+
+## Step 5: Repeat Until The Feature Resists Abuse
+
+After fixes:
+
+- rerun the relevant happy path
+- rerun the break attempts that previously failed
+- verify the fix did not create a new inconsistent state
+
+The skill is not done when the feature only works once. It is done when the feature behaves predictably under sloppy real-world use.
+
+## Step 6: Report Truthfully
+
+Summarize:
+
+- what break attempts you tried
+- which issues you found
+- what you fixed
+- what still looks risky or was not exercised

package/templates/.agents/skills/break-it-qa/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Break-It QA"
+  short_description: "Try to break a feature through the UI"
+  default_prompt: "Use this skill to verify a user-facing feature by trying to break it through the browser with invalid inputs, wrong action order, refreshes, back navigation, repeated clicks, and other adversarial interactions, then fix clear issues and repeat."

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

@@ -0,0 +1,65 @@
+---
+name: code-guide-audit
+description: Audit a specific feature, file set, or implementation slice against the coding guide and report only coding-guide-related violations or risks in that scope. Use after building a feature, when the user wants a coding-guide compliance check, before review on a targeted area, or when validating whether a change follows rules like no silent fallbacks, strong boundary validation, frontend reuse, explicit state handling, and behavior-focused verification.
+---
+
+# 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.
+
+## Step 1: Load The Right Scope
+
+- Read `.waypoint/docs/code-guide.md`.
+- 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.
+
+This skill is narrower than `pre-pr-hygiene`. Use that other skill for broader ship-readiness.
+
+## 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

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Code Guide Audit"
+  short_description: "Audit scoped code against the coding guide"
+  default_prompt: "Use this skill to audit a specific feature, file set, or implementation slice against the coding guide and report only guide-related violations or risks in that scope."

package/templates/.waypoint/agent-operating-manual.md

@@ -68,6 +68,8 @@ Do not document every trivial implementation detail. Document the non-obvious, d
 - `observability-audit` when production debugging signals look weak
 - `ux-states-audit` when async/data-driven UI likely lacks loading, empty, or error states
 - `docs-sync` when routed docs may be stale, missing, or inconsistent with the codebase
+- `code-guide-audit` when a specific feature or file set needs a targeted coding-guide compliance check
+- `break-it-qa` when a browser-facing feature should be attacked with invalid inputs, refreshes, repeated clicks, wrong action order, or other adversarial manual QA
 - `workspace-compress` after meaningful chunks, before stopping, and before review when the live handoff needs compression
 - `pre-pr-hygiene` before pushing or opening/updating a PR for substantial work
 - `pr-review` once a PR has active review comments or automated review in progress

package/templates/managed-agents-block.md

@@ -35,6 +35,8 @@ Working rules:
 - Update `.waypoint/docs/` when behavior or durable project knowledge changes, and refresh `last_updated` on touched routable docs
 - Use the repo-local skills Waypoint ships for structured workflows when relevant
 - Use `docs-sync` when the docs may be stale or a change altered shipped behavior, contracts, routes, or commands
+- Use `code-guide-audit` for a targeted coding-guide compliance pass on a specific feature, file set, or change slice
+- Use `break-it-qa` for browser-facing features that should be tested against invalid inputs, refreshes, repeated clicks, wrong navigation, and other adversarial user behavior
 - If optional reviewer roles are present and you make a commit, run `code-reviewer` and `code-health-reviewer` in parallel before calling the work done
 - Before pushing or opening/updating a PR for substantial work, use `pre-pr-hygiene`
 - Use `pr-review` once a PR has active review comments or automated review in progress