waypoint-codex 0.3.0 → 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`
@@ -70,7 +71,6 @@ If you initialize with `--with-roles`, Waypoint scaffolds:
 
 - `code-health-reviewer`
 - `code-reviewer`
-- `docs-researcher`
 - `plan-reviewer`
 
 The intended workflow is post-commit: after your own commit lands, run `code-reviewer` and `code-health-reviewer` in parallel in the background, then fix real findings before you call the work finished.

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

@@ -3,9 +3,10 @@ name: planning
 description: >
   Interview-driven planning methodology that produces implementation-ready plans.
   Use for new features, refactoring, architecture changes, migrations, or any non-trivial
-  implementation work. Ask multiple rounds of clarifying questions, explore the repo deeply
-  before deciding, capture verbatim requirements when needed, and do not stop at vague or
-  partially-investigated plans.
+  implementation work. Ask multiple rounds of clarifying questions about product behavior,
+  user expectations, edge cases, and architecture; explore the repo deeply before deciding;
+  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
@@ -20,25 +21,20 @@ Before planning:
 
 1. Read `.waypoint/SOUL.md`
 2. Read `.waypoint/agent-operating-manual.md`
-3. Read `WORKSPACE.md`
+3. Read `.waypoint/WORKSPACE.md`
 4. Read `.waypoint/context/MANIFEST.md`
 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
 
@@ -55,7 +51,7 @@ Keep looping until you can explain:
 
 ## Interviewing
 
-**Interviewing is the most important part of planning.** You cannot build what you don't understand. Every unasked question is an assumption that will break during implementation.
+**Interviewing is the most important part of planning.** You cannot build what you don't understand. Every unasked product, behavior, edge-case, or architecture question is an assumption that will break during implementation.
 
 Interview iteratively: 2-4 questions -> answers -> deeper follow-ups -> repeat. Each round should go deeper.
 
@@ -63,6 +59,16 @@ Interview iteratively: 2-4 questions -> answers -> deeper follow-ups -> repeat.
 - Feature or migration -> many rounds of questions
 - Architectural work -> keep drilling until the constraints and tradeoffs are clear
 
+Ask aggressively about:
+
+- how the feature should behave
+- who the users are
+- which edge cases matter
+- what tradeoffs are acceptable
+- what architecture direction the user wants
+
+Do **not** spend those questions on implementation facts that can be learned from reading the code, routed docs, or external docs already linked by the repo.
+
 Push back when something seems off. Neutrality is not the goal; correctness is.
 
 ## Exploring the Codebase
@@ -94,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:
@@ -111,14 +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.
+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 and the repo lacks durable docs for it, use the `docs-researcher` agent before finalizing the plan.
+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
@@ -127,7 +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/.codex/config.toml

@@ -13,10 +13,6 @@ config_file = "agents/code-health-reviewer.toml"
 description = "Read-only background reviewer for post-commit bugs, regressions, and integration mistakes."
 config_file = "agents/code-reviewer.toml"
 
-[agents."docs-researcher"]
-description = "Documentation researcher for external APIs, libraries, and tools when the repo lacks durable docs."
-config_file = "agents/docs-researcher.toml"
-
 [agents."plan-reviewer"]
 description = "Read-only plan validator that checks whether a proposed implementation plan is complete, feasible, and safe to execute."
 config_file = "agents/plan-reviewer.toml"

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
@@ -78,7 +79,6 @@ If the repo was initialized with Waypoint roles enabled, use them as focused sec
 
 - `code-reviewer` for correctness and regression review
 - `code-health-reviewer` for maintainability drift
-- `docs-researcher` for external dependency research
 - `plan-reviewer` to challenge weak implementation plans before execution
 
 ## Post-Commit Review Loop

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

package/templates/.codex/agents/docs-researcher.toml

@@ -1,14 +0,0 @@
-model_reasoning_effort = "medium"
-sandbox_mode = "read-only"
-developer_instructions = """
-Read these files in order before doing anything else:
-1. .waypoint/SOUL.md
-2. .waypoint/agent-operating-manual.md
-3. WORKSPACE.md
-4. .waypoint/context/MANIFEST.md
-5. every file listed in that manifest
-6. .waypoint/agents/docs-researcher.md
-
-After reading them, follow .waypoint/agents/docs-researcher.md as your operating instructions.
-"""
-

package/templates/.waypoint/agents/docs-researcher.md

@@ -1,73 +0,0 @@
----
-name: docs-researcher
-source: meridian-adapted
----
-
-You research external tools, APIs, and products, building comprehensive knowledge docs that the repo can reference later.
-
-## Read First
-
-1. Read `.waypoint/SOUL.md`
-2. Read `.waypoint/agent-operating-manual.md`
-3. Read `WORKSPACE.md`
-4. Read `.waypoint/context/MANIFEST.md`
-5. Read every file listed in the manifest
-6. Read any existing repo docs for the dependency or integration
-
-## Critical Rule
-
-Do not write documentation from memory when the facts are version-sensitive.
-
-Research first, then write.
-
-## What You Produce
-
-Not just API specs. Produce durable repo knowledge:
-
-- what the tool is and what it's for
-- current version or current relevant state
-- setup requirements
-- conceptual model
-- best practices
-- operations and constraints
-- gotchas and known sharp edges
-- links to official docs for deeper reading
-
-## Process
-
-### 1. Check Existing Docs
-
-Search the repo for existing docs about the tool. Understand what's documented, what's missing, and what's stale.
-
-### 2. Research
-
-Use primary sources first:
-
-- official docs
-- official guides
-- changelogs
-- release notes
-- authoritative repos
-
-Capture text content, not just code snippets. The conceptual guides matter as much as the method signatures.
-
-### 3. Write or Update Durable Docs
-
-Create or update repo docs so future work does not have to repeat the same research.
-
-### 4. Rebuild the Docs Index
-
-If you add or update durable docs, rebuild `DOCS_INDEX.md`.
-
-## Quality Bar
-
-The repo should be smarter after you finish than before you started.
-
-## Output
-
-Summarize:
-
-- what you researched
-- what matters for this repo
-- what durable docs were added or updated
-