waypoint-codex 0.7.0 → 0.8.0

package/README.md

@@ -22,10 +22,12 @@ Waypoint scaffolds a Codex-friendly repo structure built around a few core piece
 
 - `AGENTS.md` for the startup contract
 - `.waypoint/WORKSPACE.md` for live operational state
+- `.waypoint/track/` for active long-running execution trackers
 - `.waypoint/docs/` for durable project memory
 - `.waypoint/DOCS_INDEX.md` for docs routing
+- `.waypoint/TRACKS_INDEX.md` for tracker routing
 - `.waypoint/context/` for generated startup context
-- `.agents/skills/` for repo-local workflows like planning, audits, and QA
+- `.agents/skills/` for repo-local workflows like planning, tracking, audits, and QA
 
 The philosophy is simple:
 
@@ -40,7 +42,7 @@ Waypoint is most useful when you want:
 
 - multi-session continuity in a real repo
 - a durable docs and workspace structure for agents
-- stronger planning, review, QA, and closeout defaults
+- stronger planning, tracking, review, QA, and closeout defaults
 - repo-local scaffolding instead of a bunch of global mystery behavior
 
 If you only use Codex for tiny one-off edits, Waypoint is probably unnecessary.
@@ -76,9 +78,11 @@ repo/
 ├── .agents/
 │   └── skills/
 └── .waypoint/
-    ├── WORKSPACE.md
     ├── DOCS_INDEX.md
+    ├── TRACKS_INDEX.md
+    ├── WORKSPACE.md
     ├── docs/
+    ├── track/
     ├── context/
     ├── scripts/
     └── ...
@@ -126,9 +130,7 @@ Flags you can combine:
 Waypoint ships a strong default skill pack for real coding work:
 
 - `planning`
-- `error-audit`
-- `observability-audit`
-- `ux-states-audit`
+- `work-tracker`
 - `docs-sync`
 - `code-guide-audit`
 - `break-it-qa`

package/dist/src/core.js

@@ -4,14 +4,18 @@ import os from "node:os";
 import path from "node:path";
 import * as TOML from "@iarna/toml";
 import { renderDocsIndex } from "./docs-index.js";
+import { renderTracksIndex } from "./track-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 = ".waypoint/docs";
 const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
+const DEFAULT_TRACK_DIR = ".waypoint/track";
+const DEFAULT_TRACKS_INDEX = ".waypoint/TRACKS_INDEX.md";
 const DEFAULT_WORKSPACE = ".waypoint/WORKSPACE.md";
 const STATE_DIR = ".waypoint/state";
 const SYNC_RECORDS_FILE = ".waypoint/state/sync-records.json";
 const TIMESTAMPED_WORKSPACE_SECTIONS = new Set([
+    "## Active Trackers",
     "## Current State",
     "## In Progress",
     "## Next",
@@ -101,6 +105,7 @@ function scaffoldWaypointOptionalTemplates(projectRoot) {
     copyTemplateTree(templatePath(".waypoint/automations"), path.join(projectRoot, ".waypoint/automations"));
     copyTemplateTree(templatePath(".waypoint/rules"), path.join(projectRoot, ".waypoint/rules"));
     copyTemplateTree(templatePath(".waypoint/scripts"), path.join(projectRoot, ".waypoint/scripts"));
+    copyTemplateTree(templatePath(".waypoint/track"), path.join(projectRoot, ".waypoint/track"));
 }
 function scaffoldOptionalCodex(projectRoot) {
     copyTemplateTree(templatePath(".codex"), path.join(projectRoot, ".codex"));
@@ -112,6 +117,9 @@ export function initRepository(projectRoot, options) {
         "docs/README.md",
         "docs/code-guide.md",
         "docs/legacy-import",
+        ".agents/skills/error-audit",
+        ".agents/skills/observability-audit",
+        ".agents/skills/ux-states-audit",
         "WAYPOINT_MIGRATION.md",
         ".agents/skills/waypoint-planning",
         ".agents/skills/waypoint-docs",
@@ -145,6 +153,7 @@ 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_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"));
     upsertManagedBlock(path.join(projectRoot, "AGENTS.md"), readTemplate("managed-agents-block.md"));
@@ -154,13 +163,15 @@ export function initRepository(projectRoot, options) {
     }
     appendGitignoreSnippet(projectRoot);
     const docsIndex = renderDocsIndex(projectRoot, path.join(projectRoot, DEFAULT_DOCS_DIR));
+    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/WORKSPACE.md and .waypoint/docs/ scaffold",
+        "Created .waypoint/WORKSPACE.md, .waypoint/docs/, and .waypoint/track/ scaffold",
         "Installed repo-local Waypoint skills",
-        "Generated .waypoint/DOCS_INDEX.md",
+        "Generated .waypoint/DOCS_INDEX.md and .waypoint/TRACKS_INDEX.md",
     ];
 }
 export function loadWaypointConfig(projectRoot) {
@@ -366,6 +377,7 @@ export function doctorRepository(projectRoot) {
         const workspaceText = readFileSync(workspacePath, "utf8");
         for (const section of [
             "## Active Goal",
+            "## Active Trackers",
             "## Current State",
             "## In Progress",
             "## Next",
@@ -398,6 +410,7 @@ export function doctorRepository(projectRoot) {
         path.join(projectRoot, ".waypoint", "agent-operating-manual.md"),
         path.join(projectRoot, ".waypoint", "scripts", "prepare-context.mjs"),
         path.join(projectRoot, ".waypoint", "scripts", "build-docs-index.mjs"),
+        path.join(projectRoot, ".waypoint", "scripts", "build-track-index.mjs"),
     ]) {
         if (!existsSync(requiredFile)) {
             findings.push({
@@ -412,6 +425,9 @@ 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 trackDir = path.join(projectRoot, DEFAULT_TRACK_DIR);
+    const tracksIndexPath = path.join(projectRoot, DEFAULT_TRACKS_INDEX);
+    const tracksIndex = renderTracksIndex(projectRoot, trackDir);
     if (!existsSync(docsDir)) {
         findings.push({
             severity: "error",
@@ -448,11 +464,56 @@ export function doctorRepository(projectRoot) {
             paths: [docsIndexPath],
         });
     }
+    if (!existsSync(trackDir)) {
+        findings.push({
+            severity: "error",
+            category: "track",
+            message: ".waypoint/track/ directory is missing.",
+            remediation: "Run `waypoint init` to scaffold track files.",
+            paths: [trackDir],
+        });
+    }
+    for (const relPath of tracksIndex.invalidTracks) {
+        findings.push({
+            severity: "warn",
+            category: "track",
+            message: `Tracker is missing valid frontmatter or status: ${relPath}`,
+            remediation: "Add `summary`, `last_updated`, `status`, and `read_when` frontmatter using the track template.",
+            paths: [path.join(projectRoot, relPath)],
+        });
+    }
+    if (!existsSync(tracksIndexPath)) {
+        findings.push({
+            severity: "warn",
+            category: "track",
+            message: ".waypoint/TRACKS_INDEX.md is missing.",
+            remediation: "Run `waypoint sync` to generate the tracks index.",
+            paths: [tracksIndexPath],
+        });
+    }
+    else if (readFileSync(tracksIndexPath, "utf8").trimEnd() !== tracksIndex.content.trimEnd()) {
+        findings.push({
+            severity: "warn",
+            category: "track",
+            message: ".waypoint/TRACKS_INDEX.md is stale.",
+            remediation: "Run `waypoint sync` to rebuild the tracks index.",
+            paths: [tracksIndexPath],
+        });
+    }
+    if (existsSync(workspacePath) &&
+        tracksIndex.activeTrackPaths.length > 0 &&
+        !tracksIndex.activeTrackPaths.some((trackPath) => readFileSync(workspacePath, "utf8").includes(trackPath))) {
+        findings.push({
+            severity: "warn",
+            category: "track",
+            message: "Workspace does not reference any active tracker file.",
+            remediation: "Add the active `.waypoint/track/*.md` file paths under `## Active Trackers` in `.waypoint/WORKSPACE.md`.",
+            paths: [workspacePath, ...tracksIndex.activeTrackPaths.map((trackPath) => path.join(projectRoot, trackPath))],
+        });
+    }
     for (const skillName of [
         "planning",
-        "error-audit",
-        "observability-audit",
-        "ux-states-audit",
+        "work-tracker",
         "docs-sync",
         "code-guide-audit",
         "break-it-qa",
@@ -528,8 +589,12 @@ export function syncRepository(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 trackDir = path.join(projectRoot, DEFAULT_TRACK_DIR);
+    const tracksIndexPath = path.join(projectRoot, DEFAULT_TRACKS_INDEX);
+    const tracksIndex = renderTracksIndex(projectRoot, trackDir);
     writeText(docsIndexPath, `${docsIndex.content}\n`);
-    const results = ["Rebuilt .waypoint/DOCS_INDEX.md"];
+    writeText(tracksIndexPath, `${tracksIndex.content}\n`);
+    const results = ["Rebuilt .waypoint/DOCS_INDEX.md", "Rebuilt .waypoint/TRACKS_INDEX.md"];
     const featureMap = config.features ?? {};
     if (featureMap.rules) {
         results.push(...syncRules(projectRoot));

package/dist/src/track-index.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+const VALID_TRACK_STATUSES = new Set(["active", "blocked", "paused", "done", "archived"]);
+const ACTIVE_TRACK_STATUSES = new Set(["active", "blocked", "paused"]);
+const SKIP_NAMES = new Set(["README.md", "CHANGELOG.md", "LICENSE.md"]);
+function shouldSkipTrackFile(entry) {
+    return SKIP_NAMES.has(entry) || entry.startsWith("_");
+}
+function parseFrontmatter(filePath) {
+    const text = readFileSync(filePath, "utf8");
+    if (!text.startsWith("---\n")) {
+        return { summary: "", lastUpdated: "", readWhen: [], status: "" };
+    }
+    const endIndex = text.indexOf("\n---\n", 4);
+    if (endIndex === -1) {
+        return { summary: "", lastUpdated: "", readWhen: [], status: "" };
+    }
+    const frontmatter = text.slice(4, endIndex);
+    let summary = "";
+    let lastUpdated = "";
+    let status = "";
+    const readWhen = [];
+    let collectingReadWhen = false;
+    for (const rawLine of frontmatter.split("\n")) {
+        const line = rawLine.trim();
+        if (line.startsWith("summary:")) {
+            summary = line.slice("summary:".length).trim().replace(/^['"]|['"]$/g, "");
+            collectingReadWhen = false;
+            continue;
+        }
+        if (line.startsWith("last_updated:")) {
+            lastUpdated = line.slice("last_updated:".length).trim().replace(/^['"]|['"]$/g, "");
+            collectingReadWhen = false;
+            continue;
+        }
+        if (line.startsWith("status:")) {
+            status = line.slice("status:".length).trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+            collectingReadWhen = false;
+            continue;
+        }
+        if (line.startsWith("read_when:")) {
+            collectingReadWhen = true;
+            continue;
+        }
+        if (collectingReadWhen && line.startsWith("- ")) {
+            readWhen.push(line.slice(2).trim());
+            continue;
+        }
+        if (collectingReadWhen && line.length > 0) {
+            collectingReadWhen = false;
+        }
+    }
+    return { summary, lastUpdated, readWhen, status };
+}
+function walkTracks(projectRoot, currentDir, output, invalid) {
+    for (const entry of readdirSync(currentDir)) {
+        const fullPath = path.join(currentDir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+            walkTracks(projectRoot, fullPath, output, invalid);
+            continue;
+        }
+        if (!entry.endsWith(".md") || shouldSkipTrackFile(entry)) {
+            continue;
+        }
+        const { summary, lastUpdated, readWhen, status } = parseFrontmatter(fullPath);
+        const relPath = path.relative(projectRoot, fullPath);
+        if (!summary || !lastUpdated || readWhen.length === 0 || !VALID_TRACK_STATUSES.has(status)) {
+            invalid.push(relPath);
+            continue;
+        }
+        output.push({ path: relPath, summary, readWhen, status });
+    }
+}
+export function renderTracksIndex(projectRoot, trackDir) {
+    const entries = [];
+    const invalidTracks = [];
+    if (existsSync(trackDir)) {
+        walkTracks(projectRoot, trackDir, entries, invalidTracks);
+    }
+    const lines = [
+        "# Tracks Index",
+        "",
+        "Auto-generated by `waypoint sync` / `waypoint doctor`. Read active trackers when resuming long-running work.",
+        "",
+        "## .waypoint/track/",
+        "",
+    ];
+    if (entries.length === 0) {
+        lines.push("No tracker files found.");
+    }
+    else {
+        for (const entry of entries.sort((a, b) => a.path.localeCompare(b.path))) {
+            lines.push(`- **${entry.path}** — [${entry.status}] ${entry.summary}`);
+            lines.push(`  Read when: ${entry.readWhen.join("; ")}`);
+        }
+    }
+    lines.push("");
+    return {
+        content: `${lines.join("\n")}`,
+        invalidTracks,
+        activeTrackPaths: entries
+            .filter((entry) => ACTIVE_TRACK_STATUSES.has(entry.status))
+            .map((entry) => entry.path)
+            .sort((a, b) => a.localeCompare(b)),
+    };
+}

package/package.json

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

package/templates/.agents/skills/code-guide-audit/SKILL.md

@@ -47,6 +47,8 @@ Skip rules that genuinely do not apply, but say that you skipped them.
 
 This skill is narrower than `pre-pr-hygiene`. Use that other skill for broader ship-readiness.
 
+If this audit produces a large remediation campaign, create or update a tracker under `.waypoint/track/` before switching into implementation so the fix list does not live only in chat.
+
 ## Step 4: Verify Evidence
 
 Ground each finding in the actual code.

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

@@ -36,6 +36,8 @@ The plan belongs in the repo, not only in chat.
 - Make sure the doc remains discoverable through the routed docs layer.
 - In chat, return only a concise summary plus the path to the plan doc.
 
+If the planned implementation will be large, multi-step, or likely to span multiple sessions, also create or update a tracker under `.waypoint/track/` and link it from `WORKSPACE.md` before implementation begins.
+
 ## The Core Loop
 
 ```

package/templates/.agents/skills/work-tracker/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: work-tracker
+description: Create or maintain a durable tracker under `.waypoint/track/` for large multi-step work. Use when implementation will span multiple sessions, when an audit or review produces many fix items, when verification has a long checklist, or whenever `WORKSPACE.md` would become too detailed if it tried to hold the whole execution log.
+---
+
+# Work Tracker
+
+Use this skill when the work is too large, too long-running, or too itemized to live safely in `WORKSPACE.md`.
+
+This skill owns the execution tracker layer:
+
+- create or update `.waypoint/track/<slug>.md`
+- keep `WORKSPACE.md` pointing at the active tracker
+- move detailed checklists and progress into the tracker instead of bloating the workspace
+
+## Read First
+
+Before tracking:
+
+1. Read `.waypoint/SOUL.md`
+2. Read `.waypoint/agent-operating-manual.md`
+3. Read `.waypoint/WORKSPACE.md`
+4. Read `.waypoint/context/MANIFEST.md`
+5. Read every file listed in that manifest
+6. Read `.waypoint/track/README.md`
+
+## When A Tracker Is Required
+
+Create or update a tracker when any of these are true:
+
+- the work will likely span multiple sessions
+- there are many actionable items to implement
+- an audit, QA pass, or review produced a remediation campaign
+- verification requires a substantial checklist
+- `WORKSPACE.md` would become noisy if it carried all the detail
+
+Small, single-shot work does not need a tracker.
+
+## Step 1: Choose The Tracker File
+
+- Use `.waypoint/track/<kebab-case-slug>.md`.
+- If a relevant tracker already exists, update it instead of creating a competing one.
+- Keep one tracker per coherent workstream, not one tracker per tiny edit.
+
+## Step 2: Set The Frontmatter
+
+Trackers need:
+
+```yaml
+---
+summary: One-line description
+last_updated: "2026-03-13 11:38 PDT"
+status: active
+read_when:
+  - resuming this workstream
+---
+```
+
+Valid statuses:
+
+- `active`
+- `blocked`
+- `paused`
+- `done`
+- `archived`
+
+Use `active` unless there is a clear reason not to.
+
+## Step 3: Structure The Tracker
+
+A good tracker usually includes:
+
+- `Goal`
+- `Source`
+- `Current State`
+- `Next`
+- `Workstreams`
+- `Verification`
+- `Decisions`
+- `Notes`
+
+Use checklists when there are many concrete items. Use timestamped bullets for materially revised state.
+
+## Step 4: Link It From The Workspace
+
+Add or update a bullet under `## Active Trackers` in `.waypoint/WORKSPACE.md` that points at the tracker path and states the current phase or next step.
+
+`WORKSPACE.md` should answer "what matters right now?"
+The tracker should answer "what exactly is happening across the whole workstream?"
+
+## Step 5: Maintain It During Execution
+
+- Update `last_updated` whenever you materially change the tracker.
+- Mark completed items done instead of deleting the record.
+- Add blockers, new tasks, and verification status as the work evolves.
+- When the workstream finishes, set `status: done` or `status: archived`.
+
+Do not let the tracker become fiction. It must match reality.
+
+## Step 6: Distill Durable Knowledge
+
+If the tracker reveals durable architecture, rollout, or debugging knowledge, move that durable knowledge into `.waypoint/docs/` and leave the tracker focused on execution state.
+
+## Report
+
+When you create or update a tracker, report:
+
+- the tracker path
+- the current status
+- what `WORKSPACE.md` now points to

package/templates/.agents/skills/workspace-compress/SKILL.md

@@ -39,6 +39,7 @@ Ask one question:
 
 Keep only the answer to that question in the workspace. Usually that means:
 
+- active tracker pointers
 - current focus
 - latest verified state
 - open blockers or risks
@@ -52,6 +53,7 @@ Usually remove or collapse:
 - validation transcripts
 - old milestone history
 - duplicated durable documentation
+- per-item implementation checklists that belong in `.waypoint/track/`
 
 Compression is documentation quality, not data loss.
 
@@ -66,6 +68,7 @@ When editing the workspace:
 5. Do not turn the workspace into an archive, changelog, or debug notebook.
 
 If durable context is missing from `.waypoint/docs/`, add or refresh the smallest coherent routed doc before removing it from the workspace.
+If execution detail is still active but too large for the workspace, move it into `.waypoint/track/` instead of deleting it.
 
 ## Step 4: Protect User-Owned State
 

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

@@ -33,8 +33,9 @@ Do not skip this sequence.
 The repository should contain the context the next agent needs.
 
 - `.waypoint/WORKSPACE.md` is the live operational record: in progress, current state, next steps
+- `.waypoint/track/` is the durable execution-tracking layer for active long-running work
 - `.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
+- `.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.
 
@@ -43,8 +44,10 @@ 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 `.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, 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.
 - Rebuild `.waypoint/DOCS_INDEX.md` whenever routable docs change.
+- Rebuild `.waypoint/TRACKS_INDEX.md` whenever tracker files change.
 - Use the repo-local skills and optional reviewer agents instead of improvising from scratch.
 - Do not kill long-running subagents or reviewer agents just because they are slow. Wait unless they are clearly stuck, failed, or the user redirects the work.
 
@@ -64,9 +67,7 @@ Do not document every trivial implementation detail. Document the non-obvious, d
 ## When to use Waypoint skills
 
 - `planning` for non-trivial changes
-- `error-audit` when failures are being swallowed or degraded invisibly
-- `observability-audit` when production debugging signals look weak
-- `ux-states-audit` when async/data-driven UI likely lacks loading, empty, or error states
+- `work-tracker` when large multi-step work 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
 - `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

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

@@ -13,6 +13,8 @@ Put the durable context here that the next agent will need to continue the work:
 
 These are **project docs**, not Waypoint internals.
 
+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:
 
 ```yaml

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

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const VALID_TRACK_STATUSES = new Set(["active", "blocked", "paused", "done", "archived"]);
+const ACTIVE_TRACK_STATUSES = new Set(["active", "blocked", "paused"]);
+const SKIP_NAMES = new Set(["README.md", "CHANGELOG.md", "LICENSE.md"]);
+
+export function findProjectRoot(startDir) {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (existsSync(path.join(current, ".waypoint", "config.toml"))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return path.resolve(startDir);
+    }
+    current = parent;
+  }
+}
+
+function detectProjectRoot() {
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const scriptBasedRoot = findProjectRoot(path.resolve(scriptDir, "../.."));
+  if (existsSync(path.join(scriptBasedRoot, ".waypoint", "config.toml"))) {
+    return scriptBasedRoot;
+  }
+  return findProjectRoot(process.cwd());
+}
+
+function shouldSkipTrackFile(entry) {
+  return SKIP_NAMES.has(entry) || entry.startsWith("_");
+}
+
+function parseFrontmatter(filePath) {
+  const text = readFileSync(filePath, "utf8");
+  if (!text.startsWith("---\n")) {
+    return { summary: "", lastUpdated: "", readWhen: [], status: "" };
+  }
+
+  const endIndex = text.indexOf("\n---\n", 4);
+  if (endIndex === -1) {
+    return { summary: "", lastUpdated: "", readWhen: [], status: "" };
+  }
+
+  const frontmatter = text.slice(4, endIndex);
+  let summary = "";
+  let lastUpdated = "";
+  let status = "";
+  const readWhen = [];
+  let collectingReadWhen = false;
+
+  for (const rawLine of frontmatter.split("\n")) {
+    const line = rawLine.trim();
+    if (line.startsWith("summary:")) {
+      summary = line.slice("summary:".length).trim().replace(/^['"]|['"]$/g, "");
+      collectingReadWhen = false;
+      continue;
+    }
+    if (line.startsWith("last_updated:")) {
+      lastUpdated = line.slice("last_updated:".length).trim().replace(/^['"]|['"]$/g, "");
+      collectingReadWhen = false;
+      continue;
+    }
+    if (line.startsWith("status:")) {
+      status = line.slice("status:".length).trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+      collectingReadWhen = false;
+      continue;
+    }
+    if (line.startsWith("read_when:")) {
+      collectingReadWhen = true;
+      continue;
+    }
+    if (collectingReadWhen && line.startsWith("- ")) {
+      readWhen.push(line.slice(2).trim());
+      continue;
+    }
+    if (collectingReadWhen && line.length > 0) {
+      collectingReadWhen = false;
+    }
+  }
+
+  return { summary, lastUpdated, readWhen, status };
+}
+
+function walkTracks(projectRoot, currentDir, output, invalid) {
+  for (const entry of readdirSync(currentDir)) {
+    const fullPath = path.join(currentDir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      walkTracks(projectRoot, fullPath, output, invalid);
+      continue;
+    }
+
+    if (!entry.endsWith(".md") || shouldSkipTrackFile(entry)) {
+      continue;
+    }
+
+    const { summary, lastUpdated, readWhen, status } = parseFrontmatter(fullPath);
+    if (!summary || !lastUpdated || readWhen.length === 0 || !VALID_TRACK_STATUSES.has(status)) {
+      invalid.push(path.relative(projectRoot, fullPath));
+      continue;
+    }
+
+    output.push({
+      path: path.relative(projectRoot, fullPath),
+      summary,
+      readWhen,
+      status,
+    });
+  }
+}
+
+export function renderTracksIndex(projectRoot) {
+  const trackDir = path.join(projectRoot, ".waypoint", "track");
+  const entries = [];
+  const invalidTracks = [];
+
+  if (existsSync(trackDir)) {
+    walkTracks(projectRoot, trackDir, entries, invalidTracks);
+  }
+
+  const lines = [
+    "# Tracks Index",
+    "",
+    "Auto-generated by `.waypoint/scripts/build-track-index.mjs`. Read active trackers when resuming long-running work.",
+    "",
+    "## .waypoint/track/",
+    "",
+  ];
+
+  if (entries.length === 0) {
+    lines.push("No tracker files found.");
+  } else {
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    for (const entry of entries) {
+      lines.push(`- **${entry.path}** — [${entry.status}] ${entry.summary}`);
+      lines.push(`  Read when: ${entry.readWhen.join("; ")}`);
+    }
+  }
+
+  lines.push("");
+  return {
+    content: `${lines.join("\n")}\n`,
+    invalidTracks,
+    activeTracks: entries
+      .filter((entry) => ACTIVE_TRACK_STATUSES.has(entry.status))
+      .map((entry) => entry.path)
+      .sort((a, b) => a.localeCompare(b)),
+  };
+}
+
+export function writeTracksIndex(projectRoot) {
+  const outputPath = path.join(projectRoot, ".waypoint", "TRACKS_INDEX.md");
+  const rendered = renderTracksIndex(projectRoot);
+  writeFileSync(outputPath, rendered.content, "utf8");
+  return { outputPath, activeTracks: rendered.activeTracks, invalidTracks: rendered.invalidTracks };
+}
+
+const isDirectExecution = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectExecution) {
+  const projectRoot = detectProjectRoot();
+  const { outputPath } = writeTracksIndex(projectRoot);
+  console.log(`Wrote ${outputPath}`);
+}

package/templates/.waypoint/scripts/prepare-context.mjs

@@ -7,6 +7,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { findProjectRoot, writeDocsIndex } from "./build-docs-index.mjs";
+import { writeTracksIndex } from "./build-track-index.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -437,6 +438,21 @@ function writeContextFile(contextDir, name, title, body) {
   return filePath;
 }
 
+function writeActiveTrackers(contextDir, projectRoot, activeTracks) {
+  return writeContextFile(
+    contextDir,
+    "ACTIVE_TRACKERS.md",
+    "Active Trackers",
+    activeTracks.length === 0
+      ? "No active tracker files found."
+      : [
+          "These trackers should be read when resuming long-running work:",
+          "",
+          ...activeTracks.map((trackPath) => `- \`${trackPath}\``),
+        ].join("\n"),
+  );
+}
+
 function main() {
   const projectRoot = detectProjectRoot();
   const contextDir = path.join(projectRoot, ".waypoint", "context");
@@ -448,6 +464,7 @@ function main() {
       : null;
 
   const docsIndexPath = writeDocsIndex(projectRoot);
+  const { outputPath: tracksIndexPath, activeTracks } = writeTracksIndex(projectRoot);
 
   const currentDatetimePath = writeContextFile(
     contextDir,
@@ -590,6 +607,7 @@ function main() {
     ].join("\n")
   );
   const recentThreadPath = writeRecentThread(contextDir, projectRoot, threadIdOverride);
+  const activeTrackersPath = writeActiveTrackers(contextDir, projectRoot, activeTracks);
 
   const manifestPath = path.join(contextDir, "MANIFEST.md");
   const manifestLines = [
@@ -606,6 +624,8 @@ function main() {
     `- \`${path.relative(projectRoot, prsPath)}\` — open and recently merged pull requests`,
     `- \`${path.relative(projectRoot, recentThreadPath)}\` — latest meaningful turns from the local Codex session for this repo`,
     `- \`${path.relative(projectRoot, docsIndexPath)}\` — current docs index`,
+    `- \`${path.relative(projectRoot, tracksIndexPath)}\` — current tracker index`,
+    `- \`${path.relative(projectRoot, activeTrackersPath)}\` — active tracker summary`,
     "",
     "## Stable source-of-truth files to read before this manifest",
     "",
@@ -613,6 +633,10 @@ function main() {
     "- `.waypoint/agent-operating-manual.md`",
     "- `.waypoint/WORKSPACE.md`",
     "",
+    "## Active tracker files to read after this manifest",
+    "",
+    ...(activeTracks.length > 0 ? activeTracks.map((trackPath) => `- \`${trackPath}\``) : ["- None."]),
+    "",
     `Generated by: \`${path.relative(projectRoot, fileURLToPath(import.meta.url))}\``,
     "",
   ];

package/templates/.waypoint/track/README.md

@@ -0,0 +1,38 @@
+# Waypoint Trackers
+
+This directory holds active execution trackers for long-running work.
+
+Use `.waypoint/track/` when the work is too large to fit safely in `WORKSPACE.md`, especially for:
+
+- multi-session implementation campaigns
+- broad audits followed by remediation
+- large fix lists or rollout work
+- verification or review loops that will take time to close
+
+Tracker files are **execution state**, not general project memory.
+
+- Keep durable architecture, decisions, and long-term reference material in `.waypoint/docs/`.
+- Keep `WORKSPACE.md` short and current.
+- Put detailed checklists, per-item status, blockers, and verification progress in `.waypoint/track/`.
+
+Every tracker needs YAML frontmatter:
+
+```yaml
+---
+summary: One-line description
+last_updated: "2026-03-13 11:38 PDT"
+status: active
+read_when:
+  - resuming the workstream
+---
+```
+
+Valid tracker statuses:
+
+- `active`
+- `blocked`
+- `paused`
+- `done`
+- `archived`
+
+`WORKSPACE.md` should point at the active tracker file under `## Active Trackers`.

package/templates/.waypoint/track/_template.md

@@ -0,0 +1,44 @@
+---
+summary: One-line description of the workstream
+last_updated: "2026-03-13 11:38 PDT"
+status: active
+read_when:
+  - resuming this workstream
+---
+
+# Tracker Title
+
+## Goal
+
+What outcome this tracker is trying to reach.
+
+## Source
+
+- User request, audit, plan, or review thread that kicked off the work.
+
+## Current State
+
+- [2026-03-13 11:38 PDT] Current truth about the work.
+
+## Next
+
+- [2026-03-13 11:38 PDT] The next concrete action.
+
+## Workstreams
+
+### 1. Stream Name
+
+- [ ] First task
+- [ ] Second task
+
+## Verification
+
+- [ ] Verification step
+
+## Decisions
+
+- [2026-03-13 11:38 PDT] Decision and rationale.
+
+## Notes
+
+- Useful details that do not belong in `WORKSPACE.md`.

package/templates/WORKSPACE.md

@@ -1,11 +1,15 @@
 # Workspace
 
-Timestamp discipline: Prefix new or materially revised bullets in `Current State`, `In Progress`, `Next`, `Parked`, and `Done Recently` with `[YYYY-MM-DD HH:MM TZ]`.
+Timestamp discipline: Prefix new or materially revised bullets in `Active Trackers`, `Current State`, `In Progress`, `Next`, `Parked`, and `Done Recently` with `[YYYY-MM-DD HH:MM TZ]`.
 
 ## Active Goal
 
 Describe the main thing currently being built or changed.
 
+## Active Trackers
+
+List any active tracker docs under `.waypoint/track/`, with the current phase or next step.
+
 ## Current State
 
 What is already true right now?

package/templates/managed-agents-block.md

@@ -32,8 +32,10 @@ This is mandatory, not optional.
 
 Working rules:
 - Keep `.waypoint/WORKSPACE.md` current as the live execution state, with timestamped new or materially revised entries in multi-topic sections
+- For large multi-step work, create or update `.waypoint/track/<slug>.md`, keep detailed execution state there, and point to it from `## Active Trackers` in `.waypoint/WORKSPACE.md`
 - Update `.waypoint/docs/` when behavior or durable project knowledge changes, and refresh `last_updated` on touched routable docs
 - Use the repo-local skills Waypoint ships for structured workflows when relevant
+- Use `work-tracker` when a long-running implementation, remediation, or verification campaign needs durable progress tracking
 - Use `docs-sync` when the docs may be stale or a change altered shipped behavior, contracts, routes, or commands
 - Use `code-guide-audit` for a targeted coding-guide compliance pass on a specific feature, file set, or change slice
 - Use `break-it-qa` for browser-facing features that should be tested against invalid inputs, refreshes, repeated clicks, wrong navigation, and other adversarial user behavior

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

@@ -1,69 +0,0 @@
----
-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

@@ -1,37 +0,0 @@
-# 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

@@ -1,67 +0,0 @@
----
-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

@@ -1,35 +0,0 @@
-# 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/ux-states-audit/SKILL.md

@@ -1,63 +0,0 @@
----
-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

@@ -1,34 +0,0 @@
-# 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
-