waypoint-codex 0.12.1 → 0.13.0

package/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,13 +149,6 @@ 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:
@@ -166,8 +156,9 @@ 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

package/dist/src/cli.js

@@ -29,7 +29,7 @@ function printHelp() {
 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
 `);
 }

package/dist/src/core.js

@@ -8,6 +8,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";
@@ -28,7 +29,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/",
@@ -39,6 +39,7 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
     ".agents/skills/pre-pr-hygiene/",
     ".agents/skills/pr-review/",
     ".waypoint/config.toml",
+    ".waypoint/MEMORY.md",
     ".waypoint/README.md",
     ".waypoint/SOUL.md",
     ".waypoint/WORKSPACE.md",
@@ -51,7 +52,6 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
     ".waypoint/scripts/",
     ".waypoint/track/",
     ".waypoint/*",
-    "!.waypoint/MEMORY.md",
     "!.waypoint/docs/",
     "!.waypoint/docs/**",
     ".waypoint/docs/README.md",
@@ -63,7 +63,6 @@ const SHIPPED_SKILL_NAMES = [
     "docs-sync",
     "code-guide-audit",
     "adversarial-review",
-    "visual-explanations",
     "break-it-qa",
     "conversation-retrospective",
     "workspace-compress",
@@ -83,6 +82,18 @@ const TIMESTAMPED_WORKSPACE_SECTIONS = new Set([
     "## Done Recently",
 ]);
 const TIMESTAMPED_ENTRY_PATTERN = /^(?:[-*]|\d+\.)\s+\[\d{4}-\d{2}-\d{2} \d{2}:\d{2} [A-Z]{2,5}\]/;
+function docsIndexSections(projectRoot, config) {
+    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) {
     mkdirSync(dirPath, { recursive: true });
 }
@@ -316,21 +327,23 @@ export function initRepository(projectRoot, options) {
     }));
     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",
@@ -459,9 +472,10 @@ export function doctorRepository(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 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);
@@ -474,6 +488,15 @@ export function doctorRepository(projectRoot) {
             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",
@@ -488,7 +511,7 @@ export function doctorRepository(projectRoot) {
             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],
         });
     }
@@ -497,7 +520,7 @@ export function doctorRepository(projectRoot) {
             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],
         });
     }
@@ -585,9 +608,8 @@ export function doctorRepository(projectRoot) {
 }
 export function syncRepository(projectRoot) {
     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);

package/dist/src/docs-index.js

@@ -73,29 +73,40 @@ function walkDocs(projectRoot, currentDir, output, invalid) {
         output.push({ path: relPath, summary, readWhen });
     }
 }
-export function renderDocsIndex(projectRoot, docsDir) {
+function collectDocEntries(projectRoot, docsDir) {
     const entries = [];
     const invalidDocs = [];
     if (existsSync(docsDir)) {
         walkDocs(projectRoot, docsDir, entries, invalidDocs);
     }
+    return { entries, invalidDocs };
+}
+export function renderDocsIndex(projectRoot, sections) {
     const lines = [
         "# Docs Index",
         "",
-        "Auto-generated by `waypoint sync` / `waypoint doctor`. Read matching docs before working on a task.",
-        "",
-        "## .waypoint/docs/",
+        "Auto-generated by `waypoint sync` / `waypoint doctor`. Read matching docs and plans before working on a task.",
         "",
     ];
-    if (entries.length === 0) {
-        lines.push("No routable docs found.");
-    }
-    else {
-        for (const entry of entries.sort((a, b) => a.path.localeCompare(b.path))) {
-            lines.push(`- **${entry.path}** — ${entry.summary}`);
-            lines.push(`  Read when: ${entry.readWhen.join("; ")}`);
+    const invalidDocs = [];
+    for (const section of sections) {
+        const { entries, invalidDocs: sectionInvalidDocs } = collectDocEntries(projectRoot, section.dir);
+        invalidDocs.push(...sectionInvalidDocs);
+        lines.push(`## ${section.heading}`);
+        lines.push("");
+        if (entries.length === 0) {
+            lines.push("No routable docs found.");
         }
+        else {
+            for (const entry of entries.sort((a, b) => a.path.localeCompare(b.path))) {
+                lines.push(`- **${entry.path}** — ${entry.summary}`);
+                lines.push(`  Read when: ${entry.readWhen.join("; ")}`);
+            }
+        }
+        lines.push("");
+    }
+    if (sections.length === 0) {
+        lines.push("No routable docs found.");
     }
-    lines.push("");
     return { content: `${lines.join("\n")}`, invalidDocs };
 }

package/package.json

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

package/templates/.agents/skills/conversation-retrospective/SKILL.md

@@ -43,7 +43,8 @@ Treat explicit user feedback as a high-priority signal. If the user corrected th
 
 Write durable knowledge to the smallest truthful home the repo already uses:
 
-- the main docs or knowledge layer for architecture, behavior, decisions, debugging knowledge, durable plans, and reusable operating guidance
+- the main docs or knowledge layer for architecture, behavior, decisions, debugging knowledge, and reusable operating guidance
+- the repo's plans layer for durable implementation, rollout, migration, or investigation plans
 - the repo's standing guidance file for durable project context or long-lived working rules
 - the repo's live handoff or workspace file for current state, blockers, and immediate next steps
 - the repo's tracker or execution-log layer when the conversation created or materially changed a long-running workstream

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

@@ -6,7 +6,7 @@ description: >
   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.
+  code or routed docs; and write the final plan into `.waypoint/plans/` so it persists in the repo.
 ---
 
 # Planning
@@ -36,7 +36,7 @@ Before planning:
 
 The plan belongs in the repo, not only in chat.
 
-- Write or update a durable plan doc under `.waypoint/docs/`.
+- Write or update a durable plan doc under `.waypoint/plans/`.
 - 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.
@@ -127,7 +127,7 @@ 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.
+Write or update the durable plan doc under `.waypoint/plans/` as part of the skill, not as an optional follow-up.
 
 ## External APIs
 

package/templates/.agents/skills/planning/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Planning"
   short_description: "Interview, explore, and write an implementation-ready plan into the repo"
-  default_prompt: "Use $planning to deeply explore the repository, interview for the product and architectural details that materially affect the work, and write an implementation-ready plan into .waypoint/docs/."
+  default_prompt: "Use $planning to deeply explore the repository, interview for the product and architectural details that materially affect the work, and write an implementation-ready plan into .waypoint/plans/."

package/templates/.gitignore.snippet

@@ -9,7 +9,6 @@
 .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/
@@ -20,6 +19,7 @@
 .agents/skills/pre-pr-hygiene/
 .agents/skills/pr-review/
 .waypoint/config.toml
+.waypoint/MEMORY.md
 .waypoint/README.md
 .waypoint/SOUL.md
 .waypoint/WORKSPACE.md

package/templates/.waypoint/README.md

@@ -5,10 +5,11 @@ Repo-local Waypoint configuration and project memory files.
 - `MEMORY.md` — durable user/team preferences, collaboration context, and stable product defaults
 - `config.toml` — Waypoint feature toggles and file locations
 - `WORKSPACE.md` — live operational state; new or materially revised entries in multi-topic sections are timestamped
-- `DOCS_INDEX.md` — generated docs routing map
+- `DOCS_INDEX.md` — generated docs and plans routing map
 - `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); routable docs use `summary`, `last_updated`, and `read_when` frontmatter
+- `docs/` — Waypoint-managed long-lived project memory (architecture, decisions, debugging knowledge); routable docs use `summary`, `last_updated`, and `read_when` frontmatter
+- `plans/` — durable implementation, rollout, and migration plans; routable plans use `summary`, `last_updated`, and `read_when` frontmatter
 - `agents/` — agent prompt files that Waypoint's reviewer agents can read and follow
 - `context/` — generated session context bundle
 - `scripts/` — repo-local Waypoint helper scripts

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

@@ -38,7 +38,8 @@ The repository should contain the context the next agent needs.
 - `.waypoint/MEMORY.md` is the durable user/team memory layer: collaboration preferences, stable defaults, and long-lived context that should survive across sessions
 - `.waypoint/WORKSPACE.md` is the live operational record: in progress, current state, next steps
 - `.waypoint/track/` is the optional execution-tracking layer for active long-running work that genuinely needs durable progress state
-- `.waypoint/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, and debugging knowledge
+- `.waypoint/plans/` is the durable planning layer: implementation plans, rollout plans, migration plans, and other task-shaped plans worth keeping
 - `.waypoint/context/` is the generated session context bundle: current git/PR/doc/track index state
 
 If something important lives only in your head or in the chat transcript, the repo is under-documented.
@@ -54,10 +55,11 @@ If something important lives only in your head or in the chat transcript, the re
 - Update `.waypoint/MEMORY.md` only when you learned a durable user/team preference, collaboration rule, or stable product default.
 - Update `.waypoint/WORKSPACE.md` as live execution state when progress meaningfully changes. In multi-topic sections, prefix new or materially revised bullets with a local timestamp like `[2026-03-06 20:10 PST]`.
 - For large multi-step work that is likely to span sessions or needs durable progress state, create or update a tracker in `.waypoint/track/`, keep detailed execution state there, and point at it from `## Active Trackers` in `.waypoint/WORKSPACE.md`.
-- Update `.waypoint/docs/` when durable knowledge changes, and refresh each changed routable doc's `last_updated` field.
+- Update `.waypoint/docs/` when durable project knowledge changes, update `.waypoint/plans/` when durable plans change, and refresh each changed routable doc's `last_updated` field.
 - Rebuild `.waypoint/DOCS_INDEX.md` whenever routable docs change.
 - Rebuild `.waypoint/TRACKS_INDEX.md` whenever tracker files change.
 - Keep most work in the main agent. Use skills, trackers, `coding-agent`, or reviewer agents when they clearly add leverage, not as default ceremony.
+- Let skills carry their own invocation guidance. The always-on contract should only keep the high-level rule: use repo-local skills deliberately when they help the current task.
 - When spawning `coding-agent`, default to `fork_context: false` and choose the model/reasoning pair that fits the slice. Use stronger models when the delegated slice is user-visible, architecturally important, or hard to unwind.
 - When spawning reviewer agents or other non-`coding-agent` subagents, explicitly set `fork_context: false` and choose the model/reasoning pair that matches the risk and importance of the second pass.
 - Use the repo-local skills and reviewer agents deliberately, not reflexively.
@@ -67,11 +69,10 @@ If something important lives only in your head or in the chat transcript, the re
 - When waiting on reviewers, subagents, CI, automated review, or external jobs that you deliberately chose to start, wait as long as required. There is no fixed timeout where waiting itself becomes the problem.
 - Never interrupt in-flight work just to force a partial result, salvage something quickly, or avoid making the user wait longer.
 - Only stop waiting when the work has actually finished, clearly failed, or the user explicitly redirects the work.
-- When browser work is part of reproduction or verification, send screenshots of the relevant UI states to the user so they can visually confirm what you observed.
+- When browser work, app inspection, or other interactive UI work is part of reproduction, inspection, or verification, send screenshots of the relevant UI states to the user so they can visually confirm what you observed.
 - Capture the states that matter, such as the broken state, the fixed state, or an important intermediate state that explains the issue.
 - If the current environment cannot provide screenshots, state that explicitly instead of silently omitting visual evidence.
 - When an explanation would be clearer visually, prefer Mermaid diagrams directly in chat for flows, architecture, state, and plans instead of over-explaining in prose.
-- Use `visual-explanations` when the explanation needs a richer generated image or an annotated screenshot rather than only text or Mermaid.
 
 ## Execution autonomy
 
@@ -100,25 +101,10 @@ Document the things the next agent cannot safely infer from raw code alone:
 - integration behavior
 - invariants and constraints
 - debugging and operational knowledge
-- active plans and next steps
+- durable plans when they are useful beyond the current chat
 
 Do not document every trivial implementation detail. Document the non-obvious, durable, or operationally important parts.
 
-## When to use Waypoint skills
-
-- `planning` when a non-trivial change needs deliberate scoping, clarified behavior, or a durable implementation plan
-- `work-tracker` when large multi-step work is likely to span sessions or needs durable progress tracking in `.waypoint/track/`
-- `docs-sync` when routed docs may be stale, missing, or inconsistent with the codebase
-- `code-guide-audit` when a specific feature or file set needs a targeted coding-guide compliance check
-- `adversarial-review` when the user asks for a final review pass, asks whether something is ready to ship, or when the risk warrants a deliberate second-pass review loop
-- `visual-explanations` when a generated image or annotated screenshot would explain the work more clearly than prose alone; Mermaid diagrams do not need a skill
-- `conversation-retrospective` when the user asks to save what was learned, when a major work piece produced durable learnings worth preserving, or when a skill clearly needs improvement based on what happened
-- `break-it-qa` when a browser-facing feature should be attacked with invalid inputs, refreshes, repeated clicks, wrong action order, or other adversarial manual QA
-- `frontend-ship-audit` and `backend-ship-audit` when the user explicitly requests a ship-readiness audit
-- `workspace-compress` after meaningful chunks or before pausing when the live handoff needs cleanup
-- `pre-pr-hygiene` before pushing or opening/updating a PR for substantial work when you want an explicit hygiene pass
-- `pr-review` once a PR has active review comments or automated review in progress
-
 ## When to use the agent pack
 
 Waypoint scaffolds these focused specialists by default:
@@ -130,7 +116,7 @@ Waypoint scaffolds these focused specialists by default:
 
 ## Plan Review
 
-Use `plan-reviewer` when a plan includes meaningful design choices, multiple work phases, migrations, or non-obvious tradeoffs and you want an independent challenge before committing.
+Plan review is available when an independent challenge would materially improve a non-trivial plan.
 
 - Skip it for tiny obvious plans or when no plan will be presented.
 - Use a fresh `plan-reviewer` agent for each pass. After you read its findings, close it instead of reusing the old reviewer thread.
@@ -138,7 +124,7 @@ Use `plan-reviewer` when a plan includes meaningful design choices, multiple wor
 
 ## Review Loop
 
-Use `adversarial-review` when you deliberately want a closeout loop for ship-readiness, a final review request, or a risky change. It is a tool, not the default voice of the system.
+Deliberate closeout review is available when you want a second pass for ship-readiness, a final review request, or a risky change. It is a tool, not the default voice of the system.
 
 - If you use it, follow the skill's loop fully: define the reviewable slice, run the needed reviewers, wait for the outputs, fix meaningful findings, and rerun fresh passes when warranted.
 - Treat reviewer agents as one-shot workers. Once a reviewer returns its findings, read the result and close it.

package/templates/.waypoint/config.toml

@@ -2,6 +2,7 @@ version = 1
 profile = "__PROFILE__"
 workspace_file = ".waypoint/WORKSPACE.md"
 docs_dir = ".waypoint/docs"
+plans_dir = ".waypoint/plans"
 docs_index_file = ".waypoint/DOCS_INDEX.md"
 
 [features]

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

@@ -9,10 +9,11 @@ Put the durable context here that the next agent will need to continue the work:
 - integration notes
 - invariants and constraints
 - debugging knowledge
-- active plans that should survive beyond one session
 
 These are **project docs**, not Waypoint internals.
 
+Put durable implementation and rollout plans in `.waypoint/plans/`.
+
 Do not use `.waypoint/docs/` as the execution tracker layer for active long-running work. That belongs under `.waypoint/track/`.
 
 Every routable doc needs YAML frontmatter:
@@ -26,4 +27,4 @@ read_when:
 ---
 ```
 
-Refresh `last_updated` whenever you materially change a doc. `DOCS_INDEX.md` is generated from the docs here.
+Refresh `last_updated` whenever you materially change a doc. `DOCS_INDEX.md` is generated from both `.waypoint/docs/` and `.waypoint/plans/`.

package/templates/.waypoint/plans/README.md

@@ -0,0 +1,26 @@
+# Waypoint Plans
+
+This directory is for durable plan documents.
+
+Put plans here when they should stay in the repo beyond the current chat:
+
+- implementation plans
+- rollout plans
+- migration plans
+- investigation plans
+- other task-specific design docs that are still useful after the session ends
+
+Keep long-lived reference docs in `.waypoint/docs/`.
+
+Every routable plan needs YAML frontmatter:
+
+```yaml
+---
+summary: One-line description
+last_updated: "2026-03-06 20:10 PST"
+read_when:
+  - task cue
+---
+```
+
+Refresh `last_updated` whenever you materially change a plan. `DOCS_INDEX.md` is generated from both `.waypoint/docs/` and `.waypoint/plans/`.

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

@@ -107,34 +107,52 @@ function walkDocs(projectRoot, currentDir, output) {
   }
 }
 
-export function renderDocsIndex(projectRoot) {
-  const docsDir = path.join(projectRoot, ".waypoint", "docs");
+function collectDocEntries(projectRoot, docsDir) {
   const entries = [];
 
   if (existsSync(docsDir)) {
     walkDocs(projectRoot, docsDir, entries);
   }
 
+  return entries;
+}
+
+export function renderDocsIndex(projectRoot) {
+  const sections = [
+    {
+      heading: ".waypoint/docs/",
+      dir: path.join(projectRoot, ".waypoint", "docs"),
+    },
+    {
+      heading: ".waypoint/plans/",
+      dir: path.join(projectRoot, ".waypoint", "plans"),
+    },
+  ];
+
   const lines = [
     "# Docs Index",
     "",
-    "Auto-generated by `.waypoint/scripts/build-docs-index.mjs`. Read matching docs before working on a task.",
-    "",
-    "## .waypoint/docs/",
+    "Auto-generated by `.waypoint/scripts/build-docs-index.mjs`. Read matching docs and plans before working on a task.",
     "",
   ];
 
-  if (entries.length === 0) {
-    lines.push("No routable docs found.");
-  } else {
-    entries.sort((a, b) => a.path.localeCompare(b.path));
-    for (const entry of entries) {
-      lines.push(`- **${entry.path}** — ${entry.summary}`);
-      lines.push(`  Read when: ${entry.readWhen.join("; ")}`);
+  for (const section of sections) {
+    const entries = collectDocEntries(projectRoot, section.dir);
+    lines.push(`## ${section.heading}`);
+    lines.push("");
+
+    if (entries.length === 0) {
+      lines.push("No routable docs found.");
+    } else {
+      entries.sort((a, b) => a.path.localeCompare(b.path));
+      for (const entry of entries) {
+        lines.push(`- **${entry.path}** — ${entry.summary}`);
+        lines.push(`  Read when: ${entry.readWhen.join("; ")}`);
+      }
     }
-  }
 
-  lines.push("");
+    lines.push("");
+  }
   return `${lines.join("\n")}\n`;
 }
 

package/templates/managed-agents-block.md

@@ -69,8 +69,8 @@ Prefer existing persisted context over re-interviewing the user.
 
 If the user approves a plan or explicitly tells you to proceed, treat that as authorization to execute the work end to end. Do not stop mid-implementation for incremental permission unless a real blocker, hidden-risk decision, or explicit user redirect requires a pause.
 When work is in flight elsewhere — reviewer agents, subagents, CI, automated review, external jobs, or other waiting periods — wait as long as required. There is no fixed waiting limit, and slowness alone is not a reason to interrupt or abandon the work.
-When using a browser to reproduce a bug, verify behavior, or confirm that a fix works, send the user screenshots of the relevant UI states so they can see the evidence directly. If screenshots are not possible in the current environment, say so explicitly.
-When an explanation would be clearer as a visual than as prose, bias toward visual artifacts. Prefer Mermaid diagrams directly in chat for flows, architecture, state, and plans; use `visual-explanations` for richer generated images and for annotated screenshots that call out concrete UI states.
+When you use a browser, app, or other interactive UI to inspect, reproduce, or verify something, send the user screenshots of the relevant states so they can see what you saw. If screenshots are not possible in the current environment, say so explicitly.
+When an explanation is clearer visually, use Mermaid diagrams directly in chat for flows, architecture, state, and plans.
 
 Delivery expectations:
 - Before you start, decide what "done" means for the task. Set your own finish line and use it as your checklist while you work.
@@ -92,16 +92,12 @@ Delivery expectations:
 Working rules:
 - Keep `.waypoint/WORKSPACE.md` current as the live execution state, with timestamped new or materially revised entries in multi-topic sections
 - Keep `.waypoint/MEMORY.md` for durable user/team preferences, collaboration context, and stable product defaults; keep task status and active execution state out of it
-- Update `.waypoint/docs/` when behavior or durable project knowledge changes, and refresh `last_updated` on touched routable docs
+- Update `.waypoint/docs/` when durable project knowledge changes, update `.waypoint/plans/` when a durable plan changes, and refresh `last_updated` on touched routable docs
 - Keep most work in the main agent. Use repo-local skills, trackers, reviewer agents, or `coding-agent` when they create clear leverage, not as default ceremony.
-- Use `work-tracker` when work is likely to span sessions or needs durable progress tracking.
-- Use review and ship-readiness skills such as `adversarial-review`, `pre-pr-hygiene`, `pr-review`, `frontend-ship-audit`, and `backend-ship-audit` when the user asks for them, when you are about to ship or open a PR, or when the risk clearly warrants a deliberate second pass.
-- Use `plan-reviewer` or other reviewer agents when an independent challenge would materially improve the result, not before every plan or fix by default.
-- Use `visual-explanations` when a generated image or annotated screenshot would explain the work more clearly than prose alone; Mermaid diagrams can be written directly in chat without invoking a skill.
+- Let repo-local skills describe their own triggers. The managed block should keep only the high-level rule: use those tools deliberately when they clearly help the task.
+- Use reviewer agents when an independent second pass would materially improve the result, not before every plan or fix by default.
 - Treat `plan-reviewer`, `code-reviewer`, and `code-health-reviewer` as one-shot agents: once a reviewer returns findings, close it; if another pass is needed later, spawn a fresh reviewer instead of reusing the old thread
-- Before pushing or opening/updating a PR for substantial work, use `pre-pr-hygiene`
 - If you created a PR earlier in the current session and need to push more work, first confirm that PR is still open. If it is closed, create a fresh branch from `origin/main` and open a fresh PR instead of pushing more commits to the old PR branch
-- Use `pr-review` once a PR has active review comments or automated review in progress
 - Treat the generated context bundle as required session bootstrap, not optional reference material
 - After plan approval, own the execution through implementation, verification, and necessary repo-memory updates before surfacing a final completion report
 <!-- waypoint:end -->

package/templates/.agents/skills/visual-explanations/SKILL.md

@@ -1,100 +0,0 @@
----
-name: visual-explanations
-description: Create generated images or annotated screenshots when a visual artifact would explain a concept, design, flow, comparison, or observed UI state more clearly than prose alone. Use for concept cards, visual summaries, mockups, labeled screenshots, timelines, comparisons, and other explanation-first visuals. Do not use this skill when a simple Mermaid diagram in chat is sufficient.
----
-
-# Visual Explanations
-
-Use this skill when the explanation itself should become a visual artifact.
-
-Mermaid does not need this skill. If a Mermaid diagram in chat is enough, use Mermaid directly and stop here.
-
-## Step 1: Pick The Right Visual
-
-- Use Mermaid directly for flows, architecture, plans, state machines, and other text-native diagrams.
-- Use an annotated screenshot when you need to explain a real UI state, call out a specific element, or show evidence from an actual screen.
-- Use a generated image when Mermaid is too rigid and the explanation needs custom layout, stronger composition, a side-by-side comparison, a concept card, a rough mockup, or a more designed visual summary.
-
-Do not make an image just because you can. Use the lightest visual that makes the explanation clearer.
-
-## Step 2: Define The Message First
-
-Before drawing anything, write down:
-
-- the one main point the visual should communicate
-- which audience it is for
-- whether it is evidence, explanation, or a conceptual sketch
-
-One image should usually explain one idea.
-
-## Step 3: Gather Source Material
-
-For annotated screenshots:
-
-- capture the real UI state first
-- keep the untouched source screenshot available until the annotated version is verified
-- identify the exact element or area that the callout should reference
-
-For generated images:
-
-- list the minimum facts, labels, or comparison points that must appear
-- sketch the rough composition in words before building it
-- prefer using the repo's existing facts or screenshots over inventing fake details
-
-If the image is conceptual rather than a faithful representation of current UI, label it clearly in the visual or in the accompanying text.
-
-## Step 4: Build With Simple, Deterministic Tools
-
-Prefer straightforward local approaches:
-
-- SVG for cards, timelines, comparisons, and lightweight custom layouts
-- HTML/CSS rendered to an image when layout fidelity matters
-- image-editing tools such as ImageMagick or Pillow for callouts, arrows, labels, crops, and overlays
-- browser screenshots when the source needs to be a real page or app state
-
-Do not over-engineer the rendering path. Favor the most reliable approach available in the current environment.
-
-## Step 5: Design For Clarity
-
-- highlight the exact thing you are explaining
-- keep callout text short
-- use large, legible type
-- use strong contrast
-- leave enough whitespace so the image still scans quickly
-- prefer one or two callouts over covering the image in labels
-- crop or frame the relevant area when the full screen adds noise
-
-Good visuals feel obvious at a glance.
-
-## Step 6: Verify The Output Yourself
-
-Before sending the image:
-
-- open or inspect the rendered result
-- confirm it is not blank, clipped, washed out, or too tiny to read
-- confirm arrows and labels point at the intended target
-- confirm the image still makes sense without a long paragraph underneath it
-
-Do not trust the generation step blindly.
-
-## Step 7: Deliver Cleanly
-
-- show the image directly in chat
-- add one to three sentences that explain what the user should notice
-- prefer a single strong visual over a pile of mediocre ones
-
-If the artifact is only for the current conversation, store it in a temp or scratch location. If the user wants a durable asset in the repo, place it in the repo's normal docs or asset structure instead of inventing a new convention.
-
-## Gotchas
-
-- Do not make an image when Mermaid or a short paragraph would already explain the point cleanly.
-- Do not annotate a screenshot until you have verified the source screenshot actually shows the right state.
-- Do not bury the main message under too many callouts or labels. One image should usually explain one thing.
-- Do not present a conceptual mockup as if it were a real current UI state. Label it clearly when it is illustrative.
-- Do not trust the rendering step blindly; clipped text, tiny labels, and misplaced arrows are common failure modes.
-
-## Keep This Skill Sharp
-
-- Add new gotchas when the same visual clarity problem, screenshot mistake, or rendering failure keeps showing up.
-- Tighten the description if the skill fires when Mermaid would have been enough or misses real requests for annotated screenshots and concept cards.
-- If the same layout patterns or annotation helpers keep repeating, move them into reusable assets or scripts instead of rebuilding them from scratch.

package/templates/.agents/skills/visual-explanations/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Visual Explanations"
-  short_description: "Create generated images and annotated screenshots"
-  default_prompt: "Use $visual-explanations to create a generated image or annotated screenshot when a visual artifact would explain the point more clearly than prose alone. Prefer Mermaid directly when a simple in-chat diagram is enough."