Release Waypoint 0.13.0

Author: markmdev

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- Separate durable plan docs from long-lived project docs in the Waypoint scaffold.
+
+  New repos now get a dedicated `.waypoint/plans/` directory, the docs index routes both docs and plans, and the built-in guidance now points planning workflows at the new plans layer instead of mixing plans into `.waypoint/docs/`.
+
+- Remove the `visual-explanations` skill and simplify Waypoint's visual guidance.
+
+  Visual explanation now stays in the core contract: use Mermaid directly in chat for diagrams, and show screenshots whenever browser or app inspection is part of reproduction or verification work. The public docs were also tightened so they describe Waypoint more directly and leave per-skill trigger logic inside the skills themselves.
+
 ## 0.12.2
 
 ### Patch Changes

README.md

@@ -9,12 +9,11 @@ It exists to solve two problems at the same time:
 
 ## What Waypoint is for
 
-Most agent setups break down in one of two ways:
+Waypoint is built for repos where continuity and collaboration both matter.
 
-- the repo has no memory, so the next session starts half-blind
-- the repo has too much process in the always-on prompt, so the agent starts sounding like a compliance layer
+It gives the next session real context and keeps the current session clear and useful.
 
-Waypoint is meant to sit in the middle:
+Waypoint adds:
 
 - explicit repo-local memory
 - strong default collaboration
@@ -57,8 +56,9 @@ Waypoint scaffolds a Codex-friendly repo around a few core pieces:
 - `AGENTS.md` for the startup contract
 - `.waypoint/MEMORY.md` for durable user/team preferences and collaboration context
 - `.waypoint/WORKSPACE.md` for live operational state
-- `.waypoint/docs/` for durable project memory
-- `.waypoint/DOCS_INDEX.md` for docs routing
+- `.waypoint/docs/` for long-lived project docs
+- `.waypoint/plans/` for durable plan documents
+- `.waypoint/DOCS_INDEX.md` for docs and plans routing
 - `.waypoint/context/` for generated startup context
 - `.waypoint/track/` for long-running work that truly needs durable progress tracking
 - `.agents/skills/` for optional structured workflows
@@ -70,7 +70,7 @@ The philosophy is simple:
 - more explicit repo-local state
 - stronger default collaboration
 - investigation before status narration
-- procedures as tools, not identity
+- structured workflows that stay in their own tools
 
 ## Best fit
 
@@ -108,6 +108,7 @@ repo/
     ├── TRACKS_INDEX.md
     ├── WORKSPACE.md
     ├── docs/
+    ├── plans/
     ├── track/
     ├── context/
     ├── scripts/
@@ -135,12 +136,8 @@ Waypoint ships a strong default skill pack for real coding work:
 
 These are repo-local, so the workflow travels with the project.
 
-The important design choice is that they are tools, not default ceremony. Use them when the task calls for them:
-
-- `planning` when the shape of the work needs real clarification
-- `adversarial-review` when you want a deliberate ship-readiness or risky-change second pass
-- `work-tracker` when the work will span sessions
-- `conversation-retrospective` when there is durable learning worth preserving
+The important design choice is that they stay out of the always-on voice.
+Each skill explains what it is for and when it should be invoked.
 
 ## Reviewer agents
 
@@ -152,22 +149,16 @@ Waypoint scaffolds these reviewer agents by default:
 
 They are available for deliberate second passes.
 
-Use them when:
-
-- the change is risky
-- you want extra confidence
-- the user explicitly asks for review or ship-readiness
-- a PR workflow needs an explicit review pass
-
 ## What makes Waypoint different
 
 Waypoint is opinionated, but explicit:
 
 - state lives in files you can inspect
 - docs routing is generated, not guessed from memory
 - the default contract tells the agent to investigate first
-- durable memory is separated into user/team memory, live workspace state, and project docs
-- heavy procedure lives in optional skills instead of the always-on voice
+- durable memory is separated into user/team memory, live workspace state, project docs, and plan docs
+- visual explanation stays lightweight: Mermaid in chat and screenshots from real UI inspection
+- heavier workflows stay in optional skills
 
 ## Install
 
@@ -187,7 +178,7 @@ npx waypoint-codex@latest --help
 
 - `waypoint init` — scaffold or refresh the repo and, by default, update the global CLI first
 - `waypoint doctor` — validate health and report drift
-- `waypoint sync` — rebuild the docs and tracker indexes
+- `waypoint sync` — rebuild the docs/plans and tracker indexes
 - `waypoint upgrade` — update the CLI and refresh the current repo using its saved config
 
 ## Learn more

docs/architecture.md

@@ -28,6 +28,7 @@ Waypoint separates repo memory into three different jobs:
 - `.waypoint/MEMORY.md` for durable user/team preferences, collaboration context, and stable defaults
 - `.waypoint/WORKSPACE.md` for live operational state
 - `.waypoint/docs/` for durable project behavior, architecture, decisions, and debugging knowledge
+- `.waypoint/plans/` for durable implementation, rollout, migration, and investigation plans
 
 This separation matters because many bad agent experiences come from mixing personal preferences, active task state, and project knowledge into one noisy blob.
 
@@ -95,9 +96,7 @@ Waypoint adds rigor through explicit escalation paths:
 
 ## Review model
 
-Review still matters.
-
-Waypoint just treats it as a tool rather than the default voice of the system.
+Waypoint offers deliberate second-pass review for moments that benefit from extra scrutiny.
 
 Use second-pass review when:
 
@@ -106,7 +105,7 @@ Use second-pass review when:
 - you are preparing to ship
 - a PR workflow calls for it
 
-`adversarial-review` is the main explicit closeout workflow for those cases.
+`adversarial-review` is the main repo-local workflow for that pass.
 
 ## Bootstrap flow
 

docs/overview.md

@@ -7,23 +7,12 @@ Its job is to make agents better in two directions at once:
 - better continuity across sessions
 - better default behavior inside the current session
 
-## The problem it is solving
+## What Waypoint improves
 
-Agent setups usually fail in one of two ways.
+Waypoint helps a repo in two directions at once:
 
-The first failure mode is memory:
-
-- important context lives only in chat
-- the next session starts half-blind
-- the agent does not know which docs matter
-
-The second failure mode is process:
-
-- too much workflow lives in the always-on prompt
-- the agent starts narrating readiness instead of investigating
-- reviews, trackers, and closeout rituals start feeling like personality instead of tools
-
-Waypoint is designed to solve both.
+- it gives the next session real context through visible memory files
+- it gives the current session a clear working style focused on diagnosis, progress, and verification
 
 ## The Waypoint stance
 
@@ -35,6 +24,8 @@ In practice, that means:
 - lead with diagnosis and next action
 - verify before claiming success
 - keep the repo legible for the next agent
+- show screenshots when browser or app work is part of what the agent inspected or verified
+- use Mermaid in chat when a diagram explains the point more clearly
 
 ## Core pieces
 
@@ -43,7 +34,8 @@ Waypoint combines:
 - a repo contract in `AGENTS.md`
 - durable user/team memory in `.waypoint/MEMORY.md`
 - live operating state in `.waypoint/WORKSPACE.md`
-- durable project memory in `.waypoint/docs/`
+- long-lived project memory in `.waypoint/docs/`
+- durable planning docs in `.waypoint/plans/`
 - generated routing and context files
 - repo-local skills for optional structured workflows
 - optional reviewer/helper agents for deliberate second passes

docs/upgrading.md

@@ -61,7 +61,7 @@ The core contract should read like a strong collaborator with clear judgment and
 Review loops, ship audits, trackers, and retrospectives should stay available without taking over the always-on layer.
 
 3. Repo memory still has clear boundaries.
-`.waypoint/MEMORY.md`, `.waypoint/WORKSPACE.md`, and `.waypoint/docs/` should still have distinct jobs.
+`.waypoint/MEMORY.md`, `.waypoint/WORKSPACE.md`, `.waypoint/docs/`, and `.waypoint/plans/` should still have distinct jobs.
 
 ## If you customized a repo
 

package.json

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

src/cli.ts

@@ -39,7 +39,7 @@ function printHelp(): void {
 Commands:
   init                Initialize a repository with Waypoint scaffolding (auto-updates CLI unless skipped)
   doctor              Validate repository health and report drift
-  sync                Rebuild docs and tracker indexes
+  sync                Rebuild docs/plans and tracker indexes
   upgrade             Update the global Waypoint CLI and refresh this repo using existing config
 `);
 }

src/core.ts

@@ -20,6 +20,7 @@ const DEFAULT_CONFIG_PATH = ".waypoint/config.toml";
 const DEFAULT_DOCS_DIR = ".waypoint/docs";
 const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
 const DEFAULT_MEMORY = ".waypoint/MEMORY.md";
+const DEFAULT_PLANS_DIR = ".waypoint/plans";
 const DEFAULT_TRACK_DIR = ".waypoint/track";
 const DEFAULT_TRACKS_INDEX = ".waypoint/TRACKS_INDEX.md";
 const DEFAULT_WORKSPACE = ".waypoint/WORKSPACE.md";
@@ -40,7 +41,6 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
   ".agents/skills/docs-sync/",
   ".agents/skills/code-guide-audit/",
   ".agents/skills/adversarial-review/",
-  ".agents/skills/visual-explanations/",
   ".agents/skills/break-it-qa/",
   ".agents/skills/frontend-context-interview/",
   ".agents/skills/backend-context-interview/",
@@ -75,7 +75,6 @@ const SHIPPED_SKILL_NAMES = [
   "docs-sync",
   "code-guide-audit",
   "adversarial-review",
-  "visual-explanations",
   "break-it-qa",
   "conversation-retrospective",
   "workspace-compress",
@@ -96,6 +95,19 @@ const TIMESTAMPED_WORKSPACE_SECTIONS = new Set([
 ]);
 const TIMESTAMPED_ENTRY_PATTERN = /^(?:[-*]|\d+\.)\s+\[\d{4}-\d{2}-\d{2} \d{2}:\d{2} [A-Z]{2,5}\]/;
 
+function docsIndexSections(projectRoot: string, config?: WaypointConfig): { heading: string; dir: string }[] {
+  return [
+    {
+      heading: ".waypoint/docs/",
+      dir: path.join(projectRoot, config?.docs_dir ?? DEFAULT_DOCS_DIR),
+    },
+    {
+      heading: ".waypoint/plans/",
+      dir: path.join(projectRoot, config?.plans_dir ?? DEFAULT_PLANS_DIR),
+    },
+  ];
+}
+
 function ensureDir(dirPath: string): void {
   mkdirSync(dirPath, { recursive: true });
 }
@@ -363,22 +375,24 @@ export function initRepository(
   );
   writeIfMissing(path.join(projectRoot, DEFAULT_WORKSPACE), readTemplate("WORKSPACE.md"));
   ensureDir(path.join(projectRoot, DEFAULT_DOCS_DIR));
+  ensureDir(path.join(projectRoot, DEFAULT_PLANS_DIR));
   ensureDir(path.join(projectRoot, DEFAULT_TRACK_DIR));
   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"));
+  writeIfMissing(path.join(projectRoot, ".waypoint/plans/README.md"), readTemplate(".waypoint/plans/README.md"));
   upsertManagedBlock(path.join(projectRoot, "AGENTS.md"), readTemplate("managed-agents-block.md"));
   scaffoldSkills(projectRoot);
   scaffoldOptionalCodex(projectRoot);
   appendGitignoreSnippet(projectRoot);
-  const docsIndex = renderDocsIndex(projectRoot, path.join(projectRoot, DEFAULT_DOCS_DIR));
+  const docsIndex = renderDocsIndex(projectRoot, docsIndexSections(projectRoot));
   const tracksIndex = renderTracksIndex(projectRoot, path.join(projectRoot, DEFAULT_TRACK_DIR));
   writeText(path.join(projectRoot, DEFAULT_DOCS_INDEX), `${docsIndex.content}\n`);
   writeText(path.join(projectRoot, DEFAULT_TRACKS_INDEX), `${tracksIndex.content}\n`);
 
   return [
     "Initialized Waypoint scaffold",
     "Installed managed AGENTS block",
-    "Created .waypoint/MEMORY.md, .waypoint/WORKSPACE.md, .waypoint/docs/, and .waypoint/track/ scaffold",
+    "Created .waypoint/MEMORY.md, .waypoint/WORKSPACE.md, .waypoint/docs/, .waypoint/plans/, and .waypoint/track/ scaffold",
     "Installed repo-local Waypoint skills",
     "Installed coding/reviewer agents and project Codex config",
     "Generated .waypoint/DOCS_INDEX.md and .waypoint/TRACKS_INDEX.md",
@@ -514,9 +528,10 @@ export function doctorRepository(projectRoot: string): Finding[] {
     }
   }
 
-  const docsDir = path.join(projectRoot, config.docs_dir ?? DEFAULT_DOCS_DIR);
   const docsIndexPath = path.join(projectRoot, config.docs_index_file ?? DEFAULT_DOCS_INDEX);
-  const docsIndex = renderDocsIndex(projectRoot, docsDir);
+  const docsDir = path.join(projectRoot, config.docs_dir ?? DEFAULT_DOCS_DIR);
+  const plansDir = path.join(projectRoot, config.plans_dir ?? DEFAULT_PLANS_DIR);
+  const docsIndex = renderDocsIndex(projectRoot, docsIndexSections(projectRoot, config));
   const trackDir = path.join(projectRoot, DEFAULT_TRACK_DIR);
   const tracksIndexPath = path.join(projectRoot, DEFAULT_TRACKS_INDEX);
   const tracksIndex = renderTracksIndex(projectRoot, trackDir);
@@ -529,6 +544,15 @@ export function doctorRepository(projectRoot: string): Finding[] {
       paths: [docsDir],
     });
   }
+  if (!existsSync(plansDir)) {
+    findings.push({
+      severity: "error",
+      category: "docs",
+      message: ".waypoint/plans/ directory is missing.",
+      remediation: "Run `waypoint init` to scaffold plans.",
+      paths: [plansDir],
+    });
+  }
   for (const relPath of docsIndex.invalidDocs) {
     findings.push({
       severity: "warn",
@@ -543,15 +567,15 @@ export function doctorRepository(projectRoot: string): Finding[] {
       severity: "warn",
       category: "docs",
       message: ".waypoint/DOCS_INDEX.md is missing.",
-      remediation: "Run `waypoint sync` to generate the docs index.",
+      remediation: "Run `waypoint sync` to generate the docs/plans index.",
       paths: [docsIndexPath],
     });
   } else if (readFileSync(docsIndexPath, "utf8").trimEnd() !== docsIndex.content.trimEnd()) {
     findings.push({
       severity: "warn",
       category: "docs",
       message: ".waypoint/DOCS_INDEX.md is stale.",
-      remediation: "Run `waypoint sync` to rebuild the docs index.",
+      remediation: "Run `waypoint sync` to rebuild the docs/plans index.",
       paths: [docsIndexPath],
     });
   }
@@ -644,9 +668,8 @@ export function doctorRepository(projectRoot: string): Finding[] {
 
 export function syncRepository(projectRoot: string): string[] {
   const config = loadWaypointConfig(projectRoot);
-  const docsDir = path.join(projectRoot, config.docs_dir ?? DEFAULT_DOCS_DIR);
   const docsIndexPath = path.join(projectRoot, config.docs_index_file ?? DEFAULT_DOCS_INDEX);
-  const docsIndex = renderDocsIndex(projectRoot, docsDir);
+  const docsIndex = renderDocsIndex(projectRoot, docsIndexSections(projectRoot, config));
   const trackDir = path.join(projectRoot, DEFAULT_TRACK_DIR);
   const tracksIndexPath = path.join(projectRoot, DEFAULT_TRACKS_INDEX);
   const tracksIndex = renderTracksIndex(projectRoot, trackDir);