@anhvupt/tito 0.1.3 → 0.2.0

package/dist/core/retro.js

@@ -0,0 +1,444 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { AdminError, defaultGitRunner, isSecretFilename, loadRepos, } from "./admin.js";
+import { parseConfig } from "./config.js";
+import { readFeedbackOutcome } from "./feedback.js";
+import { RISK_PROFILES } from "./profiles.js";
+export const PREFIX_RULE_MARKER = "A commit subject is `<type>: <sentence>`.";
+const WEEK_ID = /^(\d{4})-W(\d{2})$/;
+const TYPE_PREFIX = /^(feat|fix|hot-fix|chores|refactor|debug): /;
+const MERGE_PULL_REQUEST = /^Merge pull request #\d+/;
+const MERGE_BRANCH = /^Merge branch(?:\s|$)/;
+const REVIEW_PATH = /^\.tito\/feedback\/[a-z0-9]+(?:-[a-z0-9]+)*\/review\.md$/;
+const QUIET_SUMMARY = "No Tito activity this week.";
+export class RetroError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "RetroError";
+        this.code = code;
+    }
+}
+export function machineTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+export function isIanaTimeZone(timeZone) {
+    try {
+        Intl.DateTimeFormat("en-US", { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function weeksInIsoYear(year) {
+    const januaryFirst = new Date(Date.UTC(year, 0, 1)).getUTCDay();
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    if (januaryFirst === 4 || (leap && januaryFirst === 3))
+        return 53;
+    return 52;
+}
+export function parseWeekId(value) {
+    const match = WEEK_ID.exec(value);
+    if (match === null)
+        return null;
+    const year = Number(match[1]);
+    const week = Number(match[2]);
+    if (!Number.isInteger(year) || !Number.isInteger(week))
+        return null;
+    if (week < 1 || week > weeksInIsoYear(year))
+        return null;
+    return { year, week };
+}
+function formatWeekId(year, week) {
+    return `${year}-W${String(week).padStart(2, "0")}`;
+}
+function partValue(parts, type) {
+    return parts.find((part) => part.type === type)?.value ?? null;
+}
+function civilDate(instant, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(instant);
+    const year = partValue(parts, "year");
+    const month = partValue(parts, "month");
+    const day = partValue(parts, "day");
+    if (year === null || month === null || day === null) {
+        throw new RetroError("invalid-timezone", `Timezone "${timeZone}" is not an IANA name.`);
+    }
+    return { year: Number(year), month: Number(month), day: Number(day) };
+}
+function isoWeekOfCivil(civil) {
+    const date = new Date(Date.UTC(civil.year, civil.month - 1, civil.day));
+    const weekday = date.getUTCDay() || 7;
+    date.setUTCDate(date.getUTCDate() + 4 - weekday);
+    const year = date.getUTCFullYear();
+    const yearStart = new Date(Date.UTC(year, 0, 1));
+    const dayIndex = Math.round((date.getTime() - yearStart.getTime()) / 86400000);
+    const week = Math.ceil((dayIndex + 1) / 7);
+    return { year, week };
+}
+export function isoWeekId(instant, timeZone) {
+    if (!isIanaTimeZone(timeZone)) {
+        throw new RetroError("invalid-timezone", `Timezone "${timeZone}" is not an IANA name.`);
+    }
+    const week = isoWeekOfCivil(civilDate(instant, timeZone));
+    return formatWeekId(week.year, week.week);
+}
+function timeZoneOffsetMs(instant, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    }).formatToParts(instant);
+    const year = partValue(parts, "year");
+    const month = partValue(parts, "month");
+    const day = partValue(parts, "day");
+    const minute = partValue(parts, "minute");
+    const second = partValue(parts, "second");
+    let hour = partValue(parts, "hour");
+    if (year === null || month === null || day === null || hour === null || minute === null || second === null) {
+        throw new RetroError("invalid-timezone", `Timezone "${timeZone}" is not an IANA name.`);
+    }
+    if (hour === "24")
+        hour = "00";
+    const asUtc = Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second));
+    return asUtc - instant.getTime();
+}
+function zonedMidnightUtc(civil, timeZone) {
+    const guess = Date.UTC(civil.year, civil.month - 1, civil.day, 0, 0, 0, 0);
+    const first = guess - timeZoneOffsetMs(new Date(guess), timeZone);
+    const second = guess - timeZoneOffsetMs(new Date(first), timeZone);
+    return new Date(second);
+}
+function addDays(civil, days) {
+    const date = new Date(Date.UTC(civil.year, civil.month - 1, civil.day + days));
+    return {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth() + 1,
+        day: date.getUTCDate(),
+    };
+}
+function isoWeekMonday(year, week) {
+    const januaryFourth = new Date(Date.UTC(year, 0, 4));
+    const weekday = januaryFourth.getUTCDay() || 7;
+    const monday = new Date(januaryFourth);
+    monday.setUTCDate(januaryFourth.getUTCDate() - (weekday - 1) + (week - 1) * 7);
+    return {
+        year: monday.getUTCFullYear(),
+        month: monday.getUTCMonth() + 1,
+        day: monday.getUTCDate(),
+    };
+}
+export function weekRange(weekId, timeZone) {
+    const parsed = parseWeekId(weekId);
+    if (parsed === null) {
+        throw new RetroError("invalid-week", `Week "${weekId}" is not an ISO week (YYYY-Www).`);
+    }
+    if (!isIanaTimeZone(timeZone)) {
+        throw new RetroError("invalid-timezone", `Timezone "${timeZone}" is not an IANA name.`);
+    }
+    const monday = isoWeekMonday(parsed.year, parsed.week);
+    return {
+        start: zonedMidnightUtc(monday, timeZone),
+        end: zonedMidnightUtc(addDays(monday, 7), timeZone),
+    };
+}
+function isMergeSubject(subject) {
+    return MERGE_PULL_REQUEST.test(subject) || MERGE_BRANCH.test(subject);
+}
+export function countPrefixMisses(commits, ruleLandedAt, range) {
+    if (ruleLandedAt === null)
+        return 0;
+    const landed = Date.parse(ruleLandedAt);
+    if (Number.isNaN(landed))
+        return 0;
+    const start = range.start.getTime();
+    const end = range.end.getTime();
+    let count = 0;
+    for (const commit of commits) {
+        const at = Date.parse(commit.date);
+        if (Number.isNaN(at) || at < start || at >= end || at < landed)
+            continue;
+        if (isMergeSubject(commit.subject) || TYPE_PREFIX.test(commit.subject))
+            continue;
+        count += 1;
+    }
+    return count;
+}
+export function countReviewOutcomes(texts) {
+    const outcomes = {
+        accepted: 0,
+        edited: 0,
+        expanded: 0,
+        unknown: 0,
+    };
+    for (const text of texts) {
+        outcomes[readFeedbackOutcome(text)] += 1;
+    }
+    return outcomes;
+}
+function emptyOutcomes() {
+    return { accepted: 0, edited: 0, expanded: 0, unknown: 0 };
+}
+function authoredFileLimit(profile) {
+    const value = RISK_PROFILES[profile];
+    return "maxAuthoredFiles" in value ? value.maxAuthoredFiles : null;
+}
+function sliceFileLimit(repoPath) {
+    const configPath = join(repoPath, "tito.yaml");
+    if (!existsSync(configPath))
+        return null;
+    try {
+        return authoredFileLimit(parseConfig(readFileSync(configPath, "utf8")).profile);
+    }
+    catch {
+        return null;
+    }
+}
+function countSliceOverLimit(commits, limit) {
+    if (limit === null)
+        return 0;
+    let count = 0;
+    for (const commit of commits) {
+        if (commit.files.length > limit)
+            count += 1;
+    }
+    return count;
+}
+function countMerged(commits) {
+    let count = 0;
+    for (const commit of commits) {
+        if (MERGE_PULL_REQUEST.test(commit.subject))
+            count += 1;
+    }
+    return count;
+}
+function summarize(commitCount, prefixMisses, sliceOverLimit, merged, outcomes) {
+    if (commitCount === 0)
+        return QUIET_SUMMARY;
+    const noun = commitCount === 1 ? "commit" : "commits";
+    return `${commitCount} ${noun}; prefix misses ${prefixMisses}; slice over limit ${sliceOverLimit}; merged ${merged}; outcomes ${outcomes.accepted} accepted, ${outcomes.edited} edited, ${outcomes.expanded} expanded, ${outcomes.unknown} unknown.`;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function tryGit(git, cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return null;
+    }
+}
+function gitInstant(date) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function parseRetroLog(stdout) {
+    const commits = [];
+    for (const block of stdout.split(/\n(?=◆)/)) {
+        const trimmed = block.trim();
+        if (!trimmed.startsWith("◆"))
+            continue;
+        const lines = trimmed.split("\n");
+        const header = lines[0];
+        if (header === undefined || !header.startsWith("◆"))
+            continue;
+        const parts = header.slice(1).split("\0");
+        const hash = parts[0] ?? "";
+        const subject = parts[1] ?? "";
+        const date = parts[2] ?? "";
+        if (hash.length === 0)
+            continue;
+        const files = [];
+        for (const line of lines.slice(1)) {
+            const file = line.trim();
+            if (file.length === 0 || isSecretFilename(file))
+                continue;
+            files.push(file);
+        }
+        commits.push({ hash, subject, date, files });
+    }
+    return commits;
+}
+function inRange(date, range) {
+    const at = Date.parse(date);
+    return !Number.isNaN(at) && at >= range.start.getTime() && at < range.end.getTime();
+}
+function readWeekCommits(git, repoPath, range) {
+    const since = gitInstant(new Date(range.start.getTime() - 1000));
+    const log = git(repoPath, [
+        "log",
+        `--since=${since}`,
+        `--until=${gitInstant(range.end)}`,
+        "--pretty=format:◆%H%x00%s%x00%cI",
+        "--name-only",
+    ]);
+    return parseRetroLog(log).filter((commit) => inRange(commit.date, range));
+}
+function ruleLandedAt(git, repoPath) {
+    const log = git(repoPath, [
+        "log",
+        "--reverse",
+        "--pretty=format:%H%x00%cI",
+        "--",
+        "AGENTS.md",
+    ]);
+    for (const line of log.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const [hash, date] = trimmed.split("\0");
+        if (hash === undefined || date === undefined || hash.length === 0 || date.length === 0)
+            continue;
+        const text = tryGit(git, repoPath, ["show", `${hash}:AGENTS.md`]);
+        if (text !== null && text.includes(PREFIX_RULE_MARKER))
+            return date;
+    }
+    return null;
+}
+function reviewTexts(git, repoPath, commits) {
+    const hashesByPath = new Map();
+    for (const commit of commits) {
+        for (const file of commit.files) {
+            if (!REVIEW_PATH.test(file))
+                continue;
+            const hashes = hashesByPath.get(file);
+            if (hashes === undefined)
+                hashesByPath.set(file, [commit.hash]);
+            else
+                hashes.push(commit.hash);
+        }
+    }
+    const texts = [];
+    for (const [file, hashes] of hashesByPath) {
+        for (const hash of hashes) {
+            const text = tryGit(git, repoPath, ["show", `${hash}:${file}`]);
+            if (text === null)
+                continue;
+            texts.push(text);
+            break;
+        }
+    }
+    return texts;
+}
+export function buildRetro(options) {
+    const timezone = options.timezone ?? machineTimeZone();
+    if (!isIanaTimeZone(timezone)) {
+        throw new RetroError("invalid-timezone", `Timezone "${timezone}" is not an IANA name.`);
+    }
+    const week = options.week ?? isoWeekId(options.now ?? new Date(), timezone);
+    if (parseWeekId(week) === null) {
+        throw new RetroError("invalid-week", `Week "${week}" is not an ISO week (YYYY-Www).`);
+    }
+    const range = weekRange(week, timezone);
+    const git = options.git ?? defaultGitRunner;
+    const outcomes = emptyOutcomes();
+    const repos = [];
+    let prefixMisses = 0;
+    let sliceOverLimit = 0;
+    let merged = 0;
+    let commitCount = 0;
+    for (const repo of loadRepos(options.adminRoot)) {
+        if (!isDirectory(repo.path)) {
+            repos.push({ path: repo.path, missing: true });
+            continue;
+        }
+        repos.push({ path: repo.path });
+        const commits = readWeekCommits(git, repo.path, range);
+        commitCount += commits.length;
+        prefixMisses += countPrefixMisses(commits, ruleLandedAt(git, repo.path), range);
+        sliceOverLimit += countSliceOverLimit(commits, sliceFileLimit(repo.path));
+        merged += countMerged(commits);
+        const counted = countReviewOutcomes(reviewTexts(git, repo.path, commits));
+        outcomes.accepted += counted.accepted;
+        outcomes.edited += counted.edited;
+        outcomes.expanded += counted.expanded;
+        outcomes.unknown += counted.unknown;
+    }
+    return {
+        week,
+        timezone,
+        source: "local",
+        summary: summarize(commitCount, prefixMisses, sliceOverLimit, merged, outcomes),
+        alerts: [],
+        outcomes,
+        prefixMisses,
+        sliceOverLimit,
+        merged,
+        reviewFixes: "unavailable",
+        docsBlank: "unavailable",
+        mergeDuration: "unavailable",
+        repos,
+    };
+}
+export function formatRetro(report, options = {}) {
+    const lines = [
+        `${report.week} (${report.timezone}, ${report.source})`,
+        report.summary,
+        "reviewFixes: unavailable",
+        "docsBlank: unavailable",
+        "mergeDuration: unavailable",
+    ];
+    if (options.alerts === true)
+        lines.push("alerts: []");
+    for (const repo of report.repos) {
+        if (repo.missing === true)
+            lines.push(`missing: ${repo.path}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function formatRetroMarkdown(report) {
+    const outcomes = report.outcomes;
+    const lines = [
+        `# ${report.week}`,
+        "",
+        `Timezone: ${report.timezone}. Source: local.`,
+        "",
+        report.summary,
+        "",
+        `Prefix misses: ${report.prefixMisses}. Slice over limit: ${report.sliceOverLimit}. Merged: ${report.merged}.`,
+        `Outcomes: ${outcomes.accepted} accepted, ${outcomes.edited} edited, ${outcomes.expanded} expanded, ${outcomes.unknown} unknown.`,
+        "Review fixes: unavailable. Docs blank: unavailable. Merge duration: unavailable.",
+        "Alerts: none.",
+    ];
+    const missing = report.repos.filter((repo) => repo.missing === true);
+    if (missing.length > 0) {
+        lines.push("", "Missing repos:");
+        for (const repo of missing)
+            lines.push(`- ${repo.path}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function retroJson(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+function writeTextAtomic(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, text, "utf8");
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        throw new AdminError("filesystem", path, error instanceof Error ? error.message : `Cannot write ${path}.`);
+    }
+}
+export function saveRetro(adminRoot, report) {
+    const dir = join(resolve(adminRoot), "retros");
+    writeTextAtomic(join(dir, `${report.week}.json`), retroJson(report));
+    writeTextAtomic(join(dir, `${report.week}.md`), formatRetroMarkdown(report));
+}

package/dist/core/specialists.js

@@ -63,7 +63,7 @@ export const SPECIALISTS = Object.freeze({
         triggers: ["where code lives", "how behavior works"],
         knowledge: [knowledge("explorer-scout", "always")],
         modes: [specialistMode("scout", "read-only", phase.discovery)],
-        stopCondition: "Return evidence, gaps, and the next specialist.",
+        stopCondition: "When scouting for a plan, report the principles and project conventions relevant to the decisions, and where each convention lives (AGENTS.md, a .cursor/rules file, or an existing pattern). Stay read-only. Return evidence, gaps, and the next specialist to Tito.",
     }),
     "product-analyst": manifest("product-analyst", {
         tier: "Standard",
@@ -133,7 +133,7 @@ export const SPECIALISTS = Object.freeze({
         triggers: ["review correctness", "check edge cases"],
         knowledge: [knowledge("qa-review", "always")],
         modes: [specialistMode("review", "read-only", phase.review)],
-        stopCondition: "Return findings without editing the slice.",
+        stopCondition: "For a plan, return Arrange / Act / Assert test cases with an ID and a layer tag `[unit]`, `[integration]`, or `[e2e]`. When tenancy is multi or more than one surface is declared, draft the applicable kinds: isolation, consistency, propagation, and permissions. Integration is the default. End-to-end only when the plan names a journey. After coding, check each approved test ID as passing or failing, and flag any test that was not in the approved list. Stay read-only. Return findings without editing the slice.",
     }),
     "security-reviewer": manifest("security-reviewer", {
         tier: "Reasoning",
@@ -149,7 +149,7 @@ export const SPECIALISTS = Object.freeze({
         triggers: ["module finished", "update technical documentation"],
         knowledge: [knowledge("tech-docs", "task")],
         modes: [specialistMode("update", "write-files", phase.implementation)],
-        stopCondition: "Stop after the technical docs match the finished module.",
+        stopCondition: "Apply the plan's Docs impact (update named docs, or record a waiver) before a pull request. The module-end pass still covers larger docs. Stop after that docs work matches the plan.",
     }),
     "user-docs-writer": manifest("user-docs-writer", {
         tier: "Standard",
@@ -157,7 +157,7 @@ export const SPECIALISTS = Object.freeze({
         triggers: ["module finished", "update user documentation"],
         knowledge: [knowledge("user-docs", "task")],
         modes: [specialistMode("update", "write-files", phase.implementation)],
-        stopCondition: "Stop after the user docs match the finished module.",
+        stopCondition: "Apply the plan's Docs impact (update named docs, or record a waiver) before a pull request. The module-end pass still covers larger docs. Stop after that docs work matches the plan.",
     }),
 });
 export class DelegationError extends Error {
@@ -176,7 +176,8 @@ function reject(code, message) {
 function isSpecialistId(value) {
     return SPECIALIST_IDS.includes(value);
 }
-export function validateDelegation(activations, phaseName) {
+const DOCUMENTATION_WRITERS = new Set(["tech-docs-writer", "user-docs-writer"]);
+export function validateDelegation(activations, phaseName, maxWriters = 1) {
     const seen = new Set();
     const resolved = [];
     for (const activation of activations) {
@@ -210,11 +211,16 @@ export function validateDelegation(activations, phaseName) {
         });
     }
     const mutators = resolved.filter((item) => item.capability !== "read-only");
-    if (mutators.length > 1) {
-        reject("multiple-mutators", "Only one specialist mode may mutate at a time.");
+    const documentationWriters = mutators.filter((item) => DOCUMENTATION_WRITERS.has(item.specialistId));
+    if (documentationWriters.length > 1) {
+        reject("multiple-mutators", "Documentation writers run one at a time.");
+    }
+    if (mutators.length > maxWriters) {
+        reject("multiple-mutators", `At most ${maxWriters} specialist modes may mutate at a time.`);
     }
     return {
-        mutator: mutators[0] ?? null,
+        mutator: mutators.length === 1 ? (mutators[0] ?? null) : null,
+        mutators,
         advisers: resolved.filter((item) => item.capability === "read-only"),
     };
 }

package/dist/core/upgrade.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { compiledCursorAgents } from "./agents.js";
+import { PULL_REQUEST_TEMPLATE_PATH, pullRequestTemplate } from "./git-flow.js";
 import { shippedSkills } from "./init.js";
 import { TITO_BOOTSTRAP_END, TITO_BOOTSTRAP_START, titoBootstrapBlock, } from "./plan.js";
 function readIfFile(root, path) {
@@ -52,7 +53,11 @@ export function planUpgrade(root, ownedFiles) {
     return files;
 }
 export function titoOwnedFiles() {
-    return [...compiledCursorAgents(), ...shippedSkills()];
+    return [
+        ...compiledCursorAgents(),
+        ...shippedSkills(),
+        { path: PULL_REQUEST_TEMPLATE_PATH, body: pullRequestTemplate() },
+    ];
 }
 export function formatUpgrade(root, files) {
     const lines = [`root: ${root}`, "consumer rules: untouched"];

package/dist/core/work-plan.js

@@ -1,5 +1,5 @@
 import { LIFECYCLE_STATES, } from "./lifecycle.js";
-import { isActiveRiskProfileId, } from "./profiles.js";
+import { RISK_PROFILES, isActiveRiskProfileId, } from "./profiles.js";
 import { SPECIALISTS, } from "./specialists.js";
 export class WorkPlanError extends Error {
     code;
@@ -177,14 +177,15 @@ export function evaluateWorkPlan(plan, progress) {
     }
     const activeWriters = validated.slices.filter((slice) => slice.kind === "implementation" &&
         progress.implementationStates[slice.id] === "IMPLEMENTING");
-    if (activeWriters.length > 1) {
-        reject("multiple-active-writers", "Only one implementation slice may be active.");
+    const maxWriters = RISK_PROFILES[validated.profile].maxWriters;
+    if (activeWriters.length > maxWriters) {
+        reject("multiple-active-writers", `At most ${maxWriters} implementation slices may be active.`);
     }
     const unreviewedSlices = validated.slices.filter((slice) => slice.kind === "implementation" &&
         progress.implementationStates[slice.id] === "READY_FOR_REVIEW");
     if (validated.profile === "client-careful" &&
-        activeWriters.length + unreviewedSlices.length > 1) {
-        reject("invalid-progress", "Client-careful cannot stack unreviewed work.");
+        activeWriters.length + unreviewedSlices.length > maxWriters) {
+        reject("invalid-progress", "Client-careful cannot stack unreviewed work beyond its writer cap.");
     }
     const dependencyReasons = (slice) => {
         const reasons = [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anhvupt/tito",
-  "version": "0.1.3",
-  "description": "Local-first AI development harness for solo builders.",
+  "version": "0.2.0",
+  "description": "Chat-first engineering coordinator for solo builders. The plan is the spec: decisions, test cases, and docs.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {

package/templates/cursor/skills/tito/SKILL.md

@@ -6,33 +6,81 @@ disable-model-invocation: true
 
 # Tito
 
-Act as the root Tito coordinator in this project.
+Act as the root Tito coordinator in the active Cursor chat.
 Start every response exactly with `Hola, Tito here!`
+Sometimes add one short joke after that greeting. The joke does not replace the answer. Skip it when the user is blocked, when the news is bad, and in CLI or machine-readable output.
 
-Ordinary chat follows `AGENTS.md`. `/tito` is the explicit coordinator. Read `tito.yaml` for the risk profile. Read project documentation only when the task needs it. Do not replace existing project guidance.
+## Authority
+
+Read `TITO-INITIAL-BRIEF.md` completely before planning or editing when that brief is present. Treat it as
+the product contract and source of workflow, risk, delegation, and review
+policy. Ordinary chat follows `AGENTS.md`. `/tito` is the explicit coordinator. Read `tito.yaml` for the risk profile. Read other project documentation only when relevant. Do not replace existing project guidance.
+
+Tito owns workflow state. Do not infer it from Cursor UI state, private
+storage, undocumented payloads, or transcript internals.
 
 ## Route the task
 
 Recommend one mode before acting:
 
 - **Ask** for read-only exploration, explanation, impact analysis, or diagnosis.
-- **Plan** for ambiguity, architecture, sensitive work, migrations, or work requiring multiple reviewable slices.
+- **Plan** for ambiguity, architecture, sensitive work, migrations, or work
+  requiring multiple reviewable slices.
 - **Agent** only for one explicitly approved implementation slice.
 
 A new command, a new write behavior, or any technical choice is always Plan
-first. That response contains the plan only. No source edits. "No need to plan"
-applies only to the slice named in that message. Implementation starts only
-after that plan is approved.
+first. That response contains the plan only. No source edits. Skip the plan only when the user clearly instructs that this slice does not need a plan. Implementation starts only
+after that plan is approved. Cursor being in Agent mode does not approve a slice.
+
+Suggest the source branch and change type before checkout. Bases are `dev`, `develop`, `main`, and `master`. `dev` and `develop` are interchangeable. `main` and `master` are interchangeable. Check out only after the user accepts. A commit subject is `<type>: <sentence>`. The type is the same token as the branch type: `feat`, `fix`, `hot-fix`, `chores`, `refactor`, or `debug`. Examples: `feat: add commit message rule`, `fix: reject a duplicate surface id`, `chores: record the commit prefix rule`, and `hot-fix: stop a bad release build`. The words after the colon are one finished sentence of at most 70 words. The type is not counted in those 70 words. The body is a separate description. When the user reviews a plan, save Tito's plan and the user's edit as separate files under `.tito/feedback/<slug>/`. `review.md` starts with front matter `outcome: accepted | edited | expanded`. After an approved slice is coded, put every review fix into one plan named `review/<slug>` on the same branch. Ask before opening a pull request only after that plan is coded, or when the user accepts the code with no changes. The pull request description has four parts within 2 to 50 lines: a one-line problem, what changed, review fixes, and checks for lint, code quality, conventions, tests, build, and docs. Init creates `.github/pull_request_template.md` from Tito's template when it is missing. Upgrade replaces that file with Tito's template. Never approve a pull request. Never merge unless the user calls for the merge and the pull request already has an approval. After a pull request is merged, ask before the next slice. Switch back to the base branch only when the user says so clearly. Push directly to the base branch only when the user clearly instructs that push.
+
+For Plan work, prefer a Reasoning-tier model unless the plan is obvious and
+bounded or the user chose another model. The implementation agent follows the approved decision and does not invent a new one. Include concise guidance code,
+signatures, schemas, or pseudocode where it removes ambiguity.
+
+Discover restates the goal and what is out of scope in one or two sentences, then asks whether that is what the user wants, and waits. After the user confirms, ask one batch of 3 to 5 clarifying questions. Each question offers options and a recommended default. `solo-fast` does only the intent check, plus questions about real ambiguity. `client-careful` and `solo-balanced` use the full batch. One obvious reading still continues, after a one-line confirmation. Ask before locking a technical decision or a product-vision change. After the user answers, the plan records that decision and includes guidance code when it removes implementation ambiguity.
+
+The workflow is Discover → Plan → Human Approval → Code → Verify → Docs gate → Review. Every plan has Decisions (each names the principle and the project convention it follows, with where that convention lives), Test cases (each has an ID and a layer tag `[unit]`, `[integration]`, or `[e2e]`; behavior tests use Arrange / Act / Assert; edge cases are one line each), Docs impact, and Slices and branch. The approved plan is the spec. For a single slice, the user may say "skip test discussion" or "skip docs", in the same spirit as skipping the plan.
 
-For Plan work, the planner decides the technical approach and includes guidance code when it removes ambiguity. Ask the user only for a genuine product or business choice.
+- Code stays English.
+- In a Vietnamese app (`screenLanguage: vi`), routes and slugs are Vietnamese first. The public path is native Vietnamese, for example `/tien-ich/ca-phe`. Do not invent that Vietnamese by translating an English slug word for word. If the product is bilingual, the English route comes second.
+- An English app (`screenLanguage: en`) keeps English routes and slugs.
+- In a Vietnamese app (`screenLanguage: vi`), every string a person reads is Vietnamese: tables, labels, buttons, headings, and messages. Write native Vietnamese first. Do not invent it by translating English word for word. English may exist as a second field only when the product is bilingual, and it comes after the Vietnamese.
+- An English app (`screenLanguage: en`) stays English on screen.
+- When `screenLanguage` is missing and the screen language is unclear, Tito asks once. One obvious reading continues without a question.
+- Globalized apps store timestamps in UTC and show them in the user's timezone. There is no switch to turn that off.
+
+Optional `product.tenancy` is `single` or `multi`. Optional `product.surfaces` is a list of `{ id }` entries. Missing `tenancy` and missing `surfaces` stay valid.
+
+A plan that touches shared data includes only the kinds that apply:
+
+- Isolation: tenant A cannot read or change tenant B's data. Required when `tenancy` is `multi` and the slice changes tenant-scoped data.
+- Consistency: a write on one surface is the value another surface reads. Required when there are two or more surfaces and the slice changes data more than one surface reads.
+- Propagation: async work is asserted before a deadline, not after a fixed sleep.
+- Permissions: each role on each surface can do only what it should.
+- Default layer is `[integration]`. `[e2e]` only when the plan names a browser journey. `[unit]` stays for logic that does not cross a surface.
+- Arrange uses a fixed seed of at least two tenants and every role when tenancy is multi, reset each run, never production credentials. Tito does not ship the seed or Playwright.
 
 ## Execute
 
-1. Inspect the repository without mutation and preserve uncommitted work.
-2. State facts, affected files, uncertainties, risks, and the recommended mode.
-3. For Plan work, produce independent slices and stop for approval.
-4. Use one code writer. Specialist advisers and reviewers stay read-only.
-5. Implement and verify only the approved slice, then stop for review.
-6. After a finished module, schedule the tech docs writer and then the user docs writer unless the user waives that handoff.
+1. Inspect the repository without mutation and preserve uncommitted work. When a Tito command exists, use that same core behavior in chat instead of sending the person to the terminal.
+2. Discover: restate the goal and what is out of scope, confirm that reading, then ask the clarifying batch the risk profile calls for. State facts, affected files, uncertainties, risks, and the recommended mode.
+3. For Plan work, produce one plan with Decisions, Test cases, Docs impact, and Slices and branch, then stop for approval. The approved plan is the spec.
+4. Before Agent work, provide the implementation handoff required by the brief.
+5. Tito does not code in this chat. Send every change, including a small one, to a sub-agent, then return to the user. `client-careful` may run 3 coding sub-agents, `solo-balanced` 6, and `solo-fast` 12. Each has its own plan and branch. Documentation writers stay one at a time. Specialist advisers and reviewers stay read-only.
+6. Code the approved slice by writing the approved tests first, confirming they fail, then implementing until they pass. A test beyond the approved list is flagged as new. A bug fix starts with a test that reproduces the bug.
+7. Verify: report each approved test ID as passing or failing, plus lint and build.
+8. Docs gate: update the docs named in Docs impact, or record the user's waiver, before offering a pull request. After a finished module, schedule the tech docs writer and then the user docs writer for larger docs, one at a time, unless the user waives that handoff.
+9. Provide the required review handoff and stop. The short code-review walkthrough stays. Review fixes still go into one plan named `review/<slug>` on the same branch.
+
+Use Tito's durable lifecycle:
+`DISCOVERY → PLANNED → APPROVED → IMPLEMENTING → READY_FOR_REVIEW → APPROVED_FOR_COMMIT → DONE`.
+`DISCOVERY` is the intent check, then clarify. `PLANNED` means the plan has Decisions, Test cases, Docs impact, and Slices and branch.
+
+Per-project Tito stays. Opt-in `tito admin add|list|remove|refresh` indexes
+registered repos under `~/.config/tito/admin/` with commit subject, date, and
+paths only — never diffs. A project `tito.yaml` overrides a personal default;
+do not weaken the safety floor.
 
-Never commit, push, publish, deploy, or perform irreversible external actions without explicit approval.
+Never commit, push, publish, deploy, or perform irreversible external actions
+without explicit approval.