waypoint-codex 0.7.0 → 0.8.1

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/
     └── ...
@@ -94,6 +98,12 @@ From there, start your Codex session in the repo and follow the generated bootst
 waypoint init
 ```
 
+By default, `waypoint init` updates the global CLI to the latest published `waypoint-codex` first, then scaffolds with that fresh version. If you want to scaffold with the currently installed binary instead, use:
+
+```bash
+waypoint init --skip-cli-update
+```
+
 ### Full local workflow setup
 
 ```bash
@@ -112,10 +122,11 @@ Flags you can combine:
 - `--with-roles`
 - `--with-rules`
 - `--with-automations`
+- `--skip-cli-update`
 
 ## Main commands
 
-- `waypoint init` — scaffold or refresh the repo
+- `waypoint init` — update the CLI to latest by default, then scaffold or refresh the repo
 - `waypoint doctor` — validate health and report drift
 - `waypoint sync` — rebuild the docs index and sync optional user-home artifacts
 - `waypoint upgrade` — update the CLI and refresh the current repo using its saved config
@@ -126,9 +137,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/cli.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import process from "node:process";
 import { doctorRepository, importLegacyRepo, initRepository, loadWaypointConfig, syncRepository } from "./core.js";
-import { upgradeWaypoint } from "./upgrade.js";
+import { maybeUpgradeWaypointBeforeInit, upgradeWaypoint } from "./upgrade.js";
 const VERSION = JSON.parse(readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8")).version;
 function resolveRepo(input) {
     return path.resolve(input ?? ".");
@@ -27,7 +27,7 @@ function printHelp() {
     console.log(`usage: waypoint [--version] <command> [options]
 
 Commands:
-  init                Initialize a repository with Waypoint scaffolding
+  init                Initialize a repository with Waypoint scaffolding (auto-updates CLI unless skipped)
   doctor              Validate repository health and report drift
   sync                Rebuild docs index and sync optional user-home artifacts
   upgrade             Update the global Waypoint CLI and refresh this repo using existing config
@@ -52,11 +52,22 @@ async function main() {
                 "app-friendly": { type: "boolean", default: false },
                 "with-roles": { type: "boolean", default: false },
                 "with-rules": { type: "boolean", default: false },
-                "with-automations": { type: "boolean", default: false }
+                "with-automations": { type: "boolean", default: false },
+                "skip-cli-update": { type: "boolean", default: false }
             },
             allowPositionals: true
         });
         const projectRoot = resolveRepo(positionals[0]);
+        if (!values["skip-cli-update"]) {
+            const status = maybeUpgradeWaypointBeforeInit({
+                currentVersion: VERSION,
+                cliEntry: process.argv[1] ? path.resolve(process.argv[1]) : fileURLToPath(import.meta.url),
+                initArgs: argv.slice(1),
+            });
+            if (status !== null) {
+                return status;
+            }
+        }
         const results = initRepository(projectRoot, {
             profile: values["app-friendly"] ? "app-friendly" : "universal",
             withRoles: values["with-roles"],

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/dist/src/upgrade.js

@@ -21,6 +21,83 @@ export function buildInitArgs(projectRoot, config) {
     }
     return args;
 }
+function parseVersion(version) {
+    const trimmed = version.trim().replace(/^v/, "");
+    const match = trimmed.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: match[4] ? match[4].split(".") : [],
+    };
+}
+function compareIdentifiers(left, right) {
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+        return Number(left) - Number(right);
+    }
+    if (leftNumeric) {
+        return -1;
+    }
+    if (rightNumeric) {
+        return 1;
+    }
+    return left.localeCompare(right);
+}
+export function compareVersions(left, right) {
+    const leftParsed = parseVersion(left);
+    const rightParsed = parseVersion(right);
+    if (!leftParsed || !rightParsed) {
+        return left.localeCompare(right);
+    }
+    for (let index = 0; index < leftParsed.core.length; index += 1) {
+        const difference = leftParsed.core[index] - rightParsed.core[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    const leftPrerelease = leftParsed.prerelease;
+    const rightPrerelease = rightParsed.prerelease;
+    if (leftPrerelease.length === 0 && rightPrerelease.length === 0) {
+        return 0;
+    }
+    if (leftPrerelease.length === 0) {
+        return 1;
+    }
+    if (rightPrerelease.length === 0) {
+        return -1;
+    }
+    const length = Math.max(leftPrerelease.length, rightPrerelease.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftIdentifier = leftPrerelease[index];
+        const rightIdentifier = rightPrerelease[index];
+        if (leftIdentifier === undefined) {
+            return -1;
+        }
+        if (rightIdentifier === undefined) {
+            return 1;
+        }
+        const difference = compareIdentifiers(leftIdentifier, rightIdentifier);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+}
+function latestWaypointVersion(options) {
+    const npmBinary = options.npmBinary ?? process.env.WAYPOINT_NPM_COMMAND ?? npmBinaryForPlatform();
+    const latest = spawnSync(npmBinary, ["view", "waypoint-codex", "version"], {
+        stdio: "pipe",
+        encoding: "utf8",
+    });
+    if ((latest.status ?? 1) !== 0) {
+        return null;
+    }
+    const version = latest.stdout?.trim();
+    return version ? version : null;
+}
 function hasWaypointConfig(projectRoot) {
     return existsSync(path.join(projectRoot, ".waypoint/config.toml"));
 }
@@ -53,3 +130,26 @@ export function upgradeWaypoint(options) {
     });
     return doctor.status ?? 1;
 }
+export function maybeUpgradeWaypointBeforeInit(options) {
+    const nodeBinary = options.nodeBinary ?? process.execPath;
+    const npmBinary = options.npmBinary ?? process.env.WAYPOINT_NPM_COMMAND ?? npmBinaryForPlatform();
+    const stdio = options.stdio ?? "inherit";
+    const latestVersion = latestWaypointVersion({ npmBinary });
+    if (!latestVersion || compareVersions(latestVersion, options.currentVersion) <= 0) {
+        return null;
+    }
+    console.log(`Waypoint CLI ${options.currentVersion} is older than latest ${latestVersion}. Updating before init...`);
+    const update = spawnSync(npmBinary, ["install", "-g", "waypoint-codex@latest"], {
+        stdio,
+    });
+    if ((update.status ?? 1) !== 0) {
+        return update.status ?? 1;
+    }
+    const reexecArgs = options.initArgs.includes("--skip-cli-update")
+        ? options.initArgs
+        : [...options.initArgs, "--skip-cli-update"];
+    const init = spawnSync(nodeBinary, [options.cliEntry, "init", ...reexecArgs], {
+        stdio,
+    });
+    return init.status ?? 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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