@anhvupt/tito 0.1.0

package/dist/core/specialists.js

@@ -0,0 +1,237 @@
+export const SPECIALIST_IDS = [
+    "explorer",
+    "product-analyst",
+    "architect",
+    "backend-engineer",
+    "frontend-engineer",
+    "devops-engineer",
+    "erp-specialist",
+    "qa-reviewer",
+    "security-reviewer",
+    "tech-docs-writer",
+    "user-docs-writer",
+];
+export const WRITER_SPECIALIST_IDS = [
+    "backend-engineer",
+    "frontend-engineer",
+    "devops-engineer",
+    "tech-docs-writer",
+    "user-docs-writer",
+];
+export const READ_ONLY_SPECIALIST_IDS = [
+    "explorer",
+    "product-analyst",
+    "architect",
+    "erp-specialist",
+    "qa-reviewer",
+    "security-reviewer",
+];
+const phase = Object.freeze({
+    discovery: ["discovery"],
+    planning: ["planning"],
+    implementation: ["implementation"],
+    review: ["review"],
+    advise: ["discovery", "planning", "implementation"],
+});
+function knowledge(id, load) {
+    return Object.freeze({ id, load });
+}
+function specialistMode(id, capability, phases, gates = []) {
+    return Object.freeze({ id, capability, phases, gates: Object.freeze([...gates]) });
+}
+function manifest(id, seed) {
+    return Object.freeze({
+        id,
+        version: 1,
+        role: seed.role,
+        model: Object.freeze({
+            tier: seed.tier,
+            preferred: "inherit",
+            fallbackPolicy: "ask-user",
+        }),
+        triggers: Object.freeze([...seed.triggers]),
+        knowledge: seed.knowledge,
+        handoffs: Object.freeze(SPECIALIST_IDS.filter((candidate) => candidate !== id)),
+        modes: seed.modes,
+        stopCondition: seed.stopCondition,
+    });
+}
+export const SPECIALISTS = Object.freeze({
+    explorer: manifest("explorer", {
+        tier: "Scout",
+        role: "Repository scout",
+        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.",
+    }),
+    "product-analyst": manifest("product-analyst", {
+        tier: "Standard",
+        role: "Requirements analyst",
+        triggers: ["clarify requirements", "define acceptance"],
+        knowledge: [knowledge("product-analysis", "task")],
+        modes: [specialistMode("analyze", "read-only", phase.planning)],
+        stopCondition: "Return one slice and its acceptance criteria.",
+    }),
+    architect: manifest("architect", {
+        tier: "Reasoning",
+        role: "Technical planner",
+        triggers: ["choose architecture", "resolve a technical trade-off"],
+        knowledge: [knowledge("architecture-decisions", "task")],
+        modes: [specialistMode("plan", "read-only", phase.planning)],
+        stopCondition: "Return the decided approach and guidance code.",
+    }),
+    "backend-engineer": manifest("backend-engineer", {
+        tier: "Standard",
+        role: "Backend implementer",
+        triggers: ["backend implementation", "API or data change"],
+        knowledge: [knowledge("backend-implementation", "task")],
+        modes: [specialistMode("implement", "write-files", phase.implementation)],
+        stopCondition: "Stop after the approved backend slice is verified.",
+    }),
+    "frontend-engineer": manifest("frontend-engineer", {
+        tier: "Standard",
+        role: "Frontend designer and implementer",
+        triggers: ["frontend design", "frontend implementation"],
+        knowledge: [
+            knowledge("frontend-ux", "always"),
+            knowledge("angular", "stack"),
+        ],
+        modes: [
+            specialistMode("design", "read-only", phase.planning, ["preview"]),
+            specialistMode("implement", "write-files", phase.implementation),
+        ],
+        stopCondition: "Stop after the approved frontend slice is verified.",
+    }),
+    "devops-engineer": manifest("devops-engineer", {
+        tier: "Standard",
+        role: "Infrastructure implementer",
+        triggers: ["infrastructure plan", "deployment change"],
+        knowledge: [knowledge("devops-safety", "always")],
+        modes: [
+            specialistMode("plan", "read-only", phase.planning),
+            specialistMode("implement", "write-infrastructure", phase.implementation, [
+                "human-approval",
+            ]),
+        ],
+        stopCondition: "Stop after the approved infrastructure slice is verified.",
+    }),
+    "erp-specialist": manifest("erp-specialist", {
+        tier: "Reasoning",
+        role: "ERP domain adviser",
+        triggers: ["ERP workflow", "inventory procurement or accounting review"],
+        knowledge: [knowledge("erp-domain", "task")],
+        modes: [
+            specialistMode("advise", "read-only", phase.advise),
+            specialistMode("review", "read-only", phase.review),
+        ],
+        stopCondition: "Return domain constraints without editing files.",
+    }),
+    "qa-reviewer": manifest("qa-reviewer", {
+        tier: "Standard",
+        role: "Independent QA reviewer",
+        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.",
+    }),
+    "security-reviewer": manifest("security-reviewer", {
+        tier: "Reasoning",
+        role: "Independent security reviewer",
+        triggers: ["security review", "authorization or secrets review"],
+        knowledge: [knowledge("security-review", "task")],
+        modes: [specialistMode("review", "read-only", phase.review)],
+        stopCondition: "Return security findings without editing the slice.",
+    }),
+    "tech-docs-writer": manifest("tech-docs-writer", {
+        tier: "Standard",
+        role: "Technical documentation writer",
+        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.",
+    }),
+    "user-docs-writer": manifest("user-docs-writer", {
+        tier: "Standard",
+        role: "User documentation writer",
+        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.",
+    }),
+});
+export class DelegationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "DelegationError";
+        this.code = code;
+    }
+}
+const ROOT_IDS = new Set(["tito", "tito-root"]);
+const MAX_PURPOSE_LENGTH = 200;
+function reject(code, message) {
+    throw new DelegationError(code, message);
+}
+function isSpecialistId(value) {
+    return SPECIALIST_IDS.includes(value);
+}
+export function validateDelegation(activations, phaseName) {
+    const seen = new Set();
+    const resolved = [];
+    for (const activation of activations) {
+        if (ROOT_IDS.has(activation.specialistId)) {
+            reject("root-recursion", "Tito remains the root coordinator.");
+        }
+        if (!isSpecialistId(activation.specialistId)) {
+            reject("unknown-specialist", `Unknown specialist "${activation.specialistId}".`);
+        }
+        if (seen.has(activation.specialistId)) {
+            reject("duplicate-specialist", `Specialist "${activation.specialistId}" is activated more than once.`);
+        }
+        seen.add(activation.specialistId);
+        const purpose = activation.purpose.trim();
+        if (purpose.length === 0 || purpose.length > MAX_PURPOSE_LENGTH) {
+            reject("missing-purpose", "Each activation needs one short purpose.");
+        }
+        const manifestFor = SPECIALISTS[activation.specialistId];
+        const selected = manifestFor.modes.find((item) => item.id === activation.modeId);
+        if (selected === undefined) {
+            reject("unknown-mode", `${activation.specialistId} has no mode "${activation.modeId}".`);
+        }
+        if (!selected.phases.includes(phaseName)) {
+            reject("wrong-phase", `${activation.specialistId}:${selected.id} cannot run during ${phaseName}.`);
+        }
+        resolved.push({
+            specialistId: activation.specialistId,
+            modeId: selected.id,
+            purpose,
+            capability: selected.capability,
+        });
+    }
+    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.");
+    }
+    return {
+        mutator: mutators[0] ?? null,
+        advisers: resolved.filter((item) => item.capability === "read-only"),
+    };
+}
+export const DOCUMENTATION_HANDOFF = Object.freeze([
+    "tech-docs-writer",
+    "user-docs-writer",
+]);
+export function documentationHandoff(moduleName) {
+    const moduleLabel = moduleName.trim();
+    if (moduleLabel.length === 0) {
+        reject("missing-purpose", "Documentation handoff needs the finished module name.");
+    }
+    return DOCUMENTATION_HANDOFF.map((specialistId) => Object.freeze({
+        specialistId,
+        modeId: "update",
+        purpose: specialistId === "tech-docs-writer"
+            ? `Update technical documentation for ${moduleLabel}.`
+            : `Update user documentation for ${moduleLabel}.`,
+    }));
+}

package/dist/core/work-plan.js

@@ -0,0 +1,270 @@
+import { LIFECYCLE_STATES, } from "./lifecycle.js";
+import { isActiveRiskProfileId, } from "./profiles.js";
+import { SPECIALISTS, } from "./specialists.js";
+export class WorkPlanError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorkPlanError";
+        this.code = code;
+    }
+}
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}
+function reject(code, message) {
+    throw new WorkPlanError(code, message);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function specialistManifest(id) {
+    if (!Object.hasOwn(SPECIALISTS, id)) {
+        reject("invalid-specialist", `Unknown specialist "${id}".`);
+    }
+    return SPECIALISTS[id];
+}
+function hasMode(id, predicate) {
+    return specialistManifest(id).modes.some(predicate);
+}
+export function validateWorkPlan(plan) {
+    const input = plan;
+    if (!isRecord(input) ||
+        typeof input.profile !== "string" ||
+        !Array.isArray(input.slices)) {
+        reject("invalid-plan", "Work plan must contain a profile and slice array.");
+    }
+    for (const slice of input.slices) {
+        if (!isRecord(slice) ||
+            typeof slice.id !== "string" ||
+            typeof slice.title !== "string" ||
+            typeof slice.kind !== "string" ||
+            typeof slice.specialist !== "string" ||
+            !Array.isArray(slice.dependsOn) ||
+            !slice.dependsOn.every((dependency) => typeof dependency === "string")) {
+            reject("invalid-plan", "Every slice must use the work-plan slice shape.");
+        }
+    }
+    if (!isActiveRiskProfileId(plan.profile)) {
+        reject("invalid-profile", `Unknown active profile "${plan.profile}".`);
+    }
+    const byId = new Map();
+    for (const slice of plan.slices) {
+        if (slice.id.trim() === "")
+            reject("invalid-id", "Slice IDs cannot be empty.");
+        if (byId.has(slice.id)) {
+            reject("duplicate-id", `Slice "${slice.id}" is declared more than once.`);
+        }
+        byId.set(slice.id, slice);
+        const prerequisites = new Set();
+        for (const dependency of slice.dependsOn) {
+            if (dependency === slice.id) {
+                reject("self-prerequisite", `Slice "${slice.id}" cannot depend on itself.`);
+            }
+            if (prerequisites.has(dependency)) {
+                reject("duplicate-prerequisite", `Slice "${slice.id}" repeats prerequisite "${dependency}".`);
+            }
+            prerequisites.add(dependency);
+        }
+    }
+    for (const slice of plan.slices) {
+        if (!["read-only", "implementation", "review"].includes(slice.kind)) {
+            reject("invalid-slice-kind", `Slice "${slice.id}" has an invalid kind.`);
+        }
+        for (const dependency of slice.dependsOn) {
+            if (!byId.has(dependency)) {
+                reject("missing-prerequisite", `Slice "${slice.id}" references missing prerequisite "${dependency}".`);
+            }
+        }
+        if (slice.kind === "implementation") {
+            if (!["self", "independent"].includes(slice.reviewRequirement)) {
+                reject("invalid-review-requirement", `Implementation slice "${slice.id}" has an invalid review requirement.`);
+            }
+            if (!hasMode(slice.specialist, (mode) => mode.capability !== "read-only" && mode.phases.includes("implementation"))) {
+                reject("invalid-specialist", `${slice.specialist} cannot implement a slice.`);
+            }
+        }
+        if (slice.kind !== "implementation" &&
+            !hasMode(slice.specialist, (mode) => mode.capability === "read-only")) {
+            reject("invalid-specialist", `${slice.specialist} cannot run a read-only slice.`);
+        }
+        if (slice.kind === "review") {
+            const target = byId.get(slice.reviews);
+            const canReview = hasMode(slice.specialist, (mode) => mode.capability === "read-only" && mode.phases.includes("review"));
+            if (target?.kind !== "implementation" ||
+                !slice.dependsOn.includes(slice.reviews) ||
+                !canReview) {
+                reject("invalid-review-target", `Review slice "${slice.id}" must depend on an implementation it can review.`);
+            }
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            reject("cycle", `Slice graph contains a cycle at "${id}".`);
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const dependency of byId.get(id)?.dependsOn ?? [])
+            visit(dependency);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const slice of plan.slices)
+        visit(slice.id);
+    for (const slice of plan.slices) {
+        if (slice.kind === "implementation" &&
+            (plan.profile === "client-careful" ||
+                slice.reviewRequirement === "independent") &&
+            (slice.reviewRequirement !== "independent" ||
+                !plan.slices.some((candidate) => candidate.kind === "review" && candidate.reviews === slice.id))) {
+            reject("missing-independent-review", `Implementation slice "${slice.id}" requires an independent review slice.`);
+        }
+    }
+    const copy = {
+        profile: plan.profile,
+        slices: plan.slices.map((slice) => ({
+            ...slice,
+            dependsOn: [...slice.dependsOn],
+        })),
+    };
+    return deepFreeze(copy);
+}
+function lifecycleRank(state) {
+    return LIFECYCLE_STATES.indexOf(state);
+}
+function reached(state, threshold) {
+    return state !== undefined && lifecycleRank(state) >= lifecycleRank(threshold);
+}
+export function evaluateWorkPlan(plan, progress) {
+    const validated = validateWorkPlan(plan);
+    const progressInput = progress;
+    if (!isRecord(progressInput) ||
+        !Array.isArray(progressInput.activeReadOnlySliceIds) ||
+        !progressInput.activeReadOnlySliceIds.every((id) => typeof id === "string") ||
+        !Array.isArray(progressInput.completedSliceIds) ||
+        !progressInput.completedSliceIds.every((id) => typeof id === "string") ||
+        !isRecord(progressInput.implementationStates)) {
+        reject("invalid-progress", "Progress must use the work-plan progress shape.");
+    }
+    const byId = new Map(validated.slices.map((slice) => [slice.id, slice]));
+    const active = new Set(progress.activeReadOnlySliceIds);
+    const completed = new Set(progress.completedSliceIds);
+    if (active.size !== progress.activeReadOnlySliceIds.length ||
+        completed.size !== progress.completedSliceIds.length) {
+        reject("invalid-progress", "Progress cannot repeat slice IDs.");
+    }
+    for (const id of [...active, ...completed]) {
+        const slice = byId.get(id);
+        if (slice === undefined || slice.kind === "implementation") {
+            reject("invalid-progress", `Progress references invalid read-only slice "${id}".`);
+        }
+        if (active.has(id) && completed.has(id)) {
+            reject("invalid-progress", `Slice "${id}" cannot be active and completed.`);
+        }
+    }
+    for (const [id, state] of Object.entries(progress.implementationStates)) {
+        if (byId.get(id)?.kind !== "implementation" ||
+            !LIFECYCLE_STATES.includes(state)) {
+            reject("invalid-progress", `Invalid implementation progress for "${id}".`);
+        }
+    }
+    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 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.");
+    }
+    const dependencyReasons = (slice) => {
+        const reasons = [];
+        for (const dependencyId of slice.dependsOn) {
+            const dependency = byId.get(dependencyId);
+            if (dependency?.kind !== "implementation") {
+                if (!completed.has(dependencyId))
+                    reasons.push(`waiting-for:${dependencyId}`);
+                continue;
+            }
+            const threshold = slice.kind === "review" && slice.reviews === dependencyId
+                ? "READY_FOR_REVIEW"
+                : validated.profile === "client-careful" ||
+                    dependency.reviewRequirement === "independent"
+                    ? "APPROVED_FOR_COMMIT"
+                    : "READY_FOR_REVIEW";
+            if (!reached(progress.implementationStates[dependencyId], threshold)) {
+                reasons.push(`waiting-for:${dependencyId}:${threshold}`);
+            }
+        }
+        return reasons;
+    };
+    for (const id of [...active, ...completed]) {
+        const slice = byId.get(id);
+        if (slice !== undefined && dependencyReasons(slice).length > 0) {
+            reject("invalid-progress", `Progressed slice "${id}" has unmet prerequisites.`);
+        }
+    }
+    for (const slice of validated.slices) {
+        if (slice.kind === "implementation" &&
+            reached(progress.implementationStates[slice.id], "IMPLEMENTING") &&
+            dependencyReasons(slice).length > 0) {
+            reject("invalid-progress", `Implementation slice "${slice.id}" has unmet prerequisites.`);
+        }
+        if (slice.kind === "implementation" &&
+            reached(progress.implementationStates[slice.id], "APPROVED_FOR_COMMIT") &&
+            (validated.profile === "client-careful" ||
+                slice.reviewRequirement === "independent") &&
+            !validated.slices.some((candidate) => candidate.kind === "review" &&
+                candidate.reviews === slice.id &&
+                completed.has(candidate.id))) {
+            reject("invalid-progress", `Implementation slice "${slice.id}" lacks completed independent review.`);
+        }
+    }
+    const writerBlocker = activeWriters[0] ??
+        (validated.profile === "client-careful"
+            ? validated.slices.find((slice) => slice.kind === "implementation" &&
+                progress.implementationStates[slice.id] === "READY_FOR_REVIEW")
+            : undefined);
+    const readyReadOnly = [];
+    const readyWriterCandidates = [];
+    const blocked = [];
+    for (const slice of validated.slices) {
+        if (completed.has(slice.id) ||
+            active.has(slice.id) ||
+            (slice.kind === "implementation" &&
+                reached(progress.implementationStates[slice.id], "IMPLEMENTING"))) {
+            continue;
+        }
+        const reasons = dependencyReasons(slice);
+        if (slice.kind === "implementation") {
+            if (progress.implementationStates[slice.id] !== "APPROVED") {
+                reasons.push("awaiting-approval");
+            }
+            if (writerBlocker !== undefined) {
+                const reason = progress.implementationStates[writerBlocker.id] === "IMPLEMENTING"
+                    ? "writer-active"
+                    : "unreviewed-slice";
+                reasons.push(`${reason}:${writerBlocker.id}`);
+            }
+        }
+        if (reasons.length > 0) {
+            blocked.push({ sliceId: slice.id, reasons });
+        }
+        else if (slice.kind === "implementation") {
+            readyWriterCandidates.push(slice);
+        }
+        else {
+            readyReadOnly.push(slice);
+        }
+    }
+    return deepFreeze({ readyReadOnly, readyWriterCandidates, blocked });
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@anhvupt/tito",
+  "version": "0.1.0",
+  "description": "Local-first AI development harness for solo builders.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "tito": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  }
+}