waypoint-codex 0.3.1 → 0.4.0

package/README.md

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

package/dist/src/core.js

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

package/package.json

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

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,7 @@ 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
 - `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,7 @@ 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
 - 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