forgetrail 0.3.0

package/content/scripts/setup-ollama.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * Install Ollama when possible, detect GPU VRAM, pull a non-thinking local model.
+ * Copy to app repo scripts/setup-ollama.mjs
+ *
+ * Policy: default to instruction models (Granite 4.1, Gemma 3) — NOT reasoning/thinking
+ * families unless OLLAMA_USE_THINKING=1 in .env.
+ *
+ * Env: OLLAMA_MODEL (override), OLLAMA_PREFER_GEMMA=1, OLLAMA_USE_THINKING=1,
+ *      OLLAMA_BASE_URL, SKIP_OLLAMA_INSTALL=1
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { loadEnv, repoRootFromImportMeta } from "./forgetrail-env.mjs";
+
+const repoRoot = repoRootFromImportMeta(import.meta.url);
+const stampPath = join(repoRoot, ".forgetrail", "ollama-model.txt");
+const isWin = process.platform === "win32";
+
+const THINKING_MODEL_RE =
+  /(^|:|\/)?(deepseek-r1|qwq|qwen3-thinking|o1|o3|reasoning|think\b|-think)/i;
+
+/** Approximate pull sizes (MB) for VRAM budgeting — leave ~2GB headroom for context/KV. */
+const MODEL_VRAM_MB = {
+  "gemma3:1b": 1200,
+  "ibm/granite4.1:3b": 2500,
+  "gemma3:4b": 4000,
+  "ibm/granite4:3b": 3500,
+  "ibm/granite4.1:8b": 6000,
+  "gemma3:12b": 9000,
+  "gemma3:27b": 18000,
+};
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { stdio: "inherit", shell: isWin, ...opts });
+    p.on("error", reject);
+    p.on("exit", (c) => (c === 0 ? resolve() : reject(new Error(`${cmd} exited ${c}`))));
+  });
+}
+
+function runCapture(cmd, args) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { shell: isWin });
+    let out = "";
+    p.stdout?.on("data", (d) => (out += d));
+    p.stderr?.on("data", (d) => (out += d));
+    p.on("error", () => resolve(""));
+    p.on("exit", () => resolve(out.trim()));
+  });
+}
+
+async function hasOllama() {
+  const out = await runCapture("ollama", ["--version"]);
+  return /ollama/i.test(out);
+}
+
+async function detectVramMb() {
+  if (isWin) {
+    const nvidia = await runCapture("nvidia-smi", [
+      "--query-gpu=memory.total",
+      "--format=csv,noheader,nounits",
+    ]);
+    const m = nvidia.match(/(\d+)/);
+    if (m) return Number(m[1]);
+  } else {
+    const nvidia = await runCapture("nvidia-smi", [
+      "--query-gpu=memory.total",
+      "--format=csv,noheader,nounits",
+    ]);
+    const first = nvidia.split(/\r?\n/)[0]?.match(/(\d+)/);
+    if (first) return Number(first[1]);
+  }
+  return 0;
+}
+
+function assertNotThinking(model, env) {
+  if (env.OLLAMA_USE_THINKING === "1") return;
+  if (THINKING_MODEL_RE.test(model)) {
+    throw new Error(
+      `Model "${model}" looks like a reasoning/thinking model. Set OLLAMA_USE_THINKING=1 only if the brief requires it. Default: Granite 4.1 or Gemma 3 instruct variants.`
+    );
+  }
+}
+
+function pickModel(vramMb, env) {
+  if (env.OLLAMA_MODEL?.trim()) {
+    const m = env.OLLAMA_MODEL.trim();
+    assertNotThinking(m, env);
+    return m;
+  }
+  const preferGemma = env.OLLAMA_PREFER_GEMMA === "1";
+  const tier = (m) => {
+    assertNotThinking(m, env);
+    return m;
+  };
+  if (vramMb >= 10000) {
+    return tier(preferGemma ? "gemma3:12b" : "ibm/granite4.1:8b");
+  }
+  if (vramMb >= 6000) {
+    return tier(preferGemma ? "gemma3:4b" : "ibm/granite4.1:8b");
+  }
+  if (vramMb >= 4000) {
+    return tier(preferGemma ? "gemma3:4b" : "ibm/granite4.1:3b");
+  }
+  if (vramMb > 0) {
+    return tier("gemma3:4b");
+  }
+  return tier(preferGemma ? "gemma3:4b" : "ibm/granite4.1:3b");
+}
+
+async function installOllama() {
+  console.log("Ollama not found — attempting install…");
+  if (isWin) {
+    try {
+      await run("winget", ["install", "-e", "--id", "Ollama.Ollama", "--accept-package-agreements", "--accept-source-agreements"]);
+      return true;
+    } catch {
+      console.log("winget install failed. Download from https://ollama.com/download/windows and re-run setup-ollama.");
+      return false;
+    }
+  }
+  if (process.platform === "darwin") {
+    try {
+      await run("brew", ["install", "ollama"]);
+      return true;
+    } catch {
+      console.log("brew install failed. Run: curl -fsSL https://ollama.com/install.sh | sh");
+      return false;
+    }
+  }
+  try {
+    await run("sh", ["-c", "curl -fsSL https://ollama.com/install.sh | sh"]);
+    return true;
+  } catch {
+    console.log("Install script failed. See https://ollama.com/download");
+    return false;
+  }
+}
+
+async function ensureOllamaServe() {
+  try {
+    const res = await fetch("http://127.0.0.1:11434/api/version", { signal: AbortSignal.timeout(2000) });
+    if (res.ok) return;
+  } catch {
+    /* start below */
+  }
+  console.log("Starting Ollama service in background…");
+  const child = spawn("ollama", ["serve"], { detached: true, stdio: "ignore", shell: isWin });
+  child.unref();
+  for (let i = 0; i < 20; i++) {
+    await new Promise((r) => setTimeout(r, 500));
+    try {
+      const res = await fetch("http://127.0.0.1:11434/api/version", { signal: AbortSignal.timeout(2000) });
+      if (res.ok) return;
+    } catch {
+      /* retry */
+    }
+  }
+  throw new Error("Ollama did not become ready on http://127.0.0.1:11434 — open the Ollama app (Windows/Mac) and retry.");
+}
+
+async function main() {
+  const env = loadEnv(repoRoot);
+  if (env.SKIP_OLLAMA_INSTALL === "1") {
+    console.log("SKIP_OLLAMA_INSTALL=1 — skipping Ollama setup.");
+    process.exit(0);
+  }
+
+  let installed = await hasOllama();
+  if (!installed && env.SKIP_OLLAMA_AUTO_INSTALL !== "1") {
+    installed = await installOllama();
+  }
+  if (!installed) {
+    console.error("Ollama is not installed. Install from https://ollama.com then run: pnpm run setup:ollama");
+    process.exit(1);
+  }
+
+  await ensureOllamaServe();
+
+  const vramMb = await detectVramMb();
+  const model = pickModel(vramMb, env);
+  const needMb = MODEL_VRAM_MB[model] || 5000;
+  console.log(
+    vramMb
+      ? `Detected GPU VRAM ≈ ${vramMb} MB — selected ${model} (needs ~${needMb} MB).`
+      : `No NVIDIA VRAM detected — using CPU-friendly ${model}. First run may be slow.`
+  );
+
+  if (existsSync(stampPath) && readFileSync(stampPath, "utf8").trim() === model && !process.argv.includes("--force")) {
+    console.log(`Model ${model} already recorded — skipping pull (use --force to re-pull).`);
+  } else {
+    console.log(`Pulling ${model}…`);
+    await run("ollama", ["pull", model]);
+    mkdirSync(join(repoRoot, ".forgetrail"), { recursive: true });
+    writeFileSync(stampPath, model, "utf8");
+  }
+
+  console.log("\nNext: node scripts/test-ollama.mjs  (or double-click test-ollama.bat)");
+  console.log(`Set in .env: OLLAMA_BASE_URL=http://127.0.0.1:11434  OLLAMA_MODEL=${model}`);
+}
+
+main().catch((e) => {
+  console.error(e.message || e);
+  process.exit(1);
+});

package/content/scripts/setup-pocketbase.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Reference PocketBase bootstrap — copy to app repo scripts/setup-pocketbase.mjs
+ * ForgeTrail: never hardcode a PocketBase version in FORGETRAIL_LITE or SCAFFOLD_INSTALL alone.
+ *
+ * Version resolution (in order):
+ * 1. POCKETBASE_VERSION in .env (semver, e.g. 0.26.2) — use when locked after a successful boot
+ * 2. POCKETBASE_VERSION=latest or unset → GitHub releases/latest at install time
+ *
+ * Idempotent: skips download if binary exists and version file matches (unless --force).
+ */
+import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmod, unlink } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pipeline } from "node:stream/promises";
+import { spawn } from "node:child_process";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+const pbDir = join(repoRoot, "pocketbase");
+const dataDir = join(pbDir, "pb_data");
+const versionFile = join(pbDir, ".pocketbase-version");
+const isWin = process.platform === "win32";
+const exeName = isWin ? "pocketbase.exe" : "pocketbase";
+const exePath = join(pbDir, exeName);
+
+function loadEnv() {
+  const envPath = join(repoRoot, ".env");
+  if (!existsSync(envPath)) return {};
+  const out = {};
+  for (const line of readFileSync(envPath, "utf8").split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const i = t.indexOf("=");
+    if (i < 1) continue;
+    out[t.slice(0, i).trim()] = t.slice(i + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+async function resolveVersion(env) {
+  const v = (env.POCKETBASE_VERSION || "latest").trim();
+  if (v !== "latest") return v.replace(/^v/, "");
+  const res = await fetch("https://api.github.com/repos/pocketbase/pocketbase/releases/latest", {
+    headers: { Accept: "application/vnd.github+json", "User-Agent": "forgetrail-setup" },
+  });
+  if (!res.ok) throw new Error(`Could not resolve latest PocketBase release (${res.status})`);
+  const data = await res.json();
+  const tag = String(data.tag_name || "").replace(/^v/, "");
+  if (!tag) throw new Error("GitHub latest release had no tag_name");
+  return tag;
+}
+
+function platformAsset(version) {
+  const os = isWin ? "windows" : process.platform === "darwin" ? "darwin" : "linux";
+  const arch = process.arch === "arm64" ? "arm64" : "amd64";
+  const ext = os === "windows" ? "zip" : "zip";
+  return {
+    url: `https://github.com/pocketbase/pocketbase/releases/download/v${version}/pocketbase_${version}_${os}_${arch}.${ext}`,
+    os,
+  };
+}
+
+async function download(url, dest) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Download failed ${res.status}: ${url}`);
+  await pipeline(res.body, createWriteStream(dest));
+}
+
+async function extractZip(zipPath) {
+  if (isWin) {
+    const ps = `Expand-Archive -LiteralPath '${zipPath.replace(/'/g, "''")}' -DestinationPath '${pbDir.replace(/'/g, "''")}' -Force`;
+    await new Promise((resolve, reject) => {
+      const p = spawn("powershell", ["-NoProfile", "-Command", ps], { stdio: "inherit", cwd: repoRoot });
+      p.on("exit", (c) => (c === 0 ? resolve() : reject(new Error(`Expand-Archive exit ${c}`))));
+    });
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    const p = spawn("unzip", ["-o", zipPath, "-d", pbDir], { stdio: "inherit" });
+    p.on("exit", (c) => (c === 0 ? resolve() : reject(new Error(`unzip exit ${c}`))));
+  });
+}
+
+async function portInUse(host, port) {
+  try {
+    const res = await fetch(`http://${host}:${port}/api/health`, { signal: AbortSignal.timeout(2000) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const force = process.argv.includes("--force");
+  const env = loadEnv();
+  const version = await resolveVersion(env);
+  const host = env.POCKETBASE_HTTP_HOST || "127.0.0.1";
+  const port = env.POCKETBASE_HTTP_PORT || env.PUBLIC_POCKETBASE_PORT || "8096";
+
+  mkdirSync(pbDir, { recursive: true });
+  mkdirSync(dataDir, { recursive: true });
+
+  if (existsSync(exePath) && existsSync(versionFile) && readFileSync(versionFile, "utf8").trim() === version && !force) {
+    console.log(`PocketBase ${version} already present — skipping download.`);
+  } else {
+    console.log(`Installing PocketBase ${version}…`);
+    const { url } = platformAsset(version);
+    const zipPath = join(pbDir, "pocketbase.zip");
+    await download(url, zipPath);
+    await extractZip(zipPath);
+    try {
+      await unlink(zipPath);
+    } catch {
+      /* ignore */
+    }
+    if (!isWin) await chmod(exePath, 0o755);
+    writeFileSync(versionFile, version, "utf8");
+    console.log(`Installed to ${exePath}`);
+  }
+
+  if (await portInUse(host, port)) {
+    console.log(`Note: something already responds on http://${host}:${port} — may be this or another PocketBase.`);
+  }
+
+  console.log(`Start with: pnpm run pocketbase  (or double-click run.bat)`);
+  console.log(`Admin UI: http://${host}:${port}/_/`);
+}
+
+main().catch((e) => {
+  console.error(e.message || e);
+  process.exit(1);
+});

package/content/scripts/test-ollama.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Isolated Ollama completion smoke test — no app required.
+ * Copy to app repo scripts/test-ollama.mjs
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadEnv, ollamaBaseUrlFromEnv, repoRootFromImportMeta } from "./forgetrail-env.mjs";
+
+const repoRoot = repoRootFromImportMeta(import.meta.url);
+const stampPath = join(repoRoot, ".forgetrail", "ollama-model.txt");
+
+function fail(msg) {
+  console.error(`Ollama check: FAIL — ${msg}`);
+  process.exit(1);
+}
+
+function resolveModel(env) {
+  if (env.OLLAMA_MODEL?.trim()) return env.OLLAMA_MODEL.trim();
+  if (existsSync(stampPath)) return readFileSync(stampPath, "utf8").trim();
+  return "ibm/granite4.1:3b";
+}
+
+async function main() {
+  const env = loadEnv(repoRoot);
+  const base = ollamaBaseUrlFromEnv(env);
+  const model = resolveModel(env);
+
+  let version;
+  try {
+    const res = await fetch(`${base.origin}/api/version`, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok) fail(`Ollama not reachable at ${base.origin} (HTTP ${res.status}). Run setup-ollama first.`);
+    version = await res.json();
+    console.log(`Ollama check: server OK — ${JSON.stringify(version)}`);
+  } catch (e) {
+    fail(`${base.origin} — ${e.message || e}. Install/start Ollama (setup-ollama.bat).`);
+  }
+
+  const tagsRes = await fetch(`${base.origin}/api/tags`, { signal: AbortSignal.timeout(5000) });
+  const tags = tagsRes.ok ? await tagsRes.json() : { models: [] };
+  const names = (tags.models || []).map((m) => m.name || m.model).filter(Boolean);
+  const hasModel = names.some((n) => n === model || n.startsWith(`${model}:`) || n.includes(model));
+  if (!hasModel) {
+    console.warn(`Model "${model}" not in local list (${names.slice(0, 5).join(", ")}…). Run setup-ollama.`);
+  }
+
+  const prompt = "Reply with exactly one word: pong";
+  console.log(`Completion test (${model})…`);
+  const genRes = await fetch(`${base.origin}/api/generate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model,
+      prompt,
+      stream: false,
+      options: { num_predict: 16, temperature: 0 },
+    }),
+    signal: AbortSignal.timeout(120000),
+  });
+  if (!genRes.ok) {
+    const errText = await genRes.text().catch(() => "");
+    fail(`generate failed HTTP ${genRes.status}${errText ? `: ${errText.slice(0, 200)}` : ""}`);
+  }
+  const out = await genRes.json();
+  const text = (out.response || "").trim();
+  if (!text) fail("empty completion — model may still be loading; retry in a minute.");
+  console.log(`Ollama check: OK — model responded: "${text.slice(0, 80)}${text.length > 80 ? "…" : ""}"`);
+  console.log(`Use OLLAMA_BASE_URL=${base.origin}  OLLAMA_MODEL=${model} in .env for runtime LLM routes.`);
+}
+
+main().catch((e) => fail(e.message || String(e)));

package/content/scripts/test-pocketbase.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Isolated PocketBase health check — no app dev server required.
+ * Copy to app repo scripts/test-pocketbase.mjs
+ *
+ * Usage: node scripts/test-pocketbase.mjs
+ * Exit 0 = healthy; non-zero = failure with actionable message.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { loadEnv, pocketBaseUrlFromEnv, repoRootFromImportMeta } from "./forgetrail-env.mjs";
+
+const repoRoot = repoRootFromImportMeta(import.meta.url);
+const env = loadEnv(repoRoot);
+const pbUrl = pocketBaseUrlFromEnv(env);
+
+function fail(msg, code = 1) {
+  console.error(`PocketBase check: FAIL — ${msg}`);
+  process.exit(code);
+}
+
+function ok(msg) {
+  console.log(`PocketBase check: OK — ${msg}`);
+}
+
+async function fetchHealth(origin) {
+  const res = await fetch(`${origin}/api/health`, { signal: AbortSignal.timeout(5000) });
+  if (!res.ok) throw new Error(`health returned ${res.status}`);
+  const body = await res.json().catch(() => ({}));
+  return body;
+}
+
+async function tryStartLocalPb() {
+  const pbDir = join(repoRoot, "pocketbase");
+  const isWin = process.platform === "win32";
+  const exe = join(pbDir, isWin ? "pocketbase.exe" : "pocketbase");
+  if (!existsSync(exe)) return false;
+  const host = env.POCKETBASE_HTTP_HOST || "127.0.0.1";
+  const port = env.POCKETBASE_HTTP_PORT || env.PUBLIC_POCKETBASE_PORT || "8096";
+  console.log(`Starting local PocketBase (${host}:${port}) for this test…`);
+  const child = spawn(exe, ["serve", `--http=${host}:${port}`], {
+    cwd: pbDir,
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  for (let i = 0; i < 15; i++) {
+    await new Promise((r) => setTimeout(r, 500));
+    try {
+      await fetchHealth(`http://${host}:${port}`);
+      return `http://${host}:${port}`;
+    } catch {
+      /* retry */
+    }
+  }
+  return false;
+}
+
+async function main() {
+  let origin = pbUrl?.origin;
+  if (!origin) {
+    fail(
+      "Set PUBLIC_POCKETBASE_URL (or POCKETBASE_HTTP_HOST + POCKETBASE_HTTP_PORT) in .env — see .env.example."
+    );
+  }
+
+  let health;
+  try {
+    health = await fetchHealth(origin);
+    ok(`${origin} — ${JSON.stringify(health)}`);
+  } catch (e) {
+    console.log(`No response at ${origin} (${e.message || e}).`);
+    const started = await tryStartLocalPb();
+    if (!started) {
+      fail(
+        `Nothing listening at ${origin}. Run setup.bat / pnpm run setup:pocketbase, then pnpm run pocketbase or run.bat.`
+      );
+    }
+    origin = started;
+    health = await fetchHealth(origin);
+    ok(`${origin} (started for test) — ${JSON.stringify(health)}`);
+  }
+
+  const email = env.POCKETBASE_ADMIN_EMAIL;
+  const password = env.POCKETBASE_ADMIN_PASSWORD;
+  if (email && password) {
+    try {
+      const res = await fetch(`${origin}/api/admins/auth-with-password`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ identity: email, password }),
+        signal: AbortSignal.timeout(8000),
+      });
+      if (res.ok) {
+        console.log("Admin auth: OK (POCKETBASE_ADMIN_* credentials accepted).");
+      } else {
+        console.warn(`Admin auth: HTTP ${res.status} — check POCKETBASE_ADMIN_EMAIL / POCKETBASE_ADMIN_PASSWORD.`);
+      }
+    } catch (e) {
+      console.warn(`Admin auth: skipped (${e.message || e}).`);
+    }
+  } else {
+    console.log("Admin auth: skipped (set POCKETBASE_ADMIN_EMAIL + POCKETBASE_ADMIN_PASSWORD in .env to test).");
+  }
+
+  console.log(`Admin UI: ${origin}/_/`);
+}
+
+main().catch((e) => fail(e.message || String(e)));

package/content/skills/forgetrail/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: forgetrail
+description: "Enforce the ForgeTrail 7-phase lifecycle (Plan → Build → Stabilize → Iterate → Refine → Align → Harden), maintain .forgetrail/workflow_tracking.json as the system of record, pause at explicit phase transitions for user approval, prefer native plan modes when available, and use subagents for parallel audits/research where the host agent supports it. Activate for any non-trivial full-stack app development. Follow progressive documentation rules and propagate lessons back."
+user-invocable: true
+argument-hint: "kickoff new project | resume session | Phase 4 feature work | run black-hat audit | stabilize current issues"
+allowed-tools: "read_file, search_replace, run_terminal_command, todo_write, spawn_subagent, getPhaseGuidance, runAudit, searchLessons, validateTracking, suggestSubagentDecomposition, getTemplate, getNewProjectKickoff, getResumeSessionInstructions"
+---
+
+# ForgeTrail Skill — Lifecycle + Memory Layer
+
+You are operating under the ForgeTrail methodology. Your primary job is to give the user a disciplined, experienced build partner instead of a generic coding assistant.
+
+## Core Rules (always active)
+
+1. **Follow the 7 phases strictly**:
+   - 1. Architecture + Planning (lock decisions before code)
+   - 2. Scaffolding + Core Build (full runnable spine + hero flow in one pass)
+   - 3. Stabilize (fix env, errors, reliability)
+   - 4. Iterate (features with real data)
+   - 5. Refine (refactor when files >500 lines or patterns duplicate)
+   - 6. Align (map to brand/strategy)
+   - 7. Harden (security, perf, docs, production readiness)
+
+   Phases 4 and 5 commonly alternate. Update `currentPhase` and exit criteria in tracking.
+
+2. **At the start of every session or major turn**:
+   - Read `.forgetrail/workflow_tracking.json` (create `.forgetrail/` if missing).
+   - Read `CONTEXT_PROMPT.md` and `TODO.md` if they exist.
+   - Call `getPhaseGuidance` for the current phase if needed.
+   - Summarize current phase, exit criteria met/remaining, and recent decisions to the user briefly.
+
+3. **Pause at phase transitions**:
+   - When you believe exit criteria for the current phase are met, explicitly tell the user: "I think we have completed Phase X because [reasons]. The remaining exit criteria are [list]. Ready to move to Phase Y?"
+   - Wait for explicit user approval before advancing `currentPhase` in tracking.
+
+4. **Maintain the tracking file** (`.forgetrail/workflow_tracking.json`):
+   - Log every major decision with rationale and alternatives_considered.
+   - Move items from `exitCriteriaRemaining` to `exitCriteriaMet`.
+   - Add to `gotchas[]` immediately when something surprising or painful happens.
+   - Append session notes at natural breaks.
+   - Use the schema from `getTrackingSchema`.
+
+5. **Use native agent capabilities**:
+   - If the agent supports a native plan mode (e.g. Grok `/plan`), use it for Phase 1. On approval, export the plan into `docs/PHASE_1_BRIEF.md` (via `getTemplate`) + `decisions[]`.
+   - When the host supports `spawn_subagent`, use `suggestSubagentDecomposition` (or reason directly) to run audits, research, and reviews in parallel with appropriate `capability_mode`, `isolation`, and personas. Synthesize results in the parent thread and update tracking/docs.
+   - Prefer `read-only` or `execute` modes for subagents doing analysis.
+
+6. **Progressive documentation**:
+   - Only create docs when the current phase requires them (see `getProgressiveDocSchedule`).
+   - Phase 1: `PHASE_1_BRIEF.md` + decisions.
+   - Phase 2: Merge brief into `CONTEXT_PROMPT.md`, plus `README.md`, `TODO.md`, `.forgetrail/IDEAS.md`.
+   - Later phases add `TECHNICAL_REFERENCE.md`, audits, etc. only when needed.
+
+7. **Reply format** (when offering options):
+   - Numbered lists for ordered pipelines/steps.
+   - Bullets for parallel options.
+   - Letters (A/B/C) for pick-one choices.
+   - Keep first user-facing replies short after bootstrap (no raw tool dumps).
+
+8. **Audits & Lessons**:
+   - Before large/complex work, call `runAudit` or `searchLessons` (or `suggestSubagentDecomposition` if subagents are available).
+   - Use `getAntiPatterns` for known failure modes.
+
+## Phase Transition Protocol
+
+When ready to advance:
+- Confirm all exit criteria.
+- Update tracking.
+- Ask user: "Ready to move to Phase X?"
+- Only after confirmation, update `currentPhase` and start the next phase's playbook.
+
+## For New Projects (Greenfield)
+
+Prefer calling `getNewProjectKickoff` (or `kickoffGreenfield`) at the very beginning. Write the returned `.forgetrail/workflow_tracking.json`, optional Cursor rules, and follow the post-bootstrap instructions exactly. Then start with Phase 1.
+
+## For Resuming
+
+Call `getResumeSessionInstructions` (or read tracking + CONTEXT_PROMPT) and continue from the current phase.
+
+## Key Tools to Use Proactively
+
+- `getPhaseGuidance(<phase>)` — before starting work in a phase.
+- `getTemplate({name: "..."})` — for PHASE_1_BRIEF, CONTEXT_PROMPT, audits, etc. Use mode "shell" for clean structure.
+- `runAudit`, `searchLessons`, `getAntiPatterns`
+- `suggestSubagentDecomposition` (when subagents available)
+- `validateTracking` (to keep the state file healthy)
+- `ingestPlanArtifact` (after native plan mode approval — map plan → PHASE_1_BRIEF + decisions[])
+- `todo_write` — mirror open exit criteria and next actions.
+
+Always keep the user in the loop on phase progress and major decisions. The tracking file + CONTEXT_PROMPT are the source of truth across sessions, not chat history.
+
+This skill makes you a much more reliable long-term build partner. Use it.