waypoint-codex 0.6.1 → 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,16 +130,13 @@ 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`
 - `workspace-compress`
 - `pre-pr-hygiene`
 - `pr-review`
-- `e2e-verify`
 
 These are repo-local, so the workflow travels with the project.
 
@@ -147,7 +148,7 @@ If you initialize with `--with-roles`, Waypoint scaffolds:
 - `code-reviewer`
 - `plan-reviewer`
 
-The intended workflow is post-commit: make your change, commit it, run the reviewers in parallel, fix real findings, then close out.
+The intended workflow is chunk-based: once there is a meaningful reviewable slice, run the reviewers in parallel, fix real findings, then close out. A recent self-authored commit is the preferred scope anchor when one cleanly represents the slice, but it is not the only valid trigger.
 
 ## What makes it different
 

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,18 +464,62 @@ 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",
         "workspace-compress",
         "pre-pr-hygiene",
         "pr-review",
-        "e2e-verify",
     ]) {
         const skillPath = path.join(projectRoot, ".agents/skills", skillName, "SKILL.md");
         if (!existsSync(skillPath)) {
@@ -529,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.6.1",
+  "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/break-it-qa/SKILL.md

@@ -7,10 +7,7 @@ description: Verify a user-facing feature by trying to break it on purpose inste
 
 Use this skill to attack the feature like an impatient, confused, or careless user.
 
-This is not the same as `e2e-verify`.
-
-- `e2e-verify` proves the intended flow works end to end.
-- `break-it-qa` tries to make the feature fail through invalid, interrupted, stale, repeated, or out-of-order interactions.
+This skill is for adversarial manual QA. It tries to make the feature fail through invalid, interrupted, stale, repeated, or out-of-order interactions instead of only proving the happy path works.
 
 ## Step 1: Ask The Three Setup Questions
 

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

@@ -11,7 +11,9 @@ This skill owns one job: inspect the specific code the user points at, map it ag
 
 ## Step 1: Load The Right Scope
 
-- Read `.waypoint/docs/code-guide.md`.
+- Read the repo's routed code guide.
+- In standard Waypoint repos, use `.waypoint/docs/code-guide.md`.
+- If the repo routes the code guide somewhere else, follow the repo's own docs and routing instead of assuming another fixed path.
 - Read only the files, routes, tests, contracts, and nearby docs needed to understand the specific feature or slice under review.
 - If the scope is ambiguous, resolve it to a concrete file set, feature path, or commit-sized change surface before auditing.
 
@@ -45,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/pre-pr-hygiene/SKILL.md

@@ -16,7 +16,9 @@ Before the hygiene pass:
 3. Read `.waypoint/WORKSPACE.md`
 4. Read `.waypoint/context/MANIFEST.md`
 5. Read every file listed in that manifest
-6. Read `.waypoint/docs/code-guide.md` and the routed docs relevant to the area being shipped
+6. Read the repo's routed code guide and the routed docs relevant to the area being shipped
+
+In standard Waypoint repos, the code guide lives at `.waypoint/docs/code-guide.md`. If the repo routes it somewhere else, follow the repo's own docs and routing instead of assuming another fixed path.
 
 ## Step 1: Audit The Whole Change Surface
 

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,16 +67,13 @@ 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
 - `workspace-compress` after meaningful chunks, before stopping, and before review when the live handoff needs compression
 - `pre-pr-hygiene` before pushing or opening/updating a PR for substantial work
 - `pr-review` once a PR has active review comments or automated review in progress
-- `e2e-verify` for major user-facing or cross-system changes that need manual end-to-end verification
 
 ## When to use the optional reviewer agents
 
@@ -83,14 +83,15 @@ If the repo was initialized with Waypoint roles enabled, use them as focused sec
 - `code-health-reviewer` for maintainability drift
 - `plan-reviewer` to challenge weak implementation plans before execution
 
-## Post-Commit Review Loop
+## Review Loop
 
-If Waypoint's optional roles are enabled and you authored a commit, immediately after that commit:
+If Waypoint's optional roles are enabled, run the reviewer pair after a meaningful reviewable implementation chunk, not just as a reflex after every tiny commit.
 
-1. Launch `code-reviewer` and `code-health-reviewer` in parallel as background, read-only reviewers.
-2. Scope them to the commit you just made, then widen only when surrounding files are needed to validate a finding.
-3. Do not call the work finished before you read both reviewer results.
-4. Fix real findings, rerun the relevant verification, update workspace/docs if needed, and make a follow-up commit when fixes change the repo.
+1. Launch `code-reviewer` and `code-health-reviewer` in parallel as background, read-only reviewers once there is a coherent slice of work worth reviewing.
+2. If you have a recent self-authored commit that cleanly represents that slice, use it as the default review scope anchor. Otherwise scope the reviewers to the current changed slice.
+3. Widen only when surrounding files are needed to validate a finding.
+4. Do not call the work finished before you read both reviewer results.
+5. Fix real findings, rerun the relevant verification, update workspace/docs if needed, and make a follow-up commit when fixes change the repo.
 
 ## Quality bar
 

package/templates/.waypoint/agents/code-health-reviewer.md

@@ -59,7 +59,13 @@ Do not create findings for:
 
 ## Scope
 
-In Waypoint's default post-commit review loop, start with the latest self-authored commit, then widen only when related files are needed to validate a maintainability issue. Focus on:
+In Waypoint's default review loop, start with the reviewable slice the main agent hands you.
+
+- If there is a recent self-authored commit that cleanly represents the slice, use that commit as the default scope anchor.
+- Otherwise, start from the current changed files or diff under review.
+- Widen only when related files are needed to validate a maintainability issue.
+
+Focus on:
 
 - recently changed files
 - their importers

package/templates/.waypoint/agents/code-reviewer.md

@@ -41,7 +41,11 @@ Not:
 
 ### 1. Get the Changes
 
-In Waypoint's default post-commit review loop, start with the latest self-authored commit. Review the actual diff or recent changed files first, then widen only as needed.
+In Waypoint's default review loop, start with the reviewable slice the main agent hands you.
+
+- If there is a recent self-authored commit that cleanly represents the slice, use that commit as the default scope anchor.
+- Otherwise, start from the current changed files or diff the main agent is asking you to review.
+- Widen only as needed.
 
 ### 2. Deep Research
 

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