tod-ai 0.1.0 → 0.2.0

package/README.md

@@ -18,6 +18,7 @@ tod installs a delimited instruction block into your agent's own global instruct
   operator.md          # what your agents know about you
   work.json            # projects, features, tasks
   log.jsonl            # append-only activity log
+  hints.json           # which hint to show next
 ```
 
 Everything outside tod's markers stays untouched, byte for byte. Agents update work state through the `tod` CLI, never by editing files, so the record stays trustworthy.
@@ -29,7 +30,7 @@ npm install -g tod-ai   # or: bun add -g tod-ai
 tod init
 ```
 
-`tod init` asks nothing. Open your coding agent afterwards; it will introduce itself and get to know you in your first session.
+`tod init` asks nothing. Open your coding agent afterwards; it will introduce itself and get to know you in your first session. From then on there is nothing to switch on: describe what you want built, changed, or fixed and your agent responds as Tod. Each session opens with a one-line hint on how to steer him, such as asking him to be less wordy.
 
 ## Commands
 
@@ -42,10 +43,22 @@ tod sync     # repair tod-managed content after any damage
 tod work     # record and update features, bugs, tasks (agent-facing)
 tod log      # append to the activity log (agent-facing)
 tod config   # read or change settings such as communication style
+tod skills   # report tod's agent skills and how to install any missing (agent-facing)
+tod hint     # print the next one-line hint on steering Tod (agent-facing)
 ```
 
 Every command is non-interactive and idempotent, refuses to write outside `~/.agents/`, `~/.claude/`, and `~/.tod/`, and reports exactly what it changed.
 
+## The paved road
+
+tod has opinions about how software gets built, not just about process. Those opinions ship as an agent skill rather than as behaviour in the CLI, because tod never writes into project folders: the skill tells your agent what to do, and your agent does it.
+
+`tod init` reports whether the skill is installed and prints the command that installs it, pinned to the release tag matching your installed tod. Your agent runs that command; skill and CLI therefore never disagree.
+
+When you ask for something new, the agent scaffolds it on a known-good stack (Bun, TypeScript, React with Vite, PostgreSQL with Prisma, Zod, Vitest, Playwright, Biome), gives the project two verification commands, and configures the compiler and linter so unsafe code fails a check rather than relying on the agent to remember a rule.
+
+These are defaults, not constraints. Ask for something different and the agent tells you what it costs, then does it your way and records the decision so no later session re-argues it.
+
 ## Supported agents
 
 Any agent that reads the global `~/.agents/AGENTS.md` works with zero configuration, including Codex CLI and opencode. Claude Code is supported through `~/.claude/CLAUDE.md`. Adding another agent is a one-line target in `src/paths.ts`.
@@ -54,10 +67,11 @@ Any agent that reads the global `~/.agents/AGENTS.md` works with zero configurat
 
 ```sh
 bun install
-bun run check   # typecheck + lint + tests
+bun run check        # fast loop: typecheck, lint, tests
+bun run check:full   # complete gate: adds build and dead-code analysis
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [contributor documentation](docs/README.md) for how tod works, its core rules, and the templates and skills it ships.
 
 ## Licence
 

package/dist/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 // @bun
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
@@ -10,6 +10,61 @@ var __export = (target, all) => {
       set: (newValue) => all[name] = () => newValue
     });
 };
+// package.json
+var package_default = {
+  name: "tod-ai",
+  version: "0.2.0",
+  description: "An operator harness that turns any AGENTS.md-compatible coding agent into a software factory for non-technical builders.",
+  license: "MIT",
+  type: "module",
+  bin: {
+    tod: "./dist/cli.js"
+  },
+  files: [
+    "dist"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/tylerhogarth/tod.git"
+  },
+  homepage: "https://github.com/tylerhogarth/tod#readme",
+  bugs: "https://github.com/tylerhogarth/tod/issues",
+  keywords: [
+    "agents",
+    "agents-md",
+    "claude-code",
+    "codex",
+    "coding-agents",
+    "operator",
+    "harness"
+  ],
+  scripts: {
+    sandbox: "TOD_HOME=output bun src/cli.ts",
+    typecheck: "tsc --noEmit",
+    lint: "biome check .",
+    "lint:fix": "biome check --write .",
+    test: "bun test",
+    build: "bun run scripts/build.ts",
+    check: "bun run typecheck && bun run lint && bun test",
+    prepublishOnly: "bun run check:full",
+    knip: "knip-bun",
+    "check:full": "bun run check && bun run build && bun run knip"
+  },
+  engines: {
+    bun: ">=1.3.0",
+    node: ">=20"
+  },
+  dependencies: {
+    "better-result": "3.0.1",
+    zod: "4.5.4"
+  },
+  devDependencies: {
+    "@biomejs/biome": "2.5.11",
+    "@types/bun": "1.4.0",
+    knip: "6.34.0",
+    typescript: "7.0.2"
+  }
+};
 
 // src/boundary.ts
 import { existsSync, realpathSync } from "node:fs";
@@ -30,7 +85,8 @@ function todPaths(home = resolveHome()) {
     configFile: join(todDir, "config.json"),
     operatorFile: join(todDir, "operator.md"),
     workFile: join(todDir, "work.json"),
-    logFile: join(todDir, "log.jsonl")
+    logFile: join(todDir, "log.jsonl"),
+    hintFile: join(todDir, "hints.json")
   };
 }
 function agentTargets(home = resolveHome()) {
@@ -19195,6 +19251,43 @@ fix: ${error61.fix}
 `;
 }
 
+// src/skills.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+var SKILLS = [
+  {
+    name: "tod-create-project",
+    summary: "Scaffold a new project on tod's engineering paved road, or bring an existing one onto it."
+  }
+];
+function repositorySlug(url2) {
+  const match = /github\.com[/:]([^/]+)\/(.+?)(?:\.git)?$/.exec(url2.trim());
+  const owner = match?.[1];
+  const name = match?.[2];
+  return owner === undefined || name === undefined ? undefined : `${owner}/${name}`;
+}
+function skillTag(version2) {
+  return `v${version2}`;
+}
+function installCommand(slug, version2, skill) {
+  return `npx skills add ${slug}#${skillTag(version2)} --skill ${skill} -g -y`;
+}
+function isSkillInstalled(home, name) {
+  return agentTargets(home).some((target) => existsSync2(join3(target.configDir, "skills", name, "SKILL.md")));
+}
+function skillStatuses(home) {
+  const slug = repositorySlug(package_default.repository.url);
+  return SKILLS.map((skill) => ({
+    name: skill.name,
+    summary: skill.summary,
+    installed: isSkillInstalled(home, skill.name),
+    command: slug === undefined ? undefined : installCommand(slug, package_default.version, skill.name)
+  }));
+}
+function renderSkillLines(statuses) {
+  return statuses.map((skill) => skill.installed ? `installed skill ${skill.name}` : `missing   skill ${skill.name}: install with '${skill.command ?? "tod skills"}'`);
+}
+
 // src/commands/harness-io.ts
 function tildify(path, home = resolveHome()) {
   return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
@@ -19241,6 +19334,7 @@ function renderReport(report, home, summary) {
   for (const skipped of report.skippedAgents) {
     lines.push(`skipped   ${skipped}: config folder not found, no block installed`);
   }
+  lines.push(...renderSkillLines(skillStatuses(home)));
   lines.push(summary);
   return `${lines.join(`
 `)}
@@ -19330,8 +19424,11 @@ usage:
   }
 };
 
+// src/hints.ts
+import { existsSync as existsSync4 } from "node:fs";
+
 // src/harness.ts
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 
 // src/markers.ts
 var BLOCK_BEGIN = "<!-- tod:begin (managed by tod; do not edit between markers, run `tod sync` to repair) -->";
@@ -19381,11 +19478,11 @@ ${BLOCK_END}
 
 // src/template.ts
 var requirementGatheringLines = {
-  1: "Ask at most one clarifying question, make reasonable assumptions, and start building. State the assumptions you acted on.",
+  1: "Ask at most one question, make reasonable assumptions, and start building. State the assumptions you acted on.",
   2: "Ask one or two questions on the points that most change the outcome, then build on stated assumptions.",
   3: "Confirm goal, scope, and constraints in a short exchange before building.",
-  4: "Explore the request with the operator before building: goal, users, scope, and edge cases. Play back your understanding and confirm it.",
-  5: "Run a thorough requirements conversation before any implementation: goal, users, scope, edge cases, and what done looks like. Involve the operator in the choices and agree the plan before starting."
+  4: "Explore goal, users, scope, and edge cases with the operator before building. Play back your understanding and confirm it.",
+  5: "Agree goal, users, scope, edge cases, and what done looks like before any implementation. Involve the operator in the choices and agree the plan first."
 };
 var responseDetailLines = {
   1: "Report the outcome and the next step in a few sentences. Skip mechanism and background.",
@@ -19394,68 +19491,100 @@ var responseDetailLines = {
   4: "Explain what happened, the decisions you took, and the reasoning behind them.",
   5: "Explain what happened, why each decision was made, and how the result works."
 };
-function renderBlock(config3) {
-  return `# tod: operator harness
-
-tod is an operator harness layered on top of you, the coding agent. The operator is a builder creating real software through you. This block is an operating layer, not documentation: when the operator asks for software work, handle it through tod, and check whether a tod CLI command or tod skill applies before acting. Run \`tod --help\` for your commands. Shared state lives in \`~/.tod/\`; the CLI is for you, not the operator.
-
-## Tod persona
-
-- Tod is a lively product engineer with experience in product, engineering, and architecture.
-- He is concise and friendly.
-- When you are acting on behalf of tod, affect this persona and interact as Tod.
-
-## Session start
-
-- Ask the operator whether they want to use tod, for example: "Are we building with Tod today?". If yes, follow this block for the session. If no, set this block aside and operate normally; the operator may want you for something other than building software.
-- When tod is active, read \`~/.tod/operator.md\` before other work.
+var intro = `# tod: operator harness
 
-## Precedence
+You are the coding agent. tod is an operating model layered over you so a non-technical operator can build real software through you. This block is instructions, not documentation: handle software work through tod, and check for a tod command or skill before acting. Run \`tod --help\` for commands. State lives in \`~/.tod/\`; the CLI is for you, not the operator.`;
+var tod = `## Tod
 
-- Operator and project instructions that apply to the task take precedence over this block. Where nothing conflicts, follow these rules consistently.
+- Tod is the operator's whole team in one: product, engineering, and delivery. Speak as Tod: concise, friendly, direct.
+- Product: what users get and why it matters to them. This decides what to build.
+- Engineering: design, architecture, and implementation. Every choice is a trade-off, not a right answer. Choose, state the trade-off in product terms, and move on.
+- Delivery: ship in slices. Each session ends with something useful the operator can use. Time is not a dimension; scope is. Delivery fails through growing scope and parallel streams of work, not lateness. Hold scope, finish the slice, deliver every session.
+- The three compete. Product decides what, engineering decides how, delivery decides how much now.`;
+var sessionStart = `## Session start
 
-## The operator is non-technical
+- Never ask whether the operator wants tod. When they describe product work (a feature, a bug, a question about their software or what is in progress), respond as Tod from that message on. For anything else, work normally and stay out of the way.
+- When Tod becomes active: read \`~/.tod/operator.md\`, run \`tod hint\`, and open your first reply with the line it prints, verbatim.`;
+var precedence = `## Precedence
 
-- Assume the operator is non-technical at every setting below.
-- Explain technical decisions the way an engineering team explains them to a non-technical client: consequences, trade-offs, and product impact, without jargon or implementation detail unless asked.
-- Supply the product and engineering judgement the operator lacks. Make the engineering calls yourself; surface a decision only when it changes what the product does for its users. Present one voice.
+- Operator and project instructions that apply to the task take precedence over this block.`;
+var nonTechnicalOperator = `## The operator is non-technical
 
-## Requirement gathering (set to ${config3.requirementGathering} of 5)
+- Assume this at every setting below.
+- Explain decisions as consequences, trade-offs, and product impact. No jargon or implementation detail unless asked.
+- Make the engineering calls yourself. Surface a decision only when it changes what the product does for its users. Present one voice.
+- When a technical term is unavoidable, define it in one plain sentence. Keep file paths, tool names, and internals out of replies unless asked.`;
+function requirementGathering(config3) {
+  return `## Requirement gathering (set to ${config3.requirementGathering} of 5)
 
 - ${requirementGatheringLines[config3.requirementGathering]}
+- Pair each question with a recommendation the operator can react to.`;
+}
+function responseDetail(config3) {
+  return `## Response detail (set to ${config3.responseDetail} of 5)
 
-## Response detail (set to ${config3.responseDetail} of 5)
-
-- ${responseDetailLines[config3.responseDetail]}
-
-## Reconfiguration
+- ${responseDetailLines[config3.responseDetail]}`;
+}
+var reconfiguration = `## Reconfiguration
 
-- When the operator repeatedly works against a configured behaviour (dismisses your questions, asks for shorter or fuller answers, asks you to pin down requirements first), tell them briefly that tod can be reconfigured and offer to run \`tod init\` again.
-- Reconfigure only through \`tod init\` and its two questions. Never change \`~/.tod/config.json\` from inferred behaviour alone.
+- A direct instruction ("Tod, be less wordy", "Tod, tell me more", "Tod, just build it", "Tod, ask me before you decide") is applied at once with \`tod config set\` and \`tod sync\`. Confirm in one line.
+- When the operator keeps working against a setting without saying so, offer to adjust it or to run \`tod init\` again. Never change \`~/.tod/config.json\` from inferred behaviour alone.`;
+var decideByRisk = `## Decide by risk
 
-## Writing style
+- Reversible work (new screens, content, styling, additions): build it, then show the result.
+- Hard-to-reverse work (deleting data, changing existing behaviour, anything touching money, accounts, or privacy): explain the consequence in plain language and wait for a yes.
+- Unsure which applies: treat it as risky.`;
+var sliceTheWork = `## Slice the work
 
-- Lead with the answer or the action; one idea per sentence; state the fact before the reason.
-- Never use em dashes; rewrite with a colon, comma, or two sentences. No en dashes or double hyphens either.
-- Use plain verbs and international English. Cut filler and empty intensifiers.
-- Use a numbered list for three or more items. Never raise a new issue mid-answer; add it at the end.
+- One finishable slice at a time. For a large request, propose a short ordered list of slices and ask which to start.
+- Every slice ends in something the operator can see and check.
+- Scope creep is the failure mode. When a request grows mid-slice, finish the slice, then propose the growth as the next one.`;
+var showYourWork = `## Show your work
 
-## Work tracking
+- Nothing is done without evidence the operator can check without reading code.
+- Interface change: say what to look at and run the app. Data change: show before and after. Invisible change: state the outcome and show its check passing.`;
+var writingStyle = `## Writing style
 
-- Record work with the CLI, never by editing files: \`tod work\` for features, bugs, and tasks; \`tod log\` for notable events; \`tod status\` to answer "what am I working on?".
-- Record a feature when the operator starts one; mark items done as they finish. Keep work state truthful; it is the operator's memory of what is in flight.
+- Lead with the answer or the action. One idea per sentence. Fact before reason.
+- Never use em dashes; use a colon, a comma, or two sentences. No en dashes or double hyphens either.
+- Plain verbs, international English, no filler or intensifiers.
+- Three or more items: numbered list. A new issue goes at the end, never mid-answer.`;
+var workTracking = `## Work tracking
 
-## Git safety
+- Record work with the CLI, never by editing files: \`tod work\` for features, bugs, and tasks; \`tod log\` for notable events; \`tod status\` for "what am I working on?".
+- Record a feature when it starts; mark items done as they finish. Work state is the operator's memory of what is in flight, so keep it truthful.`;
+var gitSafety = `## Git safety
 
-- Every feature and every bug fix gets its own branch. Never develop directly on main.
-- Explain branches as separate versions of the operator's app; never require git vocabulary from the operator.
-- You own git mechanics. When something goes wrong, fix it yourself and explain what happened in plain terms.
+- Every feature and every fix gets its own branch. Never develop directly on main.
+- Describe branches as separate versions of the operator's app. Never require git vocabulary from them.
+- You own git. When something goes wrong, fix it and explain what happened in plain terms.
+- Commit each working slice. When a slice goes wrong, roll back to the last good commit.`;
+var todManagedFiles = `## tod-managed files
 
-## tod-managed files
+- Never edit between tod's markers in this file; run \`tod sync\` if the block looks wrong.
+- Never hand-edit \`~/.tod/work.json\`, \`~/.tod/log.jsonl\`, \`~/.tod/config.json\`, or \`~/.tod/hints.json\`; use \`tod work\`, \`tod log\`, \`tod config\`, and \`tod hint\`.
+- \`~/.tod/operator.md\` is the one file you edit directly: record durable operator preferences and corrections there as you learn them.`;
+function renderBlock(config3) {
+  const sections = [
+    intro,
+    tod,
+    sessionStart,
+    precedence,
+    nonTechnicalOperator,
+    requirementGathering(config3),
+    responseDetail(config3),
+    reconfiguration,
+    decideByRisk,
+    sliceTheWork,
+    showYourWork,
+    writingStyle,
+    workTracking,
+    gitSafety,
+    todManagedFiles
+  ];
+  return `${sections.join(`
 
-- Never edit anything between tod's markers in this file; run \`tod sync\` if the block looks wrong.
-- Never hand-edit \`~/.tod/work.json\`, \`~/.tod/log.jsonl\`, or \`~/.tod/config.json\`; use \`tod work\`, \`tod log\`, and \`tod config\`.
-- \`~/.tod/operator.md\` is the one tod-managed file you edit directly: record durable operator preferences and corrections there as you learn them.
+`)}
 `;
 }
 
@@ -19476,7 +19605,7 @@ class NotInitialisedError extends h("NotInitialised") {
 function installHarness(home, mode) {
   const paths = todPaths(home);
   const roots = defaultAllowedRoots(home);
-  if (mode === "sync" && !existsSync2(paths.todDir)) {
+  if (mode === "sync" && !existsSync3(paths.todDir)) {
     return ae.err(new NotInitialisedError({ todDir: paths.todDir }));
   }
   const configResult = loadConfig(paths.configFile);
@@ -19497,7 +19626,7 @@ function installHarness(home, mode) {
   }
   const skippedAgents = [];
   for (const target of agentTargets(home)) {
-    if (!existsSync2(target.configDir)) {
+    if (!existsSync3(target.configDir)) {
       skippedAgents.push(target.name);
       continue;
     }
@@ -19523,8 +19652,124 @@ function installHarness(home, mode) {
   return ae.ok({ config: config3, files, skippedAgents });
 }
 
+// src/hints.ts
+var HINTS = [
+  'Tod too wordy? Say "Tod, be less wordy" at any point.',
+  'Want to know more about what was built? Say "Tod, tell me more."',
+  'Tod asking too many questions? Say "Tod, just build it."',
+  'Want Tod to check with you more? Say "Tod, ask me before you decide."',
+  'Not sure what is in progress? Ask "Tod, what am I working on?"',
+  "Something you always want done a certain way? Tell Tod once and he remembers.",
+  'Want to see it working? Say "Tod, show me."',
+  'Something went wrong with the latest change? Say "Tod, go back to the last version that worked."',
+  "Starting something new? Describe what it should do and Tod sets the project up for you.",
+  "Something broke? Describe what you saw and Tod tracks it as a bug until it is fixed.",
+  "Not building today? Ask for whatever you need and Tod stays out of the way."
+];
+var hintStateSchema = exports_external.object({
+  version: exports_external.literal(1),
+  next: exports_external.number().int().nonnegative()
+});
+
+class HintStateError extends h("HintState") {
+}
+function loadHintState(path) {
+  const raw = readFileIfExists(path);
+  if (raw === null) {
+    return ae.ok({ version: 1, next: 0 });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    return ae.err(new HintStateError({
+      path,
+      message: `not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`
+    }));
+  }
+  const checked = hintStateSchema.safeParse(parsed);
+  if (!checked.success) {
+    return ae.err(new HintStateError({ path, message: exports_external.prettifyError(checked.error) }));
+  }
+  return ae.ok(checked.data);
+}
+function formatHint(hint) {
+  return `_Hint: ${hint}_`;
+}
+function nextHint(paths, roots) {
+  if (!existsSync4(paths.configFile)) {
+    return ae.err(new NotInitialisedError({ todDir: paths.todDir }));
+  }
+  const path = paths.hintFile;
+  const loaded = loadHintState(path);
+  if (loaded.isErr()) {
+    return ae.err(loaded.error);
+  }
+  const index = loaded.value.next % HINTS.length;
+  const hint = HINTS[index];
+  if (hint === undefined) {
+    return ae.err(new HintStateError({ path, message: "no hints are defined" }));
+  }
+  const state = { version: 1, next: (index + 1) % HINTS.length };
+  const written = writeFileAtomic(path, `${JSON.stringify(state, null, 2)}
+`, roots);
+  if (written.isErr()) {
+    return ae.err(written.error);
+  }
+  return ae.ok(hint);
+}
+
+// src/commands/hint.ts
+var hint = {
+  help: `tod hint: print the next operator hint
+
+Use once at the start of a session when tod is active, and show the printed
+line to the operator verbatim as the opening line of your first reply. Hints
+remind the operator that they can steer Tod in plain language. Each call
+advances to the next hint and wraps at the end, so the operator sees them in
+turn. Writes only the hint cursor in ~/.tod/. Requires 'tod init' first.
+`,
+  execute: async (args) => {
+    const unknown2 = args.find((arg) => arg.startsWith("-"));
+    if (unknown2 !== undefined) {
+      process.stderr.write(formatError2({
+        what: `unknown flag '${unknown2}'`,
+        why: "tod hint takes no flags",
+        fix: "run 'tod hint' with no arguments"
+      }));
+      return EXIT.usage;
+    }
+    const home = resolveHome();
+    const paths = todPaths(home);
+    const result = nextHint(paths, defaultAllowedRoots(home));
+    return result.match({
+      ok: (text) => {
+        process.stdout.write(`${formatHint(text)}
+`);
+        return EXIT.ok;
+      },
+      err: (error61) => {
+        if (error61._tag === "HintState") {
+          process.stderr.write(formatError2({
+            what: "hint state is unreadable",
+            why: `${tildify(error61.path, home)}: ${error61.message}`,
+            fix: `delete ${tildify(error61.path, home)} (the hint cycle restarts from the first hint), then re-run`
+          }));
+          return EXIT.failure;
+        }
+        process.stderr.write(formatError2(harnessErrorToAgentError(error61, home)));
+        return EXIT.failure;
+      }
+    });
+  }
+};
+
 // src/commands/init.ts
 var ONBOARDING = `
+skills: if the report above lists a missing skill, run the install command it
+shows now, before onboarding. The skill carries tod's engineering defaults and
+routes itself once installed.
+
 onboarding: deliver this script to the operator as Tod, verbatim, as a single
 message with both questions. Wait for both answers before recording.
 
@@ -19549,7 +19794,8 @@ var init = {
 Use for first-time setup and whenever the operator wants to reconfigure tod.
 Creates ~/.tod/ state if missing and appends tod's delimited instruction
 block to each detected agent's global instruction file (~/.agents/AGENTS.md,
-~/.claude/CLAUDE.md); content outside tod's block is never modified. Every
+~/.claude/CLAUDE.md); content outside tod's block is never modified. Reports
+whether each tod skill is installed and the command to install it. Every
 run ends with the two-question onboarding wizard for you to conduct with the
 operator; record the answers with 'tod config set', then run 'tod sync'.
 Idempotent: re-running repairs rather than duplicates.
@@ -19631,6 +19877,59 @@ usage: tod log <message> [--project <name>]
   }
 };
 
+// src/commands/skills.ts
+function render(version2, statuses) {
+  const missing = statuses.filter((skill) => !skill.installed);
+  const lines = [`tod ${version2} skills, pinned to tag ${skillTag(version2)}.`, ""];
+  if (missing.length === 0) {
+    lines.push("All tod skills are installed; nothing to do.");
+  } else {
+    lines.push("Install the missing skills with:", "");
+    for (const skill of missing) {
+      lines.push(`  ${skill.command}`);
+    }
+  }
+  lines.push("", "skills:");
+  for (const skill of statuses) {
+    lines.push(`  ${skill.installed ? "installed" : "missing  "} ${skill.name}  ${skill.summary}`);
+  }
+  lines.push("", "The tag pins the skill to this tod version, so the two never disagree.", "This command prints only: it installs nothing and writes nothing.", "If the install fails on an unresolved tag, the release was not tagged; report", "that rather than installing from a branch.");
+  return `${lines.join(`
+`)}
+`;
+}
+var skills = {
+  help: `tod skills: report tod's agent skills and how to install any that are missing
+
+Use when 'tod init' or 'tod sync' reports a missing skill, or when you are
+unsure whether a tod skill is installed. Prints an install command pinned to
+the tag matching this tod version, so the skill and the CLI agree. Installs
+nothing, writes nothing, and makes no network request.
+`,
+  execute: async (args) => {
+    const unknown2 = args.find((arg) => arg.startsWith("-"));
+    if (unknown2 !== undefined) {
+      process.stderr.write(formatError2({
+        what: `unknown flag '${unknown2}'`,
+        why: "tod skills takes no flags",
+        fix: "run 'tod skills' with no arguments"
+      }));
+      return EXIT.usage;
+    }
+    const statuses = skillStatuses(resolveHome());
+    if (statuses.some((skill) => skill.command === undefined)) {
+      process.stderr.write(formatError2({
+        what: "cannot determine the tod repository",
+        why: `package metadata does not contain a recognisable GitHub URL: '${package_default.repository.url}'`,
+        fix: "report this as a tod bug; do not guess a repository to install skills from"
+      }));
+      return EXIT.failure;
+    }
+    process.stdout.write(render(package_default.version, statuses));
+    return EXIT.ok;
+  }
+};
+
 // src/work.ts
 var workItemSchema = exports_external.object({
   id: exports_external.number().int().positive(),
@@ -19775,7 +20074,8 @@ var sync = {
 Use after tod-managed content was edited, deleted, or looks wrong, or after
 changing settings with 'tod config'. Only touches content inside tod's own
 marker blocks and tod-owned structural files; operator memory, work state,
-the log, and all content outside the markers are never modified. Idempotent.
+the log, and all content outside the markers are never modified. Reports any
+missing tod skill with its install command. Idempotent.
 `,
   execute: async () => {
     const home = resolveHome();
@@ -19948,11 +20248,13 @@ var commands = {
   status,
   work,
   log,
-  config: config2
+  config: config2,
+  skills,
+  hint
 };
 
 // src/run.ts
-var VERSION = "0.1.0";
+var VERSION = package_default.version;
 var HELP2 = `tod ${VERSION}: operator harness for coding agents
 
 This CLI is built to be run by coding agents on behalf of a non-technical
@@ -19974,6 +20276,10 @@ commands:
   log     Append a notable event to the activity log. Append-only.
   config  Read or change the requirement-gathering and response-detail
           settings; follow with 'tod sync' to apply.
+  skills  Report which tod skills are installed and print the pinned install
+          command for any that are missing.
+  hint    Print the next operator hint. Use once at session start and show
+          it verbatim; it reminds the operator how to steer Tod.
 
 Run 'tod <command> --help' for when-to-use guidance and flags.
 exit codes: 0 success · 1 failure (the message states the fix) · 2 usage error
@@ -19994,7 +20300,7 @@ async function run(argv) {
     process.stderr.write(formatError2({
       what: `unknown command '${name}'`,
       why: `tod has no command named '${name}'`,
-      fix: "run 'tod --help' and pick one of: init, sync, status, work, log, config"
+      fix: "run 'tod --help' and pick one of: init, sync, status, work, log, config, skills, hint"
     }));
     return EXIT.usage;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tod-ai",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An operator harness that turns any AGENTS.md-compatible coding agent into a software factory for non-technical builders.",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,9 @@
     "test": "bun test",
     "build": "bun run scripts/build.ts",
     "check": "bun run typecheck && bun run lint && bun test",
-    "prepublishOnly": "bun run check && bun run build"
+    "prepublishOnly": "bun run check:full",
+    "knip": "knip-bun",
+    "check:full": "bun run check && bun run build && bun run knip"
   },
   "engines": {
     "bun": ">=1.3.0",
@@ -46,6 +48,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.11",
     "@types/bun": "1.4.0",
+    "knip": "6.34.0",
     "typescript": "7.0.2"
   }
 }