@anhvupt/tito 0.3.1 → 0.3.4

package/dist/core/models.js

@@ -12,13 +12,39 @@ const CLASS_ESCALATION = {
     core: "Ask the user before selecting a more expensive model.",
     reasoning: "Ask the user before selecting a more expensive model.",
 };
+const GROK_RULE = {
+    family: "Grok",
+    matchGroups: [(slug) => slug.startsWith("grok-"), (slug) => slug.startsWith("cursor-grok-")],
+    pick: "highest",
+};
+const OPUS_RULE = {
+    family: "Opus",
+    matchGroups: [(slug) => slug.startsWith("claude-opus-")],
+    pick: "highest",
+};
+const SONNET_HIGHEST = {
+    family: "Sonnet",
+    matchGroups: [(slug) => slug.startsWith("claude-sonnet-")],
+    pick: "highest",
+};
+const COMPOSER_25 = {
+    family: "Composer",
+    matchGroups: [(slug) => slug === "composer-2.5"],
+    pick: "highest",
+};
 function rulesFor(host, taskClass) {
     if (host === "cursor") {
-        return {
-            family: "Grok",
-            matchGroups: [(slug) => slug.startsWith("grok-"), (slug) => slug.startsWith("cursor-grok-")],
-            pick: "highest",
-        };
+        if (taskClass === "explore" || taskClass === "docs" || taskClass === "ordinary") {
+            return GROK_RULE;
+        }
+        if (taskClass === "core") {
+            return {
+                family: "Codex",
+                matchGroups: [(slug) => slug.includes("codex"), (slug) => slug.startsWith("composer-")],
+                pick: "highest",
+            };
+        }
+        return OPUS_RULE;
     }
     if (taskClass === "explore" || taskClass === "docs") {
         return {
@@ -28,17 +54,39 @@ function rulesFor(host, taskClass) {
         };
     }
     if (taskClass === "ordinary") {
-        return {
-            family: "Sonnet",
-            matchGroups: [(slug) => slug.startsWith("claude-sonnet-")],
-            pick: "highest",
-        };
+        return SONNET_HIGHEST;
+    }
+    return OPUS_RULE;
+}
+function rulesForRole(role) {
+    switch (role) {
+        case "explorer":
+        case "sandbox":
+            return {
+                rule: GROK_RULE,
+                tier: "Scout",
+                escalation: CLASS_ESCALATION.explore,
+            };
+        case "test-writer":
+        case "implementer":
+            return {
+                rule: GROK_RULE,
+                tier: "Standard",
+                escalation: CLASS_ESCALATION.ordinary,
+            };
+        case "planner":
+            return {
+                rule: OPUS_RULE,
+                tier: "Reasoning",
+                escalation: CLASS_ESCALATION.reasoning,
+            };
+        case "finisher":
+            return {
+                rule: COMPOSER_25,
+                tier: "Scout",
+                escalation: CLASS_ESCALATION.docs,
+            };
     }
-    return {
-        family: "Opus",
-        matchGroups: [(slug) => slug.startsWith("claude-opus-")],
-        pick: "highest",
-    };
 }
 function versionTuple(slug) {
     const groups = slug.match(/\d+/g) ?? [];
@@ -68,35 +116,71 @@ function pickVersion(slugs, pick) {
     const direction = pick === "highest" ? 1 : -1;
     return [...slugs].sort((a, b) => compareVersions(versionTuple(a), versionTuple(b)) * direction).at(-1) ?? slugs[0];
 }
-export function recommendModel({ host, taskClass, catalog, userModel, }) {
-    const tier = CLASS_TIER[taskClass];
-    const escalation = CLASS_ESCALATION[taskClass];
-    if (typeof userModel === "string" && userModel.length > 0) {
+function isFastSlug(slug) {
+    return slug.split("-").includes("fast");
+}
+function selectSlug(catalog, rule) {
+    const groups = rule.matchGroups.map((matcher) => catalog.filter((slug) => matcher(slug)));
+    const nonFastGroups = groups.map((group) => group.filter((slug) => !isFastSlug(slug)));
+    const preferNonFast = nonFastGroups.some((group) => group.length > 0);
+    const eligible = preferNonFast ? nonFastGroups : groups;
+    for (const group of eligible) {
+        if (group.length === 0) {
+            continue;
+        }
+        const model = pickVersion(group, rule.pick);
+        if (preferNonFast) {
+            return { model };
+        }
+        return { model, fast: true };
+    }
+    return undefined;
+}
+function selectionFor(input) {
+    if (input.role !== undefined) {
+        return rulesForRole(input.role);
+    }
+    return {
+        rule: rulesFor(input.host, input.taskClass),
+        tier: CLASS_TIER[input.taskClass],
+        escalation: CLASS_ESCALATION[input.taskClass],
+    };
+}
+export function recommendModel(input) {
+    const selection = selectionFor(input);
+    if (typeof input.userModel === "string" && input.userModel.length > 0) {
         return {
             status: "selected",
-            model: userModel,
-            tier,
+            model: input.userModel,
+            tier: selection.tier,
             reason: "Used the explicit model requested by the user.",
-            escalation,
+            escalation: selection.escalation,
         };
     }
-    const rule = rulesFor(host, taskClass);
-    for (const matcher of rule.matchGroups) {
-        const matches = catalog.filter((slug) => matcher(slug));
-        if (matches.length > 0) {
-            const model = pickVersion(matches, rule.pick);
-            return {
-                status: "selected",
-                model,
-                tier,
-                reason: `Selected the ${rule.pick} version in the ${rule.family} family.`,
-                escalation,
-            };
-        }
+    if (input.role !== undefined && input.host !== "cursor") {
+        return {
+            status: "ask",
+            family: selection.rule.family,
+            reason: "Pipeline roles are routed on the Cursor host.",
+        };
+    }
+    const picked = selectSlug(input.catalog, selection.rule);
+    if (picked === undefined) {
+        return {
+            status: "ask",
+            family: selection.rule.family,
+            reason: `No matching ${selection.rule.family} model was found in the current catalog.`,
+        };
     }
+    const reason = picked.fast
+        ? `Selected the ${selection.rule.pick} version in the ${selection.rule.family} family. The only match is a -fast slug.`
+        : `Selected the ${selection.rule.pick} version in the ${selection.rule.family} family.`;
     return {
-        status: "ask",
-        family: rule.family,
-        reason: `No matching ${rule.family} model was found in the current catalog.`,
+        status: "selected",
+        model: picked.model,
+        tier: selection.tier,
+        reason,
+        escalation: selection.escalation,
+        ...(picked.fast ? { fast: true } : {}),
     };
 }

package/dist/core/plan.js

@@ -1,26 +1,10 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { ACTIVE_RISK_PROFILE_IDS, isActiveRiskProfileId, isFutureRiskProfileId, } from "./profiles.js";
 export const TITO_BOOTSTRAP_START = "<!-- tito:bootstrap start -->";
 export const TITO_BOOTSTRAP_END = "<!-- tito:bootstrap end -->";
-export const ADOPTION_AGENTS_MD = `# Tito bootstrap
-
-This project uses Tito as its root engineering coordinator.
-
-- Start every Tito-coordinated chat response exactly with \`Hola, Tito here!\`
-- Keep that marker out of CLI and machine-readable output.
-- Treat ordinary requests as Tito-coordinated work.
-- Recommend Ask, Plan, or Agent before acting.
-- Preserve uncommitted work and use one code writer at a time.
-- Stop for human approval between reviewable slices.
-- Never commit, push, publish, deploy, or perform irreversible external actions without explicit approval.
-- Use \`/tito\` when Tito coordination is wanted.
-- Plans own technical decisions and include guidance code when useful.
-- Research current official sources and judge them before trusting; adopt maintained tools before building our own; show options with pros and cons for this project.
-- Confirm intent before clarifying. Plans open with Domain (business impact first), then Decisions, Test cases, Docs impact, and Slices and branch.
-- Do not merge a slice branch into \`main\`, \`master\`, \`dev\`, or \`develop\`, on the machine or on the remote, unless the user calls for that merge and the pull request already has an approval. Finishing a slice leaves the branch as it is.
-- When the user comments on an open pull request, Tito updates that pull request's description in the same turn. Review fixes lists every comment, including the earlier ones. A thread reply does not replace that update.
-
-Keep this bootstrap compact. Load project documentation only when the task needs it.
-`;
+export const ADOPTION_AGENTS_MD = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../templates/cursor/AGENTS.md"), "utf8");
 export function titoBootstrapBlock() {
     return `${TITO_BOOTSTRAP_START}\n${ADOPTION_AGENTS_MD.trim()}\n${TITO_BOOTSTRAP_END}\n`;
 }
@@ -66,3 +50,21 @@ export function formatAdoptionPlan(plan) {
     }
     return `${lines.join("\n")}\n`;
 }
+function bulletSection(title, lines) {
+    const body = lines.length > 0 ? lines.map((line) => `- ${line}`).join("\n") : "-";
+    return `## ${title}\n${body}`;
+}
+export function renderImplementationPlan(plan) {
+    const cases = plan.testFirst.length > 0
+        ? plan.testFirst.map((item) => `- \`${item.file}\`: ${item.expectedFailure}`).join("\n")
+        : "-";
+    return [
+        bulletSection("Domain", [plan.domain]),
+        bulletSection("Decisions", plan.decisions),
+        bulletSection("Test cases", plan.testCases),
+        `## Test-first commit\n${cases}`,
+        bulletSection("Docs impact", plan.docsImpact),
+        bulletSection("Slices and branch", plan.slicesAndBranch),
+        "",
+    ].join("\n\n");
+}

package/dist/core/skills.js

@@ -0,0 +1,64 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+function frontMatter(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0] !== "---")
+        return null;
+    const close = lines.indexOf("---", 1);
+    if (close < 1)
+        return null;
+    return lines.slice(1, close).join("\n");
+}
+function cardFrom(matter) {
+    let value;
+    try {
+        value = parse(matter);
+    }
+    catch {
+        return null;
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const nameValue = record.name;
+    if (typeof nameValue !== "string" || nameValue.trim() === "")
+        return null;
+    const name = nameValue.trim();
+    const descriptionValue = record.description;
+    const description = typeof descriptionValue === "string" ? descriptionValue.trim() : "";
+    return {
+        name,
+        description,
+        role: name === "tito" ? "coordinator" : "candidate",
+    };
+}
+export function listSkillCards(dir) {
+    let folders;
+    try {
+        folders = readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    }
+    catch {
+        return [];
+    }
+    const cards = [];
+    for (const folder of folders) {
+        let text;
+        try {
+            text = readFileSync(join(dir, folder, "SKILL.md"), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const matter = frontMatter(text);
+        if (matter === null)
+            continue;
+        const card = cardFrom(matter);
+        if (card !== null)
+            cards.push(card);
+    }
+    return cards;
+}

package/dist/core/specialists.js

@@ -26,6 +26,19 @@ export const READ_ONLY_SPECIALIST_IDS = [
     "qa-reviewer",
     "security-reviewer",
 ];
+export const SPECIALIST_MODEL_ROLES = Object.freeze({
+    explorer: "explorer",
+    "product-analyst": "planner",
+    architect: "planner",
+    "backend-engineer": "implementer",
+    "frontend-engineer": "implementer",
+    "devops-engineer": "implementer",
+    "erp-specialist": "planner",
+    "qa-reviewer": "reviewer",
+    "security-reviewer": "planner",
+    "tech-docs-writer": "finisher",
+    "user-docs-writer": "finisher",
+});
 const phase = Object.freeze({
     discovery: ["discovery"],
     planning: ["planning"],
@@ -46,7 +59,7 @@ function manifest(id, seed) {
         role: seed.role,
         model: Object.freeze({
             tier: seed.tier,
-            preferred: "inherit",
+            role: SPECIALIST_MODEL_ROLES[id],
             fallbackPolicy: "ask-user",
         }),
         triggers: Object.freeze([...seed.triggers]),

package/dist/core/test-first.js

@@ -0,0 +1,95 @@
+import { spawnSync } from "node:child_process";
+export class TestFirstError extends Error {
+    code = "git";
+    constructor(message) {
+        super(message);
+        this.name = "TestFirstError";
+    }
+}
+function git(root, args) {
+    const result = spawnSync("git", [...args], { cwd: root, encoding: "utf8" });
+    if (result.error)
+        throw new TestFirstError(result.error.message);
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || "git command failed").trim();
+        throw new TestFirstError(detail);
+    }
+    return result.stdout ?? "";
+}
+function normalize(file) {
+    return file.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function hasMarker(base, marker) {
+    const index = base.indexOf(marker);
+    return index >= 0 && index + marker.length < base.length;
+}
+function isTestFile(file) {
+    const path = normalize(file);
+    if (path === "test" || path.startsWith("test/"))
+        return true;
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    return hasMarker(base, ".test.") || hasMarker(base, ".spec.");
+}
+function changedFiles(root, sha) {
+    const output = git(root, [
+        "diff-tree",
+        "--no-commit-id",
+        "--name-only",
+        "-r",
+        "-m",
+        "--root",
+        sha,
+    ]);
+    const files = [];
+    const seen = new Set();
+    for (const line of output.split("\n")) {
+        const file = line.trim();
+        if (file.length === 0 || seen.has(file))
+            continue;
+        seen.add(file);
+        files.push(file);
+    }
+    return files;
+}
+function fail(file, commit, message) {
+    return { ok: false, retry: false, file, commit, message };
+}
+export function guardTestFirst(input) {
+    const listed = new Set(input.testFiles.map(normalize));
+    const commits = git(input.root, ["rev-list", "--reverse", `${input.base}..HEAD`])
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const first = commits[0];
+    if (first === undefined) {
+        return fail("(none)", input.base, "The slice branch has no commits after its base.");
+    }
+    for (const file of changedFiles(input.root, first)) {
+        if (!listed.has(normalize(file))) {
+            return fail(file, first, `Commit 1 changes ${file}, which is outside the listed test files.`);
+        }
+    }
+    for (let index = 1; index < commits.length; index += 1) {
+        const sha = commits[index];
+        if (sha === undefined)
+            continue;
+        for (const file of changedFiles(input.root, sha)) {
+            if (!isTestFile(file))
+                continue;
+            return fail(file, sha, `Commit ${index + 1} changes test file ${file}.`);
+        }
+    }
+    return { ok: true, retry: false };
+}
+export function formatTestFirstReport(report) {
+    if (report.ok)
+        return "ok: true\nretry: false\n";
+    return [
+        "ok: false",
+        "retry: false",
+        `file: ${report.file}`,
+        `commit: ${report.commit}`,
+        `message: ${report.message}`,
+        "",
+    ].join("\n");
+}

package/dist/core/upgrade.js

@@ -1,9 +1,10 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { parseDocument } from "yaml";
 import { compiledCursorAgents } from "./agents.js";
-import { parseConfig } from "./config.js";
+import { ConfigValidationError, DEFAULT_MODELS, MODEL_ROLES, parseConfig, } from "./config.js";
 import { PULL_REQUEST_TEMPLATE_PATH, pullRequestTemplate } from "./git-flow.js";
-import { shippedSkills, titoYamlBody } from "./init.js";
+import { shippedCursorRules, shippedSkills, titoYamlBody, } from "./init.js";
 import { TITO_BOOTSTRAP_END, TITO_BOOTSTRAP_START, titoBootstrapBlock, } from "./plan.js";
 function readIfFile(root, path) {
     try {
@@ -41,6 +42,13 @@ export function planUpgrade(root, ownedFiles) {
             ? { path: file.path, action }
             : { path: file.path, action, body: file.body };
     });
+    const yaml = readIfFile(root, "tito.yaml");
+    const withModels = yaml === null ? null : addMissingModels(yaml);
+    if (yaml !== null && withModels !== null) {
+        files.push(withModels === yaml
+            ? { path: "tito.yaml", action: "keep" }
+            : { path: "tito.yaml", action: "replace", body: withModels });
+    }
     const agents = readIfFile(root, "AGENTS.md");
     if (agents === null) {
         files.push({ path: "AGENTS.md", action: "create", body: titoBootstrapBlock() });
@@ -53,10 +61,37 @@ export function planUpgrade(root, ownedFiles) {
     }
     return files;
 }
-export function titoOwnedFiles() {
+function readConfigText(text) {
+    try {
+        return parseConfig(text);
+    }
+    catch (error) {
+        if (error instanceof ConfigValidationError)
+            return null;
+        throw error;
+    }
+}
+export function addMissingModels(yamlText) {
+    const config = readConfigText(yamlText);
+    if (config === null)
+        return null;
+    const missing = MODEL_ROLES.filter((role) => config.models?.[role] === undefined);
+    if (missing.length === 0)
+        return yamlText;
+    const document = parseDocument(yamlText, { version: "1.2" });
+    for (const role of missing)
+        document.setIn(["models", role], DEFAULT_MODELS[role]);
+    return document.toString();
+}
+export function projectModels(root) {
+    const text = readIfFile(root, "tito.yaml");
+    return text === null ? undefined : readConfigText(text)?.models;
+}
+export function titoOwnedFiles(models) {
     return [
-        ...compiledCursorAgents(),
+        ...compiledCursorAgents(models),
         ...shippedSkills(),
+        ...shippedCursorRules(),
         { path: PULL_REQUEST_TEMPLATE_PATH, body: pullRequestTemplate() },
     ];
 }
@@ -122,7 +157,7 @@ export function mergeSettings(yamlText, answers) {
     }
     if (!changed)
         return yamlText;
-    return titoYamlBody(config.profile, settings);
+    return titoYamlBody(config.profile, config.models === undefined ? settings : { ...settings, models: config.models });
 }
 export function applyUpgrade(root, files) {
     for (const file of files) {

package/dist/core/work-plan.js

@@ -269,3 +269,20 @@ export function evaluateWorkPlan(plan, progress) {
     }
     return deepFreeze({ readyReadOnly, readyWriterCandidates, blocked });
 }
+const TEST_FIRST_RULE = "Test-first: Commit 1 changes test files only and they fail. Later commits touch no test file.";
+export function buildSliceHandoff(input) {
+    const skills = input.skillNames.length === 0
+        ? "Skills: none match"
+        : `Skills: ${input.skillNames.join(", ")}`;
+    return [
+        `Spec: ${input.specPath}`,
+        "Targets:",
+        ...input.targetFiles,
+        "Forbidden:",
+        ...input.forbiddenFiles,
+        `Stop: ${input.stopCondition}`,
+        TEST_FIRST_RULE,
+        skills,
+        "",
+    ].join("\n");
+}