waypoint-codex 0.3.1 → 0.5.0

package/README.md

@@ -59,6 +59,8 @@ repo/
 - `error-audit`
 - `observability-audit`
 - `ux-states-audit`
+- `docs-sync`
+- `code-guide-audit`
 - `workspace-compress`
 - `pre-pr-hygiene`
 - `pr-review`

package/dist/src/core.js

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

package/package.json

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

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/.agents/skills/docs-sync/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: docs-sync
+description: Audit routed docs against the actual codebase and shipped behavior. Use when docs may be stale after implementation work, before pushing or opening a PR, when routes/contracts/config changed, or when the agent should find missing, incorrect, outdated, or broken documentation and then update or flag the exact gaps.
+---
+
+# Docs Sync
+
+Use this skill to keep repo docs aligned with reality.
+
+This is not a vendor-doc ingestion skill and not a workspace-cleanup skill. It owns one job: compare the codebase and shipped behavior against routed docs, then fix or flag the mismatches.
+
+## Read First
+
+Before auditing docs:
+
+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 for the area under review
+
+## Step 1: Compare Docs To Reality
+
+Audit the real code, routes, contracts, config surfaces, and user-visible behavior against `.waypoint/docs/`.
+
+Look for:
+
+- missing docs for real shipped behavior
+- stale docs that describe removed or changed behavior
+- broken routing links or docs index gaps
+- examples or commands that no longer work
+- contract/schema/config docs that no longer match the code
+- docs that still describe future work as if it is already shipped
+
+## Step 2: Fix Or Flag
+
+- Update the docs when the correct wording is clear.
+- Add the smallest routed doc needed when behavior exists but is undocumented.
+- Remove or reframe stale claims instead of letting them linger.
+- If a mismatch is real but the correct doc shape is unclear, flag it explicitly instead of bluffing.
+
+Do not mirror vendor reference docs into the repo. Link to the real upstream docs when that is the right source of truth.
+
+## Step 3: Refresh Routing
+
+After changing routed docs:
+
+- Run `node .waypoint/scripts/prepare-context.mjs` so the docs index and generated context match the updated docs.
+
+## Step 4: Report The Sync Result
+
+Summarize:
+
+- what docs were stale or missing
+- what you updated
+- what still needs a decision, if anything

package/templates/.agents/skills/docs-sync/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Docs Sync"
+  short_description: "Audit docs against the real codebase"
+  default_prompt: "Use this skill to audit routed docs against the actual codebase and shipped behavior, then update or flag any missing, incorrect, or outdated documentation."

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

@@ -5,8 +5,8 @@ description: >
   Use for new features, refactoring, architecture changes, migrations, or any non-trivial
   implementation work. Ask multiple rounds of clarifying questions about product behavior,
   user expectations, edge cases, and architecture; explore the repo deeply before deciding;
-  and do not waste questions on implementation details that can be learned directly from the
-  code or routed docs.
+  do not waste questions on implementation details that can be learned directly from the
+  code or routed docs; and write the final plan into `.waypoint/docs/` so it persists in the repo.
 ---
 
 # Planning
@@ -26,20 +26,15 @@ Before planning:
 5. Read every file listed in the manifest
 6. Read the routed docs relevant to the task
 
-## Verbatim Requirements
+## Output Location
 
-Capture the user's exact words at the top of every plan when the wording matters. No paraphrasing, no compression.
+The plan belongs in the repo, not only in chat.
 
-```markdown
-## Verbatim Requirements
-
-### Original Request
-> [User's ENTIRE message, word for word]
-
-### Clarifications
-**Q:** [Your question]
-**A:** [User's ENTIRE answer, verbatim]
-```
+- Write or update a durable plan doc under `.waypoint/docs/`.
+- Choose the smallest routed location that matches the work, such as a project plan, implementation plan, or focused design note.
+- If a relevant plan doc already exists, update it instead of creating a competing one.
+- Make sure the doc remains discoverable through the routed docs layer.
+- In chat, return only a concise summary plus the path to the plan doc.
 
 ## The Core Loop
 
@@ -105,6 +100,8 @@ Plans document your understanding. Include what matters for this task:
 
 Use ASCII diagrams when they clarify flow, layering, or state.
 
+Distill the requirements and clarifications into a clean plan document. Do not turn the plan into a transcript dump.
+
 ## Self-Review Before Finalizing
 
 Before presenting the plan, verify against real code:
@@ -122,15 +119,15 @@ Before presenting the plan, verify against real code:
 - No pretending you verified something you didn't
 
 If the change touches durable project behavior, include docs/workspace updates in the plan.
-If the plan is meant to outlive the current chat, write or update a durable plan doc under `.waypoint/docs/` and make sure it is discoverable through the routed docs layer.
+Write or update the durable plan doc under `.waypoint/docs/` as part of the skill, not as an optional follow-up.
 
 ## External APIs
 
 If an external API or library is relevant, read the actual upstream docs before finalizing the plan. Prefer the repo's external-doc links or URL registry when one exists. Read the real source docs; do not copy vendor reference material into the repo unless the user explicitly wants a durable local note.
 
-## Output
+## Plan Shape
 
-A good final plan usually includes:
+A good durable plan doc usually includes:
 
 1. Current state
 2. Proposed changes
@@ -139,6 +136,14 @@ A good final plan usually includes:
 5. Verification
 6. TL;DR
 
+## Final Response
+
+When the plan doc is written:
+
+- give a short chat summary
+- include the doc path
+- call out any unresolved decisions that still need the user's input
+
 ## Quality Bar
 
 If the plan would make the implementer ask "where does this hook in?" or "what exactly am I changing?", it is not done.

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

@@ -67,6 +67,8 @@ Do not document every trivial implementation detail. Document the non-obvious, d
 - `error-audit` when failures are being swallowed or degraded invisibly
 - `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
 - `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

@@ -34,6 +34,8 @@ Working rules:
 - Keep `.waypoint/WORKSPACE.md` current as the live execution state, with timestamped new or materially revised entries in multi-topic sections
 - 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
 - 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