waypoint-codex 0.1.0

package/dist/src/templates.js

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function findTemplatesRoot() {
+    const candidates = [
+        path.resolve(__dirname, "../templates"),
+        path.resolve(__dirname, "../../templates"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(path.join(candidate, "managed-agents-block.md"))) {
+            return candidate;
+        }
+    }
+    throw new Error("Could not locate Waypoint templates directory.");
+}
+const templatesRoot = findTemplatesRoot();
+export const MANAGED_BLOCK_START = "<!-- waypoint:start -->";
+export const MANAGED_BLOCK_END = "<!-- waypoint:end -->";
+export function templatePath(relativePath) {
+    return path.join(templatesRoot, relativePath);
+}
+export function readTemplate(relativePath) {
+    return readFileSync(templatePath(relativePath), "utf8");
+}
+export function renderWaypointConfig(options) {
+    return readTemplate(".waypoint/config.toml")
+        .replace("__PROFILE__", options.profile)
+        .replace("__ROLES__", String(options.roles))
+        .replace("__RULES__", String(options.rules))
+        .replace("__AUTOMATIONS__", String(options.automations));
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "waypoint-codex",
+  "version": "0.1.0",
+  "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "waypoint": "bin/waypoint.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "changeset": "changeset",
+    "check": "npm run clean && npm run build && npm test",
+    "clean": "rm -rf dist",
+    "dev": "tsx src/cli.ts",
+    "prepack": "npm run check",
+    "release": "npm publish --access public",
+    "version-packages": "changeset version",
+    "test": "tsx --test tests/**/*.test.ts"
+  },
+  "keywords": [
+    "codex",
+    "agents",
+    "automation",
+    "skills",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.6",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5"
+  }
+}

package/templates/.agents/skills/error-audit/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: error-audit
+description: Audit code for silent error swallowing, fallbacks to degraded alternatives, backwards compatibility shims, and UI that fails to show errors to the user. Finds and fixes all occurrences in the specified scope.
+---
+
+# Error Audit
+
+The core principle: **every error belongs to the user**. Not to a catch block, not to a console, not to a null return. Scan the specified code, fix every violation, report what changed.
+
+## 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 `references/error-patterns.md`
+
+## Step 0: Understand the app's error mechanisms
+
+Before fixing anything, identify how this app surfaces errors to users — toast notifications, error banners, error boundaries, returned error states, alert dialogs, inline messages. Use these patterns exclusively. Don't invent a new one.
+
+## Anti-patterns to find and fix
+
+**Silent error swallowing — backend/logic layer:**
+- Empty catch blocks: `catch(e) {}`
+- Log-and-continue with execution proceeding normally
+- `.catch(() => {})` on promises
+- Functions returning `null`, `undefined`, or empty defaults on failure instead of throwing
+
+**Silent error swallowing — UI layer:**
+- Data fetching catches an error and returns null/empty -> component renders blank with no explanation
+- Error boundaries that catch but show nothing (or a generic "something went wrong" with no recovery path)
+- `try/catch` in a loader or server action that swallows the error and returns partial/empty data
+- Async operations where the UI has no error state at all — success renders fine, failure renders identical to loading or empty
+
+**Fallbacks to degraded alternatives:**
+- Catch -> silently switch to a worse model, API, or service
+- Catch -> return cached or stale data without telling the user
+- Catch -> offline/degraded mode with no visible indication
+
+**Backwards compatibility shims:**
+- `if (legacyFormat)` or `if (oldVersion)` branches
+- Deprecated fields still being populated alongside new ones
+- Old code paths running in parallel with new ones
+
+**Config defaults that hide misconfiguration:**
+- `process.env.X || 'fallback'` for required values — missing required config is a startup crash, not a default
+- Optional environment variables that should be required
+
+**Optional chaining hiding missing required data:**
+- `user?.profile?.name ?? 'Guest'` when profile must always exist — the absence is a bug, not an edge case to handle silently
+
+## Fix principles
+
+- Throw or re-throw rather than catch-and-continue
+- In the UI: every error path must render something visible — use the app's established error display mechanism
+- Required config missing at startup -> log a clear message and exit
+- Delete fallback branches — don't comment them out
+- When unsure if a fallback was intentional, flag it in your report rather than guessing
+
+## Reference files
+
+- `references/error-patterns.md` — Concrete anti-patterns with structural descriptions, examples, and false positive notes. Read this before starting the audit.
+
+## Report
+
+After fixing, summarize by file: what was found, what the fix was. Be specific — file paths and the pattern removed.
+

package/templates/.agents/skills/error-audit/references/error-patterns.md

@@ -0,0 +1,37 @@
+# Error Anti-Patterns Reference
+
+Patterns to identify when auditing error handling. Each section describes the anti-pattern structurally — what the code does, not just what keywords to grep for.
+
+## Silent error swallowing
+
+- empty catch blocks
+- `.catch(() => {})`
+- broad exception handlers that return defaults
+- ignored Go errors via `_`
+
+## Log-and-continue
+
+An error gets logged, but execution continues as if the operation succeeded.
+
+## Return-null-on-failure
+
+The function converts a real operational failure into what looks like a normal "empty" result.
+
+## Invisible degradation
+
+The code silently falls back to a worse model, API, cache, or degraded mode with no visible signal.
+
+## Config defaults hiding misconfiguration
+
+Required settings should fail loudly, not silently pick a fallback.
+
+## UI error blindness
+
+Failure should not render the same as loading or empty.
+
+Quality bar:
+
+- confirm the issue is real in context
+- prefer concrete fixes over broad rewrites
+- use existing repo patterns for user-visible error handling
+

package/templates/.agents/skills/observability-audit/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: observability-audit
+description: Audit code for observability gaps — debug logs left in, errors caught without being logged, missing context on log entries, and untracked slow operations. Uses the app's existing observability tooling exclusively.
+---
+
+# Observability Audit
+
+Code that works locally but is impossible to debug in production. This skill finds and fixes observability gaps using whatever tools the app already has.
+
+## 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 `references/observability-patterns.md`
+
+## Step 0: Research existing observability tooling
+
+Before anything else, explore the codebase to understand what's already in use:
+
+- Error tracking
+- Logging
+- APM / metrics
+- Analytics
+- Any custom logger or telemetry utilities
+
+Read how they're configured and how they're used. All fixes must use these — never introduce a new observability dependency or pattern.
+
+## What to look for
+
+**Debug artifacts left in production code**
+
+**Errors that disappear**
+
+**Missing context on log entries**
+
+**Untracked slow or critical operations**
+
+See `references/observability-patterns.md` for concrete patterns.
+
+## Process
+
+1. Research existing tooling
+2. Identify the scope
+3. Find every instance of the anti-patterns
+4. Fix using the existing tooling and patterns
+5. Remove debug artifacts, add context to thin logs, add tracking where missing
+6. Report changes
+
+## Fix principles
+
+- Every caught error should be logged with enough context to reproduce the problem
+- Use the existing logger/tracker — never introduce a second one
+- Debug `console.log` goes away entirely — no conversion to structured log, just deleted
+- Log context should include: what operation, what failed, relevant IDs
+- Don't add logging to every function — focus on boundaries and critical paths
+
+## Reference files
+
+- `references/observability-patterns.md` — Detection patterns, bad/fix examples for debug artifacts, missing logging, missing context, untracked operations. Read before starting the audit.
+
+## Report
+
+Summarize by file: what was removed, what was added or improved, what context was missing and is now included.
+

package/templates/.agents/skills/observability-audit/references/observability-patterns.md

@@ -0,0 +1,35 @@
+# Observability Anti-Patterns Reference
+
+Use this file to guide observability audits.
+
+## Debug artifacts
+
+- `console.log`, `console.debug`, `print`, `fmt.Printf` in non-CLI production paths
+- commented-out debug statements
+- `debugger` and focused tests left behind
+
+## Errors without useful traces
+
+- catch/except blocks that rethrow or return without logging context
+- tracker calls with no metadata
+- logs that say "failed" without saying what failed
+
+## Missing context
+
+- no user, entity, request, or job identifiers
+- no operation name
+- no correlation/request ID at service boundaries
+
+## Slow paths with no timing
+
+- external API calls
+- critical database queries
+- background jobs without start/complete/fail visibility
+- webhook handlers with no event-level logging
+
+Quality bar:
+
+- use the existing observability stack
+- improve debugging value, not log volume
+- focus on boundaries and critical paths
+

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

@@ -0,0 +1,133 @@
+---
+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.
+---
+
+# Planning
+
+Good plans prove you understand the problem. Size matches complexity — a rename might be 20 lines, a complex feature might be 500.
+
+**The handoff test:** Could someone implement this plan without asking you questions? If not, find what's missing.
+
+## Read First
+
+Before planning:
+
+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 the routed docs relevant to the task
+
+## Verbatim Requirements
+
+Capture the user's exact words at the top of every plan when the wording matters. No paraphrasing, no compression.
+
+```markdown
+## Verbatim Requirements
+
+### Original Request
+> [User's ENTIRE message, word for word]
+
+### Clarifications
+**Q:** [Your question]
+**A:** [User's ENTIRE answer, verbatim]
+```
+
+## The Core Loop
+
+```
+ASK -> EXPLORE -> LEARN -> MORE QUESTIONS? -> REPEAT
+```
+
+Keep looping until you can explain:
+
+- what exists today
+- how the data and control flow work
+- what needs to change
+- what could go wrong
+
+## 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.
+
+Interview iteratively: 2-4 questions -> answers -> deeper follow-ups -> repeat. Each round should go deeper.
+
+- Simple bug -> a few focused questions
+- Feature or migration -> many rounds of questions
+- Architectural work -> keep drilling until the constraints and tradeoffs are clear
+
+Push back when something seems off. Neutrality is not the goal; correctness is.
+
+## Exploring the Codebase
+
+**More exploration = better plans.** The number one cause of plan failure is insufficient exploration.
+
+Explore until you stop having questions, not until you've "done enough."
+
+Use the repository like a map:
+
+- find the real entry points
+- trace callers and imports
+- inspect nearby modules solving similar problems
+- identify existing patterns worth following
+- identify constraints that the change must respect
+
+Do not plan from abstractions alone. Ground major decisions in actual files.
+
+## Plan Content
+
+Plans document your understanding. Include what matters for this task:
+
+- **Current State**: What exists today — relevant files, data flows, constraints, existing patterns
+- **Changes**: Every file to create/modify/delete, how changes connect
+- **Decisions**: Why this approach, tradeoffs, assumptions
+- **Acceptance criteria**: What must be true when each step is "done"
+- **Test cases**: For behavioral changes, include input -> expected output examples
+- **Non-Goals**: Explicitly out of scope to prevent implementation drift
+
+Use ASCII diagrams when they clarify flow, layering, or state.
+
+## Self-Review Before Finalizing
+
+Before presenting the plan, verify against real code:
+
+- existing controls
+- state invariants
+- transaction boundaries for multi-write operations
+- verification executability with current tooling
+
+## Rules
+
+- No TBD
+- No "we'll figure it out during implementation"
+- No literal code unless the user explicitly wants it
+- No pretending you verified something you didn't
+
+If the change touches durable project behavior, include docs/workspace updates in the plan.
+
+## 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.
+
+## Output
+
+A good final plan usually includes:
+
+1. Current state
+2. Proposed changes
+3. Decisions and tradeoffs
+4. Acceptance criteria
+5. Verification
+6. TL;DR
+
+## 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/.agents/skills/ux-states-audit/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ux-states-audit
+description: Audit UI code for missing loading states, empty states, and error states. Every async operation and data-driven UI must handle all three. Finds gaps and implements the missing states using the app's existing patterns.
+---
+
+# UX States Audit
+
+Every piece of UI that fetches data or triggers async work has three states beyond the happy path: **loading**, **empty**, and **error**. LLMs implement the happy path and leave the rest blank. This skill finds and fills those gaps.
+
+This is distinct from `error-audit`: `error-audit` finds errors that are suppressed. This finds states that were never implemented.
+
+## 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 `references/ux-patterns.md`
+
+## Step 0: Understand existing patterns
+
+Before touching anything, read the codebase to understand how it currently handles these states:
+
+- loading components or primitives
+- empty state patterns
+- error display patterns
+
+Use these patterns exclusively. Don't introduce a new loading spinner if one already exists.
+
+## What to look for
+
+**Missing loading state**
+
+**Missing empty state**
+
+**Missing error state**
+
+See `references/ux-patterns.md` for concrete patterns.
+
+## Process
+
+1. Identify the scope
+2. Find every component that fetches data or triggers async work
+3. For each: check whether loading, empty, and error states are handled
+4. Implement missing states using the patterns found in Step 0
+5. Report what was added, by component
+
+## Fix principles
+
+- Loading states should be immediate
+- Empty states should explain the situation and, where appropriate, offer an action
+- Error states should say what went wrong and what the user can do
+- Don't invent new UI primitives — use what already exists
+
+## Reference files
+
+- `references/ux-patterns.md` — Detection patterns and examples for missing loading, empty, and error states. Read before starting the audit.
+
+## Report
+
+Summarize by component: which states were missing, what was added.
+

package/templates/.agents/skills/ux-states-audit/references/ux-patterns.md

@@ -0,0 +1,34 @@
+# UX State Patterns Reference
+
+Use this file to guide UX state audits.
+
+## Missing loading state
+
+Look for:
+
+- fetch starts and nothing changes visually
+- button-triggered async action with no pending state
+- form submission with no disabled or in-progress signal
+
+## Missing empty state
+
+Look for:
+
+- empty lists rendering blank space
+- search results with no explanation when empty
+- dashboard widgets vanishing instead of explaining that no data exists
+
+## Missing error state
+
+Look for:
+
+- fetch failure rendering the same as loading
+- mutation failure with no user-visible feedback
+- components returning blank/null on failure
+
+Quality bar:
+
+- use the repo's established UI primitives
+- implement all three states where relevant
+- favor clarity over decorative treatment
+

package/templates/.codex/agents/code-health-reviewer.toml

@@ -0,0 +1,14 @@
+model_reasoning_effort = "high"
+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/code-health-reviewer.md
+
+After reading them, follow .waypoint/agents/code-health-reviewer.md as your operating instructions.
+"""
+

package/templates/.codex/agents/code-reviewer.toml

@@ -0,0 +1,14 @@
+model_reasoning_effort = "high"
+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/code-reviewer.md
+
+After reading them, follow .waypoint/agents/code-reviewer.md as your operating instructions.
+"""
+

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

@@ -0,0 +1,14 @@
+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/.codex/agents/plan-reviewer.toml

@@ -0,0 +1,14 @@
+model_reasoning_effort = "high"
+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/plan-reviewer.md
+
+After reading them, follow .waypoint/agents/plan-reviewer.md as your operating instructions.
+"""
+

package/templates/.codex/config.toml

@@ -0,0 +1,19 @@
+[agents]
+max_depth = 1
+max_threads = 4
+
+[agents."code-health-reviewer"]
+description = "Read-only reviewer focused on maintainability drift, dead code, duplication, and refactoring opportunities worth fixing."
+config_file = "agents/code-health-reviewer.toml"
+
+[agents."code-reviewer"]
+description = "Read-only deep code reviewer focused on real 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/.gitignore.snippet

@@ -0,0 +1,3 @@
+# Waypoint state
+.waypoint/state/
+.waypoint/context/

package/templates/.waypoint/README.md

@@ -0,0 +1,13 @@
+# .waypoint
+
+Repo-local Waypoint configuration and optional integration sources.
+
+- `config.toml` — Waypoint feature toggles and file locations
+- `SOUL.md` — agent identity and working values
+- `agent-operating-manual.md` — required session workflow
+- `agents/` — agent prompt files that optional Codex roles can read and follow
+- `automations/` — optional automation source specs
+- `context/` — generated session context bundle
+- `rules/` — optional rule source files
+- `scripts/` — repo-local Waypoint helper scripts
+- `state/` — local sync state and tooling metadata