@anhvupt/tito 0.1.0 → 0.1.2

package/README.md

@@ -84,10 +84,18 @@ npx tito init --profile client-careful
 npx tito init --profile client-careful --confirm
 ```
 
-The first `init` prints the plan and writes nothing. `--confirm` creates the
-missing Tito files and specialist agents. It keeps an existing `AGENTS.md` and
-refuses to overwrite a file that is already there. Open a new Cursor chat, then
-start with `/tito`.
+The first `init` prints the plan and writes nothing. In a terminal, omitting
+`--profile` asks you to choose `client-careful`, `solo-balanced`, or
+`solo-fast`. A script or piped command must still pass `--profile`.
+`--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`.
+
+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.
 
 ## What works today
 

package/dist/cli.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { readFileSync } from "node:fs";
 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, } from "./core/init.js";
+import { InitError, applyInitialization, formatInitialization, planInitialization, promptForProfile, } from "./core/init.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const help = `Tito — quiet orchestration for solo builders
 
@@ -11,7 +13,7 @@ Usage:
   tito [options]
   tito inspect [--root <path>]
   tito apply --dry-run --profile <id> [--root <path>]
-  tito init --profile <id> [--root <path>] [--confirm]
+  tito init [--profile <id>] [--root <path>] [--confirm]
 
 Options:
   -h, --help     Show help
@@ -106,7 +108,7 @@ function runApply(args) {
         throw error;
     }
 }
-function runInit(args) {
+async function runInit(args) {
     if (args.includes("-h") || args.includes("--help")) {
         process.stdout.write(help);
         return;
@@ -136,8 +138,17 @@ function runInit(args) {
         return;
     }
     if (profile === undefined) {
-        fail("Missing required option --profile.");
-        return;
+        if (!input.isTTY) {
+            fail("Missing required option --profile.");
+            return;
+        }
+        const prompts = createInterface({ input, output });
+        try {
+            profile = await promptForProfile((prompt) => prompts.question(prompt));
+        }
+        finally {
+            prompts.close();
+        }
     }
     try {
         const plan = planInitialization(inspectRepository(root), profile);
@@ -163,7 +174,7 @@ function runInit(args) {
         throw error;
     }
 }
-function run(args) {
+async function run(args) {
     if (args[0] === "inspect") {
         runInspect(args.slice(1));
         return;
@@ -173,8 +184,7 @@ function run(args) {
         return;
     }
     if (args[0] === "init") {
-        runInit(args.slice(1));
-        return;
+        return runInit(args.slice(1));
     }
     let helpRequested = false;
     let versionRequested = false;

package/dist/core/init.js

@@ -1,7 +1,9 @@
-import { mkdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { compiledCursorAgents } from "./agents.js";
-import { PlanError, planAdoption, } from "./plan.js";
+import { ACTIVE_RISK_PROFILE_IDS } from "./profiles.js";
+import { ADOPTION_AGENTS_MD, PlanError, planAdoption, } from "./plan.js";
 export class InitError extends Error {
     code;
     constructor(message) {
@@ -10,6 +12,17 @@ export class InitError extends Error {
         this.code = "conflict";
     }
 }
+export async function promptForProfile(ask) {
+    const choices = ACTIVE_RISK_PROFILE_IDS.map((id, index) => `  ${index + 1}. ${id}`).join("\n");
+    const answer = (await ask(`Profiles:\n${choices}\nProfile: `)).trim();
+    const index = Number(answer);
+    if (Number.isInteger(index) &&
+        index >= 1 &&
+        index <= ACTIVE_RISK_PROFILE_IDS.length) {
+        return ACTIVE_RISK_PROFILE_IDS[index - 1] ?? answer;
+    }
+    return answer;
+}
 function exists(root, path) {
     try {
         return statSync(join(root, path)).isFile();
@@ -18,19 +31,47 @@ function exists(root, path) {
         return false;
     }
 }
+function shippedSkills() {
+    const root = join(dirname(fileURLToPath(import.meta.url)), "../../templates/cursor/skills");
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({
+        path: `.cursor/skills/${entry.name}/SKILL.md`,
+        body: readFileSync(join(root, entry.name, "SKILL.md"), "utf8"),
+    }));
+}
+function agentsBootstrap(report) {
+    if (report.agentsMd === "absent") {
+        return { path: "AGENTS.md", action: "create", body: ADOPTION_AGENTS_MD };
+    }
+    const current = readFileSync(join(report.root, "AGENTS.md"), "utf8");
+    if (current.includes("Hola, Tito here!")) {
+        return { path: "AGENTS.md", action: "keep" };
+    }
+    return {
+        path: "AGENTS.md",
+        action: "append",
+        body: `\n${ADOPTION_AGENTS_MD}`,
+    };
+}
 export function planInitialization(report, profile) {
     const adoption = planAdoption(report, profile);
+    const files = adoption.files.map((file) => file.path === "AGENTS.md" ? agentsBootstrap(report) : file);
     const agents = compiledCursorAgents().map((agent) => exists(report.root, agent.path)
         ? { path: agent.path, action: "conflict" }
         : { path: agent.path, action: "create", body: agent.body });
-    return { root: adoption.root, profile: adoption.profile, files: [...adoption.files, ...agents] };
+    const skills = shippedSkills().map((skill) => exists(report.root, skill.path)
+        ? { path: skill.path, action: "keep" }
+        : { path: skill.path, action: "create", body: skill.body });
+    return { root: adoption.root, profile: adoption.profile, files: [...files, ...agents, ...skills] };
 }
 export function formatInitialization(plan) {
     const lines = [`root: ${plan.root}`, `profile: ${plan.profile}`];
     for (const file of plan.files) {
         lines.push(`${file.path}: ${file.action}`);
-        if (file.action === "create")
+        if (file.action === "create" || file.action === "append") {
             lines.push("---", file.body.trimEnd(), "---");
+        }
     }
     return `${lines.join("\n")}\n`;
 }
@@ -42,6 +83,13 @@ export function applyInitialization(plan) {
     const created = [];
     try {
         for (const file of plan.files) {
+            if (file.action === "append") {
+                const absolute = join(plan.root, file.path);
+                const current = readFileSync(absolute, "utf8");
+                const separator = current.endsWith("\n") ? "\n" : "\n\n";
+                writeFileSync(absolute, `${current}${separator}${file.body}`, "utf8");
+                continue;
+            }
             if (file.action !== "create")
                 continue;
             const absolute = join(plan.root, file.path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhvupt/tito",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local-first AI development harness for solo builders.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/",
+    "templates/",
     "README.md",
     "LICENSE"
   ],

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

@@ -0,0 +1,33 @@
+---
+name: tito
+description: Runs Tito's chat-first engineering coordination workflow. Invoke explicitly with /tito for repository exploration, planning, approved implementation slices, and review handoffs.
+disable-model-invocation: true
+---
+
+# Tito
+
+Act as the root Tito coordinator in this project.
+Start every response exactly with `Hola, Tito here!`
+
+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.
+
+## 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.
+- **Agent** only for one explicitly approved implementation slice.
+
+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.
+
+## 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.
+
+Never commit, push, publish, deploy, or perform irreversible external actions without explicit approval.

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

@@ -0,0 +1,12 @@
+---
+name: tito-apply
+description: Dry-run Tito's adoption plan. Invoke explicitly with /tito-apply. Uses the same output as tito apply --dry-run.
+disable-model-invocation: true
+---
+
+# Tito apply
+
+Chat adapter for `npx tito apply --dry-run`. Show the command stdout unchanged.
+Start the chat response exactly with `Hola, Tito here!`
+
+The user must name `client-careful`, `solo-balanced`, or `solo-fast`. If they do not, ask which profile to use and stop. Do not omit `--dry-run`. Do not write project files.

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

@@ -0,0 +1,12 @@
+---
+name: tito-init
+description: Preview or confirm Tito initialization. Invoke explicitly with /tito-init. Uses the same plan as tito init.
+disable-model-invocation: true
+---
+
+# Tito init
+
+Chat adapter for `npx tito init`. Show the command stdout unchanged.
+Start the chat response exactly with `Hola, Tito here!`
+
+Preview first without `--confirm`. Run `npx tito init --profile <id> --confirm` only after the user approves that exact plan. In a terminal, omitting `--profile` asks for one. Do not overwrite existing project guidance.

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

@@ -0,0 +1,12 @@
+---
+name: tito-inspect
+description: Run Tito's read-only repository inspection. Invoke explicitly with /tito-inspect. Uses the same report as tito inspect.
+disable-model-invocation: true
+---
+
+# Tito inspect
+
+Chat adapter for `npx tito inspect`. Run that command and show its stdout unchanged.
+Start the chat response exactly with `Hola, Tito here!` The greeting is not part of the command output.
+
+Add `--root <path>` only when the user names another directory. Do not reimplement inspection by reading files yourself. Do not write project files.