getadvantage 0.2.0 → 0.3.0

package/README.md

@@ -26,6 +26,7 @@ npx getadvantage            # run the pre-deploy checks (GO / NO-GO)
 npx getadvantage brief      # generate / refresh the project brain
 npx getadvantage init       # auto-load the brain at every session start
 npx getadvantage handoff    # save your place for the next session
+npx getadvantage switch     # move to a new tool/model without losing context
 ```
 
 Or add it to your project:
@@ -49,7 +50,9 @@ whichever reads better to you.
 | `ship-safe` (default `check`) | Read-only pre-deploy checks → exit `0` on **GO**, `1` on **NO-GO**. Add `--build` for a full build. |
 | `ship-safe brief` | Generate / refresh `PROJECT-BRIEF.md` — the **COLD** layer (what the project *is*). `--check` warns if it's stale; it never blocks. |
 | `ship-safe handoff` | Refresh the brief **and** write `HANDOFF.md` — the **HOT** layer (where you *left off*). Your notes are preserved across refreshes; it never overwrites a `HANDOFF.md` it didn't create. |
-| `ship-safe init` | Wire the brain into your agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `.cursorrules`) so `PROJECT-BRIEF.md` + `HANDOFF.md` load automatically at session start. |
+| `ship-safe init` | Wire the brain into your agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `.cursorrules` / `.windsurfrules` / `.clinerules`) so `PROJECT-BRIEF.md` + `HANDOFF.md` load automatically at session start. |
+| `ship-safe switch [tool]` | Switch tools/models without losing context — saves your place, wires every AI-tool file, and prints the prompt to start the new session. |
+| `ship-safe models` | A plain-language playbook for choosing + switching AI models (principles, not benchmarks). |
 | `ship-safe gauge` | A quick "is this session getting heavy?" read (repo activity since your last handoff) that nudges a reset before things slow down — a heuristic, not a token count. |
 | `ship-safe ledger` | Show the session ledger — the running log of save-points each `handoff` records. |
 | `ship-safe deploy` | _(Advanced)_ Deploy from a clean, detached worktree and confirm the deployment URL's project prefix. Runs a real `vercel --prod`; the project prefix is derived from your linked `.vercel` (or pass `--expect-prefix`). |

package/handoff.mjs

@@ -268,9 +268,11 @@ export function runHandoff(o) {
       c.yellow("  ▸ First handoff — fill in the short narrative (Where we are / Next steps) so the next session knows the plan."),
     );
   }
-  console.log(c.gray("  Next session, paste this to pick up instantly:"));
-  console.log(c.cyan(`      Read PROJECT-BRIEF.md and ${relPath(handoffAbs, cwd)}, then continue where we left off.`));
-  console.log(c.gray("  Commit both files — your brain lives in the repo, not your tool."));
+  if (!o.quiet) {
+    console.log(c.gray("  Next session, paste this to pick up instantly:"));
+    console.log(c.cyan(`      Read PROJECT-BRIEF.md and ${relPath(handoffAbs, cwd)}, then continue where we left off.`));
+    console.log(c.gray("  Commit both files — your brain lives in the repo, not your tool."));
+  }
   return 0;
 }
 

package/index.mjs

@@ -38,6 +38,8 @@ import { runHandoff } from "./handoff.mjs";
 import { runLedger } from "./ledger.mjs";
 import { runGauge } from "./gauge.mjs";
 import { runInit } from "./init.mjs";
+import { runSwitch } from "./switch.mjs";
+import { runModels } from "./models.mjs";
 
 function parseArgs(argv) {
   // First non-flag token is the subcommand; default to "check".
@@ -58,7 +60,7 @@ function parseArgs(argv) {
       positional.push(a);
     }
   }
-  return { cmd: positional[0] || "check", flags };
+  return { cmd: positional[0] || "check", arg: positional[1], flags };
 }
 
 function header() {
@@ -85,7 +87,11 @@ ${c.bold("Commands")}
   ${c.cyan("ledger")}   Show the session ledger — the running log of save-points (the project's
            history); each ${c.bold("handoff")} adds an entry.
   ${c.cyan("init")}     Wire the brain into your agent's instructions file (CLAUDE.md / AGENTS.md /
-           .cursorrules) so the brief + handoff load automatically at session start.
+           .cursorrules / .windsurfrules / .clinerules) so the brief + handoff load at session start.
+  ${c.cyan("switch")}   Switch tools/models without losing context: saves your place, wires every
+           AI-tool file, and prints the prompt to start the new session. ${c.dim("(switch <tool>)")}
+  ${c.cyan("models")}   A plain-language playbook for choosing + switching AI models (which model
+           for which job) — principles, not benchmarks.
   ${c.cyan("deploy")}   Run check, then deploy from a clean detached worktree and confirm the
            deployment URL prefix. Performs a real ${c.bold("vercel --prod")}.
 
@@ -111,13 +117,14 @@ ${c.bold("Examples")}
   ship-safe brief                  generate / refresh the project brain
   ship-safe init                   auto-load the brain at every session start
   ship-safe handoff                save your place for the next session
+  ship-safe switch cursor          move to a new tool/model without losing context
   ship-safe gauge                  is this session getting heavy?
   ship-safe deploy --expect-prefix myproject-
 `);
 }
 
 async function main() {
-  const { cmd, flags } = parseArgs(process.argv.slice(2));
+  const { cmd, arg, flags } = parseArgs(process.argv.slice(2));
 
   if (cmd === "help" || flags.help) {
     printHelp();
@@ -166,6 +173,16 @@ async function main() {
     process.exit(code);
   }
 
+  if (cmd === "switch") {
+    header();
+    process.exit(runSwitch({ cwd, target: arg }));
+  }
+
+  if (cmd === "models") {
+    header();
+    process.exit(runModels());
+  }
+
   if (cmd === "gauge") {
     header();
     process.exit(runGauge({ cwd }));

package/init.mjs

@@ -34,6 +34,8 @@ const TARGETS = [
   "CLAUDE.md",
   "AGENTS.md",
   ".cursorrules",
+  ".windsurfrules",
+  ".clinerules",
   ".github/copilot-instructions.md",
 ];
 

package/models.mjs

@@ -0,0 +1,40 @@
+// Ship-Safe — MODEL PLAYBOOK (`ship-safe models`).
+//
+// A plain-language guide to choosing + switching AI models, for people who don't
+// want to track benchmarks. HONESTY (hard): model strengths shift constantly and
+// depend on YOUR task — this is PRINCIPLE-based guidance, never a "best model"
+// claim or a benchmark. The real point: because your brain is portable
+// (PROJECT-BRIEF.md + HANDOFF.md live in the repo), switching is cheap, so you can
+// match the model to the job and move freely.
+//
+// Node built-ins only. ESM. Read-only (prints; writes nothing).
+
+import { c } from "./util.mjs";
+
+export function runModels() {
+  const L = [
+    "",
+    c.bold("  Choosing + switching AI models — a plain-language playbook"),
+    "",
+    "  Your context lives in the repo (PROJECT-BRIEF.md + HANDOFF.md), so switching",
+    "  models or tools is cheap. Match the model to the job:",
+    "",
+    `  ${c.cyan("Routine / boilerplate")}   repetitive edits, simple components, formatting, copy.`,
+    "    A cheaper, faster model is usually plenty. Save the strong one for the hard parts.",
+    "",
+    `  ${c.cyan("Hard reasoning")}          architecture, tricky bugs, security, big refactors.`,
+    "    Reach for the strongest model you have — the quality gap shows up right here.",
+    "",
+    `  ${c.cyan("Slow or down?")}           a provider is lagging or offline — switch and keep moving`,
+    "    (ChatGPT, Claude, Gemini, Qwen, …). Run `ship-safe switch` first so the next one",
+    "    starts with your brain instead of a blank slate.",
+    "",
+    c.gray("  Rule of thumb: try a cheaper model first, escalate when it struggles. Don't get"),
+    c.gray("  locked to one — verify what works for YOUR task, and switch freely."),
+    "",
+    c.gray("  (Principles, not benchmarks — model strengths change; your portable brain doesn't.)"),
+    "",
+  ];
+  for (const line of L) console.log(line);
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getadvantage",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The getAdvantage CLI — a local, dependency-free pre-deploy gate + portable project brain for AI-built apps. Plain-language GO / NO-GO, a repo-resident PROJECT-BRIEF.md any model reads first, and a session handoff so you can switch models or tools without re-explaining your project.",
   "type": "module",
   "bin": {

package/switch.mjs

@@ -0,0 +1,60 @@
+// Ship-Safe — SWITCH WITHOUT LOSS (`ship-safe switch`).
+//
+// The portability move. Your brain lives in the REPO (PROJECT-BRIEF.md +
+// HANDOFF.md), not in any one tool or model — so switching from Claude to Cursor
+// to Qwen (or just starting a fresh session) should cost nothing. `switch` makes
+// that a single command:
+//   1. saves your place + refreshes the brain (handoff),
+//   2. wires every AI-tool entry file so the new tool auto-loads it (init),
+//   3. prints the exact paste-ready prompt to start the new session.
+//
+// Optionally name the tool/model you're switching TO for a tailored tip:
+//   ship-safe switch cursor
+//
+// Node built-ins only. ESM. (Delegates to handoff + init.)
+
+import { c } from "./util.mjs";
+import { runHandoff } from "./handoff.mjs";
+import { runInit } from "./init.mjs";
+
+// A friendly per-target line. Unknown targets get the generic guidance.
+const TOOL_TIPS = {
+  claude: "Claude Code reads CLAUDE.md at startup — it'll pick up your brain automatically.",
+  "claude-code": "Claude Code reads CLAUDE.md at startup — it'll pick up your brain automatically.",
+  cursor: "Cursor reads .cursorrules at startup — it'll pick up your brain automatically.",
+  windsurf: "Windsurf reads .windsurfrules at startup — it'll pick up your brain automatically.",
+  cline: "Cline reads .clinerules at startup — it'll pick up your brain automatically.",
+  copilot: "GitHub Copilot reads .github/copilot-instructions.md — it'll pick up your brain.",
+  codex: "Codex (and AGENTS.md-aware tools) read AGENTS.md — it'll pick up your brain.",
+  qwen: "Qwen / any model: paste the prompt below to load your brain into the new chat.",
+  chatgpt: "ChatGPT / any model: paste the prompt below to load your brain into the new chat.",
+  gemini: "Gemini / any model: paste the prompt below to load your brain into the new chat.",
+};
+
+export function runSwitch(o) {
+  const cwd = o.cwd;
+  const target = (o.target || "").toLowerCase();
+
+  console.log(c.bold("\n  Switching without loss — your brain lives in the repo, not the tool.\n"));
+
+  // 1. Save your place + refresh the brain.
+  console.log(c.cyan("  1. Saving your place"));
+  const ho = runHandoff({ cwd, quiet: true });
+  if (ho !== 0) {
+    console.log(c.yellow("     (Couldn't refresh the handoff — see the note above; continuing.)"));
+  }
+
+  // 2. Wire every AI-tool entry file so whatever you switch to auto-loads it.
+  console.log(c.cyan("\n  2. Wiring your tools"));
+  runInit({ cwd });
+
+  // 3. The exact prompt to start the new session/tool/model.
+  console.log(c.cyan("\n  3. Start the new session"));
+  if (target && TOOL_TIPS[target]) {
+    console.log(`     ${c.gray(TOOL_TIPS[target])}`);
+  }
+  console.log("     Open your new tool or model and paste this:");
+  console.log(c.bold("\n     Read PROJECT-BRIEF.md and HANDOFF.md, then continue where we left off.\n"));
+  console.log(c.gray("     Same project, new model — no re-explaining. Need help choosing one? `ship-safe models`."));
+  return 0;
+}