waypoint-codex 0.1.0 → 0.1.1

package/README.md

@@ -1,156 +1,84 @@
 # Waypoint
 
-It gives a repository a clean working contract for Codex:
+Waypoint is a docs-first repository operating system for Codex.
 
-- a small `AGENTS.md` map
-- a live `WORKSPACE.md`
-- indexed `docs/`
-- repo-local skills under `.agents/skills/`
-- optional sync for Codex App automations and user-home rules
+It helps the next agent pick up your repo with full context by keeping the important things in markdown files inside the repo:
 
-Waypoint is a standalone Codex-native repository operating system. It is advisory-first, repo-local, and open-source-first.
+- `AGENTS.md` for startup instructions
+- `WORKSPACE.md` for live state
+- `.waypoint/docs/` for durable project memory
+- `DOCS_INDEX.md` for docs routing
+- repo-local skills for planning and audits
 
-## Why it exists
-
-The next agent should be able to pick up a repository with full context by reading the repository itself.
-
-Waypoint pushes projects toward:
-
-- docs-first project memory
-- visible operational state
-- explicit session bootstrap
-- battle-tested reusable workflows
-- less hidden magic and less reliance on chat history
-
-## What ships today
-
-- `waypoint init` — scaffold the core repository contract
-- `waypoint doctor` — validate repo health and detect drift
-- `waypoint sync` — rebuild `DOCS_INDEX.md` and optionally sync automations/rules into Codex home
-- `waypoint import-legacy` — analyze a legacy repository layout and write an adoption report into a target Waypoint repo
-
-## Install for development
-
-From the `projects/waypoint/` directory:
-
-```bash
-npm install
-npm run build
-```
-
-Run directly in development:
-
-```bash
-npm run dev -- --help
-```
-
-Run the compiled CLI after building:
-
-```bash
-node dist/src/cli.js --help
-```
-
-Run the tests:
-
-```bash
-npm test
-```
-
-## Install for usage
-
-Global install:
+## Install
 
 ```bash
 npm install -g waypoint-codex
 ```
 
-One-off usage:
+Or use it without installing globally:
 
 ```bash
 npx waypoint-codex@latest --help
 ```
 
-After upgrading the CLI, refresh a repo's scaffold with:
+## Start using it
+
+Inside your Codex project:
 
 ```bash
 waypoint init --with-automations --with-roles
 waypoint doctor
 ```
 
-## Quick start
-
-Initialize a repository:
-
-```bash
-npx tsx src/cli.ts init /path/to/repo
-```
-
-Check repo health:
-
-```bash
-npx tsx src/cli.ts doctor /path/to/repo
-```
-
-Sync optional user-home artifacts:
-
-```bash
-npx tsx src/cli.ts sync /path/to/repo
-```
-
-Analyze a legacy repository layout and scaffold a target Waypoint repo:
-
-```bash
-npx tsx src/cli.ts import-legacy /path/to/source-repo /path/to/new-repo --init-target
-```
-
-## Repo contract
-
-Waypoint creates and manages:
+That scaffolds:
 
 ```text
 repo/
 ├── AGENTS.md
 ├── WORKSPACE.md
 ├── DOCS_INDEX.md
-├── docs/
 ├── .agents/skills/
 └── .waypoint/
+    ├── docs/
+    ├── context/
+    └── ...
 ```
 
-Optional packs:
+## Main commands
 
-- `.waypoint/automations/*.toml`
-- `.waypoint/rules/*.rules`
-- `.codex/config.toml`
-- `.codex/agents/*.toml`
+- `waypoint init` — scaffold or refresh the repo
+- `waypoint doctor` — check for drift and missing pieces
+- `waypoint sync` — rebuild `DOCS_INDEX.md` and sync optional automations/rules
+- `waypoint import-legacy` — import from an older repo layout
 
-## Shipped Waypoint skills
+## Shipped skills
 
 - `planning`
 - `error-audit`
 - `observability-audit`
 - `ux-states-audit`
 
-## Optional role pack
+## Optional reviewer roles
 
-If you initialize with `--with-roles`, Waypoint also scaffolds project-scoped Codex role configs for:
+If you initialize with `--with-roles`, Waypoint scaffolds:
 
 - `code-health-reviewer`
 - `code-reviewer`
 - `docs-researcher`
 - `plan-reviewer`
 
-## Tested
-
-- `waypoint init`
-- `waypoint doctor`
-- `waypoint sync` with real Codex automation TOML output
-- `waypoint import-legacy`
+## Update
 
-## Notes
+```bash
+npm install -g waypoint-codex@latest
+waypoint init --with-automations --with-roles
+waypoint doctor
+```
 
-- Core Waypoint does not require Codex App, Cloud tasks, IDE integration, plugins, or MCP.
-- App automations are supported as an optional declarative sync target.
-- Rules are supported as an optional sync target.
+## Learn more
 
-For public docs, see [docs/overview.md](docs/overview.md), [docs/architecture.md](docs/architecture.md), [docs/upgrading.md](docs/upgrading.md), [docs/releasing.md](docs/releasing.md), and [docs/importing-existing-repos.md](docs/importing-existing-repos.md).
+- [Overview](docs/overview.md)
+- [Architecture](docs/architecture.md)
+- [Upgrading](docs/upgrading.md)
+- [Importing Existing Repositories](docs/importing-existing-repos.md)

package/dist/src/core.js

@@ -6,7 +6,7 @@ import * as TOML from "@iarna/toml";
 import { renderDocsIndex } from "./docs-index.js";
 import { readTemplate, renderWaypointConfig, MANAGED_BLOCK_END, MANAGED_BLOCK_START, templatePath } from "./templates.js";
 const DEFAULT_CONFIG_PATH = ".waypoint/config.toml";
-const DEFAULT_DOCS_DIR = "docs";
+const DEFAULT_DOCS_DIR = ".waypoint/docs";
 const DEFAULT_DOCS_INDEX = "DOCS_INDEX.md";
 const DEFAULT_WORKSPACE = "WORKSPACE.md";
 const STATE_DIR = ".waypoint/state";
@@ -91,6 +91,8 @@ function scaffoldOptionalCodex(projectRoot) {
 export function initRepository(projectRoot, options) {
     ensureDir(projectRoot);
     for (const deprecatedPath of [
+        "docs/README.md",
+        "docs/code-guide.md",
         ".agents/skills/waypoint-planning",
         ".agents/skills/waypoint-docs",
         ".agents/skills/waypoint-review",
@@ -123,8 +125,8 @@ export function initRepository(projectRoot, options) {
     }));
     writeIfMissing(path.join(projectRoot, DEFAULT_WORKSPACE), readTemplate("WORKSPACE.md"));
     ensureDir(path.join(projectRoot, DEFAULT_DOCS_DIR));
-    writeIfMissing(path.join(projectRoot, "docs/README.md"), readTemplate("docs/README.md"));
-    writeIfMissing(path.join(projectRoot, "docs/code-guide.md"), readTemplate("docs/code-guide.md"));
+    writeIfMissing(path.join(projectRoot, ".waypoint/docs/README.md"), readTemplate(".waypoint/docs/README.md"));
+    writeIfMissing(path.join(projectRoot, ".waypoint/docs/code-guide.md"), readTemplate(".waypoint/docs/code-guide.md"));
     upsertManagedBlock(path.join(projectRoot, "AGENTS.md"), readTemplate("managed-agents-block.md"));
     scaffoldSkills(projectRoot);
     if (options.withRoles) {
@@ -136,7 +138,7 @@ export function initRepository(projectRoot, options) {
     return [
         "Initialized Waypoint scaffold",
         "Installed managed AGENTS block",
-        "Created WORKSPACE.md and docs/ scaffold",
+        "Created WORKSPACE.md and .waypoint/docs/ scaffold",
         "Installed repo-local Waypoint skills",
         "Generated DOCS_INDEX.md",
     ];

package/dist/src/docs-index.js

@@ -78,7 +78,7 @@ export function renderDocsIndex(projectRoot, docsDir) {
         "",
         "Auto-generated by `waypoint sync` / `waypoint doctor`. Read matching docs before working on a task.",
         "",
-        "## docs/",
+        "## .waypoint/docs/",
         "",
     ];
     if (entries.length === 0) {

package/package.json

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

package/templates/.waypoint/README.md

@@ -5,6 +5,7 @@ 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
+- `docs/` — Waypoint-managed project memory (architecture, decisions, debugging knowledge, durable plans)
 - `agents/` — agent prompt files that optional Codex roles can read and follow
 - `automations/` — optional automation source specs
 - `context/` — generated session context bundle

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

@@ -20,7 +20,7 @@ Do not skip this sequence.
 The repository should contain the context the next agent needs.
 
 - `WORKSPACE.md` is the live operational record: in progress, current state, next steps
-- `docs/` is the durable project memory: architecture, decisions, integration notes, debugging knowledge, and durable plans
+- `.waypoint/docs/` is the durable project memory: architecture, decisions, integration notes, debugging knowledge, and durable plans
 - `.waypoint/context/` is the generated session context bundle: current git/PR/doc index state
 
 If something important lives only in your head or in the chat transcript, the repo is under-documented.
@@ -30,7 +30,7 @@ If something important lives only in your head or in the chat transcript, the re
 - Read code before editing it.
 - Follow the repo's documented patterns when they are healthy.
 - Update `WORKSPACE.md` as live execution state when progress meaningfully changes.
-- Update `docs/` when durable knowledge changes.
+- Update `.waypoint/docs/` when durable knowledge changes.
 - Rebuild `DOCS_INDEX.md` whenever routable docs change.
 - Use the repo-local skills and optional reviewer agents instead of improvising from scratch.
 

package/templates/.waypoint/config.toml

@@ -1,7 +1,7 @@
 version = 1
 profile = "__PROFILE__"
 workspace_file = "WORKSPACE.md"
-docs_dir = "docs"
+docs_dir = ".waypoint/docs"
 docs_index_file = "DOCS_INDEX.md"
 
 [features]
@@ -10,4 +10,3 @@ docs_index = true
 roles = __ROLES__
 rules = __RULES__
 automations = __AUTOMATIONS__
-

package/templates/.waypoint/docs/README.md

@@ -0,0 +1,27 @@
+# Waypoint Docs
+
+This directory is Waypoint-managed project memory.
+
+Put the durable context here that the next agent will need to continue the work:
+
+- architecture
+- decisions and tradeoffs
+- integration notes
+- invariants and constraints
+- debugging knowledge
+- active plans that should survive beyond one session
+
+These are **project docs**, not Waypoint internals.
+
+Every routable doc needs YAML frontmatter:
+
+```yaml
+---
+summary: One-line description
+read_when:
+  - task cue
+---
+```
+
+`DOCS_INDEX.md` is generated from the docs here.
+

package/templates/.waypoint/docs/code-guide.md

@@ -0,0 +1,95 @@
+---
+summary: Opinionated rules for writing and changing Waypoint code so behavior stays explicit, strict, observable, and easy to evolve.
+read_when:
+  - writing new code
+  - changing existing behavior
+  - introducing or removing configuration
+  - handling external input or external systems
+  - adding tests, logging, or state transitions
+---
+
+# Code Guide
+
+Waypoint favors explicitness over convenience, correctness over compatibility theater, and deletion over accumulation. Code should make the system easier to reason about after the change, not merely pass today.
+
+## 1. Compatibility is opt-in, not ambient
+
+Do not preserve old behavior unless a user-facing requirement explicitly asks for it.
+
+When replacing a path, remove the old one instead of leaving a shim, alias, translation layer, or silent compatibility branch. If compatibility must be preserved, document the exact contract being preserved and the planned removal condition.
+
+Do not keep dead fields, dead parameters, dual formats, or migration-only logic "just in case". Every compatibility layer becomes part of the design whether intended or not.
+
+## 2. Fail clearly, never quietly
+
+Errors are part of the contract. Surface them early and with enough context to diagnose the cause.
+
+Do not swallow errors, downgrade them to logs, or return partial success unless partial success is the explicit API. If an operation can fail in distinct ways, preserve those distinctions. Do not replace a specific failure with a generic one that destroys meaning.
+
+Error messages should identify what failed, at which boundary, and why the system refused to proceed. They should not force readers to infer missing state from generic text.
+
+## 3. No silent fallback paths
+
+Fallbacks are allowed only when they are deliberate product behavior, not a coding reflex.
+
+Do not silently retry with weaker behavior, alternate providers, cached data, inferred defaults, empty values, or best-effort modes unless the user asked for degraded operation and the degraded result remains truthful.
+
+If degradation exists, it must be explicit in code, testable, and observable. Hidden fallback logic makes the system look healthy while it is already off-contract.
+
+## 4. Validate at boundaries, not deep inside
+
+Anything that crosses a boundary must be treated as untrusted: user input, config, environment, files, network responses, database reads, queue payloads, generated content, and data from other modules.
+
+Validate structure, required fields, allowed values, and invariants at the boundary. Convert external data into a trusted internal shape once. Do not pass loosely-typed or half-validated data deeper into the system and hope downstream code copes.
+
+Boundary validation should reject invalid data, not "normalize" it into something ambiguous.
+
+## 5. Configuration must be strict
+
+Missing or invalid configuration should stop the system at startup or at the feature boundary where it becomes required.
+
+Do not hide absent configuration behind guessed defaults, environment-dependent behavior, or implicit no-op modes. Defaults are acceptable only when they are safe, intentional, and documented as part of the product contract.
+
+Configuration should be centralized enough to audit. A reader should be able to tell which settings matter, what values are valid, and what happens when they are wrong.
+
+## 6. Prefer direct code over speculative abstraction
+
+Do not introduce abstractions for imagined future use. Add them only when multiple concrete cases already demand the same shape.
+
+A small amount of duplication is cheaper than the wrong abstraction. Prefer code that exposes the current domain plainly over generic layers, plugin systems, factories, wrappers, or strategy trees created before the need is real.
+
+Abstractions must remove real complexity, not relocate it. If a helper hides critical behavior, state changes, validation, or failure modes, it is making the system harder to read.
+
+## 7. Make state and invariants explicit
+
+State transitions should be visible in code. Readers should be able to answer: what states exist, what moves the system between them, and what must always be true.
+
+Do not encode important transitions as scattered flag mutations, ordering assumptions, optional fields, or side effects hidden in utility calls. Avoid representations where invalid states are easy to create and hard to detect.
+
+When a function changes state, make the transition obvious. When a module depends on an invariant, assert it at the boundary of the operation instead of relying on folklore.
+
+## 8. Tests define behavior changes, not just regressions
+
+Any behavior change must update tests to describe the new contract. If the old behavior mattered, remove or rewrite the old tests instead of making them weaker.
+
+Test observable behavior and boundary cases, not implementation trivia. Cover failure modes, validation rules, configuration strictness, and any intentional degradation path. If a bug fix closes a previously possible bad state, add a test that proves the bad state is now rejected.
+
+Do not merge code whose behavior changed without leaving behind executable evidence of the new rules.
+
+## 9. Observability is part of correctness
+
+Code is not complete if production failures cannot be understood from its signals.
+
+Emit structured logs, metrics, or events at important boundaries and state transitions, especially around input rejection, external calls, retries, and degraded modes. Observability should explain which path executed and why.
+
+Do not log noise to compensate for poor design. Prefer a small number of high-value signals tied to decisions, failures, and contract edges.
+
+## 10. Optimize for future legibility
+
+Write code for the next person who must change it under pressure.
+
+Keep modules narrow in responsibility. Keep data flow obvious. Keep control flow boring. Prefer designs where the main path is easy to follow and unusual behavior is explicitly named.
+
+When changing code, improve the shape around the change if needed. Do not leave behind half-migrated designs, obsolete branches, commented-out code, or placeholders for imagined follow-ups.
+
+The best code is not code that can handle every possible future. It is code whose current truth is obvious, whose failures are visible, and whose wrong parts can be deleted without fear.

package/templates/.waypoint/scripts/build-docs-index.mjs

@@ -108,7 +108,7 @@ function walkDocs(projectRoot, currentDir, output) {
 }
 
 export function renderDocsIndex(projectRoot) {
-  const docsDir = path.join(projectRoot, "docs");
+  const docsDir = path.join(projectRoot, ".waypoint", "docs");
   const entries = [];
 
   if (existsSync(docsDir)) {
@@ -120,7 +120,7 @@ export function renderDocsIndex(projectRoot) {
     "",
     "Auto-generated by `.waypoint/scripts/build-docs-index.mjs`. Read matching docs before working on a task.",
     "",
-    "## docs/",
+    "## .waypoint/docs/",
     "",
   ];
 

package/templates/managed-agents-block.md

@@ -15,7 +15,7 @@ This is mandatory, not optional. Do not skip the context refresh or skip files i
 
 Working rules:
 - Keep `WORKSPACE.md` current as the live execution state
-- Update `docs/` when behavior or durable project knowledge changes
+- Update `.waypoint/docs/` when behavior or durable project knowledge changes
 - Use the repo-local skills Waypoint ships for structured workflows when relevant
 - Treat the generated context bundle as required session bootstrap, not optional reference material
 <!-- waypoint:end -->

package/templates/docs/README.md

@@ -1,16 +0,0 @@
-# Docs
-
-Store durable project knowledge here.
-
-Each document that should be routable by Codex needs YAML frontmatter:
-
-```yaml
----
-summary: One-line description
-read_when:
-  - keyword or task cue
----
-```
-
-`DOCS_INDEX.md` is generated from the docs that include this frontmatter.
-

package/templates/docs/code-guide.md

@@ -1,31 +0,0 @@
----
-summary: Repository coding conventions — correctness, explicit error handling, maintainability, and testing discipline
-read_when:
-  - writing code
-  - implementing a feature
-  - fixing a bug
-  - updating tests
----
-
-# Code Guide
-
-## Core rules
-
-- Prefer explicit behavior over clever shortcuts.
-- Keep changes scoped and reviewable.
-- Update docs when durable behavior changes.
-- Validate external data at boundaries.
-- Do not swallow errors silently.
-
-## Testing
-
-- Run the smallest relevant verification first.
-- Add or update tests when behavior changes.
-- If tests cannot be run, say exactly why.
-
-## Maintainability
-
-- Reuse existing patterns where they are healthy.
-- Do not introduce hidden fallback behavior without making it visible.
-- Prefer clear names and clear module boundaries over compact code.
-