@anhvupt/tito 0.1.3 → 0.3.0

package/README.md

@@ -3,12 +3,13 @@
 **Quiet orchestration. Trusted continuity.**
 
 Tito is a chat-first engineering coordinator for solo builders. You talk to one
-coordinator; Tito explores the repository, chooses the right working mode,
-turns larger work into reviewable slices, and keeps implementation inside the
-scope you approved.
+coordinator. Tito confirms what you want, writes the plan as the spec, and
+sends only the approved slice to a sub-agent.
 
-It is local-first, Git-friendly, and designed to add coordination without
-replacing your project documentation, rules, or specialists.
+The spec records the decisions and the conventions behind them, the test cases
+you review before they are written, and the docs that must change. Tito is
+local-first and Git-friendly. It coordinates your documentation, rules, and
+specialists, and it updates the docs named in the plan before a pull request.
 
 ## What Tito helps with
 
@@ -17,9 +18,16 @@ replacing your project documentation, rules, or specialists.
 - **The right amount of process:** Tito recommends Ask for discovery, Plan for
   uncertain or critical work, and Agent only for an approved implementation
   slice.
-- **Plans that make decisions:** the planner owns technical choices, records
-  important trade-offs, and includes signatures, schemas, pseudocode, or
-  guidance code when that makes implementation clearer.
+- **Plans that make decisions:** Tito confirms the goal and what is out of
+  scope, then asks one batch of clarifying questions, lighter on `solo-fast`.
+  One obvious reading continues after a one-line confirmation. Tito still asks
+  before locking a technical decision or a product-vision change. The plan
+  records that decision and includes signatures, schemas, pseudocode, or
+  guidance code when that makes implementation clearer. Decisions name the
+  convention they follow. Test cases carry a layer tag: `[unit]`,
+  `[integration]`, or `[e2e]`. The plan also lists its docs impact.
+- **A light joke, sometimes:** after `Hola, Tito here!`, Tito may add one short
+  joke. It does not replace the answer, and it stays out of the CLI.
 - **Smaller reviews:** work is split into bounded slices with acceptance
   criteria, tests, forbidden changes, risks, and a stop condition.
 - **Safer changes:** Tito preserves uncommitted work, refuses silent overwrites,
@@ -29,9 +37,11 @@ replacing your project documentation, rules, or specialists.
   rules, skills, BMad workflows, and project-owned specialists rather than
   replacing them.
 - **Controlled model use:** Tito recommends the least expensive capable tier,
-  using stronger reasoning models for architecture, ambiguity, migrations,
-  security, and other high-consequence planning. If a requested model is
-  unavailable, Tito asks instead of substituting one silently.
+  and each launch names the selected model. Explore, docs, and ordinary work
+  use the cheap host family (Grok on Cursor, Sonnet on Claude). Core work uses
+  the stronger coding family. Architecture, security, and ERP work stay on the
+  reasoning family. If a requested model is unavailable, Tito asks instead of
+  substituting one silently.
 
 ## Specialists
 
@@ -52,16 +62,25 @@ mode decides whether it may change anything:
 | Tech docs writer | — | Update technical documentation |
 | User docs writer | — | Update user documentation |
 
-Several read-only specialists may work together. Only one mutating mode may be
-active. Backend and frontend work is split into sequential slices. After a
-module is finished, Tito schedules the tech docs writer and then the user docs
-writer, one at a time, before calling that module done. Skip that handoff only
-when you explicitly waive it for that module. Each specialist carries triggers,
+Several read-only specialists may work together. Coding sub-agents follow the
+profile cap: `client-careful` 3, `solo-balanced` 6, and `solo-fast` 12. Each
+has its own plan and branch. Tito does not code in the chat. Every change,
+including a small one, goes to a sub-agent, and Tito returns to the user.
+When two or more slices are independent, Tito sends those sub-agents together,
+each on its own branch, up to that cap, and does not line them up one after
+another. Check out each branch only after you accept that branch.
+Documentation writers stay one at a time. Backend and frontend work can run
+together inside that cap. Docs named in
+the plan are updated, or you waive them, before Tito offers a pull request.
+After a module is finished, Tito still schedules the tech docs writer and then
+the user docs writer, one at a time, before calling that module done. Skip
+that handoff only when you explicitly waive it for that module. Each specialist carries triggers,
 knowledge references, handoffs, and a stop condition. The detailed prompt stays
 lean and loads knowledge only when that mode needs it.
 
-Cursor agent files such as `.cursor/agents/tito-frontend.md` are not generated
-yet. The roster above is the contract those files will follow.
+Stack knowledge points to the stack owner's official resource for the project's version and is never copied in.
+
+`tito init` writes Cursor agent files such as `.cursor/agents/tito-frontend.md` from the roster above, and `tito upgrade` refreshes them.
 
 ## Chat first, CLI when useful
 
@@ -90,7 +109,18 @@ The first `init` prints the plan and writes nothing. In a terminal, omitting
 `--confirm` creates the missing `tito.yaml`, specialist agents, and `/tito`
 skills. If `AGENTS.md` already exists, Tito appends its bootstrap and leaves
 the existing guidance in place. It refuses to overwrite a Tito file that is
-already there. Open a new Cursor chat, then start with `/tito`.
+already there. In a terminal, `tito init --confirm` then asks for the git base
+(`dev`, `develop`, `main`, or `master`), screen language (`vi` or `en`),
+tenancy (`single` or `multi`), optional comma-separated surface ids, and
+whether to auto-create a pull request after implementation. That question is
+`Auto-create a pull request after implementation? [Y/n]`. Enter, `y`, or `yes`
+stores yes. `n` or `no` stores no. Empty surface ids omit `product.surfaces`.
+A non-interactive init with `--profile` does not ask; it stores
+`git.autoPullRequest: true` and does not invent the other product fields.
+Preview without `--confirm` does not ask and does not write. An existing
+`tito.yaml` is left unchanged. Storing the answer does not open a pull request.
+Errors on a terminal are red, and `NO_COLOR` turns that off.
+Open a new Cursor chat, then start with `/tito`.
 
 Upgrade an existing project after installing a newer Tito:
 
@@ -101,12 +131,13 @@ npx tito upgrade --confirm
 
 `--confirm` installs the latest `@anhvupt/tito` and replaces Tito-owned
 agents, skills, and the Tito section of `AGENTS.md`. Consumer rules, consumer
-agents, and other project skills stay untouched.
+agents, and other project skills stay untouched. In a terminal, `tito upgrade --confirm` asks only for settings missing from `tito.yaml`: git base, screen language, tenancy, surfaces, and auto-create pull request. Enter on that last question still stores yes. It does not change a value that is already present, and it does not change the profile. A non-interactive upgrade does not ask. If `tito.yaml` is missing, it skips those questions.
 
-Tito is installed in each project. It is not a required global command, and
-there is no global configuration yet. A future personal default would be
-overridden by that project's `tito.yaml`. The safety floor still cannot be
-weakened.
+Tito is installed in each project. It is not a required global command.
+An opt-in local admin index (`tito admin add|list|remove|refresh`) can register
+repos under `~/.config/tito/admin/` and store recent commit subjects, dates, and
+touched paths — never diffs. A project `tito.yaml` still overrides any personal
+default. The safety floor cannot be weakened.
 
 ## What works today
 
@@ -142,6 +173,11 @@ node dist/cli.js inspect
 node dist/cli.js inspect --root .
 node dist/cli.js apply --dry-run --profile solo-balanced
 node dist/cli.js init --profile solo-balanced
+node dist/cli.js admin add
+node dist/cli.js admin list
+node dist/cli.js admin refresh
+node dist/cli.js admin remove --root /path/to/repo
+node dist/cli.js admin retro --week 2026-W40
 ```
 
 `inspect` reads `tito.yaml` when it exists and checks whether `AGENTS.md` is
@@ -155,16 +191,65 @@ specialist agent files. It writes those files only with `--confirm`, and it
 refuses when an existing file would be overwritten. In chat, `/tito-init` runs
 this same command.
 
+`admin` is opt-in. `add` registers the current repo (or `--root`), `list` prints
+registered paths, `remove` drops one path, and `refresh` writes local branch plus
+the last 50 commit subjects, dates, and file paths (secrets like `.env` skipped;
+no diffs) for chat and CLI to share.
+
+`retro` builds that week's report from local git and saves `retros/<week>.json`
+and `retros/<week>.md` under the admin root. Review-fix counts, docs-blank, and
+merge duration say unavailable until GitHub data is added.
+
 ## How work moves
 
 The normal careful path is:
 
 `DISCOVERY → PLANNED → APPROVED → IMPLEMENTING → READY_FOR_REVIEW → APPROVED_FOR_COMMIT → DONE`
 
+Work follows clarify, then domain, then the spec doc, then failing tests, then code. Discover clarifies. The plan opens with Domain. In Code, the agent writes the spec doc named in Docs impact first, then the approved tests, confirms they fail, then implements until they pass.
+
+Six working principles guide that path: research, then judge; fixed floor, flexible tools; adopt before building; business before tech; clarify, domain, document, test, then code; and it depends, so show it.
+
 A small, obvious change can move from discovery directly to an explicitly
 approved slice. Review feedback can return an in-scope slice to implementation.
 Other lifecycle skips are rejected.
 
+## Git flow
+
+Tito suggests the branch before checkout, for example `Suggested branch: feat/short-slug from develop`. You accept it or name another base or type. The base is `dev`, `develop`, `main`, or `master`. `dev` and `develop` are interchangeable. `main` and `master` are interchangeable. The type is `feat`, `fix`, `hot-fix`, `chores`, `refactor`, or `debug`.
+
+`tito.yaml` may set the default base:
+
+```yaml
+schemaVersion: 1
+profile: client-careful
+git:
+  defaultBase: develop
+  autoPullRequest: true
+```
+
+`git.autoPullRequest` is an optional boolean. Missing it is valid. A non-boolean value is rejected. Storing it does not open a pull request.
+
+`product.screenLanguage` is optional and accepts only `vi` or `en`. A missing product block is valid. A missing `screenLanguage` is valid. Unknown product fields are rejected. `product.tenancy` is optional (`single` or `multi`). `product.surfaces` is an optional list of `{ id }` entries. Missing `tenancy` and missing `surfaces` stay valid.
+
+```yaml
+product:
+  screenLanguage: vi
+  tenancy: single
+  surfaces:
+    - id: admin
+```
+
+- 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.
+
+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 you review a plan, Tito saves that plan and your edit as separate files under `.tito/feedback/<slug>/`. `review.md` starts with front matter `outcome: accepted | edited | expanded`. Tito indexes only the plan name. The plan body stays in Cursor's plan file. After an approved slice is coded, every review fix goes into one plan named `review/<slug>` on the same branch. Tito asks before opening a pull request only after that plan is coded, or when you accept 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. 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. Init creates `.github/pull_request_template.md` from Tito's template when it is missing. Upgrade replaces that file with Tito's template. Tito does not approve a pull request. Tito merges only when you call for the merge and the pull request already has an approval. 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. After a pull request is merged, Tito asks before the next slice. Tito switches back to the base branch only when you say so clearly. Tito pushes directly to the base branch only when you clearly instruct that push.
+
 ## Development
 
 Requirements:

package/dist/cli.js

@@ -2,13 +2,17 @@
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { InspectionError, formatInspection, inspectRepository, } from "./core/inspect.js";
 import { PlanError, formatAdoptionPlan, planAdoption } from "./core/plan.js";
-import { InitError, applyInitialization, formatInitialization, planInitialization, promptForProfile, } from "./core/init.js";
-import { applyUpgrade, formatUpgrade, planUpgrade, titoOwnedFiles, } from "./core/upgrade.js";
+import { ConfigValidationError, parseConfig } from "./core/config.js";
+import { INIT_SETTING_KEYS, InitError, applyInitialization, formatInitialization, planInitialization, promptForProfile, promptForSettings, } from "./core/init.js";
+import { applyUpgrade, formatUpgrade, mergeSettings, missingSettings, planUpgrade, titoOwnedFiles, } from "./core/upgrade.js";
+import { AdminError, addRepo, formatContexts, formatRepos, listRepos, refreshRepos, removeRepo, resolveAdminRoot, } from "./core/admin.js";
+import { RetroError, buildRetro, formatRetro, retroJson, saveRetro, } from "./core/retro.js";
+import { formatInitError } from "./core/terminal.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const help = `Tito — quiet orchestration for solo builders
 
@@ -18,6 +22,11 @@ Usage:
   tito apply --dry-run --profile <id> [--root <path>]
   tito init [--profile <id>] [--root <path>] [--confirm]
   tito upgrade [--root <path>] [--confirm]
+  tito admin add [--root <path>] [--admin-root <path>]
+  tito admin list [--admin-root <path>]
+  tito admin remove --root <path> [--admin-root <path>]
+  tito admin refresh [--admin-root <path>]
+  tito admin retro [--week <YYYY-Www>] [--timezone <IANA>] [--json] [--admin-root <path>]
 
 Options:
   -h, --help     Show help
@@ -28,11 +37,19 @@ Commands:
   apply          Dry-run an adoption plan. Writes are not available.
   init           Install Tito files and specialist agents. Confirm before writing.
   upgrade        Install the latest Tito and replace Tito-owned files only.
+  admin          Opt-in local repo index: add, list, remove, refresh, retro.
 `;
 function fail(message) {
     process.stderr.write(`${message}\n`);
     process.exitCode = 1;
 }
+function failInit(message) {
+    process.stderr.write(formatInitError(message, {
+        tty: process.stderr.isTTY === true,
+        noColor: process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "",
+    }));
+    process.exitCode = 1;
+}
 function runInspect(args) {
     if (args.includes("-h") || args.includes("--help")) {
         process.stdout.write(help);
@@ -139,12 +156,12 @@ async function runInit(args) {
             root = values.root;
     }
     catch (error) {
-        fail(error instanceof Error ? error.message : "Invalid init arguments.");
+        failInit(error instanceof Error ? error.message : "Invalid init arguments.");
         return;
     }
     if (profile === undefined) {
         if (!input.isTTY) {
-            fail("Missing required option --profile.");
+            failInit("Missing required option --profile.");
             return;
         }
         const prompts = createInterface({ input, output });
@@ -156,24 +173,39 @@ async function runInit(args) {
         }
     }
     try {
-        const plan = planInitialization(inspectRepository(root), profile);
+        const report = inspectRepository(root);
+        const creatingYaml = report.titoYaml.status === "absent";
+        let settings;
+        if (creatingYaml && !input.isTTY)
+            settings = { autoPullRequest: true };
+        let plan = planInitialization(report, profile, settings);
         if (!confirm) {
             process.stdout.write(formatInitialization(plan));
             return;
         }
+        if (creatingYaml && input.isTTY) {
+            const prompts = createInterface({ input, output });
+            try {
+                settings = await promptForSettings((prompt) => prompts.question(prompt), INIT_SETTING_KEYS);
+            }
+            finally {
+                prompts.close();
+            }
+            plan = planInitialization(report, profile, settings);
+        }
         applyInitialization(plan);
         process.stdout.write(formatInitialization(plan));
     }
     catch (error) {
         if (error instanceof InspectionError || error instanceof PlanError || error instanceof InitError) {
-            fail(`${error.code}: ${error.message}`);
+            failInit(`${error.code}: ${error.message}`);
             return;
         }
         if (typeof error === "object" &&
             error !== null &&
             "code" in error &&
             error.code === "EPERM") {
-            fail("filesystem: Tito could not create .cursor/agents.");
+            failInit("filesystem: Tito could not create .cursor/agents.");
             return;
         }
         throw error;
@@ -212,6 +244,8 @@ async function runUpgrade(args) {
         process.stdout.write(formatUpgrade(root, files));
         return;
     }
+    if (!filesOnly && input.isTTY)
+        await fillMissingSettings(root);
     if (!filesOnly && !isTitoSource(root)) {
         const install = spawnSync("npm", ["install", "-D", "@anhvupt/tito@latest"], { cwd: root, encoding: "utf8" });
         if (install.status !== 0) {
@@ -229,6 +263,34 @@ async function runUpgrade(args) {
     applyUpgrade(root, files);
     process.stdout.write(formatUpgrade(root, files));
 }
+async function fillMissingSettings(root) {
+    let text;
+    try {
+        text = readFileSync(join(root, "tito.yaml"), "utf8");
+    }
+    catch {
+        return;
+    }
+    let missing;
+    try {
+        missing = missingSettings(parseConfig(text));
+    }
+    catch (error) {
+        if (error instanceof ConfigValidationError)
+            return;
+        throw error;
+    }
+    if (missing.length === 0)
+        return;
+    const prompts = createInterface({ input, output });
+    try {
+        const answers = await promptForSettings((prompt) => prompts.question(prompt), missing);
+        writeFileSync(join(root, "tito.yaml"), mergeSettings(text, answers), "utf8");
+    }
+    finally {
+        prompts.close();
+    }
+}
 function isTitoSource(root) {
     try {
         const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
@@ -238,6 +300,127 @@ function isTitoSource(root) {
         return false;
     }
 }
+function runAdmin(args) {
+    if (args.includes("-h") || args.includes("--help") || args.length === 0) {
+        process.stdout.write(help);
+        return;
+    }
+    const action = args[0];
+    const rest = args.slice(1);
+    if (action === "retro") {
+        runRetro(rest);
+        return;
+    }
+    if (action !== "add" &&
+        action !== "list" &&
+        action !== "remove" &&
+        action !== "refresh") {
+        fail(`Unknown admin action: ${action}`);
+        return;
+    }
+    let root = process.cwd();
+    let adminRoot = resolveAdminRoot();
+    let rootProvided = false;
+    try {
+        const { values } = parseArgs({
+            args: rest,
+            options: {
+                root: { type: "string" },
+                "admin-root": { type: "string" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        if (values.root !== undefined) {
+            root = values.root;
+            rootProvided = true;
+        }
+        if (values["admin-root"] !== undefined) {
+            adminRoot = resolveAdminRoot(values["admin-root"]);
+        }
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : "Invalid admin arguments.");
+        return;
+    }
+    try {
+        if (action === "add") {
+            const result = addRepo(adminRoot, root);
+            process.stdout.write(result.created
+                ? `added: ${result.repo.path}\n`
+                : `kept: ${result.repo.path}\n`);
+            return;
+        }
+        if (action === "list") {
+            process.stdout.write(formatRepos(listRepos(adminRoot)));
+            return;
+        }
+        if (action === "remove") {
+            if (!rootProvided) {
+                fail("Missing required option --root.");
+                return;
+            }
+            const removed = removeRepo(adminRoot, root);
+            process.stdout.write(`removed: ${removed.path}\n`);
+            return;
+        }
+        process.stdout.write(formatContexts(refreshRepos(adminRoot)));
+    }
+    catch (error) {
+        if (error instanceof AdminError) {
+            fail(`${error.code}: ${error.message}`);
+            return;
+        }
+        throw error;
+    }
+}
+function runRetro(args) {
+    let week;
+    let timezone;
+    let json = false;
+    let adminRoot = resolveAdminRoot();
+    try {
+        const { values } = parseArgs({
+            args,
+            options: {
+                week: { type: "string" },
+                timezone: { type: "string" },
+                json: { type: "boolean" },
+                "admin-root": { type: "string" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        if (values.week !== undefined)
+            week = values.week;
+        if (values.timezone !== undefined)
+            timezone = values.timezone;
+        json = values.json === true;
+        if (values["admin-root"] !== undefined) {
+            adminRoot = resolveAdminRoot(values["admin-root"]);
+        }
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : "Invalid admin arguments.");
+        return;
+    }
+    try {
+        const report = buildRetro({
+            adminRoot,
+            ...(week !== undefined ? { week } : {}),
+            ...(timezone !== undefined ? { timezone } : {}),
+        });
+        saveRetro(adminRoot, report);
+        process.stdout.write(json ? retroJson(report) : formatRetro(report));
+    }
+    catch (error) {
+        if (error instanceof RetroError || error instanceof AdminError) {
+            fail(`${error.code}: ${error.message}`);
+            return;
+        }
+        throw error;
+    }
+}
 async function run(args) {
     if (args[0] === "inspect") {
         runInspect(args.slice(1));
@@ -253,6 +436,10 @@ async function run(args) {
     if (args[0] === "upgrade") {
         return runUpgrade(args.slice(1));
     }
+    if (args[0] === "admin") {
+        runAdmin(args.slice(1));
+        return;
+    }
     let helpRequested = false;
     let versionRequested = false;
     try {